init-project
Zweck
Bootet das Agenten-Dokumentationssystem eines neuen Projekts aus einem tragbaren Bündel in einem Durchgang. Nach der Initialisierung wartet sich das Projekt selbstständig unter Verwendung der bereitgestellten Standards (Entscheidungsbaum in doc-organization.md §8.3 + tragbare Meta-Standards). init wird einmal pro Projekt ausgeführt; update kann später im selben Projekt erneut ausgeführt werden, um neuere portable Dateien aus dem Bündel zu ziehen (3-Wege-Sichere-Merge – niemals Überschreiben nicht freigegebener lokaler Änderungen). check/promote warten das Bündel selbst und werden nur im Master-Repository ausgeführt.
Abhängigkeiten
./portable/rules/ – 7 portable Regeln (immer geladen + pfadbezogen)./portable/agent-guide/ – five-why.md, markdown.md, mermaid.md, orchestration-policy.md, worktree.md (bereitstellen nach docs/agent-guide/general/)./portable/skills/ – skill-designer/, skill-writer/, document-writer/ (ganze Bäume)./portable/agents/ – skill-writer-auditor.md./templates/ – CLAUDE.md.tpl, agent-guide/index.md.tpl, docs/index.md.tpl./VERSION – Bündelversion, bei jedem Promote erhöhtscripts/update.mjs (Repository-Stamm) – Engine für den update-Modus (3-Wege-Bündel→Live-Merge); scripts/sync-version.mjs – Single-Source-Versionssynchronisation
Modi
| Aufruf | Ausführung in | Aktion |
|---|
/init-project | neues Projekt | Bündel bereitstellen (Workflow unten) |
/init-project check | Master-Repo | sha256-Vergleich Bündel ↔ Live gemäß §map → Abweichung melden |
/init-project promote | Master-Repo | Live → Bündel für jede gemappte Datei kopieren, VERSION erhöhen |
/init-project update | initialisiertes Projekt | Neuere portable Dateien Bündel → Live ziehen, 3-Wege-sicher (Manifest ↔ Live ↔ Bündel); Konflikte überspringen (Workflow unten) |
Workflow (init – neues Projekt)
- Projekt scannen: Stack + optionale Module gemäß Signal-Spalte der
## Modulmatrix erkennen. Ausgabe: vorgeschlagener Modulsatz + ermittelte Slot-Werte.
- Interview: Vorgeschlagenen Modulsatz bestätigen; nicht scannbare Slots abfragen (verwendete Entwickler-Ports, Verantwortungsbereich, Dokusprache). Nicht beantwortbarer Slot → TODO-Marker hinterlassen, niemals einen Wert erfinden; unsicheres Modul → überspringen.
portable/ wörtlich kopieren: portable/rules/* → .claude/rules/; portable/agent-guide/* → docs/agent-guide/general/; portable/skills/* → .claude/skills/; portable/agents/* → .claude/agents/.- Templates rendern:
{{slots}} aus dem Interview in CLAUDE.md, docs/agent-guide/index.md, docs/index.md füllen; fehlender Slot → TODO-Marker belassen.
- Optionale Regeln generieren: Für jedes bestätigte optionale Modul eine projektspezifische Regel in
docs/agent-guide/general/ gemäß rule-writing-standards schreiben und im selben Schritt deren Auslöserzeile an CLAUDE.md anhängen – keine fest codierten Vorlagen.
- Manifest
.claude/init-manifest.json schreiben: { version, deployedAt, files:[{path,sha256}], templates:[{path,sha256}], modules:[...] } (Herkunftsnachweis; files[] wird von update für die 3-Wege-Abweichungserkennung gelesen – sha256 genau halten; templates[] zeichnet den .tpl-sha auf, aus dem jede gerenderte Datei erstellt wurde – path = Vorlagenpfad relativ zu templates/, z.B. CLAUDE.md.tpl, wird von update verwendet, um eine WARNUNG auszugeben, wenn sich eine Vorlage seit der Bereitstellung geändert hat).
- Verifizieren: Jede bereitgestellte Datei befindet sich auf der richtigen Ebene; jede Regel-/Agenten-Anleitungsdatei hat
scope:-Frontmatter; CLAUDE.md innerhalb des Token-Budgets; jede verhaltensrelevante On-Demand-Datei hat eine Auslöserzeile oder einen Router-Eintrag (Erreichbarkeit, Datei→Auslöser); jeder MUST Read-Auslöser in CLAUDE.md verweist auf eine bereitgestellte Datei (Erreichbarkeit, Auslöser→Datei – kein toter Auslöser); kein ungerenderter {{slot}} bleibt außer beabsichtigten TODO-Markern. Fertig = Checkliste bestanden + Manifest geschrieben.
Bündel ↔ Live-Karte (check / promote – Master-Repo; update – initialisiertes Projekt)
| Bündelpfad | Live-Pfad |
|---|
portable/rules/* | .claude/rules/* |
portable/agent-guide/* | docs/agent-guide/general/* |
portable/skills/* | .claude/skills/* |
portable/agents/* | .claude/agents/* |
check: sha256 für jedes Paar → Abweichungen auflisten. Standard-Aktualisierungsrichtung ist Live → Bündel (promote); zuerst Live korrigieren, dann promote.promote: Live → Bündel für jede gemappte Datei kopieren, dann die Version per node scripts/sync-version.mjs set <x.y.z> hochzählen (schreibt kanonisches VERSION + spiegelt es in .claude-plugin/* und das README-Abzeichen).
Workflow (update – initialisiertes Projekt)
Richtung Bündel → Live (umgekehrt von promote). Betrifft nur den wörtlich kopierten portablen Satz; gerenderter Phänotyp (CLAUDE.md, index.md, projekteigene Anleitungen) ist nicht betroffen. update.mjs über seinen Pfad innerhalb des installierten Plugins aufrufen (es findet das Bündel selbstständig anhand seines eigenen Speicherorts); --project ist das initialisierte Projektstammverzeichnis und standardmäßig das aktuelle Verzeichnis.
- Probelauf:
node <plugin>/scripts/update.mjs --project <project-root> → ADD / UPDATE / CONFLICT-Plan und Versionsdifferenz prüfen.
- Zuerst jeden CONFLICT auflösen – ein Konflikt = eine portable Datei, die seit der Bereitstellung lokal bearbeitet wurde. Sie upstream befördern (damit die Verbesserung ins Bündel gelangt) oder nach Überprüfung manuell überschreiben. Niemals blind überschreiben.
- Anwenden:
node <plugin>/scripts/update.mjs --apply --project <project-root> → ADD + UPDATE schreiben, Konflikte überspringen, Manifest version + files[].sha256 aktualisieren.
- Nur hinzufügend und inplace –
update löscht nie: Eine aus dem Bündel entfernte Datei bleibt im Projekt, und eine lokal gelöschte Datei wird wieder hinzugefügt. Diese bei Bedarf manuell bereinigen.
templates/* (CLAUDE.md, index.md – gerenderter Phänotyp) werden nie überschrieben: Ihre Slots enthalten projektspezifische Werte. update gibt nur eine WARNUNG aus, wenn sich ein .tpl seit der Bereitstellung geändert hat (sha vs manifest.templates[]); manuell neu rendern (diff .tpl vs Live, strukturelle Änderungen erneut anwenden, Slot-Werte erhalten) oder /init-project erneut ausführen. Die WARNUNG bleibt bestehen, bis der nächste Init den Template-sha neu aufzeichnet.
- Exit-Code: 0 = aktuell oder sauber angewendet; 1 = Konflikte verbleiben; 2 = Einrichtungsfehler (kein Manifest → Projekt wurde nicht von diesem Plugin initialisiert).
Modulmatrix
| Modul | Enthält | Bereitstellen wenn | Scan-Signal (Beispiele, nicht abschließend) |
|---|
| core | portable/* (alle 4 Gruppen) + 3 Vorlagen | immer | — |
| runtime | agent-guide/general/local-runtime.md + CLAUDE.md-Auslöser (Skill schreibt per Scan, Schritt 5) | Projekt führt einen Dev-Server aus | package.json dev/start-Skripte, launchSettings.json, vite/next/dotnet/django/cargo-Konfiguration |
| e2e | agent-guide/general/<tool>.md (benannt nach erkanntem Tool) + CLAUDE.md-Auslöser (Schritt 5) | Projekt hat E2E-Browser-Tests | playwright/cypress/selenium-Abhängigkeit, e2e/-Ordner, E2E-Konfiguration |
- Optionales Modul wird nur bereitgestellt, wenn der Scan bestätigt ODER der Benutzer es im Interview bestätigt – unsicher → überspringen.
- Git: Minimaler Schutz (Commit nur auf Anfrage, niemals Push) wird in
CLAUDE.md.tpl ausgeliefert; detaillierte Richtlinie ist scope: project – Projekt schreibt bei Bedarf docs/agent-guide/general/git.md und fügt die Auslöserzeile im selben Commit hinzu (Erreichbarkeit – niemals ein Auslöser, der auf eine fehlende Datei verweist).
- Ein später benötigtes übersprungenes Modul → Projekt schreibt die Regel selbst gemäß dem bereitgestellten Standard. Ein neues Modul gelangt nur via
promote ins Bündel, nachdem ein echtes Projekt das Muster getestet hat.
Unabhängigkeitsregeln
- Skill wird einmal pro Projekt ausgeführt; bereitgestellte Dateien verweisen auf keine Datei dieses Master-Repositorys; Projektregeln nennen dieses Skill nie.
- In sich geschlossen, außer der obigen Bündel↔Live-Karte, die nur im Master-Repository für check/promote ausgeführt wird.
Beispiele
✅ Scan findet package.json mit „dev"-Skript → Laufzeitmodul vorschlagen → Schritt 5 schreibt
general/local-runtime.md + hängt „Dev-Server selbst ausführen → MUSS ... lesen" an CLAUDE.md an
❌ Laufzeitmodul ohne Scan-Signal und ohne Interviewbestätigung bereitstellen (geratenes Modul)
✅ /init-project check → „MISMATCH: portable/rules/doc-organization.md != .claude/rules/doc-organization.md"
→ zuerst Live korrigieren → /init-project promote
❌ portable/* direkt bearbeiten und dann ein neues Projekt initialisieren (Bündel weicht still vom Live ab)
Referenzdateien
- Bündel:
./portable/**
- Vorlagen:
./templates/**
- Version:
./VERSION