From 20a0ab38f215a966bda9eabd84d5ac4afdee1f0f Mon Sep 17 00:00:00 2001 From: Kristian Date: Fri, 17 Apr 2026 07:28:49 +0200 Subject: [PATCH] initial: claude code workflow bundle (plan-start, status, handoff, adr) --- .gitignore | 15 ++ README.md | 173 ++++++++++++++++++ global-skills/adr/SKILL.md | 98 ++++++++++ global-skills/adr/templates/adr.md.tmpl | 59 ++++++ global-skills/handoff/SKILL.md | 120 ++++++++++++ .../handoff/templates/session-log.md.tmpl | 21 +++ global-skills/plan-start/SKILL.md | 97 ++++++++++ .../plan-start/templates/00-overview.md.tmpl | 49 +++++ .../plan-start/templates/10-plan.md.tmpl | 40 ++++ .../templates/20-architecture.md.tmpl | 55 ++++++ .../templates/30-decisions.README.md.tmpl | 32 ++++ .../templates/40-workflows.README.md.tmpl | 41 +++++ .../plan-start/templates/90-status.md.tmpl | 37 ++++ .../plan-start/templates/CLAUDE.md.tmpl | 45 +++++ .../templates/sessions.README.md.tmpl | 28 +++ global-skills/status/SKILL.md | 68 +++++++ 16 files changed, 978 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 global-skills/adr/SKILL.md create mode 100644 global-skills/adr/templates/adr.md.tmpl create mode 100644 global-skills/handoff/SKILL.md create mode 100644 global-skills/handoff/templates/session-log.md.tmpl create mode 100644 global-skills/plan-start/SKILL.md create mode 100644 global-skills/plan-start/templates/00-overview.md.tmpl create mode 100644 global-skills/plan-start/templates/10-plan.md.tmpl create mode 100644 global-skills/plan-start/templates/20-architecture.md.tmpl create mode 100644 global-skills/plan-start/templates/30-decisions.README.md.tmpl create mode 100644 global-skills/plan-start/templates/40-workflows.README.md.tmpl create mode 100644 global-skills/plan-start/templates/90-status.md.tmpl create mode 100644 global-skills/plan-start/templates/CLAUDE.md.tmpl create mode 100644 global-skills/plan-start/templates/sessions.README.md.tmpl create mode 100644 global-skills/status/SKILL.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..157e785 --- /dev/null +++ b/.gitignore @@ -0,0 +1,15 @@ +# macOS +.DS_Store +.AppleDouble +.LSOverride + +# Editor / IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS / tooling +Thumbs.db +.Trash-* diff --git a/README.md b/README.md new file mode 100644 index 0000000..3199582 --- /dev/null +++ b/README.md @@ -0,0 +1,173 @@ +# Claude Code Workflow — Universal Bundle + +Ein minimaler Satz von vier Skills plus Templates für einen nachvollziehbaren +Planungs-, Bau- und Übergabe-Workflow in Claude Code. Ziel: Projektstatus lebt +auf der Platte (in `docs/`), nicht im Sitzungskontext — und die Skills sorgen +dafür, dass diese Dateien konsistent wachsen statt chaotisch. + +Dieses Bundle ist **rechnerübergreifend portabel**: du klonst / kopierst diesen +Ordner auf jede neue Maschine und installierst den globalen Teil mit einem +einzigen Kopier- bzw. Symlink-Schritt. + +--- + +## Speicherorte auf einen Blick + +Die Skills teilen sich in zwei Ebenen. Wichtig: in diesem Bundle liegt aktuell +**nur der globale Teil**. Projektspezifische Skills entstehen pro Projekt direkt +im jeweiligen Repo (siehe unten) und gehören nicht hierher, weil sie projekt- +spezifischen Kontext tragen. + +| Was | Quelle in diesem Bundle | Ziel auf deinem Rechner | Scope | +|---|---|---|---| +| Globale Skills (plan-start, status, handoff, adr) | `global-skills/` | `~/.claude/skills/` | maschinenweit, alle Projekte | +| Projekt-Wegweiser | wird von `plan-start` erzeugt | `/CLAUDE.md` | nur dieses Projekt | +| Projekt-Doku | wird von `plan-start` erzeugt | `/docs/` | nur dieses Projekt | +| Projektspezifische Skills (optional) | — (im Projekt anlegen) | `/.claude/skills/` | nur dieses Projekt | + +Die Trennung ist bewusst: alles unter `~/.claude/skills/` ist **Verb** (Prozess, +überall gleich), alles unter `/` ist **Kontext** (Inhalt, projekt- +spezifisch). Skills im Projekt-Repo werden mitcommittet und sind Teil der +Dokumentation. + +--- + +## Installation (pro Rechner, einmalig) + +### Option A — symlinken (empfohlen) + +Wenn du dieses Bundle per Git versionierst und auf mehreren Rechnern spiegelst, +sind Symlinks der saubere Weg. Änderungen werden zentral gepflegt, jeder +Rechner zieht nach `git pull` automatisch mit. + +```bash +# einmalig anlegen +mkdir -p ~/.claude/skills + +# für jeden Skill einen Symlink — Pfad auf dein geklontes Bundle anpassen +ln -s "$PWD/global-skills/plan-start" ~/.claude/skills/plan-start +ln -s "$PWD/global-skills/status" ~/.claude/skills/status +ln -s "$PWD/global-skills/handoff" ~/.claude/skills/handoff +ln -s "$PWD/global-skills/adr" ~/.claude/skills/adr +``` + +### Option B — kopieren + +Wenn du lieber unabhängige Kopien willst (z. B. weil du pro Rechner abweichend +tunen möchtest): + +```bash +mkdir -p ~/.claude/skills +cp -r global-skills/plan-start ~/.claude/skills/ +cp -r global-skills/status ~/.claude/skills/ +cp -r global-skills/handoff ~/.claude/skills/ +cp -r global-skills/adr ~/.claude/skills/ +``` + +### Prüfen + +Nach Install sollte in Claude Code die Skill-Liste die vier Namen enthalten. +Grobe Kontrolle auf der Shell: + +```bash +ls ~/.claude/skills/ +# plan-start status handoff adr +``` + +--- + +## Die vier Skills im Überblick + +| Skill | Phase | Was er tut | +|---|---|---| +| `plan-start` | Projektstart | Legt `CLAUDE.md`, `docs/`-Struktur und erste Dateien nach Template an. Einmal pro Projekt. | +| `status` | Wiedereinstieg | Liest `docs/90-status.md` + letztes Session-Log, fasst in 5–10 Zeilen zusammen. Dein „Wo stehen wir?"-Befehl. | +| `handoff` | Sessionende | Fragt drei kurze Reflexionsfragen, schreibt Session-Log nach `docs/sessions/`, aktualisiert `docs/90-status.md`. | +| `adr` | nach Architektur-Entscheidung | Legt nummerierten ADR nach `docs/30-decisions/` an. Kontext, Entscheidung, Konsequenzen, Alternativen. | + +Nicht dabei (bewusst): `/debug-log` und `/concept-lock`. Die baust du nach zwei, +drei Wochen Praxis — dann weißt du, wie sie konkret aussehen müssen. Alles +andere wäre hypothetisch. + +--- + +## Was `plan-start` im Projekt erzeugt + +``` +/ +├── CLAUDE.md # Wegweiser, verweist auf docs/90-status.md +├── .claude/ +│ └── skills/ # leer — hier landen später projektspezifische Skills +└── docs/ + ├── 00-overview.md # Zweck, Ziele, Nicht-Ziele + ├── 10-plan.md # Phasen, Milestones, aktueller Fokus + ├── 20-architecture.md # Stack, Entscheidungen in Kurzform + ├── 30-decisions/ # ADRs, einer pro Datei, nummeriert + ├── 40-workflows/ # Deploy-, Backup-, Debug-Prozeduren + ├── 90-status.md # Single Source of Truth: aktueller Stand + └── sessions/ # Session-Logs chronologisch, YYYY-MM-DD-.md +``` + +Die Nummerierung ist kein Selbstzweck — sie sortiert alphabetisch in der +Lese-Reihenfolge, in der eine frische Claude-Code-Instanz die Dateien beim +Scannen wahrnimmt, und gibt dir visuelle Hierarchie im Editor. +`90-status.md` steht bewusst ganz unten: die eine Datei, die du immer +aktualisierst und die jede neue Session zuerst liest. + +--- + +## Projektspezifische Skills (optional, pro Repo) + +Wenn du in einem konkreten Projekt merkst, dass du immer wieder denselben +projektspezifischen Handgriff ausführst (z. B. „Deploy-Pipeline prüfen", +„Testdaten regenerieren"), lege ihn als Skill in diesem Repo an: + +``` +/.claude/skills//SKILL.md +``` + +Commit mit. Damit ist der Skill Teil der Projekt-Doku — und andere Rechner / +Mitwirkende haben ihn automatisch. + +--- + +## Konventionen, die das Ganze tragen + +- **Sprache**: Prosa auf Deutsch, Code / Pfade / Kommandos / Skill-Namen auf + Englisch. Das gilt in allen Templates und Skills konsistent. +- **Single Source of Truth**: `docs/90-status.md`. Kein anderer Ort beschreibt + „wo wir gerade stehen". +- **ADRs sind append-only**: einmal geschrieben, nur noch durch neue ADRs + ersetzt (`Supersedes: 0003`). Nie rückwirkend umschreiben — das killt die + Nachvollziehbarkeit. +- **Session-Logs sind verpflichtend**: `handoff` am Ende jeder relevanten + Session. Wer das überspringt, hat nach drei Sessions wieder das alte Problem + — nur mit mehr Dateien drumherum. +- **CLAUDE.md bleibt schlank** (~50–80 Zeilen): Navigation, nicht Enzyklopädie. + Sie verweist auf `docs/`, sie enthält keine Inhalte, die dort hingehören. + +--- + +## Erste Schritte in einem neuen Projekt + +```bash +cd ~/projekte/mein-neues-ding +# in Claude Code: +# skill: plan-start "Kurzbeschreibung der Idee" +``` + +`plan-start` fragt ein paar Basics ab (Name, Zweck, Stack-Hinweise), +generiert die Ordnerstruktur und schreibt eine erste `CLAUDE.md` sowie +`docs/00-overview.md`, `docs/10-plan.md` und `docs/90-status.md`. + +Am Ende der Session: `skill: handoff`. +Beim nächsten Einstieg: `skill: status`. + +Das ist der komplette Kreislauf. + +--- + +## Lizenz / Umgang + +Internes Tooling, keine formelle Lizenz. Passe die Templates an deinen Stil +an — sie sind als Ausgangspunkt gedacht, nicht als Dogma. diff --git a/global-skills/adr/SKILL.md b/global-skills/adr/SKILL.md new file mode 100644 index 0000000..32db330 --- /dev/null +++ b/global-skills/adr/SKILL.md @@ -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: "" +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/-.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`. diff --git a/global-skills/adr/templates/adr.md.tmpl b/global-skills/adr/templates/adr.md.tmpl new file mode 100644 index 0000000..5840f8a --- /dev/null +++ b/global-skills/adr/templates/adr.md.tmpl @@ -0,0 +1,59 @@ +# ADR {{ADR_NUMBER}} — {{ADR_TITLE}} + +**Status:** proposed +**Datum:** {{ADR_DATE}} +**Autor:** {{ADR_AUTHOR}} + + +## Context + + + +TBD + +## Decision + + + +TBD + +## Consequences + + + +### Positiv + +- TBD + +### Negativ + +- TBD + +### Neutral / strukturell + +- TBD + +## Alternatives considered + + + +- **Alternative A:** TBD — verworfen, weil TBD. +- **Alternative B:** TBD — verworfen, weil TBD. + +## Rückfallplan + + + +TBD diff --git a/global-skills/handoff/SKILL.md b/global-skills/handoff/SKILL.md new file mode 100644 index 0000000..4a74ab4 --- /dev/null +++ b/global-skills/handoff/SKILL.md @@ -0,0 +1,120 @@ +--- +name: handoff +description: Schreibt am Ende einer Arbeitssession einen Session-Log nach docs/sessions/YYYY-MM-DD-.md und aktualisiert docs/90-status.md. Erzwingt eine kurze Reflexion des Nutzers (drei Fragen), bevor geschrieben wird — bewusst NICHT autonom aus dem Sitzungskontext ableiten. +disable-model-invocation: true +argument-hint: "" +allowed-tools: + - Read + - Write + - Edit + - Bash +--- + +# handoff — Sessionende + +## Warum es diesen Skill überhaupt gibt + +Die Disziplin des ganzen Workflows liegt nicht in den anderen Skills, sondern +in diesem hier. Wer `handoff` am Sessionende überspringt, hat nach drei +Sessions wieder das alte Problem: Kontext verdunstet, „wo war ich stehen- +geblieben?" ist Rateraten. + +Und: `handoff` fragt **explizit nach**, statt autonom zusammenzufassen. Das ist +gegen die LLM-Intuition („kann ich doch selbst"), aber genau der Punkt. +Automatisch generierte Session-Logs sind nach drei Wochen formal korrekt und +inhaltlich beliebig. Die fünf Sekunden Reflexion pro Session sind die +Investition, die das System überhaupt tragbar macht. + +## Wann der Skill läuft + +Auf expliziten Aufruf am Ende einer Session. Vorher prüfen: existiert +`docs/90-status.md`? Wenn nicht → melden „Kein initialisiertes Projekt", abbrechen. + +## Was der Skill tut + +### Schritt 1 — Drei Fragen an den Nutzer + +Nacheinander, nicht als Liste. Auf jede Antwort kurz warten, nicht selbst +vorschlagen. Die Fragen sind bewusst stumpf und weit, damit der Nutzer +reflektiert: + +1. **„Was hast du in dieser Session konkret erledigt?"** + (Faktisch. Nicht „wir haben über X gesprochen", sondern „Datei Y angelegt, + Test Z bestanden, Entscheidung A getroffen".) + +2. **„Was hast du angefangen und nicht beendet?"** + (Die Dinge, die sonst vergessen werden. Halbe Edits, offene Branches, + angetestete Hypothesen ohne Ergebnis.) + +3. **„Was sind die nächsten 1–3 konkreten Schritte, wenn du das Projekt + wieder aufnimmst?"** + (Klein, prüfbar. Nicht „Feature X bauen", sondern „Funktion `parse_header` + um Content-Type erweitern, dann Test dafür schreiben".) + +Zusätzlich darf der Skill **nur wenn nötig** nachfragen: + +- Gab es eine größere Entscheidung, die einen ADR verdient? (Falls ja: den + Nutzer an `adr ` erinnern — **nicht** selbst anlegen.) +- Ist der aktuelle Fokus in `docs/10-plan.md` noch korrekt? (Wenn nein: Notiz + machen, dass der Nutzer das beim nächsten Mal anpassen sollte. Nicht selbst + editieren.) + +### Schritt 2 — Slug und Dateiname bauen + +- Datum: `date +%F` → `YYYY-MM-DD`. +- Slug: aus `$ARGUMENTS`, sonst aus der Antwort auf Frage 1 automatisch + ableiten (2–4 Wörter, lowercase, Bindestriche, keine Sonderzeichen). +- Dateiname: `docs/sessions/YYYY-MM-DD-.md`. +- Kollision vermeiden: wenn die Datei existiert, suffix `-2`, `-3`, … anhängen. + +### Schritt 3 — Session-Log schreiben + +Nach dem Template `templates/session-log.md.tmpl` (liegt im Skill-Ordner). +Platzhalter füllen: + +| Platzhalter | Quelle | +|---|---| +| `{{SESSION_DATE}}` | aktuelles Datum `YYYY-MM-DD` | +| `{{SESSION_SLUG}}` | der Slug von oben | +| `{{WHAT_DONE}}` | Antwort auf Frage 1, als Bulletpoints | +| `{{WHAT_OPEN}}` | Antwort auf Frage 2, als Bulletpoints | +| `{{NEXT_STEPS}}` | Antwort auf Frage 3, als nummerierte Liste | +| `{{DURATION}}` | optional, wenn der Nutzer ihn nennt, sonst weglassen | + +### Schritt 4 — `docs/90-status.md` aktualisieren + +Keine komplette Neuschreibung. Gezielt: + +- Zeitstempel „Letzte Aktualisierung" auf heute setzen. +- Abschnitt **„Aktueller Stand"** ersetzen durch eine Destillation aus Frage 1 + + Frage 2 (2–4 Sätze). +- Abschnitt **„Nächste Schritte"** ersetzen durch die Antwort auf Frage 3. +- Abschnitt **„Offene Entscheidungen / Blocker"**: nur anfassen, wenn der + Nutzer im Gespräch explizit eine Entscheidung oder einen Blocker erwähnt + hat. Sonst unverändert lassen. +- Abschnitt **„Zuletzt geändert durch"**: auf + `handoff — am ` setzen. + +### Schritt 5 — Kurze Bestätigung + +Dem Nutzer in 2–3 Zeilen zurückmelden: welche Datei wurde geschrieben, was +wurde in `90-status.md` aktualisiert. Keine Zusammenfassung der Zusammenfassung +— der Nutzer weiß, was er gerade gesagt hat. + +Optional, wenn relevant: Hinweis auf einen anzulegenden ADR, falls in Schritt 1 +eine Architektur-Entscheidung genannt wurde. + +## Harte Regeln + +- **Nicht automatisch zusammenfassen** ohne die drei Fragen zu stellen. Auch + dann nicht, wenn der Sitzungsverlauf scheinbar alles klar macht. Die Fragen + sind Pflicht. +- **Nichts in `30-decisions/` schreiben.** Dafür gibt's `adr`. Der Nutzer wird + daran erinnert, aber er entscheidet. +- **Nie `git commit`.** Der Nutzer entscheidet, ob und wann. +- **Niemals einen bestehenden Session-Log überschreiben.** Bei Kollision + Suffix anhängen. + +## Template + +Siehe `./templates/session-log.md.tmpl`. diff --git a/global-skills/handoff/templates/session-log.md.tmpl b/global-skills/handoff/templates/session-log.md.tmpl new file mode 100644 index 0000000..5a7eb1d --- /dev/null +++ b/global-skills/handoff/templates/session-log.md.tmpl @@ -0,0 +1,21 @@ +# Session {{SESSION_DATE}} — {{SESSION_SLUG}} + +**Datum:** {{SESSION_DATE}} +**Dauer:** {{DURATION}} + +## Was wurde erledigt + +{{WHAT_DONE}} + +## Was ist offen / angefangen + +{{WHAT_OPEN}} + +## Nächste Schritte + +{{NEXT_STEPS}} + +## Notizen / Überraschungen + + diff --git a/global-skills/plan-start/SKILL.md b/global-skills/plan-start/SKILL.md new file mode 100644 index 0000000..08e8a68 --- /dev/null +++ b/global-skills/plan-start/SKILL.md @@ -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: "" +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 + `` 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` diff --git a/global-skills/plan-start/templates/00-overview.md.tmpl b/global-skills/plan-start/templates/00-overview.md.tmpl new file mode 100644 index 0000000..0fa929a --- /dev/null +++ b/global-skills/plan-start/templates/00-overview.md.tmpl @@ -0,0 +1,49 @@ +# 00 — Overview + +**Projekt:** {{PROJECT_NAME}} +**Angelegt:** {{TODAY_ISO}} + +## Zweck in einem Satz + +{{PROJECT_PURPOSE}} + +## Warum überhaupt + + + +## Ziele + + + +- TBD +- TBD +- TBD + +## Nicht-Ziele + + + +- TBD +- TBD + +## Stakeholder / Betroffene + + + +- Nutzer: TBD +- Betrieb: TBD +- Auftraggeber: TBD + +## Erfolgskriterien + + + +- TBD diff --git a/global-skills/plan-start/templates/10-plan.md.tmpl b/global-skills/plan-start/templates/10-plan.md.tmpl new file mode 100644 index 0000000..0fc4fa6 --- /dev/null +++ b/global-skills/plan-start/templates/10-plan.md.tmpl @@ -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 + + + +- TBD + +## Milestones + + + +- [ ] M1 — TBD +- [ ] M2 — TBD +- [ ] M3 — TBD + +## Offene Fragen / Risiken + + + +- TBD diff --git a/global-skills/plan-start/templates/20-architecture.md.tmpl b/global-skills/plan-start/templates/20-architecture.md.tmpl new file mode 100644 index 0000000..04f1c37 --- /dev/null +++ b/global-skills/plan-start/templates/20-architecture.md.tmpl @@ -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}} + + + +- Runtime: TBD +- Framework: TBD +- Persistenz: TBD +- Infrastruktur: TBD + +## Komponenten + + + +``` + +``` + +## Datenfluss + + + +TBD + +## Externe Abhängigkeiten + + + +- TBD + +## Laufende ADRs + + + +_(Noch keine ADRs. `adr ` ausführen, um einen anzulegen.)_ diff --git a/global-skills/plan-start/templates/30-decisions.README.md.tmpl b/global-skills/plan-start/templates/30-decisions.README.md.tmpl new file mode 100644 index 0000000..d49bfd3 --- /dev/null +++ b/global-skills/plan-start/templates/30-decisions.README.md.tmpl @@ -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: ` im Header trägt. Der alte ADR bekommt dann den Status + `superseded by `. +- **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. diff --git a/global-skills/plan-start/templates/40-workflows.README.md.tmpl b/global-skills/plan-start/templates/40-workflows.README.md.tmpl new file mode 100644 index 0000000..1f842d7 --- /dev/null +++ b/global-skills/plan-start/templates/40-workflows.README.md.tmpl @@ -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-.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 +# + +**Wann anwenden:** +**Voraussetzungen:** + +## 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. diff --git a/global-skills/plan-start/templates/90-status.md.tmpl b/global-skills/plan-start/templates/90-status.md.tmpl new file mode 100644 index 0000000..875f9f3 --- /dev/null +++ b/global-skills/plan-start/templates/90-status.md.tmpl @@ -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 + + + +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) + + + +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 `). + +## Offene Entscheidungen / Blocker + + + +_Keine offenen Blocker. Noch keine Entscheidungen getroffen._ + +## Zuletzt geändert durch + + + +`plan-start` am {{TODAY_ISO}} diff --git a/global-skills/plan-start/templates/CLAUDE.md.tmpl b/global-skills/plan-start/templates/CLAUDE.md.tmpl new file mode 100644 index 0000000..2cb38c1 --- /dev/null +++ b/global-skills/plan-start/templates/CLAUDE.md.tmpl @@ -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 ` — 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: `, 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. + + diff --git a/global-skills/plan-start/templates/sessions.README.md.tmpl b/global-skills/plan-start/templates/sessions.README.md.tmpl new file mode 100644 index 0000000..117678f --- /dev/null +++ b/global-skills/plan-start/templates/sessions.README.md.tmpl @@ -0,0 +1,28 @@ +# Sessions + +Chronologische Session-Logs. Je Session eine Datei, Format: + +``` +YYYY-MM-DD-.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**. diff --git a/global-skills/status/SKILL.md b/global-skills/status/SKILL.md new file mode 100644 index 0000000..27625bd --- /dev/null +++ b/global-skills/status/SKILL.md @@ -0,0 +1,68 @@ +--- +name: status +description: Fasst den aktuellen Projektstand in 5–10 Zeilen zusammen. Liest docs/90-status.md und den jüngsten Eintrag in docs/sessions/ und destilliert daraus "Wo stehen wir, was ist als Nächstes, was ist offen". Der Wiedereinstiegs-Befehl nach einer Pause. +disable-model-invocation: true +allowed-tools: + - Read + - Bash +--- + +# status — Wiedereinstieg + +## Wann der Skill läuft + +Auf expliziten Aufruf, typischerweise am Anfang einer neuen Session — bevor +Claude oder Nutzer irgendwas anderes tun. Zweck: in unter 30 Sekunden einen +verlässlichen Lagebericht bekommen, ohne `git log` oder Datei-Archäologie. + +## Was der Skill tut + +1. Prüft, ob `docs/90-status.md` existiert. + - Wenn **nein**: meldet „Hier scheint noch keine `plan-start`-Struktur zu + liegen. Entweder ist das kein initialisiertes Projekt, oder du bist im + falschen Ordner." Abbrechen. +2. Liest `docs/90-status.md`. +3. Listet `docs/sessions/*.md` (ohne `README.md`) und öffnet die **chronologisch + jüngste** Datei. Sortierung: die Dateinamen beginnen mit `YYYY-MM-DD`, also + reicht `ls -1 | sort -r | head -n 1`. +4. Liest ggf. `docs/10-plan.md`, aber **nur den Abschnitt „Aktueller Fokus"** — + nicht das ganze Dokument, um den Kontext klein zu halten. +5. Destilliert daraus eine **kompakte Ausgabe** in genau dieser Struktur: + + ``` + 📍 Stand ({{TODAY_ISO}}) + + Wo wir stehen: + <2–3 Sätze, direkt aus 90-status.md abgeleitet> + + Aktueller Fokus: + <1–2 Zeilen aus 10-plan.md / „Aktueller Fokus"> + + Letzte Session (): + <1–2 Sätze, was passiert ist und was offen blieb> + + Offene Blocker / Entscheidungen: + + + Empfehlung für heute: + + ``` + +6. Gibt diese Ausgabe als reinen Text aus. **Keine** weitere Konversation, + keine Rückfragen, kein „Soll ich …?". + +## Harte Regeln + +- **Nicht zusammenfassen, was nicht da ist.** Wenn `90-status.md` veraltet ist + (z. B. letzte Änderung älter als das letzte Session-Log), am Ende der Ausgabe + einen knappen Warnhinweis: „⚠️ 90-status ist älter als das letzte Session-Log + — vermutlich wurde beim letzten Handoff nicht aktualisiert." +- **Nicht kreativ werden.** Keine Interpretation, keine „ich würde empfehlen, + Feature X zu bauen" — der Skill referiert, er plant nicht. +- **Keine Schreib-Operationen.** Dieser Skill liest ausschließlich. + +## Wenn der Nutzer dann weiterarbeiten will + +Nach der Ausgabe ist der Skill fertig. Die nächste Handlung steuert der +Nutzer — typischerweise durch eine konkrete Frage („los, weiter mit Punkt 2 +aus dem Fokus") oder einen anderen Skill-Aufruf.