initial: claude code workflow bundle (plan-start, status, handoff, adr)

2026-04-17 07:28:49 +02:00
commit 20a0ab38f2
16 changed files with 978 additions and 0 deletions
@@ -0,0 +1,98 @@
+---
+name: adr
+description: Legt unter docs/30-decisions/ einen neuen Architecture Decision Record an, automatisch hochnummeriert, nach festem Template (Context, Decision, Consequences, Alternatives). Ergänzt gleichzeitig den Abschnitt "Laufende ADRs" in docs/20-architecture.md.
+disable-model-invocation: true
+argument-hint: "<titel der entscheidung, z. b.: 'pocketbase statt supabase'>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# adr — Architecture Decision Record
+
+## Wann der Skill läuft
+
+Immer dann, wenn eine **Entscheidung getroffen wird, die später Kopfschmerzen
+kostet, wenn sie niemand dokumentiert**. Typische Beispiele:
+
+- Wahl einer Technologie gegen Alternativen („PocketBase statt Supabase").
+- Struktur-Entscheidung, die konkurrierende Optionen hatte („Monorepo statt
+  mehrerer Repos", „Events statt direktem Call").
+- Betriebs-Entscheidung mit Tragweite („Caddy als Reverse-Proxy", „tägliches
+  Snapshot-Backup auf Hetzner Storage Box").
+
+**Nicht** für triviale Entscheidungen („wir benennen die Variable `user_id`
+statt `uid`") — da ist der ADR mehr Last als Nutzen.
+
+## Voraussetzungen
+
+Existiert `docs/30-decisions/`? Wenn nicht → meldet „Kein initialisiertes
+Projekt. Erst `plan-start` ausführen." Abbrechen.
+
+## Was der Skill tut
+
+### Schritt 1 — Titel bestimmen
+
+- Titel kommt aus `$ARGUMENTS`. Wenn leer: freundlich nach einem Titel fragen
+  (eine Zeile), nicht weiter spekulieren.
+- Slug aus Titel ableiten: lowercase, Leerzeichen → Bindestrich, Sonderzeichen
+  raus. Beispiel: `PocketBase statt Supabase` → `pocketbase-statt-supabase`.
+
+### Schritt 2 — Nummer vergeben
+
+- `ls docs/30-decisions/ | grep -E '^[0-9]{4}-'` listet bestehende ADRs.
+- Höchste bestehende Nummer + 1, auf 4 Stellen gepaddet (`0001`, `0042`).
+- Erste ADR → `0001`.
+
+### Schritt 3 — Datei anlegen
+
+- Dateiname: `docs/30-decisions/<NNNN>-<slug>.md`.
+- Inhalt: aus `templates/adr.md.tmpl`, Platzhalter füllen:
+
+| Platzhalter | Quelle |
+|---|---|
+| `{{ADR_NUMBER}}` | die vergebene Nummer, 4-stellig |
+| `{{ADR_TITLE}}` | der Titel |
+| `{{ADR_DATE}}` | `date +%F` |
+| `{{ADR_AUTHOR}}` | `git config user.name`, sonst leer |
+
+**Status** ist initial `proposed`. Der Nutzer wechselt ihn später auf
+`accepted`, wenn die Entscheidung gelebt wird — oder auf
+`superseded by NNNN`, wenn ein späterer ADR sie ablöst.
+
+### Schritt 4 — Abschnitt „Laufende ADRs" in 20-architecture.md ergänzen
+
+Am Ende von `docs/20-architecture.md` steht ein Abschnitt `## Laufende ADRs`.
+Dort wird eine Zeile nach folgendem Muster angehängt:
+
+```markdown
+- [{{ADR_NUMBER}}](30-decisions/{{ADR_NUMBER}}-{{slug}}.md) — {{ADR_TITLE}} (`proposed`, {{ADR_DATE}})
+```
+
+Wenn dort noch der Platzhalter-Text `_(Noch keine ADRs. ...)_` steht: diesen
+entfernen und die erste Zeile einfügen.
+
+### Schritt 5 — Kurze Bestätigung
+
+Dem Nutzer den neuen Pfad und die Nummer zurückmelden, und einen knappen
+Hinweis: „Datei ist als `proposed` markiert. Wenn die Entscheidung steht: auf
+`accepted` setzen."
+
+## Harte Regeln
+
+- **Nie einen bestehenden ADR überschreiben.** Nummerierung ist append-only.
+- **Nie den Status eines anderen ADR ändern.** Wenn der neue ADR einen alten
+  ablöst: das trägt der Nutzer selbst am alten ADR nach (im neuen ADR sollte
+  er es im Header `Supersedes: NNNN` notieren — aber auch das macht der
+  Nutzer, der Skill verdrahtet das nicht automatisch, weil das Fehlerquelle
+  ist).
+- **Keine Entscheidung erfinden.** Der Skill legt nur das Gerüst an.
+  Context / Decision / Consequences füllt der Nutzer. Der Skill darf ruhig
+  Vorschläge machen, wenn im Chatkontext genug Information da ist — aber er
+  schreibt nichts in die Datei, was der Nutzer nicht bestätigt hat.
+
+## Template
+
+Siehe `./templates/adr.md.tmpl`.