n0ctx/DAG-Engineering

DAG Engineering

Größere Engineering-Aufgaben in abhängige Unteraufgaben (Knoten) aufteilen. Jeder Knoten wird von einem Unteragenten in seinem eigenen Worktree und Branch implementiert. Der Hauptagent führt die Integration im Integrations-Worktree durch, indem er die Ergebnisse nacheinander zusammenführt und verifiziert. Auch Nachbesserungen halten diese Isolation ein; Unteragenten nehmen keine Änderungen im Integrations-Worktree vor oder committen dort. Der Hauptagent ist verantwortlich für die Untersuchung, Planung, Verteilung, Integration, Nachbesserungsplanung und finale Abnahme.

Die Tiefe der Untersuchung, die Anzahl der Unteragenten und der Umfang der Verifizierung richten sich nach der tatsächlichen Komplexität der Aufgabe. Es werden keine Unteragenten eingesetzt, wenn es keine unabhängige Arbeit gibt, die eine solche Aufteilung rechtfertigt.

Bei der Zuweisung von Unteragenten mit Codex wird explizit fork_turns="none" gesetzt.

0. Fortsetzung eines bestehenden Plans

Vor dem Start wird das .dag/-Verzeichnis im Hauptarbeitsbereich überprüft. Wenn ein Plan mit dem Status „plan status: in progress“ (in Arbeit) existiert, wird dieser gelesen. In Kombination mit dem tatsächlichen Git-Status wird er vom aktuellen Fortschritt aus fortgesetzt, ohne neu aufgeteilt zu werden. Wenn der Plan nicht mit dem Git-Status übereinstimmt, wird der Plan basierend auf dem verifizierten Code-Status korrigiert.

1. Wenn im Integrations-Worktree eine MERGE_HEAD existiert (git -C <integrations-wt> rev-parse -q --verify MERGE_HEAD): Die Integration wurde unterbrochen, das Ergebnis ist unbekannt. Führe git merge --abort aus und integriere den Knoten als submitted erneut.
2. Gehe jeden Knoten einzeln durch:
   • done: Stelle sicher, dass der Commit des Knotens in den Integrations-Branch gemerged wurde (git -C <integrations-wt> merge-base --is-ancestor <commit> HEAD), und führe ihn nicht erneut aus.
   • submitted: Wenn der Commit des Knotens bereits in den Integrations-Branch gemerged wurde, markiere ihn direkt als done (Merge-Commits entstehen nur nach bestandener Verifizierung); andernfalls integriere ihn gemäß Schritt 6.
   • running: Wenn der Agent in dieser Sitzung noch ausgeführt wird, warte auf ihn. Wenn der Agent nicht mehr existiert, überprüfe die Commits und nicht-committierten Änderungen im Worktree des Knotens und weise einen neuen Agenten zu, der im selben Worktree auf Basis der vorhandenen Ergebnisse fortfährt. Es wird kein neuer Worktree erstellt.
   • blocked: Lese den Grund und prüfe, ob die Bedingung inzwischen erfüllt ist.
   • pending: Plane gemäß Schritt 5. Wenn der Knoten noch im alten Format (Ziel, Umfang, Schritte, Abnahme, Verifizierung) vorliegt, schreibe ihn vor der Zuweisung in die Vorlage von Schritt 4 um.
3. Wenn alle Knoten done sind: Fahre mit Schritt 7 fort.

Wenn der Status unklar ist, werden Worktrees, Branches oder nicht-committierte Änderungen nicht gelöscht.

1. Integrations-Worktree erstellen

Jeder DAG erhält einen Integrations-Worktree und -Branch, die nur vom Hauptagenten beschrieben werden. Der Hauptarbeitsbereich wird nicht geändert.

git worktree add "../<repo>-<plan-id>" -b "dag/<plan-id>"

• <plan-id>: Verwende eine kurze kebab-case-Beschreibung der Arbeit. Wenn der Branch oder das Verzeichnis bereits existiert, verwende einen anderen Namen.
• Wenn der Hauptarbeitsbereich nicht-committierte Änderungen enthält, teile dem Benutzer mit, dass diese Änderungen nicht in den Worktree übernommen werden. Der Benutzer entscheidet, ob er sie zuerst committet oder fortfährt.
• Wenn Verifizierungsbefehle von Installationsschritten abhängen (z. B. node_modules, virtuelle Umgebungen), führe die Installation zuerst im Integrations-Worktree durch.
• Notiere den Start-Commit (git rev-parse HEAD). Die Gesamtüberprüfung verwendet diesen als Basis.

2. Untersuchung und Schlüsseldesign

Reihenfolge: Anforderungsanalyse → gezielte Code-Untersuchung → vereinheitlichtes Schlüsseldesign.

Der Hauptagent identifiziert basierend auf den Anforderungen die bestehende Implementierung, relevante Module, Aufrufbeziehungen und Tests. Er listet unbekannte Probleme auf, die die Planung beeinflussen. Wenn Unklarheiten das Ziel, den Umfang oder die Abnahmekriterien ändern würden, wird zuerst der Benutzer gefragt. Andere Unsicherheiten werden als „Annahmen“ in den Plan aufgenommen.

Wenn es mehrere unabhängige Untersuchungsfragen gibt, werden schreibgeschützte Untersuchungs-Unteragenten in einer Nachricht parallel losgeschickt. Bei wenigen oder voneinander abhängigen Fragen recherchiert der Hauptagent selbst. Die Untersuchung erfolgt nach konkreten Fragen (bestehende Implementierung und Wiederverwendung, Schlüsselschnittstellen und Aufrufketten, gemeinsamer Zustand und externe Ressourcen, Tests und technische Randbedingungen usw.), nicht nach einer mechanischen Verzeichnisaufteilung. Untersuchungs-Unteragenten lesen direkt den Integrations-Worktree und benötigen keinen eigenen Worktree. Die Anweisung lautet:

Führe eine schreibgeschützte Untersuchung von <integrations-wt> durch. Ändere keine Dateien und weise keine anderen Agenten zu. Ziel: <…>. Umfang: <…>. Beantworte: . Stoppe, sobald die Fragen beantwortet sind, ohne Erkundungen außerhalb des Umfangs. Berichte nur: Wichtige Fakten und ihre Position (Datei:Symbol), wiederverwendbare bestehende Implementierungen, technische Randbedingungen, nicht bestätigte Punkte. Unterscheide zwischen bestätigten Fakten und Spekulationen.

Der Hauptagent integriert die Ergebnisse, behandelt widersprüchliche Schlussfolgerungen und recherchiert nur zu Lücken, die die Planung beeinflussen. Wenn genügend Fakten vorliegen, um die goal, scope, verify und stop der Knoten zu schreiben, wird die Untersuchung eingestellt; die Details der steps überlässt man den Knoten-Unteragenten zur Verfeinerung bei Arbeitsbeginn (Schritt 5). Die Untersuchung während der Planung geht nur so tief, wie es zur Festlegung der Knotengrenzen nötig ist: Es werden strukturelle Abfragen (Dateien und Zeilenanzahl, Aufrufbeziehungen, Abhängigkeitskanten, Manifesteinträge) verwendet, um zu antworten, ohne Funktionsimplementierungen zu lesen. Das Verstehen der Implementierung ist Aufgabe der Knoten-Unteragenten.

Modulübergreifende Fakten (wer ruft ein Symbol auf, wovon hängt ein Modul ab, wie groß ist eine Gruppe von Dateien mit ihren Abhängigkeiten) werden bei Bedarf mit Spracherkennungsservern, ast-grep oder Suche ermittelt. Es wird nicht der gesamte Quellcode gelesen, um sie abzuleiten. Einmal gefundene Fakten werden zur Wiederverwendung notiert: Vom Hauptagenten oder Untersuchungs-Unteragenten gefundene Fakten werden in das refine-Ergebnis oder eine note des relevanten Knotens geschrieben. Knoten-Unteragenten listen neu entdeckte modulübergreifende Fakten in ihrem Bericht auf. Der Hauptagent notiert sie im refine des downstream-Knotens, der sie verwenden wird. Wenn der downstream-Knoten mit der Arbeit beginnt, schaut er sich zunächst diese Notizen an. Wenn die Notizen unzureichend sind oder möglicherweise veraltet (weil der relevante Code durch nachfolgende Knoten geändert wurde), wird erneut recherchiert.

Anschließend wird das „Schlüsseldesign“ bestimmt und in den Plan aufgenommen:

• Zielverhalten und Nicht-Ziele;
• Direkt wiederverwendbare bestehende Implementierungen, Abhängigkeiten oder Plattformfunktionen;
• Funktions- und Code-Zuordnung;
• Schnittstellen, Datenstrukturen und Architekturbeschränkungen, die knotenübergreifend konsistent sein müssen;
• Gemeinsame Ressourcen und Integrationsbedingungen.

Es wird nur das Design festgelegt, das für die knotenübergreifende Zusammenarbeit notwendig ist. Die interne Implementierung der Knoten wird den Knoten-Unteragenten überlassen. Es wird keine Abstraktion für zukünftige Anforderungen hinzugefügt und keine bestehenden Fähigkeiten dupliziert.

3. DAG-Aufteilung

• Knotengranularität: Ein Knoten hat die Größe eines unabhängig abnahmefähigen Verhaltens und enthält die Integration, die es ausführbar und verifizierbar macht. Konfiguration, Gerüst und Dokumentation werden in den Knoten integriert, wenn sie nur von einem Knoten verwendet werden. Wenn sie von mehreren Knoten verwendet werden, werden sie als vorgelagerter Knoten ausgegliedert. Hochgekoppelte Arbeiten, deren Aufteilung einen nicht überprüfbaren Zwischenzustand oder viele doppelte Änderungen erzeugen würde, werden zu einem Knoten zusammengefasst. Gering gekoppelte Arbeiten werden zur Parallelisierung aufgeteilt. Es wird nicht gewaltsam aufgeteilt, um die Parallelität zu erhöhen.
• Punktweise Überprüfung: Wenn ein Knoten viele Dateien oder Einträge abdecken muss, werden die Prüfpunkte und die punktuellen Abnahmekriterien im Voraus festgelegt. Bereiche, die unabhängig überprüft werden können, werden parallel von schreibgeschützten Unteragenten bearbeitet. Die Lücken werden zusammengefasst, bevor mit der Implementierung begonnen wird. Wenn vorhandene Prüfergebnisse noch gültig sind, werden sie direkt wiederverwendet und nicht erneut gescannt.
• Abhängigkeiten: Abhängigkeiten werden nur geschrieben, wenn der downstream-Knoten den Code, die Entscheidung oder das verifizierte Verhalten des upstream-Knotens tatsächlich benötigt oder wenn ein Fehlschlagen des upstream-Knotens den downstream-Knoten ungültig machen würde. Wenn die gemeinsame Schnittstelle bereits im Schlüsseldesign festgelegt ist und beide Seiten unabhängig implementieren und testen können, wird keine Abhängigkeit geschrieben. Dies ermöglicht Parallelität; die tatsächliche Integration wird durch die Integrationsverifizierung überprüft. Es werden keine Abhängigkeiten erfunden, um die Reihenfolge zu steuern.
• Konflikte: Knoten, die keine Abhängigkeit haben, aber nicht sicher gleichzeitig ausgeführt werden können, werden als konfliktbehaftet markiert: Änderungen, die sich logisch gegenseitig beeinflussen, gemeinsame Laufzeitressourcen (Datenbank, Ports), Ressourcen, die seriell zugewiesen werden müssen (Migrationsnummern). Normale überlappende Änderungen an derselben Datei gelten nicht als Konflikt. Sie erlauben Parallelität und werden durch den Git-Merge behandelt. Nur wenn die Überschneidungen konzentriert sind und die Merge-Kosten deutlich höher sind als eine serielle Ausführung, wird ein Konflikt markiert.
• Lösungen, die noch experimentell bestimmt werden müssen: Erstelle einen Untersuchungsknoten, der Schlussfolgerungen liefert. Der downstream-Knoten hängt von diesem ab.

Jeder Knoten wird gemäß der Vorlage in Schritt 4 geschrieben. Bei der Planung werden goal, scope, verify, stop und refine geschrieben. Die steps werden vom Knoten-Unteragenten bei Arbeitsbeginn gemäß refine verfeinert (Schritt 5). Schritte, die bei der Planung bereits festgelegt werden können, können vorab geschrieben werden.

• goal: Ein bis zwei Sätze, welches Verhalten nach der Fertigstellung eintritt.
• scope: Dateien oder Verzeichnisse, die geändert werden dürfen, Teile, die explizit nicht geändert werden dürfen, sowie einzuhaltende Schlüsseldesigns und Geschäftsrandbedingungen.
• verify: Beobachtbare Abnahmeergebnisse und direkt ausführbare, reale Befehle. Dies umfasst bestehende Wächter, die von den Änderungen des Knotens betroffen sind (z. B. Dokumentationsumfang, Code-Komplexität, Schichtungs- und Vertragsprüfungen). Bevorzugt werden schmale Einstiegspunkte verwendet. Wenn es keinen schmalen Einstiegspunkt gibt, wird eine vollständige Prüfung durchgeführt. Die vollständige Prüfung wird nicht gleichzeitig mit anderen Verifizierungen ausgeführt.
• stop: Knotenspezifische Bedingungen für einen Stopp und Bericht, z. B. „Zugehörigkeit kann nicht nach Regel bestimmt werden“, „Eine bestimmte Schnittstelle existiert nicht“. Allgemeine Bedingungen sind bereits in der Zuweisungsanweisung enthalten und werden nicht wiederholt.
• refine: Schreibe die Punkte, die für die steps geklärt werden müssen, als ausführbare Abfragen, z. B. „Liste alle Einträge unter X-Präfix und ihre Abhängigkeiten von nicht verarbeiteten Modulen auf“, „Liste alle Aufrufer von Y auf“. Diese werden vom Knoten-Unteragenten im ersten Teil seiner Arbeit abgeschlossen. Wenn bei der Planung oder Untersuchung bereits Schlussfolgerungen gezogen wurden, werden diese direkt in refine geschrieben und als „bereits geprüft“ markiert. Der Unteragent verwendet sie direkt und wiederholt die Recherche nicht. refine enthält nur noch nicht beantwortete Punkte als Abfragen. Wenn es nichts zu klären gibt, schreibe „Keine“. (None)
• steps: Geordnete Schritte. Jeder Schritt macht genau eine überprüfbare Sache. Schreibe auf Modulebene, Befehlsebene, Schnittstellenebene: Was wird getan, wo wird es getan, wie ist das externe Verhalten? Funktionsdetails werden nur an den Grenzen geschrieben: Wenn eine Datei auf verschiedene Knoten aufgeteilt werden muss oder wenn die Zugehörigkeit einer Funktion umstritten ist, liste die Funktionen auf beiden Seiten der Grenze auf.

Bestimmte Werte, Bedingungen und Grenzen aus Quellmaterialien und dem Schlüsseldesign werden direkt in die relevanten Knoten geschrieben und nicht dem Unteragenten zur Ableitung überlassen. Dateien, Symbole und Befehle müssen aus dem tatsächlichen Code stammen. Sie dürfen nicht erfunden werden. Die folgenden Formulierungen müssen geändert werden:

• Nicht ausführbare Beschreibungen wie „nach Ermessen implementieren“, „Grenzfälle behandeln“.
• Abnahmekriterien, die nur den Implementierungsakt wiederholen, z. B. „hat X implementiert“.
• Verhaltensabnahmen, die nur durch Dateiexistenz, Importierbarkeit oder Stichwortsuche nachgewiesen werden.
• Klassifizierungen oder Entscheidungen, die nur Regelnamen oder Dokumentationskapitel zitieren (z. B. „nach D7 entscheiden“), ohne Standardaktionen und Ausnahmebedingungen zu schreiben.

Vor der Zuweisung wird der Plan überprüft und zwei Fragengruppen beantwortet.

Werden die globalen Abnahmekriterien nach Abschluss des Plans zwangsläufig erfüllt? Suche nach Lücken in den folgenden Punkten:

1. Der Umfang wird aus tatsächlichen Quellen aufgezählt, nicht nur aus den Anforderungen abgeleitet: betroffener Code, Konfiguration, Dateien außerhalb des Versionierungs-Repositorys und lokaler Maschinenzustand, Installations- und Bereitstellungsmethode, andere Laufzeitplattformen, externe Aufrufer. Jeder Punkt ist genau einem Knoten zugeordnet oder wird als Nicht-Ziel festgelegt.
2. Jede Verifizierung ist haltbar: Sie kann in der Zielumgebung ausgeführt werden; sie schreibt während der Ausführung keine Produktionsdaten oder externen Systeme; wenn ein Schreiben erforderlich ist, wird im Knoten die Isolationsmethode angegeben; das Bestehen der Verifizierung impliziert die entsprechende Abnahmeschlussfolgerung; das verwendete Werkzeug selbst wurde verifiziert.
3. Zeitweilige Ausnahmen, Kompatibilitätsschichten, Übergangsdaten und -werkzeuge, die der Plan einführt, haben einen Knoten, der für ihre Entfernung oder Regularisierung verantwortlich ist.
4. Pfade, die externe Systeme schreiben, Produktionsumgebungen umschalten oder nur auf anderen Plattformen ausgeführt werden, haben vor der Auslieferung mindestens einen Knoten, der einmal tatsächlich in der realen Umgebung ausgeführt wird.
5. Die Schnittstellen und die Architektur zwischen den Knoten sind konsistent; Abhängigkeiten und Konflikte sind korrekt und vollständig; es gibt einen Knoten, der für die Integration zwischen den Knoten verantwortlich ist; das refine jedes Knotens kann die steps ermitteln, und alle verify können ausgeführt werden.

Lücken werden als Knoten ergänzt. Wenn die Ergänzung nicht möglich ist oder die Kosten der Ergänzung eine Entscheidung des Benutzers erfordern, wird dies als „Vollständigkeitslücke“ in den Plan aufgenommen und dem Benutzer zur Entscheidung vorgelegt.

Verschwendet das Design Zeit?

6. Jeder Knoten hat einen downstream-Abnnehmer seiner Ergebnisse; die Verifizierung zählt auch. Knoten ohne Abnehmer werden gelöscht.
7. Knoten, die eine Benutzerentscheidung oder -anwesenheit erfordern oder das bestehende Verhalten ändern, lassen andere Knoten nicht warten. Wenn ein downstream-Knoten auf sie warten muss, werden sie in einen Teil, der das Verhalten nicht ändert (zuerst erledigt), und einen Teil, der das Verhalten ändert (später erledigt), aufgeteilt.
8. Eine gemeinsame Fähigkeit oder ein gemeinsames Werkzeug, das von mehr als zwei Knoten verwendet wird, wird als upstream-Knoten ausgegliedert. Die Knoten führen es nicht jeweils separat aus. Für jeden Knoten wird überprüft, womit seine verify bewiesen wird. Wenn zwei oder mehr Knoten dieselbe Verifizierungsmethode verwenden (Alt-Neu-Vergleich, Playback, Artefaktvergleich usw.), wird auch diese als upstream-Werkzeugknoten ausgegliedert. Die verify dieses Knotens enthält den Nachweis, dass das Werkzeug einen Unterschied bei einer bekannten abweichenden Probe meldet. Wenn zwei oder mehr Knoten wiederholt auf dasselbe große Dokument (Liste, Zuordnungstabelle, Entscheidungsdokument) zugreifen müssen, das Projekt aber keinen Abfrageeinstiegspunkt bietet, wird ebenfalls ein upstream-Knoten erstellt, um den Abfrageeinstiegspunkt bereitzustellen.
9. Schätze das Lese- und Änderungsvolumen für jeden Knoten (basierend auf Dateien im scope zuzüglich des noch nicht verarbeiteten Codes, von dem er abhängt). Wenn das Volumen zu groß ist, als dass ein Unteragent es zuverlässig bewältigen könnte, oder wenn es sich über nicht zusammenhängende Module erstreckt, die unabhängig voneinander abgenommen werden könnten, teile den Knoten auf. Wenn die Kohäsion eng ist und eine Aufteilung einen nicht überprüfbaren Zwischenzustand erzeugen würde, teile auch bei großem Volumen nicht auf. Die Zeilenanzahl dient nur als Entscheidungshilfe; es gibt keinen festen Schwellenwert. Wenn eine Schätzung nicht möglich ist, schreibe die zu berechnenden Inhalte in das refine. Der Knoten-Unteragent schätzt sie im ersten Teil seiner Arbeit. Die Aufteilungsmethode muss vor der Erstellung des Worktrees festgelegt werden. Entsprechend wird in Schritt 5 zunächst ein Untersuchungs-Unteragent zur Schätzung entsandt.
10. Es gibt keine Doppelimplementierung bestehender Fähigkeiten, keine unnötige Aufteilung oder kein Overengineering. Knoten, die sicher parallelisiert werden können, sind nicht serialisiert.

Wenn der Plan nicht mehr als 5 Knoten umfasst, wird die Prüfung vom Hauptagenten durchgeführt. Bei mehr als 5 Knoten wird der Entwurf zunächst gemäß Schritt 4 in .dag/<plan-id>.md geschrieben. Anschließend wird ein schreibgeschützter Unteragent zur Prüfung entsandt. Dieser erhält nur den Plan, die Anforderungen und die Codepositionen, nicht die Argumentation des Hauptagenten:

Führe eine schreibgeschützte Prüfung von <plan-pfad> durch. Ändere keine Dateien und weise keine anderen Agenten zu. Anforderungen: <ursprüngliche Anforderungen oder deren Position>. Code: <integrations-wt>. Prüfe Punkt für Punkt gemäß den folgenden Kriterien: <obige Punkte 1–10 im Original>. Berichte nur: Lücken für die Zielerreichung, Zeitverschwendung im Design, Punkte, die eine Benutzerentscheidung erfordern. Gib für jeden Punkt die Position, den Beweis (Datei:Symbol, Befehlsausgabe oder Plan-Originaltext) und einen minimalen Änderungsvorschlag an. Unterscheide zwischen identifizierten Problemen und Spekulationen.

Der Hauptagent ändert nur Probleme mit konkretem Nachweis.

4. Plan speichern

Schreibe den Plan in die Datei im Hauptarbeitsbereich .dag/<plan-id>.md. Lege ihn nicht in einem Worktree ab, um ein Einchecken zu vermeiden. Wenn .dag/ nicht von Git ignoriert wird, füge es zu .git/info/exclude hinzu.

# <plan-id>

- Ziel:
- Globale Abnahmekriterien:
- Nicht-Ziele:
- Annahmen:
- Vollständigkeitslücke: <Teile, die nach Abschluss des Plans nicht garantiert erreicht werden können, und die Entscheidung des Benutzers; falls keine, schreibe „Keine“ (None)>
- Schlüsseldesign:
- Plan-Status: in Arbeit (in progress)
- Integrations-Worktree: <Pfad>   Branch: dag/<plan-id>   Start: <sha>
- Schnittstellenprotokoll: `.dag/<plan-id>-interfaces.md`

## Knoten

### N1 <Titel>
#### goal
#### scope
#### steps
<Wird vom Knoten-Unteragenten bei Arbeitsbeginn verfeinert>
#### verify
#### stop
#### refine
#### state
- Abhängigkeiten: Keine
- Konflikte: Keine
- Status: pending
- Worktree:   Branch:   Commit:

## Ausführungsprotokoll
- N1: <Merge-Commit-Sha> <Ergebnis in einem Satz>. <Nachbesserungen, Ausnahmen oder offene Punkte; falls keine, nicht schreiben>

Die Schnittstellenprotokolldatei wird zusammen mit dem Plan abgelegt. Nach dem Zusammenführen jedes Knotens wird ein Abschnitt angehängt. Knoten-Unteragenten können sie schreibgeschützt einsehen:

## N1 (<Merge-Commit-Sha>)
- <Schnittstelle, Benennung und Position>: <Form und Verwendung>

Das Ausführungsprotokoll enthält nur Ergebnisse und offene Punkte. Externe Schnittstellen werden in der Schnittstellenprotokolldatei festgehalten. Modulübergreifende Fakten werden im refine der downstream-Knoten notiert, die sie verwenden. Details zu Unterschieden verbleiben in der Commit-Beschreibung und der Berichtsdatei des Knotens.

goal bis refine werden an die Knoten-Unteragenten weitergegeben. state wird nur vom Hauptagenten verwendet.

Statuswerte:

• pending: Noch nicht zugewiesen.
• running: Der Unteragent implementiert oder bessert nach.
• submitted: Der Unteragent hat einen Commit erstellt und wartet auf die Integration.
• done: Wurde in den Integrations-Branch gemerged und vom Hauptagenten abgenommen.
• blocked: Kann nicht fortgesetzt werden. Der Grund wird im Ausführungsprotokoll festgehalten.

Der Plan wird nur vom Hauptagenten geändert. Jede Statusänderung wird sofort aktualisiert. Der Plan ist die Grundlage für die Fortsetzung der Arbeit über mehrere Sitzungen hinweg.

Nach dem Speichern werden dem Benutzer kurz die Knoten, Abhängigkeiten, parallel ausführbare Knoten, Vollständigkeitslücken und alle punkte, die eine Benutzerentscheidung erfordern, angezeigt (alle auf einmal, nicht in mehreren Runden). Wenn der Benutzer nur einen Plan anfordert, wird hier angehalten; andernfalls wird mit der Ausführung fortgefahren.

5. Dynamische Zuweisung

pending-Knoten, deren Abhängigkeiten alle done sind und die keine Konflikte mit running/submitted-Knoten haben, sind bereit. Alle bereiten Knoten werden in einer Nachricht parallel zugewiesen. Es gibt kein festes Parallelitätslimit; die tatsächliche Parallelität hängt vom Agentenwerkzeug und der Umgebung ab. Sobald ein Knoten done ist, werden sofort erneut bereite Knoten gesucht und zugewiesen, ohne auf das Ende anderer unabhängiger Knoten zu warten.

Vor der Zuweisung jedes Knotens führt der Hauptagent nur eine vorbereitende Prüfung durch: Er listet die upstream-Entscheidungen, Schnittstellen, Benennungen und Regeln auf, die dieser Knoten verwendet, und stellt sicher, dass sie alle im HEAD des Integrations-Branches enthalten sind. Wenn einer dieser Punkte noch von einem running- oder pending-Knoten geändert wird, wird diesem Knoten eine Abhängigkeit hinzugefügt und er wird vorerst nicht zugewiesen.

Die Abfragen in refine werden vom Knoten-Unteragenten im ersten Teil seiner Arbeit abgeschlossen. Der Hauptagent führt sie nicht selbst aus. Es gibt zwei Ausnahmen, bei denen zunächst gemäß Schritt 2 ein schreibgeschützter Untersuchungs-Unteragent mit den Ergebnissen beauftragt wird:

• Ein Knoten muss möglicherweise in mehrere parallel ausführbare Knoten aufgeteilt werden. Die Aufteilungsmethode muss vor der Erstellung des Worktrees festgelegt werden: Der Untersuchungs-Unteragent schätzt das Volumen und die Kopplung gemäß refine. Der Hauptagent teilt gemäß Schritt 3, Punkt 9 auf und weist dann die Knoten separat zu.
• Mehrere bereite Knoten müssen dieselbe Frage beantworten: Ein Untersuchungs-Unteragent wird entsandt, um sie gemeinsam zu beantworten, anstatt einen pro Knoten.

Dann wird ein Knoten-Worktree vom aktuellen HEAD des Integrations-Branches (dem letzten abgenommenen Integrations-Commit) erstellt. Pfad und Branch werden in den Plan geschrieben und der Status auf running gesetzt:

git -C <integrations-wt> worktree add "../<repo>-<plan-id>-<node-id>" -b "dag-node/<plan-id>/<node-id>" HEAD

Wenn die Verifizierung von Installationsschritten abhängt, wird der Knoten-Unteragent in der Anweisung aufgefordert, die Installation zuerst in seinem eigenen Worktree durchzuführen.

Die Anweisung an den Knoten-Unteragenten wird in der folgenden Reihenfolge organisiert und enthält nur diese Inhalte:

1. Worktree-Pfad und Branch.
2. Der Originaltext von goal, scope, steps (falls vorhanden), verify, stop und refine des Knotens aus dem Plan.
3. note (nur in der Anweisung, nicht im Plan):
   • Absoluter Pfad zur Schnittstellenprotokolldatei. Gib nur den Pfad an; wiederhole keine upstream-Schnittstellen in der Anweisung.
   • Knotenspezifische Ergänzungen: Vom Hauptagenten festgelegte Grenzen und Entscheidungen, Originaltext der Benutzerentscheidung, nur für diesen Knoten relevante upstream-Fakten, bekannte Fallstricke, Befehle zum Nachschlagen von Informationen. Allgemein nicht mehr als etwa 20 Zeilen. Wenn die Informationen mehr als etwa 200 Zeilen umfassen oder nur ein Teil benötigt wird, gib Auszüge oder Abfragebefehle an, nicht nur den Dateipfad. Projektbeschreibungsdateien werden vom Unteragenten automatisch geladen; darin bereits geschriebene Regeln werden nicht wiederholt. Wenn verify einen Befehl mit sehr langer Ausgabe enthält, gib an, welcher Teil zu betrachten ist (z. B. die Zusammenfassungszeilen am Ende).
   • Pfad zur Berichtsdatei: .dag/<plan-id>-reports/<node-id>.md (absoluter Pfad im Hauptarbeitsbereich).
4. Die folgenden Anforderungen, platziert am Ende der Anweisung:

Arbeite nur im angegebenen Worktree. Greife nicht auf den Integrations-Branch, die Branches oder Worktrees anderer Knoten zu. Weise keine anderen Agenten zu. Ändere keine Dateien unter .dag/, mit Ausnahme der in der Anweisung angegebenen Berichtsdatei. Lese keine Dateien unter .dag/, mit Ausnahme der Schnittstellenprotokolldatei. Die Start- und Endschritte, die in der Projektbeschreibungsdatei für die Hauptsitzung geschrieben wurden (Plan lesen, Statusprüfung ausführen, Plan wiederherstellen usw.), gelten nicht für dich.

Arbeite in zwei Phasen. Erste Phase: Kläre die Fakten gemäß refine (in refine als „bereits geprüft“ markierte Schlussfolgerungen direkt verwenden, nur die noch nicht beantworteten Punkte recherchieren). Lege die steps fest (auf Modulebene, Befehlsebene, Schnittstellenebene; wenn eine Datei mit einem anderen Knoten geteilt werden muss, liste die Funktionen auf beiden Seiten der Grenze), ohne goal, Schnittstellen und scope zu ändern. Schätze das Lese- und Änderungsvolumen. Halte in einem der folgenden Fälle an und gib eine Zusammenfassung von nicht mehr als etwa 30 Zeilen zurück (Steps-Entwurf, Schätzung, vorgeschlagene Aufteilung, punkte, die eine Entscheidung des Hauptagenten oder Benutzers erfordern), und warte auf eine Antwort: Grenze oder Zugehörigkeit kann nicht bestimmt werden; eine Änderung einer knotenübergreifenden Schnittstelle oder einer Datei außerhalb des scope ist erforderlich; der tatsächliche Code widerspricht der Knotenbeschreibung; das Volumen ist zu groß für einen Unteragenten oder erstreckt sich über Module, die unabhängig voneinander abgenommen werden könnten; eine in stop aufgeführte Bedingung tritt ein. Wenn keiner dieser Fälle eintritt, halte nicht an, sondern fahre direkt mit der zweiten Phase fort. Füge die Zusammenfassung in den endgültigen Bericht ein.

Zweite Phase: Implementiere gemäß den steps. Entscheide eigenständig über die lokale Implementierungsweise, ohne goal, Schnittstellen und scope zu ändern. Führe die Befehle aus verify aus. Wenn sie bestanden werden, committe alle Änderungen dieses Knotens. Die Commit-Nachricht lautet <plan-id>/<Knoten>: <Zusammenfassung>. Stelle sicher, dass git status sauber ist. Committe nicht, wenn die Verifizierung fehlschlägt. Wenn in der zweiten Phase einer der in der ersten Phase aufgeführten Stopp-Fälle eintritt oder der tatsächliche Umfang die Schätzung der ersten Phase um etwa das Doppelte übersteigt, halte an und berichte. Erweitere die Arbeit nicht eigenständig. Der bereits abgeschlossene Teil kann mit den anwendbaren Befehlen aus verify committet werden, wenn er besteht. Andernfalls verbleiben die Änderungen im Worktree ohne Commit. Liste die abgeschlossene und die verbleibende Arbeit im Bericht auf.

Schreibe nach Abschluss oder Stopp den vollständigen Bericht (Änderungszusammenfassung, Verifizierungsbefehle und vollständige Ergebnisse, Vergleichsunterschiede, Abweichungserklärungen) in die Berichtsdatei. Gib an den Hauptagenten nur eine Zusammenfassung von nicht mehr als etwa 40 Zeilen zurück: Status (DONE: abgeschlossen und verifiziert; DONE_WITH_CONCERNS: abgeschlossen mit Bedenken; BLOCKED: kann nicht abgeschlossen werden oder angehalten), Commit-Sha, eine Zeile Verifizierungsergebnis, neue oder geänderte externe Schnittstellen, neu entdeckte knotenübergreifende Fakten (z. B. von welchen Modulen ein Symbol noch verwendet wird, die tatsächliche Form einer Schnittstelle), Grund für Bedenken oder Blockade, punkte, die entschieden werden müssen.

Wenn der Unteragent in der ersten Phase mit einer Zusammenfassung anhält, überprüft der Hauptagent die Grenzen und die zu entscheidenden punkte (bei Bedarf wird der Benutzer befragt). Die bestätigten steps werden in den Plan zurückgeschrieben. Dann wird die Fortsetzungsfähigkeit des Agentenwerkzeugs genutzt (Claude Code's SendMessage; Codex sendet nachfolgende Eingaben an denselben Agenten), um denselben Unteragenten mit der zweiten Phase fortfahren zu lassen. Es wird kein neuer Agent entsandt, um das erneute Lesen des bereits gelesenen Codes zu vermeiden. Bei einem Aufteilungsvorschlag wird gemäß der Regel „Plan selbst ist fehlerhaft“ aus Schritt 6 aufgeteilt: Der ursprüngliche Agent fährt mit einem Teil fort, die restlichen Teile werden als neue Knoten ab Schritt 5 zugewiesen. Wenn der ursprüngliche Agent nicht fortgesetzt werden kann, wird ein neuer Agent im selben Worktree entsandt, zusammen mit der Zusammenfassung.

Nachdem der Unteragent einen Commit zurückgegeben hat, wird die Commit-Sha in den Plan geschrieben und der Status auf submitted gesetzt. Fahre mit Schritt 6 fort.

Warteregeln (gelten auch für Untersuchungs- und Prüf-Unteragenten):

• Wenn es konkrete, nicht in Konflikt mit dem Umfang des Unteragenten stehende unabhängige Arbeit gibt (z. B. Integration von bereits eingereichten Knoten), erledige diese zuerst. Wenn nicht, tritt das native Warten ein.
• Claude Code verwendet die Benachrichtigung über die Fertigstellung von Hintergrundagenten oder natives Warten. Codex ruft das Agentenwerkzeug direkt auf, nicht über functions.exec oder functions.wait; setze wait_agent auf timeout_ms=600000. Wenn der Werkzeugparameter diesen Wert nicht unterstützt, verwende die längste zulässige Wartezeit. Wenn das Werkzeug nur Batch-Ergebnisse zurückgeben kann, verarbeite diese entsprechend seiner Fähigkeiten. Simuliere keine nicht existierenden Benachrichtigungen.
• Verwende keine Schleifen mit kurzem sleep, keine Abfragen der Agentenliste oder wiederholtes Überprüfen des Git-Status als Ersatz für das Warten. Verkürze die Wartezeit auch nicht, um Fortschrittsaktualisierungen zu senden.
• Verarbeite Ergebnisse oder Benutzernachrichten sofort nach Erhalt. Ein Timeout bedeutet nicht zwangsläufig einen Fehlschlag. Warte weiter. Weise keine noch ausgeführten Knoten erneut zu.

6. Schrittweise Knotenintegration und -abnahme

Der Hauptagent integriert im Integrations-Worktree jeweils einen submitted-Knoten, während andere Unteragenten weiterarbeiten. Der Bericht des Unteragenten wird nicht direkt übernommen:

1. git -C <integrations-wt> diff --stat HEAD...<knoten-branch>: Die geänderten Dateien liegen alle innerhalb des Knoten-scope. Der git status des Knoten-Worktrees zeigt keine verbleibenden nicht-committierten Änderungen. Überprüfe dann das vollständige Diff für Dateien, die mit anderen Knoten geteilt werden (öffentliche Module, Konfiguration, Wächter-Baselines, Manifeste, Vertragstests), um die Übereinstimmung mit dem goal und dem Schlüsseldesign sicherzustellen. Beurteile den neuen Code des Knotens anhand der Verifizierung in Schritt 3 und des tatsächlichen Verhaltens; lies ihn nicht Zeile für Zeile. Wenn Details benötigt werden, lese die relevanten Abschnitte in der Berichtsdatei.
2. Merge, aber committe noch nicht:

   git -C <integrations-wt> merge --no-ff --no-commit "dag-node/<plan-id>/<node-id>"
   

3. Führe im Integrations-Worktree die Befehle aus der verify des Knotens sowie die von dem Merge betroffenen Integrationstests aus. Gleiche die Ergebnisse Punkt für Punkt mit den Abnahmeergebnissen in verify ab. Verifiziere mindestens ein Verhalten tatsächlich. Neue Fehlschläge von betroffenen Wächtern werden in diesem Knoten behoben und nicht für die finale Abnahme aufbewahrt. Bestehende Fehlschläge werden separat dokumentiert. Die Toleranz oder Baseline wird nicht erweitert. Nicht jedes Mal die vollständige Testsuite ausführen.
4. Alle Prüfungen bestanden: git -C <integrations-wt> commit --no-edit. Markiere den Knoten als done. Schreibe eine Zeile im Ausführungsprotokoll. Füge die externen Schnittstellen zur Schnittstellenprotokolldatei hinzu. Schreibe knotenübergreifende Fakten in das refine des downstream-Knotens, der sie verwenden wird. Kehre dann zu Schritt 5 zurück, um neu freigegebene Knoten zuzuweisen.

Bei Abnahmen, die eine Listenabdeckung erfordern (wie Checklisten), müssen die bestätigten Schlussfolgerungen, die noch zu prüfenden Punkte und die Lücken Punkt für Punkt dokumentiert werden. Ein Knoten kann erst dann als done markiert werden, wenn der gesamte deklarierte Umfang überprüft wurde und die Abnahmekriterien erfüllt. Dateiexistenz, nicht-leerer Inhalt oder stichprobenartiges Bestehen ersetzen keine vollständige Abdeckung.

Wenn ein Merge zu Konflikten führt, werden gewöhnliche Überlappungen mit klarer Absicht beider Seiten direkt vom Hauptagenten gelöst. Anschließend wird Schritt 3 ausgeführt.

Bei anderen Konflikten oder nicht bestandenen Prüfungen wird der unvollständige Merge rückgängig gemacht (git -C <integrations-wt> merge --abort). Der Integrations-Branch bleibt auf dem letzten abgenommenen Commit. Der Commit des Knotens bleibt auf dem Knoten-Branch. Die Behandlung richtet sich nach der Ursache des Problems:

• Implementierungsfehler des Knotens: Setze den Status des Knotens zurück auf running. Gib das konkrete Problem an den ursprünglichen Knoten-Unteragenten zur Behebung im ursprünglichen Worktree und zur erneuten Einreichung zurück. Wenn der ursprüngliche Agent nicht fortgesetzt werden kann, weise einen neuen Agenten im selben Worktree zu. Der Hauptagent übernimmt standardmäßig nicht selbst die Neuschreibung der Knotenimplementierung.
• Konflikt, weil der Knoten die neuesten Integrationsergebnisse berücksichtigen muss: Lasse den Knoten-Unteragenten den Branch dag/<plan-id> in seinem eigenen Worktree mergen, die Konflikte lösen, erneut verifizieren und committen.
• Knotenübergreifende Schnittstellen- oder Logikkonflikte: Der Hauptagent bestimmt das korrekte Design, aktualisiert das Schlüsseldesign des Plans und die relevanten Knoten und übergibt es dann an die relevanten Knoten-Unteragenten zur Anpassung.
• Der Plan selbst ist fehlerhaft (scope, steps, Abhängigkeiten oder verify stimmen nicht mit dem tatsächlichen Code überein): Ändere basierend auf den neu entdeckten Code-Fakten nur die betroffenen Knoten, Abhängigkeiten und Abnahmen. Behalte die gültigen, abgeschlossenen Ergebnisse bei. Entwerfe den gesamten DAG nicht neu. Wenn die Änderung die globalen Abnahmekriterien oder die Nicht-Ziele betrifft, frage zuerst den Benutzer.
• Der Unteragent meldet DONE_WITH_CONCERNS: Wenn die Bedenken die Abnahmekriterien beeinflussen, behandle sie als nicht bestanden. Andernfalls integriere sie wie gewohnt und dokumentiere die Bedenken im Ausführungsprotokoll.
• Der Unteragent hält an, weil der tatsächliche Umfang die Schätzung übersteigt: Wenn der bereits committete Teil unabhängig abgenommen werden kann, ändere goal, scope und verify des Knotens auf den abgeschlossenen Teil und integriere ihn gemäß diesem Schritt. Behandle die verbleibende Arbeit als neue Knoten gemäß der Regel „Plan selbst ist fehlerhaft“ und weise sie ab Schritt 5 zu. Wenn der bereits committete Teil nicht unabhängig abgenommen werden kann, integriere ihn nicht. Lasse den Knoten auf running. Schreibe die verbleibende Arbeit in die steps des Knotens. Weise einen neuen Agenten im selben Worktree zu, der auf den vorhandenen Ergebnissen aufbaut.
• Der Unteragent meldet BLOCKED oder der Knoten kann nicht fortgesetzt werden: Markiere den Knoten als blocked und dokumentiere den genauen Grund. Weise keine von ihm abhängigen Knoten zu. Fahre mit anderen Knoten fort. Wenn es keine bereiten oder laufenden Knoten mehr gibt, aber noch blocked-Knoten vorhanden sind, halte an und melde dem Benutzer den Blockierungsgrund. Warte auf die Entscheidung des Benutzers, bevor du fortfährst. Gehe nicht zu Schritt 7 über.

Nachdem ein Knoten done ist, bereinige seinen Worktree und Branch. Wenn der Worktree nicht-committierte Änderungen enthält, halte an und überprüfe sie. Verwende nicht --force oder -D:

git -C <knoten-wt> status --porcelain
git -C <integrations-wt> worktree remove "<knoten-wt>"
git -C <integrations-wt> branch -d "dag-node/<plan-id>/<node-id>"

blocked-, nachbesserungsbedürftige oder statusunklare Knoten behalten ihren Worktree und Branch.

7. Gesamtprüfung

Nachdem alle Knoten done sind, wird ein schreibgeschützter Unteragent zur Prüfung der vollständigen Änderungen im Integrations-Branch entsandt:

Führe eine schreibgeschützte Prüfung aller Änderungen in <integrations-wt> zwischen <start-sha>..HEAD durch. Ändere keine Dateien und weise keine anderen Agenten zu. Prüfe anhand der folgenden Ziele, globalen Abnahmekriterien und Nicht-Ziele: Anforderungsabdeckung, Konsistenz knotenübergreifender Schnittstellen und Verhaltensweisen, Doppelimplementierung, von dem Schlüsseldesign abweichende Architektur, Korrektheitsfehler, verbleibender Debug- oder temporärer Code, Fehlen wichtiger Tests oder unzureichende Testabdeckung des behaupteten Verhaltens. Gib für jedes Problem die Position, den Beweis und die beteiligten Knoten an. Unterscheide zwischen identifizierten Problemen und Spekulationen. Liste separat die Punkte auf, die eine Benutzerentscheidung erfordern.

Füge der Anweisung das Ziel, die globalen Abnahmekriterien, die Nicht-Ziele und das Schlüsseldesign des Plans bei.

Nach der Überprüfung jedes Problems durch den Hauptagenten wird die Behebung entsprechend der Zuständigkeit geplant:

• Probleme, die eine Implementierung erfordern, werden als Reparaturknoten (z. B. F1) in den Plan aufgenommen und gemäß den Schritten 5–6 zugewiesen und integriert.
• Lokale, offensichtliche Kleinigkeiten (z. B. verbleibende Debug-Anweisungen) können vom Hauptagenten direkt im Integrations-Worktree geändert und committet werden.
• Punkte, die eine Benutzerentscheidung erfordern, werden nicht eigenständig entschieden, sondern in den Bericht aufgenommen.

8. Endgültige Abnahme und Bericht

Der Hauptagent führt im Integrations-Worktree die folgenden Prüfungen durch:

1. Überprüfe das vollständige Diff von <start-sha>..HEAD, um sicherzustellen, dass es keine Änderungen gibt, die über die Planziele hinausgehen.
2. Führe alle Verifizierungsbefehle aller Knoten sowie die Tests, Builds und Lint-Befehle des Projekts aus, die die geänderten Module abdecken.
3. Gleiche die globalen Abnahmekriterien Punkt für Punkt ab.

Wenn eine Prüfung fehlschlägt: Wenn das Problem innerhalb der Planziele liegt, repariere es gemäß der Zuständigkeitsregel aus Schritt 7 und führe die Prüfung erneut durch. Wenn das Problem außerhalb der Planziele liegt (z. B. ein bereits zu Beginn fehlgeschlagener Test), repariere es nicht, sondern dokumentiere es im Bericht. Nach Abschluss aller Prüfungen ändere den „Plan-Status“ auf „Abgeschlossen“ (Completed).

Der endgültige Bericht enthält: die abgeschlossenen Knoten und die entsprechenden Merge-Commits, die Ergebnisse der Prüfung und deren Behandlung, die Verifizierungsergebnisse, nicht abgeschlossene oder riskante Punkte, Punkte, die eine Benutzerentscheidung erfordern, den Pfad und Branch des Integrations-Worktrees, beibehaltene Knoten-Worktrees. Das Mergen in den Ziel-Branch und das Löschen des Integrations-Worktrees erfolgen nur auf Anfrage des Benutzers.