Lego-Plan

Lego Plan

Wandle eine entschiedene Änderung in einen geschichteten DAG (Directed Acyclic Graph) aus einfachen Primitiven bis hin zu einer funktionierenden Funktion um. Nur planen. Dann anhalten.

Der Graph ist eine Pyramide: unabhängige Blöcke unten, zusammengesetzte Blöcke darüber, ein Endknoten. Ein späterer Fahrer kann Knoten in der gleichen Ebene parallel ausführen, den status setzen und diesen Graphen neu zeichnen. Dieses Skill startet keine Subagenten. Es lädt keine anderen Skills.

Wann verwenden

Laden, wenn die Aufgabe darin besteht, eine entschiedene Änderung in eine Implementierungskarte umzuwandeln, der der Fahrer folgen kann.

• Bedarf: Was gebaut werden soll, ist bereits gewählt. Wenn eine Liste der zu bearbeitenden Dateien oder eine Pfadauswahl bereits in dieser Konversation vorhanden ist, verwende sie. Wenn nicht, arbeite von der entschiedenen Absicht und dem Code aus, den du lesen musst, um Dateien zu benennen. Erfinde keine zweite Systemkarte.
• Überspringen: Tippfehler, Kommentare, Formatierung, Dokumentation ohne Code.
• Wenn die Absicht noch offen ist: Anhalten. Nachfragen, bis die Änderung entschieden ist. Erstelle keine Blöcke für eine Funktion, die nicht gewählt ist.

Ein Knoten ist immer noch ein DAG. Gib den vollständigen Vertrag aus.

Harte Grenzen

1. Nur planen. Keinen Produktionscode schreiben. Keine Tests schreiben. Benenne den Check in done when. Implementiere ihn hier nicht.
2. Nach der Ausgabe anhalten. Chat-DAG plus die Scratch-Datei. Kein Dispatch. Kein nächstes Skill laden.
3. Keine Zyklen. Wenn ein Block von einem späteren Block abhängt, ist die Aufteilung falsch. Teile erneut auf.
4. Nicht auf Genehmigung warten. Zeige den DAG und halte an. Der Benutzer unterbricht, wenn er falsch ist.
5. Öffne die Scratch-Datei nicht für den Benutzer. Schreibe keinen Plan unter docs/.

Knotengranularität

Graphknoten (parallele Einheit): ein unabhängig versendbares Primitive, das ein Subagent besitzen kann, ohne auf einen anderen in Bearbeitung befindlichen Knoten zu warten.

Beispiele: write fetchOrder, write OrderCard, wire fetchOrder into the loader.

Zu groß: implement auth. Teile es auf. Zu klein: rename a variable. Füge es in den Knoten ein, der es braucht.

Teile (innerhalb eines Knotens): die Funktionen, die zusammen landen müssen, damit der Knoten kompiliert. Ein Subagent führt Teile in Reihenfolge aus. Teile nicht auffächern.

Beispielknoten fetch-order:

• files: src/fetchOrder.ts, src/fetchOrder.test.ts
• parts: Order-Typ, dann fetchOrder, dann src/fetchOrder.test.ts schreiben oder erweitern
• diese Teile sind keine separaten Graphknoten

Graphenform

• Ebene 0: Knoten mit depends on: none. Der Fahrer kann sie alle parallel ausführen.
• Ebene N: Knoten, deren Abhängigkeiten alle in früheren Ebenen liegen.
• Letzte Ebene: Ein Knoten (oder eine enge Gruppe), der bedeutet, dass das Feature Ende-zu-Ende funktioniert.
• Zwei Knoten, die nicht voneinander abhängen, müssen sich eine Ebene teilen (oder in Ebenen liegen, die nicht aufeinander warten).
• depends on listet Knoten-IDs, niemals Dateinamen.

Gleiche Datei: Wenn zwei Knoten denselben Pfad erstellen oder bearbeiten, dürfen sie sich keine Ebene teilen. Führe sie zusammen oder füge eine depends on-Kante hinzu, sodass einer wartet. Teile eine Datei nicht nur auf, um sie parallel auszuführen. Zwei Knoten, die einen Pfad nur lesen, können sich eine Ebene teilen. files listet nur Erstellen-oder-Bearbeiten-Pfade. Die gleiche-Datei-Regel schließt Testdateien ein.

Knotenfelder

Jeder Knoten hat alle sieben:

1. id: kebab-case, eindeutig in diesem Plan, stabil (ein späterer Fahrer markiert diese ID als erledigt).
2. name: Kurzer englischer Name.
3. depends on: Andere IDs oder none.
4. files: Erstellen oder Bearbeiten (Pfade). Den Testpfad aus done when einschließen.
5. parts: Geordnete C-Liste. Letzter Teil ist das Schreiben oder Erweitern des Tests. Wenn done when ein manueller Check ohne Testdatei ist, ist der letzte Teil dieser Check und files hat keinen Testpfad.
6. done when: Eine Testdatei oder ein Befehl, den der Fahrer ausführen kann, bevor er Abhängigkeiten startet.
7. status: Dieses Skill schreibt immer pending. Ein späterer Fahrer kann in-progress oder done setzen. Dieses Skill schreibt niemals diese beiden.

Setze keinen vollständigen Quellcode in den Plan.

Live-Board

Pfad: <repo>/.agent/scratch/lego-plan.json

Gleiches JSON wie der Chat-Fence. Agenten folgen dieser Datei. Das benutzerseitige Produkt ist das Chat-Bild.

• Erstelle .agent/scratch/, falls nötig.
• Immer überschreiben. Nicht fragen, auch wenn vorhandene Knoten in-progress oder done sind.
• Wenn das Repo Git hat, stelle sicher, dass .gitignore .agent/scratch/ enthält. Wenn .gitignore existiert und die Zeile fehlt, hänge sie an. Wenn .gitignore fehlt, erstelle es mit dieser einen Zeile.
• Öffne die Datei nicht. Gib sie nicht als zweite Kopie im Chat aus. Der JSON-Fence ist die Kopie, die der Benutzer sieht.

Abläufe

Ablauf 1: Bestätige eine entschiedene Änderung

1. Wenn die Änderung klar ist, fahre fort.
2. Wenn der Benutzer noch wählt, was er will, halte an. Frage. Kehre hierher zurück, nachdem es entschieden ist.

Ablauf 2: Sammle bereits in der Sitzung vorhandene Eingaben

1. Wenn diese Konversation bereits eine Ziellinien-Dateiliste, Teile oder eine Pfadauswahl hat, verwende diese als Startsatz.
2. Wenn nicht, leite Blöcke aus der entschiedenen Absicht und dem Code ab, den du lesen musst, um Dateien zu benennen. Durchstöbere nicht das gesamte Repo.

Ablauf 3: Teile in Knoten und Teile auf

1. Liste Kandidaten-Primitive (B-Granularität).
2. Für jedes Primitive liste die C-Teile auf, die zusammen kompilieren müssen. Endet mit dem Schreiben oder Erweitern des Tests (oder der manuellen Prüfung).
3. Zeichne depends on: Ein Knoten hängt nur von einem anderen ab, wenn er das Ergebnis dieses Knotens aufruft oder einbettet.
4. Weise Ebenen aus den Abhängigkeiten zu. Unabhängige Knoten → gleiche Ebene.
5. Wenn zwei Knoten denselben Pfad erstellen oder bearbeiten und sich eine Ebene teilen, führe sie zusammen oder füge eine Kante hinzu. Dann ordne die Ebenen neu.
6. Wenn ein Zyklus auftritt, teile den falschen Knoten auf und wiederhole diesen Ablauf.

Ablauf 4: Fülle jeden Knoten

Fülle die sieben Felder aus. status ist bei jedem Knoten pending.

Ablauf 5: Zeige den DAG im Chat

Zeige in dieser Reihenfolge:

1. Ebenen: Ebene 0 bis zur letzten. Unter jeder Ebene die Knoten in dieser Ebene.
2. Knoten: Die sieben Felder für jede ID.
3. Mermaid: Immer. Ein flowchart (oder graph TD). Knoten-IDs im Diagramm müssen mit den Plan-IDs übereinstimmen. Kein classDef. Keine Statusfarben. Jeder Knoten ist pending.
4. JSON-Fence: Ein json-Block mit dem Live-Board-Objekt. Quelle der Wahrheit für IDs, Abhängigkeiten, Dateien, Teile, doneWhen und status. Ebenen werden aus depends abgeleitet. Speichere kein layer-Feld.

Dann Ablauf 6.

Mermaid-Form:

flowchart TD
  fetch-order[fetch-order]
  order-card[order-card]
  wire-loader[wire-loader]
  fetch-order --> wire-loader
  order-card --> wire-loader

Knoten derselben Ebene haben keine Kante zwischen sich.

JSON-Form:

{
  "version": 1,
  "nodes": [
    {
      "id": "fetch-order",
      "name": "fetch order",
      "depends": [],
      "files": ["src/fetchOrder.ts", "src/fetchOrder.test.ts"],
      "parts": ["Order type", "fetchOrder", "write or extend src/fetchOrder.test.ts"],
      "doneWhen": "pnpm test src/fetchOrder.test.ts",
      "status": "pending"
    }
  ]
}

depends ist ein Array von IDs. Leeres Array bedeutet keine.

Ablauf 6: Schreibe das Live-Board

1. Schreibe dasselbe JSON nach .agent/scratch/lego-plan.json (überschreiben).
2. Stelle sicher, dass .gitignore .agent/scratch/ ignoriert, wie unter Live-Board.
3. Öffne die Datei nicht.

Ablauf 7: Anhalten

Nach Ablauf 6 anhalten. Keinen Code schreiben. Kein Dispatch. Kein weiteres Skill laden.

Entscheidungsbaum

• Absicht nicht entschieden → Ablauf 1.
• Entschiedene Änderung, Implementierungskarte benötigt → Ablauf 2 → 3 → 4 → 5 → 6 → 7.
• Ein Knoten → trotzdem Ablauf 2 → 7 (vollständiger Vertrag).
• Tippfehler / Formatierung / nur Dokumentation → dieses Skill gilt nicht.
• Zyklus in Abhängigkeiten → Ablauf 3 Schritt 6.
• Gleicher Pfad auf zwei Knoten derselben Ebene → Ablauf 3 Schritt 5.
• Knoten ist "implementiere das gesamte Feature" → aufteilen (Ablauf 3).

Rote Flaggen

Signal	Was es bedeutet	Stattdessen tun
Die Fetch-Funktion in diesem Skill schreiben	Plan wurde zur Implementierung	Ablauf 7. Anhalten.
Eine lineare Liste ohne Ebenen	Kann nicht auffächern	Unabhängige Knoten in dieselbe Ebene setzen.
Subagenten von hier aus dispatchen	Blatt wurde zum Fahrer	Ablauf 7. Anhalten.
Mermaid-IDs unterscheiden sich von Knoten-IDs	Fahrer kann nicht als erledigt markieren	Gleiche kebab-case-ID an beiden Stellen.
JSON-Fence unterscheidet sich von der Scratch-Datei	Zwei Quellen der Wahrheit	Ein Objekt schreiben. In beide kopieren.
Zyklus (a → b → a)	Aufteilung ist falsch	Aufteilen und neu schichten.
Zwei Knoten derselben Ebene bearbeiten order.ts	Paralleler Schreibkonflikt	Zusammenführen oder eine depends on-Kante hinzufügen.
Eine Datei aufteilen, damit zwei Knoten parallel laufen können	Ungefragtes Design	Datei behalten. Knoten sequenzieren.
Testpfad fehlt in files / letztem Teil	Knoten ist nicht versendbar	Ablauf 3 Schritt 2.
classDef oder Statusfarben im Plan-Mermaid	Dieses Skill malt Fortschritt	Ohne Stil. Alle pending.
Teile eines Knotens in parallele Knoten aufgeteilt, die allein nicht kompilieren können	C als B behandelt	Diese Teile innerhalb eines Knotens behalten.
"Implement auth" als einzelner Knoten	Zu groß	In Primitive aufteilen.
Auf "sieht gut aus?" warten	Grenze ist show-and-stop	Ausgeben und anhalten.
Vor dem Überschreiben der Scratch-Datei fragen	Live-Board ist ein Slot	Ablauf 6. Überschreiben.
Öffnen von .agent/scratch/lego-plan.json	Zusätzlich für den Benutzer	Nur Chat. Datei ist für Agenten.
Schreiben von docs/lego-plan.md	Zusätzliches Artefakt	Chat plus Scratch. Keine Docs-Plan-Datei.

Fehlerbehandlung

• Keine zu bearbeitenden Dateien in der Sitzung: Aus Absicht und gezielten Lesevorgängen ableiten. Wenn du keine Dateien benennen kannst, anhalten und sagen, was fehlt. Keine Pfade erfinden.
• Zyklus: Den Zyklus per ID melden. Aufteilen. Ablauf 3 erneut ausführen. Keinen zyklischen Mermaid als Plan zeigen.
• Letzte Ebene bedeutet nicht, dass das Feature funktioniert: Einen Endknoten hinzufügen, der von den zusammengesetzten Teilen (der Verdrahtung) abhängt, oder sagen, warum die aktuelle letzte Ebene bereits der Ende-zu-Ende-Pfad ist.
• Benutzer unterbricht und sagt, ein Knoten sei falsch: Diesen Knoten und alle depends on, die auf ihn zeigten, bearbeiten. IDs stabil halten, wenn der Knoten noch existiert. Wenn du einen Knoten löschst, entferne ihn aus dem Mermaid und dem JSON. Die Scratch-Datei überschreiben. Den DAG erneut anzeigen. Anhalten.
• done when ist vage ("es funktioniert"): Durch einen Befehl oder Testpfad ersetzen. Wenn das Projekt noch keinen Testbefehl hat, benenne die manuelle Prüfung in einer Zeile. Letzter Teil ist diese Prüfung.
• Kein Git-Repo: Trotzdem .agent/scratch/lego-plan.json unter dem Workspace schreiben, wenn er beschreibbar ist. Den Gitignore-Schritt überspringen. Das in einer Zeile im Chat sagen.
• Scratch-Schreiben fehlschlägt (Berechtigungen, Festplatte): Trotzdem Chat-DAG und JSON-Fence zeigen. Sagen, dass das Live-Board nicht geschrieben wurde. Nicht so tun, als ob die Datei existiert.
• Vorhandenes Scratch-JSON ist ungültig oder mitten im Lauf: Überschreiben. Nicht zusammenführen. Nicht fragen.