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,97 @@
+---
+name: plan-start
+description: Legt in einem neuen oder leeren Projektordner die standardisierte Dokumentations- und Wegweiser-Struktur an (CLAUDE.md, docs/ mit 00-overview, 10-plan, 20-architecture, 90-status, 30-decisions/, 40-workflows/, sessions/). Nutzt die Templates unter templates/ dieses Skills. Soll nur auf explizite Nutzeranforderung laufen, nie autonom.
+disable-model-invocation: true
+argument-hint: "<kurzer projekttitel oder eine zeile zur idee>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# plan-start — Projekt-Scaffolding
+
+## Wann der Skill läuft
+
+Ausschließlich auf expliziten Aufruf, in einem **neuen oder noch leeren
+Projektordner**. Der Skill legt eine Grundstruktur an und darf vorhandene
+Dateien nicht überschreiben.
+
+## Was der Skill tut
+
+1. Prüft den aktuellen Arbeitsordner. Wenn dort bereits `CLAUDE.md` oder
+   `docs/` existiert → **abbrechen** und dem Nutzer melden: „Hier liegt schon
+   ein initialisiertes Projekt. `plan-start` ist idempotent nicht — du willst
+   vermutlich `status` oder direkt in `docs/` editieren."
+2. Stellt dem Nutzer vor dem Schreiben **kurz und konkret** diese Fragen
+   (eine nach der anderen, nicht als Sammel-Liste):
+   - **Projektname** (wird als Titel in CLAUDE.md und Headings verwendet)
+   - **Ein-Satz-Zweck** („Wofür ist das Projekt da?")
+   - **Aktuelle Phase** (Planung / Build / Wartung — Default: Planung)
+   - **Stack in Stichworten** (z. B. „Python + FastAPI + PocketBase",
+     „NixOS + Caddy + Docker Compose" — darf auch leer sein, wenn noch unklar)
+3. Legt folgende Struktur an — relativ zum aktuellen Arbeitsordner:
+
+   ```
+   ./CLAUDE.md
+   ./.claude/skills/.gitkeep
+   ./docs/00-overview.md
+   ./docs/10-plan.md
+   ./docs/20-architecture.md
+   ./docs/90-status.md
+   ./docs/30-decisions/README.md
+   ./docs/40-workflows/README.md
+   ./docs/sessions/README.md
+   ```
+
+4. Befüllt jede Datei aus dem passenden Template unter
+   `./templates/` dieses Skills. Platzhalter werden wie folgt ersetzt:
+
+   | Platzhalter | Quelle |
+   |---|---|
+   | `{{PROJECT_NAME}}` | aus Frage 1 |
+   | `{{PROJECT_PURPOSE}}` | aus Frage 2 |
+   | `{{PROJECT_PHASE}}` | aus Frage 3 |
+   | `{{PROJECT_STACK}}` | aus Frage 4, leer → `TBD` |
+   | `{{TODAY_ISO}}` | heutiges Datum als `YYYY-MM-DD` via `date +%F` |
+   | `{{USER_NAME}}` | optional: `git config user.name`, sonst leer |
+
+5. Erzeugt `.claude/skills/.gitkeep` als leere Datei, damit das
+   projektspezifische Skill-Verzeichnis unter Versionskontrolle bleibt, auch
+   solange es leer ist.
+
+6. Gibt am Ende eine **kurze Bestandsaufnahme** in 3–5 Zeilen aus: was wurde
+   angelegt, was als Nächstes sinnvoll ist (Empfehlung: `docs/00-overview.md`
+   und `docs/10-plan.md` durchgehen und konkretisieren, dann `handoff`).
+
+## Harte Regeln
+
+- **Nie** Dateien überschreiben. Wenn auch nur eine der Zieldateien existiert:
+  komplett abbrechen und den Nutzer informieren.
+- **Nie** in ein nicht-leeres Git-Repo schreiben, ohne vorher zu warnen. Ein
+  Repo mit einer `.git/`, aber ohne `CLAUDE.md` und ohne `docs/` ist in Ordnung
+  — das heißt der Nutzer hat bereits `git init` gemacht, das ist der Normalfall.
+- **Nie** `git commit` selbstständig ausführen. Der Nutzer entscheidet, was
+  committet wird.
+
+## Tonfall in den erzeugten Templates
+
+- Prosa auf Deutsch, kurz, konkret.
+- Code, Pfade, Kommandos auf Englisch.
+- Platzhalter-Abschnitte sind mit `TBD` oder einem sichtbaren HTML-Kommentar
+  `<!-- TODO: ... -->` markiert, damit der Nutzer sofort sieht, was noch gefüllt
+  werden muss.
+
+## Templates
+
+Siehe `./templates/` im Skill-Ordner:
+
+- `CLAUDE.md.tmpl`
+- `00-overview.md.tmpl`
+- `10-plan.md.tmpl`
+- `20-architecture.md.tmpl`
+- `90-status.md.tmpl`
+- `30-decisions.README.md.tmpl`
+- `40-workflows.README.md.tmpl`
+- `sessions.README.md.tmpl`
@@ -0,0 +1,49 @@
+# 00 — Overview
+
+**Projekt:** {{PROJECT_NAME}}
+**Angelegt:** {{TODAY_ISO}}
+
+## Zweck in einem Satz
+
+{{PROJECT_PURPOSE}}
+
+## Warum überhaupt
+
+<!-- TODO: In 3–6 Sätzen die Motivation. Welches Problem löst das Projekt?
+     Für wen? Was war der Auslöser? Dieses Feld altert am schnellsten — trotzdem
+     wichtig, weil es Monate später erklärt, warum das Ding existiert. -->
+
+## Ziele
+
+<!-- TODO: 3–5 konkrete, prüfbare Ziele. Nicht „schneller sein", sondern
+     „Antwortzeit < 200 ms bei p95". -->
+
+- TBD
+- TBD
+- TBD
+
+## Nicht-Ziele
+
+<!-- TODO: Explizit festhalten, was das Projekt NICHT sein will. Spart später
+     viele Diskussionen. Beispiel: „Kein Multi-Tenant", „Keine Mobile-App",
+     „Keine Echtzeitfähigkeit im ersten Release". -->
+
+- TBD
+- TBD
+
+## Stakeholder / Betroffene
+
+<!-- TODO: Wer nutzt das? Wer zahlt? Wer operiert es? Wer wird wach, wenn es
+     bricht? -->
+
+- Nutzer: TBD
+- Betrieb: TBD
+- Auftraggeber: TBD
+
+## Erfolgskriterien
+
+<!-- TODO: Woran messen wir „fertig" und „gut"? Idealerweise eine Kombination
+     aus quantitativen Kennzahlen und qualitativen Aussagen („Kristian kann
+     ohne Nachfrage deployen"). -->
+
+- TBD
@@ -0,0 +1,40 @@
+# 10 — Plan
+
+**Letzte Aktualisierung:** {{TODAY_ISO}}
+
+Der Plan ist ein **lebendes Dokument**. Er darf sich ändern — jede nicht-
+triviale Änderung sollte ein kurzer Eintrag in `docs/sessions/` erklären,
+grobe Kursänderungen einen eigenen ADR in `docs/30-decisions/` bekommen.
+
+## Phasen-Übersicht
+
+| Phase | Status | Ziel | Zeitfenster |
+|---|---|---|---|
+| 1 — Konzept & Planung | in progress | Overview, Plan, erste Architektur-Skizze | {{TODAY_ISO}} – TBD |
+| 2 — Build / Prototype | pending | TBD | TBD |
+| 3 — Härtung / Launch | pending | TBD | TBD |
+| 4 — Betrieb / Wartung | pending | laufend | — |
+
+## Aktueller Fokus
+
+<!-- TODO: Der eine oder zwei Punkte, an denen jetzt konkret gearbeitet wird.
+     Nicht die große Vision — der nächste Schritt. -->
+
+- TBD
+
+## Milestones
+
+<!-- TODO: 3–7 grobe Marker, nicht mehr. Jeder Milestone sollte demonstrier-
+     bar sein: „X funktioniert, Y ist dokumentiert". -->
+
+- [ ] M1 — TBD
+- [ ] M2 — TBD
+- [ ] M3 — TBD
+
+## Offene Fragen / Risiken
+
+<!-- TODO: Was ist noch unklar? Wo liegt das größte Risiko? Explizit festhalten
+     — das sind die Dinge, die sonst beim nächsten Wiedereinstieg vergessen
+     werden. -->
+
+- TBD
@@ -0,0 +1,55 @@
+# 20 — Architecture
+
+**Letzte Aktualisierung:** {{TODAY_ISO}}
+
+Diese Datei ist **kein Ort für detaillierte Begründungen** — die leben in
+`docs/30-decisions/` als ADRs. Hier steht die kompakte Architektur-Sicht, so
+wie sie aktuell gilt. Wenn du hier etwas änderst, schreibst du idealerweise
+einen ADR, der erklärt warum.
+
+## Stack
+
+**Kurz:** {{PROJECT_STACK}}
+
+<!-- TODO: Aufdröseln nach Schicht. Beispiel:
+     - Runtime: Python 3.12, uv
+     - Web-Framework: FastAPI
+     - Persistenz: PocketBase (SQLite-basiert)
+     - Reverse-Proxy: Caddy
+     - Deployment: systemd-Unit auf NixOS
+-->
+
+- Runtime: TBD
+- Framework: TBD
+- Persistenz: TBD
+- Infrastruktur: TBD
+
+## Komponenten
+
+<!-- TODO: Kurze Liste der Hauptkomponenten mit je 1–2 Sätzen Zweck. Ein
+     simples ASCII-Diagramm oder Mermaid-Block ist oft Gold wert. -->
+
+```
+<!-- TODO: Komponenten-Skizze -->
+```
+
+## Datenfluss
+
+<!-- TODO: Wie fließen Daten durch das System? Eingänge, Transformationen,
+     Ausgänge, Persistenzpunkte. Ein Absatz reicht am Anfang. -->
+
+TBD
+
+## Externe Abhängigkeiten
+
+<!-- TODO: APIs, SaaS, Hardware, die wir nicht selbst betreiben. Jede Zeile:
+     Name, Zweck, was passiert, wenn sie ausfällt. -->
+
+- TBD
+
+## Laufende ADRs
+
+<!-- Dieser Abschnitt wird durch den `adr`-Skill gepflegt: er ergänzt die Liste
+     unten beim Anlegen eines neuen ADR. -->
+
+_(Noch keine ADRs. `adr <titel>` ausführen, um einen anzulegen.)_
@@ -0,0 +1,32 @@
+# 30 — Decisions (ADRs)
+
+Hier leben **Architecture Decision Records** — je eine Markdown-Datei pro
+Entscheidung, nummeriert. Neue ADRs werden mit dem `adr`-Skill angelegt, der
+automatisch hochzählt und das Template anwendet.
+
+## Regeln
+
+- **Append-only.** Eine einmal getroffene Entscheidung wird nicht rückwirkend
+  umgeschrieben. Stattdessen wird sie durch einen neuen ADR ersetzt, der
+  `Supersedes: <nummer>` im Header trägt. Der alte ADR bekommt dann den Status
+  `superseded by <neue-nummer>`.
+- **Ein ADR pro Entscheidung.** Nicht „ADR für Q2" oder „ADR für Auth-Stack
+  insgesamt", sondern „ADR für: PocketBase statt Supabase".
+- **Begründung vor Details.** Der „Warum"-Teil ist der wertvolle. Wenn du in
+  sechs Monaten auf den ADR zurückkommst, willst du nicht die Spec lesen,
+  sondern verstehen, warum diese Wahl damals sinnvoll erschien.
+
+## Namensschema
+
+```
+NNNN-kurzer-slug.md
+```
+
+Beispiel: `0001-pocketbase-statt-supabase.md`, `0002-caddy-als-reverse-proxy.md`.
+
+## Status-Werte
+
+- `proposed` — wird diskutiert, aber noch nicht gelebt.
+- `accepted` — gilt, Code / Betrieb folgt dem.
+- `superseded by NNNN` — überholt durch einen neueren ADR.
+- `deprecated` — gilt nicht mehr, aber es gibt (noch) keinen Nachfolger.
@@ -0,0 +1,41 @@
+# 40 — Workflows
+
+Operative Prozeduren: Deploy, Backup, Restore, Debug-Playbooks, Incident-
+Response. Jede Datei beschreibt **eine Prozedur**, die man zur Not um 3 Uhr
+morgens halbwach abarbeiten kann.
+
+## Was hier hineingehört
+
+- `deploy.md` — wie wird released?
+- `backup.md` — was wird gesichert, wohin, wie oft, wie restoren?
+- `debug-<thema>.md` — strukturierte Playbooks für wiederkehrende Debug-Situa-
+  tionen (z. B. „Mail kommt nicht raus", „DB antwortet langsam").
+- `incident-response.md` — erste Schritte bei Ausfall.
+
+## Format
+
+Jede Datei folgt einem einfachen Schema:
+
+```markdown
+# <Titel>
+
+**Wann anwenden:** <konkreter Auslöser>
+**Voraussetzungen:** <was muss verfügbar / installiert sein>
+
+## Ablauf
+
+1. Schritt
+2. Schritt
+3. Schritt
+
+## Verifikation
+
+Wie erkenne ich, dass der Prozess erfolgreich war?
+
+## Wenn es schiefgeht
+
+Fallback, Rollback, wen ansprechen.
+```
+
+Keine Poesie. Kopierbare Kommandos und harte Fakten — Workflows sind für den
+schlechten Tag geschrieben, nicht für den guten.
@@ -0,0 +1,37 @@
+# 90 — Status
+
+> **Single Source of Truth** für „wo stehen wir gerade?".
+> Wird durch den `handoff`-Skill am Sessionende aktualisiert.
+> Manuelle Edits sind erlaubt, aber bitte den Zeitstempel oben anpassen.
+
+**Letzte Aktualisierung:** {{TODAY_ISO}} (via `plan-start`)
+**Aktuelle Phase:** {{PROJECT_PHASE}}
+
+---
+
+## Aktueller Stand
+
+<!-- 2–5 Sätze: was funktioniert, was ist der Status des aktuellen Fokus? -->
+
+Projekt gerade initialisiert. Grundstruktur steht, inhaltliche Ausarbeitung
+von `docs/00-overview.md` und `docs/10-plan.md` ist der nächste Schritt.
+
+## Nächste Schritte (priorisiert)
+
+<!-- 3–5 konkrete, kleine Schritte. Keine Jahresziele. -->
+
+1. `docs/00-overview.md` ausfüllen — Zweck, Ziele, Nicht-Ziele konkretisieren.
+2. `docs/10-plan.md` ausfüllen — Phasen und Milestones grob setzen.
+3. Erste Architektur-Entscheidungen als ADRs festhalten (`adr <titel>`).
+
+## Offene Entscheidungen / Blocker
+
+<!-- Was wartet auf einen Entschluss? Was blockiert den Fortschritt? -->
+
+_Keine offenen Blocker. Noch keine Entscheidungen getroffen._
+
+## Zuletzt geändert durch
+
+<!-- handoff trägt hier Session-Slug und Datum ein. -->
+
+`plan-start` am {{TODAY_ISO}}
@@ -0,0 +1,45 @@
+# {{PROJECT_NAME}}
+
+{{PROJECT_PURPOSE}}
+
+**Aktuelle Phase:** {{PROJECT_PHASE}}
+**Stack (grob):** {{PROJECT_STACK}}
+
+---
+
+## Wegweiser für Claude Code
+
+Der Projektstatus lebt in `docs/`, **nicht** in dieser Datei. Diese `CLAUDE.md`
+ist bewusst kurz und dient nur der Navigation.
+
+**Bevor du arbeitest, lies in dieser Reihenfolge:**
+
+1. `docs/90-status.md` — wo wir gerade stehen. Single Source of Truth.
+2. `docs/10-plan.md` — aktueller Plan, Phasen, offene Milestones.
+3. Den neuesten Eintrag in `docs/sessions/` — was in der letzten Session
+   passiert ist und was als Nächstes dran war.
+4. Bei Architektur-Fragen: die relevanten ADRs in `docs/30-decisions/`.
+
+## Workflow-Skills (global installiert)
+
+- `status` — Wiedereinstieg nach Pause: liest 90-status + letztes Session-Log.
+- `handoff` — am Sessionende: Session-Log schreiben, Status aktualisieren.
+- `adr <titel>` — neue Architektur-Entscheidung festhalten.
+- `plan-start` — wurde bereits ausgeführt, um dieses Projekt zu scaffolden.
+
+## Wichtigste Konventionen
+
+- **Prosa auf Deutsch, Code / Kommandos auf Englisch.**
+- **ADRs sind append-only.** Ersetzt werden sie durch neue ADRs mit
+  `Supersedes: <nummer>`, nicht durch Umschreiben der alten.
+- **`docs/90-status.md` ist die einzige Datei, die den aktuellen Stand
+  beschreibt.** Wenn es widersprüchliche Angaben gibt, gewinnt 90-status.
+- **Session-Logs sind verpflichtend.** Wer `handoff` überspringt, hat nach drei
+  Sessions wieder keinen Überblick — nur mit mehr Dateien drumherum.
+
+<!-- TODO: Die drei bis fünf wichtigsten projektspezifischen Kommandos hier
+     ergänzen, sobald der Stack steht. Beispiele:
+     - `make dev` — lokale Entwicklung starten
+     - `pytest -x` — Tests bis zum ersten Fehler
+     - `docker compose up` — Infrastruktur lokal hochfahren
+-->
@@ -0,0 +1,28 @@
+# Sessions
+
+Chronologische Session-Logs. Je Session eine Datei, Format:
+
+```
+YYYY-MM-DD-<kurzer-slug>.md
+```
+
+Beispiel: `2026-04-17-mail-unbound-fix.md`.
+
+Werden vom `handoff`-Skill am Sessionende geschrieben. Manuelles Editieren ist
+erlaubt — wer hier schreibt, trägt die aktuelle Wahrheit über das, was passiert
+ist.
+
+## Was in einen Session-Log gehört
+
+- **Was wurde gemacht?** Faktisch, knapp, mit Dateipfaden wo relevant.
+- **Was ist offen?** Was wurde angefangen und nicht beendet?
+- **Nächste Schritte.** 1–3 konkrete Punkte für die nächste Session.
+- **Überraschungen / Erkenntnisse.** Was hat nicht so funktioniert, wie erwartet?
+
+## Was NICHT hineingehört
+
+- Vollständige Code-Listings. Dafür gibt's den Commit.
+- Begründungen für Architektur-Entscheidungen. Dafür gibt's ADRs.
+- Aktueller Gesamtstand. Dafür gibt's `docs/90-status.md`.
+
+Session-Logs sind **Protokoll**, nicht **Referenz**.