Was macht plan-it?
Nimm eine vage Anforderung → liefere ein baubares Lieferpaket. Dies ist der
Planungsdirigent: die disziplinierte vordere Hälfte des Lebenszyklus, die genau dort
endet, wo /build-it beginnt. Er führt Discovery (Recherche der Grundwahrheit), Spezifikation
(Erstellung der Designdokumente) und agilen Split (PRDs, Epics, Tests, den gemeinsamen
Vertrag) durch – und übergibt dann.
/plan-it ─────────────► docs/ + delivery/ ─────────────► /build-it
(discovery → spec → plan) (das baubare Paket) (baut es)
Benutzbar direkt durch einen Menschen und durch jeden orchestrierenden Conductor-Agenten, der eine neue Anforderung erhält und diese in ein Lieferpaket verwandeln muss, bevor er Arbeiter entsendet.
Die fünf unverhandelbaren Regeln (durchsetzen – nicht nur vorschlagen)
Dies sind die tragenden Regeln, die aus jedem erfolgreichen Lauf reverse-engineered wurden. Wenn du eine verletzt, driftet der nachgelagerte Build oder schlägt stillschweigend fehl.
-
Friere einen gemeinsamen CONTRACT ein, bevor paralleles Planen beginnt. Der CONTRACT ist das Gesetz: kanonische Entitäten, Schema, API/Schnittstelle, Enums, Repo/Branch-Karte und die Definition von "ausgeliefert". Squads schreiben darauf; jede bereichsübergreifende Discovery fließt zurück als datierte Änderung (v1.0 → v1.1 …). Kein eingefrorener Contract → keine parallelen Squads.
-
Bündle jede nur-menschliche Entscheidung in EIN Gate. Entscheide nichts Irreversibles vorab (Repo-Topologie, Hosting, Produktname, Architekturmodell, Build-vs-Buy). Präsentiere sie gemeinsam, jede mit einer Empfehlung versehen, und lasse den Menschen nummeriert antworten. Dieses Gate ist der Ort, an dem der Mensch Vision einbringt, nicht nur Optionen auswählt – lasse Raum, damit sie ein Konzept hinzufügen können, das du nicht vorgeschlagen hast. Versiegle jede Antwort mit Besitzer + Datum.
-
Verifiziere die Ausgabe jedes Agenten auf der Festplatte – "untätig ≠ geliefert". Ein Team, das untätig wird, bedeutet NICHT, dass es Dateien geschrieben hat. Nach jedem Fan-Out überprüfe, ob die tatsächlichen Pfade existieren und nicht leer sind, bevor du fortfährst. Wenn ein Team seine Ausgabe als Nachricht hält, weise es an, auf den exakten absoluten Pfad zu
Writen. Vertraue niemals einem "erledigt". -
Verankere den Plan am LIVE-System, nicht am Repo – bevor du einfrierst. Für jeden Plan, der ein laufendes System berührt, ist das Repo eine Hypothese; die bereitgestellte Realität ist die Wahrheit, und sie driften auseinander. Verifiziere vor dem Einfrieren des CONTRACTs gegen das tatsächliche System und schreibe die Beobachtungen hinein (keine Repo-abgeleiteten Annahmen). Kampferprobt: In einem Programm ließ sich JEDE Korrektur in der Mitte des Flugs auf eine Repo-gestützte Annahme zurückführen, die die Realität widerlegte – falsche kanonische Identifikatoren (Manifeste waren vom bereitgestellten Katalog abgedriftet), ein Konfigurationswert, der vorhanden war, aber auf einen toten Host zeigte, "zu bauende" Komponenten, die bereits bereitgestellt waren, und ein gefundenes Credential, das das falsche war. Siehe Phase 3.
-
Betreibe die Maschine, nicht den Prosa. Der Kontrollfluss der Pipeline lebt in
machine.json(dem expliziten Zustandsdiagramm), nicht in diesem Dokument – dieser Prosa erklärt die Maschine. Beim Aufruf lies oder initialisiere.plan-it/state.json(im Zielprojekt) und setze ab seinemstatefort; schreibe es bei jedem Übergang. Führe bei jedem bewachten Übergang den zugeordneten Unterbefehl des Guards aus (node scripts/gate-check.mjs <check> …) und schreite niemals bei einem Exit-Code ungleich Null fort – repariere, führe erneut aus, dann wechsle. Wenn Node nicht verfügbar ist, führe dieselben Prüfungen manuell durch und protokolliere sie in der Zustandsdatei (degradiere, unterbrich nie). Vollständiges Protokoll:references/machine.md.
Der deterministische Kern (v2) – warum eine Maschine
Kontrollfluss, der als Prosa geschrieben ist ("mache Schritt 1, überspringe niemals das Gate"), ist das, was die Determinismus-Literatur Prosa-Kontrollfluss nennt: Er verlässt sich auf die Disziplin des Modells über einen langen, zusammenfassungsanfälligen Kontext hinweg, und manchmal folgt das Modell ihm nicht. V2 kehrt dies auf der richtigen Höhe um – Nichtdeterminismus an den Rändern, Determinismus im Kern:
machine.json– XState v5-kompatibles Zustandsdiagramm der Pipeline: 15 Zustände, die drei menschlichen Gates (meta.gate+meta.human), bewachte Übergänge und eineAMENDMENT-Selbstschleife aufparallelPlanning. Füge es in stately.ai/viz ein, um es zu sehen..plan-it/state.json– der persistierte Lauf: aktueller Zustand, Gate-Freigaben (Besitzer + Datum), Vertragsversion, verifiziertes Artefakt-Register, Historie. Dies macht einen Lauf absturzsicher oder eine neue Sitzung fortsetzbar.scripts/gate-check.mjs– die Guards als Exit-Codes:verify(Regel 3, untätig ≠ geliefert),freeze(Regel 1, kein Contract → keine Squads),handoff(die mechanisierbare Hälfte der Playbooks §F),state(Regel 2, Gates protokolliert),adversary(Regel 6 / D4 – Fehlermodustiefe: Eine modellierte Maschine muss die fünf Kaskadenklassen abdecken oder darauf verzichten; n/a für lineare Workflows). Die ÜbergängeLINT_CLEANundADVERSARY_CLEAN(verify → adversaryGate → handoff) bewachen die letzten beiden.
Die unscharfen Phasen – Discovery, Synthese, Spezifikationserstellung, Beurteilung – bleiben
LLM-am-Knoten (im llmAtTheNode-Tag der Maschine). Formaliere sie nicht; Modellierung ist nur
dann keine Zeremonie, wenn sie Verwirrung ersetzt. Details, Zustandsdatei-Schema und das
Fortsetzungsprotokoll: references/machine.md.
Harte Durchsetzung (v2.1, Plugin-Installation nur auf Claude Code): Ein PreToolUse-Hook
(scripts/hooks/planit-guard.mjs) verweigert Write/Edit-Aufrufe auf PRD/Epic-
Auslieferungsgegenstände, während der Contract des Laufs nicht eingefroren ist – Regel 1
hört auf, eine Anweisung zu sein, und wird zu etwas, das das Harness ablehnt. Fail-Open: Es
berührt niemals Nicht-Plan-It-Arbeit. Skill-only-Installationen verlassen sich stattdessen auf die
Disziplin von Regel 5.
Der Testvertrag – der Qualitätsunterschied (mache dies unverhandelbar)
Das Einzige, was die gelieferte Codequalität am meisten steigert: **Jede PRD/jeder Epic endet mit der Generierung eines eigenen Testvertrags – bis zu ~20 konkreten Anwendungsfällen/Szenarien,
die die Implementierung belasten – und das Feature ist NICHT "erledigt", bis 100% von ihnen bestanden sind.** Der Build-Agent kann nicht einfach das Feature liefern; er muss den Vertrag
erfüllen, und /iterate so lange, bis es grün ist.
Dies ist eine benannte, bewährte Disziplin: Specification by Example (Gojko Adzic) + ATDD/BDD für Code (konkrete Beispiele werden zu ausführbaren Abnahmetests und lebendiger Dokumentation) und Eval-Driven Development für Skills/LLM-Funktionen (registriere Goldene mit erwarteten Ausgaben, iteriere, bis sie bestehen). Die Fälle zur Planungszeit zu erstellen,
ist der springende Punkt – sie werden ein verbindlicher Vertrag, kein nachträglicher Einfall.
Regeln des Testvertrags:
- Zur Planungszeit erstellt – der LETZTE Schritt beim Schreiben jedes Epics/PRDs ist sein Testvertrag. Erwartete Ausgaben werden jetzt registriert ("zuerst entworfen; erwartete Ausgaben registriert"), nicht während des Builds entdeckt.
- Bis zu ~20 hochwertige Fälle pro Feature – genug, um echtes Verhalten + Kanten zu belasten; nicht Tausende von oberflächlichen (Qualität > Quantität – automatische Massenproduktion = "Schlonz", gemäß der Eval-Literatur). Ziehe Fälle aus echten/wahrscheinlichen Fehlermodi. Anzahlregel nach Shape: Große Shape-1-Multi-Squad-Programme haben eine ≥10 Fälle-pro-Epic-Untergrenze (jeder Epic ist ein großes Feature); kleine Shapes (einzelner Skill/Feature, S/M) erstellen ~20 Fälle insgesamt über das Paket (eine Handvoll pro Epic). Niemals beides gleichzeitig – wähle nach Shape, damit ein Reviewer kein korrektes kleines Paket als untertestet markiert.
- Verbindlich – DoD = 100% des Vertrags bestehen; bis dahin
/iterate. Kein teilweises Ausliefern; kein VERIFIED-auf-einem-Mock (ein[REAL]-Fall, dessen Ziel unerreichbar ist → IMPLEMENTED-NOT-VERIFIED, niemals ein falsches Grün). - Wähle die Testtypen nach Implementierung (einer oder mehrere von unit / e2e / Anwendungsfälle / Stress):
| Implementierung | Testtypen | Wie |
|---|---|---|
| CRUD / REST API | Anwendungsfälle (Happy+Edge) + e2e | führe jedes Szenario via API und via UI mit Chrome CDP (chrome-cdp-control) aus; Unit-Test der Logik |
| Skill / Prompt / LLM-Funktion | Anwendungsfälle mit erwarteter Ausgabe | führe es aus, vergleiche real vs. erwartet – exakte Übereinstimmung für geschlossene Ausgaben, Rubrik / LLM-als-Richter für offene (make-eval, promptfoo, DeepEval G-Eval) |
| Agent / zustandsbehaftet / mehrschrittig | Stresse-Szenarien + Anwendungsfälle | sechs Achsen: async, Fan-Out, Eskalation, Human-Gate, Rekursion, Cycle-Guard (Setup/Erwartet/Bestanden) |
| Reine Logik / Bibliothek | Unit + eigenschaftsbasiert | aufgezählte Fälle + Invarianten |
| Datenpipeline / Migration | Goldener Wert + e2e | handberechnete erwartete Werte; Idempotenz/Rollback |
| Alles mit Last-/Missbrauchsoberfläche | Stress / adversarial | Parallelität, Rate, fehlerhafte Eingabe, Red-Team |
- Ausführungspfad:
/full-qaführt den Vertrag aus,/iterateschleift ihn auf 100%,chrome-cdp-controltreibt UI-Szenarien. Der Vertrag ist die Brücke von plan-it → build-it:/build-it's Definition of Done = dieser Vertrag.
Grammatiken und das Vertragskopfformat: references/formats.md (der Testvertrag-Block + §4–5).
Autonomie-Posture (geführt mit autonomen Ausbrüchen)
Führe Recherche und Erstellung autonom mit hohem Aufwand durch, aber halte an drei Gates an:
| Gate | Wann | Was du fragst |
|---|---|---|
| G1 – Umfang | nach der Aufnahme (Phase 2) | bestätige die Größe (Feature vs. Programm) + die nummerierte DoD, bevor du Aufwand verbrennst |
| G2 – Entscheidungen | nachdem Spezifikationen entworfen wurden (Phase 7) | die gebündelten "Entscheidungen, die nur du treffen kannst", jede mit einer Empfehlung |
| G3 – Lieferung | vor dem agilen Split (Phase 8) | "Spezifikationen sehen ausgerichtet aus – mit PRDs/Epics fortfahren?" |
Alles zwischen den Gates läuft unbeaufsichtigt. Empfehle /effort xhigh zu Beginn
(du kannst es nicht selbst setzen – sage dem Benutzer, /effort xhigh auszuführen, wenn sie es
nicht getan haben).
Phase 0 – Aufnahme
Maschine zuerst (Regel 5): wenn .plan-it/state.json im Zielprojekt existiert,
führe node scripts/gate-check.mjs state .plan-it/state.json aus und setze ab dem
ausgegebenen Zustand fort – starte keine Phasen neu, die bereits in history sind. Wenn
sie nicht existiert, erstelle sie jetzt im Zustand intake (Schema in references/machine.md)
und halte sie bei jedem Übergang für den Rest des Laufs aktualisiert.
Nimm die Anforderung in jeder Form an, die sie hat: ein Brain-Dump, eine eingefügte
Transkription, eine Liste von Wünschen oder ein Einzeiler. Erwarte Verweise, nicht Inhalte –
Session-Namen (/read-chat "<name>"), Repo-Pfade, Dokumentenordner. Deine Aufgabe ist es, die
Grundwahrheit zu holen, nicht sie dir geben zu lassen.
Halte zu Beginn fest:
- Die rohe Vision in den eigenen Worten des Benutzers (du wirst sie in
02 §1zitieren). - Verweise auf vorherige Sessions / Repos / Docs zur Recherche.
- Anwendungsfall (automatisch erkennen – dieser treibt die Verpackungsform an Gate G1):
- neue einzelne App, Greenfield · Feature auf einem großen bestehenden Repo · Multi-Subsystem-Programm von Grund auf · Multi-App-Plattform (viele PRDs) · Refaktor / Migration / Debt · Research-Spike (noch kein Build) · PM/Board- Automatisierung · Dokumentation/Prüfung eines bereits gebauten Systems.
- Recherchemethode: Standardmäßig parallele Claude-Teams bei xhigh.
Wenn die Anforderung wirklich ein vager Absatz ohne Verweise und mit einem bestehenden Repo ist, ist das in Ordnung – die Vorerfassung (Phase 3) wird die Ziele finden.
Phase 1 – DoD-Festlegung
Formuliere den vagen Prosa in eine nummerierte, einzeln verifizierbare Definition of Done
- eine kurze Liste von genannten Annahmen um. Dies ist dein Vertrag mit dem Benutzer für den Planungsjob selbst. Beispielform:
DoD für diesen Planungslauf:
1. Grundwahrheits-Erkenntnisdokument (jede Behauptung → Pfad:Zeile oder Tabelle)
2. Vision + Architekturdokument, das jede Erkenntnis/Contradiction löst
3. Daten-/Schnittstellenvertrag
4. … (automatisch skaliert – siehe Phase 2)
N. Übergabe: Contract eingefroren, PRDs+Epics mit ≥10 Tests each, Kickoff-Prompt
Annahmen: <Liste>
Phase 2 – Umfang & Form-Governor ⏸ GATE G1
Wähle Größe (wie viel) und Form (welche Gestalt) aus, bevor du Aufwand betreibst. Bestätige beides mit dem Benutzer.
Größe skaliert die Artefaktanzahl:
| Signal | Größe |
|---|---|
| Einzelnes Feature, 1 Subsystem | S |
| Multi-Feature / neues Subsystem, 1–2 Repos | M |
| Programm von Grund auf / viele Subsysteme | L |
Form wird nach Anwendungsfall gewählt (vollständige Definitionen + die Tabelle
Anwendungsfall→Form in references/templates.md TEIL D):
- Multi-Doc +
delivery/(Basis) – Programm von Grund auf, parallele Squads. - Single-File PRD-as-everything – Greenfield Single-App; CONTRACT inline als G-Regeln.
- Research → locked-Architektur → Master+Phase PRDs – Feature auf einem großen bestehenden Repo.
implementation/<name>/mit nummeriertem PRD-NN – Multi-App-Plattform, viele PRDs.- Refaktor-/Debt-Workstream-Katalog – Brownfield an Ort und Stelle. (+ Research-Spike, ausführbares Board und Reverse-Dokumentationsmodi – siehe TEIL D.)
Gleiche Phasen unabhängig davon – nur die Artefaktanzahl und -form ändern sich. Gib einem
Feature keine 4-Squad-Org; gib einem Brownfield-Refaktor kein Greenfield-Visionsdokument.
Präsentiere die gewählte Größe + Form + die nummerierte DoD und erhalte ein Ja, bevor du
fortfährst. Bei Ja protokolliere G1 = {approved, owner, date} plus die gewählte Größe/Form in
.plan-it/state.json – der G1_APPROVED-Übergang wird von gateRecorded bewacht.
Phase 3 – Vorab-Erfassung
Bevor irgendein Fan-Out stattfindet, lokalisiere exakte Ziele, damit Agenten präzise Pfade bekommen, keine vagen Anweisungen:
- Löse Verweis-Sessions mit einer Session-Lese-Fähigkeit (
/read-chatoder ähnlich) auf, falls eine installiert ist; andernfalls frage nach dem relevanten Transkript oder der Zusammenfassung. ls/grepdie genannten Repos; finde diedocs/, Schema-Dateien, Einstiegspunkte.- Lies den Wiki-Hot-Cache/Index, wenn das Repo vault-verbunden ist (gemäß seiner
CLAUDE.md).
Ausgabe: eine Liste von {Subsystem → exakte Pfade zum Lesen}, die die Recherche-Teams speist.
Live-Verankerungs-Gate (Regel 4) – wenn der Plan ein LAUFENDES System berührt
Das Repo sagt dir, was wahr sein sollte; das Live-System sagt dir, was ist. Tue dies vor dem Einfrieren von Phase 8 und schreibe die Erkenntnisse als beobachtete Fakten in den CONTRACT:
- Konfigurationserreichbarkeit, nicht Vorhandensein. Für jeden Env-/Config-Hebel, von dem der Plan abhängt (Basis-URLs, API-Hosts, Feature-Flags), greife darauf zu – bestätige nicht nur, dass er gesetzt ist. Ein Wert kann auf einen toten Host gesetzt sein und eine "existiert es"-Prüfung bestehen, während er die Produktion stillschweigend zerstört.
- Live-Register / kanonische Identifikatoren. Due …
…
[truncated for translation]