Dokumentationsstandard

Version 5.0.0. Dieser Standard definiert, wie Deep Work Plans ihre Struktur, Aufgaben und Fortschritte dokumentieren, und wie sich ein Repository selbst so dokumentiert, dass ein Agent sicher darauf handeln kann. Er gilt für jeden Plan, der unter der DWP-Methodik erstellt wird. Diese Version gleicht die eigene Version des Dokuments an den DWP-Standard an, den es begleitet — keine bestehende Anforderung ändert sich — und fügt die unten beschriebene Durchsetzung des Lean-Index-Budgets sowie die Feature-Ebene hinzu. Die Schlüsselwörter MUSS, SOLLTE und KANN werden so verwendet, wie in RFC 2119 definiert.

AGENTS.md als kompakter Einstiegspunkt

Die Wurzel-AGENTS.md-Datei SOLLTE innerhalb eines Budgets von 150–500 Zeilen bleiben. Würde generierter oder vom Harness gepflegter Inhalt dieses Budget überschreiten, MUSS der Agent das Detail in den docs/-Guide (oder das Modul-/Feature-Dokument) verschieben, dem es gehört, und von der Index-Datei aus verlinken — nichts wird verworfen, nur verlagert, und der Index MUSS jedes Dokument verlinken, das verlagerten Inhalt erhalten hat. Eine bestehende, handgeschriebene AGENTS.md über dem Budget wird niemals stillschweigend umgeschrieben: Der Agent schlägt eine konkrete Migration vor (was wohin verschoben wird, welche Links hinzukommen) und wendet sie nur mit der Zustimmung des Entwicklers an. Ein Konformitätsprüfer behandelt das Budget als Empfehlung, denn eine Zeilenzahl ist objektiv, Autorenschaft jedoch nicht — das MUSS bindet das Harness, das die Datei erzeugt oder aktualisiert, nicht die Vermutung eines Prüfers darüber, wer sie geschrieben hat. AGENTS.md DARF NICHT auf eine docs/-Datei verlinken, die nicht existiert.

Über der Pro-Modul-Dokumentationsebene (unten) liegt eine Feature-Ebene: Ein größerer Fähigkeitsbereich — größer als ein einzelnes Modul — erhält einen eigenen docs/-Ordner neben seinem Code, erschlossen über ein eigenes README.md. Ein Bereich qualifiziert sich, wenn er zwei oder mehr Hauptmodule umspannt, ein in sich geschlossenes Sub-App- oder Subsystem-Verzeichnis besitzt oder eigene Verträge trägt (eine API-Oberfläche, Event- oder Schema-Verträge), von denen mehrere Konsumenten abhängen. Sobald ein Bereich als bedeutend erfasst ist, SOLLTE sein Feature-docs/-Ordner existieren, und seine wichtigsten Einträge SOLLTEN von den Modulen, die er umspannt, sowie vom Wurzel-AGENTS.md-Index aus verlinkt werden, genau wie Pro-Modul-Dokumente. Ein Bereich, der bewusst undokumentiert bleibt, trägt einen festgehaltenen Grund — eine Entscheidung, kein Versehen.

Plan-README

Jeder Plan MUSS eine README.md haben, die Folgendes enthält:

Titel — # Deep Work Plan: <name>.
Ziel — eine prosaische Formulierung des Plan-Ziels.
Quellmaterial — Links oder Pfade zu kanonischen Eingaben (optional).
Aufgaben — eine Markdown-Tabelle mit der Aufgabennummer, dem Namen und einer Status-Checkbox.
Status — eine Zeile in der Form <n>/<total> tasks complete.

Aufgabendateien

Jede Aufgabendatei MUSS den Namen <n>.task_<slug>.md tragen und die zehnteilige Anatomie enthalten — die neun klassischen Abschnitte plus die Touched Surface: der Vertrag zwischen dem, was die Aufgabe ändert, und dem, was validiert werden muss (geplante vs. tatsächliche Oberfläche, betroffene Konsumenten, eine Risikoklasse isoliert, Nahtstelle, geteilt/zentral oder unbekannt, die verwendete Test-Abbildung und das gewählte Gate mit seiner Begründung).

PROGRESS.md

PROGRESS.md ist ein reines Anhänge-Ausführungsprotokoll. Jeder Eintrag MUSS Folgendes festhalten:

Einen ISO-8601-Zeitstempel.
Die Aufgabennummer und den Namen.
Was getan wurde.
Etwaige Abweichungen oder Übersprung-Gründe.

Statusmarkierungen

[ ] — nicht begonnen.
[~] — in Arbeit.
[x] — erledigt.
[!] — blockiert.

Überschriften

Alle Überschriften MÜSSEN Satzschreibweise (sentence case) verwenden. Dokumente SOLLTEN Marketing-Sprache und Ausrufezeichen vermeiden.

Das Final Review, Aufgaben-lokale Skills-Entscheidungen und der optionale Bericht

Jeder Plan, der unter dieser Version verfasst wird, MUSS mit genau einer verpflichtenden Aufgabe enden: dem Final Review — dem Sicherheitstest über den vollständigen Änderungssatz des Plans, der Validierung des Endzustands auf dem letzten relevanten Zustand und dem Abgleich der Skills-Entscheidungen. Ein kritischer Sicherheitsbefund blockiert den Abschluss.

Aufgaben-lokale Skills-Entscheidungen. Der Completion-&-Log-Abschnitt jeder Aufgabe trägt eine Skills-Disposition — none, ein Update einer bestehenden Skill oder eines bestehenden Agenten, eine benannte Neuerstellung oder eine Verschiebung mit Begründung und Verantwortlichem. Berechtigte Autorenschaft geschieht innerhalb der erzeugenden Aufgabe, vor ihrem Validierungs-Gate, nach einer Duplikatprüfung gegen den .agents/-Katalog; berechtigte Einträge werden als stabile Kandidaten (T{task}-{seq}) im Skills-Kandidaten-Ledger des Plans erfasst.
Der Executive Report ist optional, auf Anfrage. Er wird einmal beim Abschluss angeboten und nur auf explizite Anfrage aus dauerhaften Belegen erzeugt. Bleibt die Antwort aus oder läuft der Plan unbeaufsichtigt, bleibt der Plan ohne ihn abgeschlossen.
Legacy-Pläne. Pläne, die unter früheren Versionen verfasst wurden, enden mit den drei verpflichtenden Abschlussaufgaben und bleiben konform — ein Konformitätsprüfer MUSS diese Form akzeptieren.