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,15 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS / tooling
+Thumbs.db
+.Trash-*
@@ -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 | `<projekt>/CLAUDE.md` | nur dieses Projekt |
+| Projekt-Doku | wird von `plan-start` erzeugt | `<projekt>/docs/` | nur dieses Projekt |
+| Projektspezifische Skills (optional) | — (im Projekt anlegen) | `<projekt>/.claude/skills/` | nur dieses Projekt |
+
+Die Trennung ist bewusst: alles unter `~/.claude/skills/` ist **Verb** (Prozess,
+überall gleich), alles unter `<projekt>/` 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
+
+```
+<projekt>/
+├── 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-<slug>.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:
+
+```
+<projekt>/.claude/skills/<skill-name>/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.
@@ -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`.
@@ -0,0 +1,59 @@
+# ADR {{ADR_NUMBER}} — {{ADR_TITLE}}
+
+**Status:** proposed
+**Datum:** {{ADR_DATE}}
+**Autor:** {{ADR_AUTHOR}}
+<!-- Bei Ablösung eines früheren ADR: Supersedes: NNNN -->
+
+## Context
+
+<!-- Die Ausgangslage. Welches Problem / welche Anforderung stellt sich?
+     Welche Randbedingungen (Budget, Zeit, Team-Know-how, Betriebs-Kontext)
+     schränken die Wahl ein? Dieser Abschnitt soll in einem Jahr noch
+     verständlich sein, ohne dass jemand den Projekt-Kontext präsent hat. -->
+
+TBD
+
+## Decision
+
+<!-- Was wurde entschieden? In einem klaren Satz. Danach ggf. 2–5 Sätze zur
+     Konkretisierung (Version, Variante, Konfiguration). -->
+
+TBD
+
+## Consequences
+
+<!-- Was folgt aus der Entscheidung?
+     - Positiv: was wird dadurch einfacher / möglich?
+     - Negativ: welche Kosten / Einschränkungen / Risiken erkauft man sich?
+     - Neutral / strukturell: was ändert sich im Ablauf, auch wenn's weder
+       gut noch schlecht ist?
+-->
+
+### Positiv
+
+- TBD
+
+### Negativ
+
+- TBD
+
+### Neutral / strukturell
+
+- TBD
+
+## Alternatives considered
+
+<!-- Die Hauptalternativen, die erwogen wurden, jeweils mit einem Satz warum
+     sie NICHT gewählt wurden. Das ist der Teil, der in zwei Jahren am
+     wertvollsten ist: „Wir haben X bewusst verworfen, weil …". -->
+
+- **Alternative A:** TBD — verworfen, weil TBD.
+- **Alternative B:** TBD — verworfen, weil TBD.
+
+## Rückfallplan
+
+<!-- Falls diese Entscheidung sich später als falsch erweist: wie kommt man
+     raus? Wie hoch ist der Umstellungsaufwand grob? -->
+
+TBD
@@ -0,0 +1,120 @@
+---
+name: handoff
+description: Schreibt am Ende einer Arbeitssession einen Session-Log nach docs/sessions/YYYY-MM-DD-<slug>.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: "<optional: kurzer slug für den log-dateinamen>"
+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 <titel>` 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-<slug>.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 — <slug> am <datum>` 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`.
@@ -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
+
+<!-- Optional: unerwartete Erkenntnisse, Sackgassen, Dinge, die später noch
+     mal aufschlagen könnten. Wenn nichts — Abschnitt weglassen. -->
@@ -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**.
@@ -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 (<Dateiname ohne Extension>):
+   <1–2 Sätze, was passiert ist und was offen blieb>
+
+   Offene Blocker / Entscheidungen:
+   <aus 90-status.md — wenn keine, dann "keine">
+
+   Empfehlung für heute:
+   <eine einzige konkrete nächste Aktion>
+   ```
+
+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.