DWP-Spezifikation

Version 4.0.0. Status: Stabil. Dieses Dokument ist die normative Spezifikation für die Deep Work Plan (DWP) Methodik. Die Schlüsselwörter MUSS, DARF NICHT, SOLLTE, SOLLTE NICHT und KANN sind so zu interpretieren, wie in RFC 2119 beschrieben.

Additiv in 2.4.0, keine Breaking Changes. (1) Der Abschnitt Touched Surface — der Vertrag zwischen dem, was eine Aufgabe ändert, und dem, was validiert werden muss, mit Gate-Auswahl nach Risikoklasse (isoliert / Nahtstelle / geteilt-zentral / unbekannt); (2) die vollständige Validierung wird zu einer Endzustands-Anforderung, die im einzigen verpflichtenden Final Review des Plans läuft, mit expliziten Regeln zur Beweiswiederverwendung; (3) aufgaben-lokale Skills-Entscheidungen wandern in die erzeugende Aufgabe, und der Executive Report wird optional, auf Anfrage; (4) ein modus-bewusster create-Ablauf — der Trust-Modus materialisiert direkt, behält aber Analyse und Qualitätsprüfungen; (5) eine Lite-first-Plan-Materialisierung — der geführte create-Ablauf erzeugt direkt einen ausführbaren Lite-Plan anstelle eines nicht ausführbaren Entwurfs, der jederzeit zu einem Full-Plan befördert werden kann (siehe Lite-Pläne); und (6) eine explizite Kompatibilitätsmatrix: Pläne und Repositorys aus früheren Versionen bleiben konform.

Standard 4.0.0. Der Versionssprung richtet die Nummer des Standards an der Produktlinie aus — 2.x ist historisch, einen 3.x-Standard gibt es nicht — und ändert keine Anforderung gegenüber 2.4.0. Pläne und Repositories aus früheren Versionen bleiben konform.

Definition

Ein Deep Work Plan ist ein strukturiertes, reines Markdown-Artefakt, das eine komplexe Engineering-Aufgabe beschreibt, zerlegt in aufeinanderfolgende, prüfbare Arbeitseinheiten, entworfen, um von autonom arbeitenden KI-Coding-Agenten erstellt, ausgeführt und gepflegt zu werden.

DWP ist spec-driven: Der Plan ist die Spezifikation, und Agenten MÜSSEN gegen seine expliziten Akzeptanzkriterien und Validierungs-Gates ausführen, statt zu improvisieren. Die Spezifikation — nicht ein Chat-Verlauf — ist die dauerhafte Quelle der Wahrheit, sodass die Arbeit über Sitzungen und Agenten hinweg überprüfbar und wiederaufnehmbar ist. Es ist zugleich Harness Engineering, portabel gemacht: Der Kontext, die Steuerschleife, die Leitplanken und der wiederaufnehmbare Zustand, die einen Agenten verlässlich machen, werden als reines Markdown in das Repository selbst installiert, sodass jeder konforme Agent das Repository ohne werkzeugspezifisches Framework steuern KANN.

Create-Ablauf — ein Schritt, modus-bewusst

Der create-Ablauf erhebt Ziel, Kontext, Einschränkungen und Aufgaben-Gliederung einmal, führt seine Anforderungsanalyse durch (Umfang, Abhängigkeitsreihenfolge zwischen den Aufgaben, Auswahl der Validierung aus der Touched Surface, Proportionalitäts-Stufe) und materialisiert dann gemäß dem Modus, den der Entwickler gewählt hat:

• Geführter Modus (Standard). Der Ablauf materialisiert direkt einen Lite-Plan — einen kompakten, bereits ausführbaren Vorschlag mit inline {#task-N}-Aufgabendatensätzen, der in einem Durchgang überprüfbar ist — und bittet den Entwickler, ihn als Lite beizubehalten, zu einem Full-Plan zu befördern, Änderungen anzufordern oder zu stoppen. Es wird kein zwischengeschalteter, nicht ausführbarer Entwurf erzeugt.
• Trust-Modus (trust / auto). Der Ablauf materialisiert die gewählte Darstellung (Lite, oder Lite unmittelbar gefolgt von einer Beförderung zu Full) direkt, ohne Review-Schritt — der Entwickler hat darauf verzichtet. Die Anforderungsanalyse, die Abhängigkeitsreihenfolge und eine Plan-Qualitätsprüfung laufen dennoch: Trust verzichtet auf die Review, nicht auf die Analyse. Ein Trust-Modus-Plan wird als für unbeaufsichtigte Ausführung vorgenehmigt aufgezeichnet.

Beide Modi entscheiden das Format des Plans (Lite oder Full) als Teil derselben Anforderungsanalyse, niemals nachträglich. Siehe Lite-Pläne für den vollständigen Lebenszyklus von Darstellung, Erstellung und Auswahl sowie Beförderung.

Planstruktur

Ein Plan MUSS ein Verzeichnis unter .dwp/plans/ mit dem Namen PLAN_<slug>/ sein, in einer von zwei Darstellungen:

• Full. Das Verzeichnis MUSS README.md (Planübersicht, Ziel, Aufgabentabelle und Status), eine Datei je Aufgabe, benannt <n>.task_<slug>.md, und PROGRESS.md (ein laufendes Protokoll der Ausführung) enthalten.
• Lite. Kompakte, vollständig ausführbare Aufgabendatensätze leben inline in README.md hinter stabilen {#task-N}-Ankern anstelle separater Aufgabendateien — jeder Datensatz trägt weiterhin ein Ziel, eine Touched Surface, Akzeptanzkriterien, eine Validierung und ein Abschlussprotokoll. PROGRESS.md ist weiterhin ERFORDERLICH. Ein Lite-Plan KANN jederzeit zu Full befördert werden. Siehe Lite-Pläne für den vollständigen Lebenszyklus, statt ihn hier zu duplizieren.

Ein Plan KANN zusätzlich die maschinenlesbare Zustandsschicht tragen: manifest.json (statische Identität, einmal bei der Materialisierung geschrieben) und state.json (lebendiger aufgabenbezogener Ausführungszustand). Die Zustandsschicht ist für neue Pläne EMPFOHLEN und für unbeaufsichtigte Ausführung sowie für Agenten-Arbeitsbereiche ohne git ERFORDERLICH. Siehe Plan-Zustand.

Aufgaben-Anatomie

Aufgabendatei

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

Jede Aufgabendatei MUSS diese zehn Abschnitte enthalten, in dieser Reihenfolge:

1. Goal — eine Formulierung in einem Absatz, was die Aufgabe erreicht.
2. Context — Hintergrund, Links und warum diese Aufgabe existiert.
3. Touched Surface — der Vertrag zwischen dem, was die Aufgabe ändert, und dem, was validiert werden muss.
4. Steps — geordnete, konkrete auszuführende Handlungen.
5. Acceptance criteria — eine Checkliste von Bedingungen, die „erledigt” definieren.
6. Validation — Befehle oder Tests, die zur Verifizierung auszuführen sind, ausgewählt aus der Touched Surface.
7. Files — Pfade, die voraussichtlich erstellt oder geändert werden.
8. Dependencies — andere Aufgaben oder externe Voraussetzungen.
9. Risks — was schiefgehen könnte und Gegenmaßnahmen.
10. Completion & Log — eine Statusmarkierung plus chronologische Notizen.

Eine Aufgabe KANN zusätzlich einen Delta-Abschnitt enthalten (EMPFOHLEN für Brownfield-Verhaltensänderungen — siehe unten) sowie einen Rollback-Abschnitt (EMPFOHLEN für Migrationen, Infrastrukturänderungen oder Deployments).

Die Touched Surface

Die Touched Surface ist der Vertrag zwischen dem, was eine Aufgabe ändert, und dem, was validiert werden muss. Sie existiert, damit Validierung nach Wirkung ausgewählt wird, nicht nach Gewohnheit, und damit ein späterer Leser sehen kann, warum ein Gate gewählt wurde. Eine verhaltensändernde Aufgabe MUSS festhalten:

• Geplante Oberfläche — die Pfade, Module, Pakete oder Konfigurationen, die die Aufgabe zu ändern beabsichtigt, geschrieben vor dem Editieren.
• Tatsächliche Oberfläche — die abgeglichene Liste nach dem Editieren, entnommen aus dem echten Diff. Der Agent MUSS geplante und tatsächliche Oberflächen abgleichen, bevor er das Gate wählt.
• Betroffene Konsumenten — Module, Pakete oder Dienste, die von der tatsächlichen Oberfläche abhängen, soweit die dokumentierte Abbildung des Repositorys es feststellen kann. Wo sie es nicht kann, MUSS der Eintrag dies sagen.
• Risikoklasse — eine von: isoliert (auf ein Modul und seine Tests beschränkt); Nahtstelle (ändert einen Vertrag, Persistenz, Routing, Serialisierung, Authentifizierung oder Framework-Verdrahtung zwischen Kollaborateuren); geteilt/zentral (breit importiert oder eine Abhängigkeits-, Migrations-, Build-/Test-Konfigurations-, Schema- oder Toolchain-Änderung); unbekannt (die Abbildung fehlt, ist veraltet oder unverifiziert).
• Verwendete Test-Abbildung — welche dokumentierte Abbildung oder welches Werkzeug die Auswahl erzeugt hat.
• Gewähltes Gate und Begründung — die exakten Befehle und warum sie die tatsächliche Oberfläche abdecken.

Konfigurationsdateien, Schemata, Abhängigkeits-Manifeste, Templates, Fixtures, Migrationen und Agenten-Instruktionsdateien können Verhalten ändern und MÜSSEN nach ihrer Wirkung klassifiziert werden, niemals nach Dateiendung. Eine Aufgabe, die nur Prosa, Kommentare oder Recherche-Artefakte ändert, KANN die Oberfläche als nicht zutreffend deklarieren und führt dennoch die nicht-laufzeitbezogenen Prüfungen des Repositorys aus.

Der Delta-Abschnitt (Brownfield-Änderungen)

Die meisten reale Arbeit verändert bestehendes Verhalten, anstatt neues zu schaffen. Eine Aufgabe, die das Verhalten eines bestehenden Systems ändert, SOLLTE einen Delta-Abschnitt tragen, der die Änderung als expliziten Vorher/Nachher-Vertrag beschreibt, unter Verwendung von drei Listenüberschriften:

• ADDED — Verhalten, das nach der Aufgabe existiert und vorher nicht existierte.
• MODIFIED — Verhalten, das in beiden Zuständen existiert, dargestellt als was: … → now: ….
• REMOVED — Verhalten, das vorher existierte und danach absichtlich nicht mehr vorhanden ist.

Jeder Eintrag MUSS beobachtbares Verhalten sein — die Antwort eines Endpunkts, ein CLI-Flag, ein UI-Zustand, ein Standardwert — kein Implementierungsdetail. Der Delta-Abschnitt ist das Diff des Reviewers auf Verhaltensebene: Akzeptanzkriterien verifizieren die ADDED/MODIFIED-Einträge, und die REMOVED-Einträge sind die explizite Erlaubnis zum Löschen. Alles, was nicht als REMOVED aufgeführt ist, MUSS weiterhin funktionieren.

Validierungs-Gates — Auswahl nach Risikoklasse

Die Validierung ist das Gate, das eine Behauptung des Abschlusses in einen Beleg dafür verwandelt: Eine Aufgabe DARF NICHT als abgeschlossen markiert werden, bevor nicht jeder Befehl in ihrem Validation-Abschnitt ausgeführt wurde und bestanden hat. Das Gate einer verhaltensändernden Aufgabe wird aus ihrer abgeglichenen Touched Surface gewählt, nach Risikoklasse:

Eine Verhaltensänderung MUSS eine nicht-leere, relevante Testauswahl hervorbringen — ein ungültiger Selektor oder ein Runner, der null Tests ausgewählt hat, ist keine Abdeckung. Wo die Test-Abbildung des Repositorys veraltet ist, wird die korrekte Aufrufform abgeleitet und die Aktualisierung der Abbildung aufgezeichnet; ein kleiner fehlender Befehl erfordert niemals einen vollständigen Onboarding-Lauf. Wo keine eingegrenzte Aufrufform existiert, gilt die vollständige zutreffende Suite — Legacy-Verhalten, niemals ein Fehler.

Wenn eine Aufgabe neue Kernfunktionalität hinzufügt oder bestehendes Verhalten wesentlich ändert, MÜSSEN ihre Akzeptanzkriterien automatisierte Testabdeckung für das neue oder geänderte Verhalten umfassen, und ihre Validierung führt die Tests des Repositorys zusammen mit Lint-, Typprüfungs- und Formatprüfungen aus — nicht den Build allein. Bestehende Tests MÜSSEN grün bleiben.

Validierung des Endzustands

Gates je Aufgabe validieren, was jede Aufgabe berührt hat; sie ersetzen nicht die Validierung des Plans als Ganzem. Bevor ein Plan abschließt, MUSS die vollständige zutreffende Validierung des Repositorys auf dem finalen relevanten Zustand ausgeführt werden und bestehen — nach der letzten substanziellen Änderung, im Final Review. Breitere Läufe zuvor geschehen an Integrationsgrenzen oder nach geteilt/zentral-Änderungen, nicht nach einem Aufgabenanzahl-Zeitplan. Ein bestandenes Ergebnis DARF nur mit dem Nachweis wiederverwendet werden, dass die relevanten Eingaben gleichwertig sind; andernfalls wird es erneut ausgeführt. Jeder Gate-Lauf hinterlässt einen knappen Eintrag: Befehl, Umfang, Revision, Ergebnis und einen Beweispfad.

Sicherheitsdisziplin

Sicherheit ist erstklassig auf dieselbe Weise wie Tests und folgt demselben zweischichtigen Modell: Disziplin je Aufgabe, während die Arbeit geschieht, plus der Sicherheitstest des Final Review über den gesamten Änderungssatz am Ende. Wann immer eine Aufgabe Authentifizierung oder Autorisierung, die Eingabeverarbeitung, Secrets oder Konfiguration, die Netzwerk-, Datei- oder Shell-Oberfläche oder Abhängigkeiten berührt:

• Ihre Akzeptanzkriterien MÜSSEN die Sicherheitserwartungen der Änderung benennen — Eingaben validiert und maskiert, kein geheimes Material in Code oder Fixtures, Authentifizierungsprüfungen erhalten oder gestärkt — in Übereinstimmung mit docs/SECURITY.md.
• Jeder Commit MUSS vor dem Einfließen als frei von Secrets oder Anmeldedaten bestätigt werden, Test-Fixtures und Dokumentationsbeispiele eingeschlossen. Ein Secret in einem bereits gepushten Commit MUSS als geleakt behandelt und rotiert werden, nicht bloß entfernt.
• Wo die sicherheitsrelevante Arbeit erheblich ist, SOLLTE eine eigene Härtungsaufgabe unmittelbar nach den Implementierungsaufgaben und vor der Aufgabe der umfassenden Tests platziert werden, damit Befunde behoben werden, bevor die Tests das Verhalten festschreiben, und jeder Befund zu einem Regressionsfall statt zu Nacharbeit wird.

Diese Disziplin je Aufgabe ersetzt nicht den Sicherheitstest des Final Review: Prüfungen je Aufgabe fangen Probleme in dem Commit ab, in dem sie entstehen, während das finale Gate den gesamten Plan auditiert — einschließlich der Test- und Dokumentationsaufgaben selbst.

Plan-Lebenszyklus — das Final Review

Jeder konforme Plan, der unter dieser Version verfasst wird, endet mit genau einer verpflichtenden Aufgabe: dem Final Review (Aufgabe N). Zwei Verantwortlichkeiten, die frühere Versionen in separate Abschlussaufgaben gelegt hatten, werden verlagert: Skills-Entscheidungen wandern in die Aufgabe, die das Muster erzeugt hat, und der Executive Report wird zu einem optionalen Artefakt auf Anfrage. Nichts am Sicherheitstest wird abgeschwächt.

Das Final Review MUSS, in dieser Reihenfolge:

(a) Sicherheitstest — den vollständigen akkumulierten Änderungssatz des Plans auf hartkodierte Secrets, Injection-Risiken, neue Angriffsfläche, geschwächte Authentifizierung und sensible Daten in Logs oder Dokumenten prüfen; eingeführte Abhängigkeiten auditieren; verifizieren, dass docs/SECURITY.md weiterhin die Realität widerspiegelt; den Sicherheitsbericht auch dann schreiben, wenn er sauber ist. Ein kritischer Befund wird behoben — oder vom Nutzer explizit akzeptiert —, bevor der Plan abschließt.

(b) Validierung des Endzustands — die vollständige zutreffende Validierung des Repositorys läuft auf dem finalen relevanten Zustand und besteht.

(c) Abgleich der Skills — jede Aufgabe trägt eine Skills-Disposition, und jeder aufgezeichnete Kandidat hat eine Disposition; kein zweiter Discovery-Bericht.

(d) Abschluss — den Abschluss mit Lieferungen, Validierungsbeweisen und Einschränkungen berichten; den Executive Report einmal anbieten. Der Plan ist abgeschlossen, ob das Angebot beantwortet wird oder nicht.

Das Final Review läuft sequenziell nach allen anderen Aufgaben und wird niemals in eine parallele Gruppe platziert.

Aufgaben-lokale Skills-Entscheidungen

Die Frage „hat diese Arbeit ein wiederverwendbares Muster erzeugt, das eine Skill oder einen Agenten wert ist?” wird innerhalb der Aufgabe beantwortet, die das Muster erzeugt hat, während ihre Beweise im Kontext sind. Der Completion-&-Log-Abschnitt jeder Aufgabe trägt eine Skills-Disposition: keine, ein Update einer bestehenden Skill, die Erstellung eines benannten Artefakts oder eine Verschiebung mit Begründung. Berechtigte Autorenschaft geschieht innerhalb dieser Aufgabe, vor ihrem Validierungs-Gate und Commit, nach einer Duplikatprüfung gegen den bestehenden Katalog.

Executive-Bericht — optional, auf Anfrage

Der Executive Report ist keine verpflichtende Aufgabe mehr. Beim Abschluss bietet ihn der Agent einmal an; er wird nur auf explizite Anfrage erzeugt, aus dauerhaften Belegen befriedigt, ohne den Plan abzuspielen. Bleibt die Antwort aus oder läuft der Plan unbeaufsichtigt, bleibt der Plan abgeschlossen, ohne dass ein Bericht erzeugt wird.

Aufgabenabschlussprotokoll

Nach dem Bestehen der Validierung und vor dem Weitergehen zur nächsten Aufgabe MUSS der Agent der Reihe nach: (1) die Aufgabe in der Plan-README mit [x] markieren; (2) den Planstatuszähler erhöhen; (3) den Completion-&-Log-Abschnitt der Aufgabe ohne Platzhalterwerte ausfüllen; (4) einen 3–5-Punkte-Eintrag zu PROGRESS.md hinzufügen; (5) committen (wo der Plan committet) im Format {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) wo der Plan die Zustandsschicht trägt, state.json atomar neu schreiben — Aufgabe completed, Gate-Einträge, Ergebnis-Eintrag, Commit-Hash.

Die sechs Schritte bilden eine logische Transaktion. Ein Agent, der mitten im Protokoll unterbrochen wird, DARF NICHT mit der nächsten Aufgabe beginnen — er muss den partiellen Abschluss erst fertigstellen oder rückgängig machen.

Das DWP-Wiederaufnahme-Protokoll

Die Wiederaufnahme MUSS allein aus den Dateien des Plans plus dem git-Protokoll möglich sein, ohne externen Zustand. In einem Arbeitsbereich ohne git — siehe Archetypen §3 — ist state.json des Plans ERFORDERLICH und tritt an die Stelle des git-Protokolls.

Ein wiederaufnehmender Agent — eine neue Sitzung, ein anderer Agent, ein geplanter Daemon-Turn oder eine aufwachende Cloud-Sitzung — MUSS dieses Ritual in der angegebenen Reihenfolge durchführen:

1. Neu verankern. Den Plan-README lesen: Ziel, globale Richtlinien, die Aufgabenliste.
2. Den Checkpoint lokalisieren. Die erste nicht markierte Aufgabe im README finden; das git-Protokoll und den git-Status lesen (oder state.jsons checkpoint, wo git nicht vorhanden ist).
3. Zustand abgleichen. Wo state.json existiert, gegen die README-Checkboxen abgleichen; bei Desync vor dem Fortfahren aus dem Markdown neu erzeugen.
4. Die Naht prüfen. Den Completion-&-Log-Abschnitt der Wiederaufnahme-Aufgabe und den letzten PROGRESS.md-Eintrag lesen — den letzten verifizierten Stand der vorherigen Sitzung.
5. Smoke-Test. Die günstigste stehende Validierung des Repositorys ausführen, um zu bestätigen, dass die Welt noch funktioniert, bevor darauf aufgebaut wird. Ein fehlschlagender Smoke-Test wird zuerst untersucht, nicht übergangen.
6. Atomar fortfahren. Genau die nächste Aufgabe ausführen; nicht vorausbündeln.

Der Agent MUSS abgeschlossenen ([x]) Markierungen vertrauen und DARF abgeschlossene Aufgaben NICHT neu validieren, es sei denn, der Nutzer fordert dies explizit an oder der Smoke-Test schlägt auf eine Weise fehl, die eine abgeschlossene Aufgabe impliziert.

Die Ausführungsschleife

DWP definiert fünf Operationen:

• create — Einen neuen Plan aus einem Ziel erzeugen.
• execute — Den Plan Aufgabe für Aufgabe ausführen.
• refine — Einen bestehenden Plan ändern.
• resume — Einen unterbrochenen Plan wiederaufnehmen.
• status — Den Planstatus berichten, ohne auszuführen.

Ausgabe-Arbeitsbereich

Ausgabe-Arbeitsbereich

• .dwp/ von git ignoriert · verwerfbar
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ Berichte
• SECURITY_REVIEW.md Sicherheitsüberprüfung
• EXECUTIVE_REPORT.md Management-Bericht

Alle DWP-Artefakte MÜSSEN unter einem per gitignore ausgeschlossenen .dwp/-Verzeichnis im Repository-Stammverzeichnis leben.

Maschinenlesbarer Plan-Zustand

Ein Plan KANN die maschinenlesbare Zustandsschicht tragen — manifest.json (statische Identität) und state.json (lebendiger aufgabenbezogener Zustand, Validierungs-Gate-Einträge, Ergebnis-Einträge, Checkpoint, blockierter Zustand). Der Markdown-Plan bleibt die Quelle der Wahrheit; die JSON-Schicht ist eine abgeleitete Projektion, die bei Protokollpunkten neu erzeugt und bei der Wiederaufnahme abgeglichen wird.

Die Zustandsschicht ist für neue Pläne EMPFOHLEN, für unbeaufsichtigte Ausführung ERFORDERLICH und für Agenten-Arbeitsbereiche ohne git ERFORDERLICH. Siehe die vollständige normative Definition in Plan-Zustand.

Proportionaler Rigor

Rigor MUSS proportional zur Arbeit sein. Zeremonie bei trivialen Änderungen ist ein Methodikversagen, keine zusätzliche Sicherheit. Jede Arbeit fällt in genau eine Stufe:

Ein Agent, der gebeten wird, einen Plan für Micro-Stufen-Arbeit zu erstellen, MUSS mitteilen, dass ein Plan unverhältnismäßig ist, und stattdessen die Inline-Form anbieten. Ein Plan-Ordner DARF NICHT für eine triviale Einzeldatei-Änderung erstellt werden.

Micro-Stufen-Arbeit hält dennoch die Nicht-Verhandelbaren: ein explizites Ziel, ein Validierungs-Gate, das ausgeführt wird und besteht, sowie Testdisziplin für Verhaltensänderungen. Die Stufe ändert die Verpackung, niemals die Gates.

Wenn der Umfang während der Ausführung wächst — eine Micro-Aufgabe deckt realen Umfang auf, ein Standard-Plan bekommt Sub-Repositorys — MUSS der Agent stoppen und die Arbeit in die nächste Stufe befördern, anstatt die aktuelle zu dehnen.

Kompatibilität

Pläne und Repositorys aus früheren Versionen bleiben konform, und ein Konformitätsprüfer MUSS ein bekanntes Legacy-Artefakt (akzeptiert) von einem Artefakt unterscheiden, das diese Version deklariert und objektiv unter ihr ungültig ist (zurückgewiesen):

Versionierung

Diese Spezifikation folgt der semantischen Versionierung.