bassemZohdy/todo

todo (Kern)

Das Repository ist eine geschlossene Zustandsmaschine, die aus bereits vorhandenen Dateien besteht. Nichts anderes speichert den Zustand.

Ebene	Datei(en)	Rolle	Schreibrichtlinie
Anforderungen	README.md, docs/*.md	Ground Truth: Verträge, Spezifikationen, Setup, langfristige Pläne	Meistens lesend. Bearbeitet im Rahmen von "Dokumentationsdrift" in todo-continue; Plandokumente (docs/plans/) durch todo-init/todo-plan/todo-add/todo-update; die README-Zeile Tests: durch todo-init bei Zusage; das optionale RTM (reference/rtm.md) durch todo-plan/todo-add/todo-continue nur, wenn es bereits existiert; docs/status.html durch todo-report
Aktive Warteschlange	TODO.md	Ein Aufgabenbaum. Ein Tracker für Arbeitspunkte, kein Ort für Design	Nur durch die todo-*-Skills bearbeitet
Validierung	Quellcode + Testsuiten	Ground Truth für "erledigt"	Nur für die anstehende Aufgabe geändert
Archiv	CHANGELOG.md	Permanent, nur anhängbar (Keep a Changelog + Conventional Commits)	Nur ## [Unreleased] (bei einem Release: in die Version umbenannt, eine neue leere darüber, und die Linkzeilen am Ende) wird von einem Root-Drain und dem bestätigten /todo-release berührt; todo-init erstellt die Datei oder fügt ein fehlendes [Unreleased] hinzu
Prüfungen (optional)	.todo/check.sh, .todo/todo-lint.sh, CI-Job	Lint + Tests, ausgeführt von CI, einem Pre-Push-Hook und /todo-continue	check.sh geschrieben von /todo-init --ci bei Zusage; todo-lint.sh vom Benutzer kopiert; vom Benutzer committet
Versionsspeicher	git	Branch oder Worktree pro Aufgabe. Nichts erreicht den Basis-Branch unverifiziert	Siehe "Git-Modus"

Bevorzugen Sie native Dateiwerkzeuge (Read/Edit/Write) für Dateibearbeitungen; bearbeiten Sie jedoch nur die beabsichtigten Zeilen und behalten Sie die letzte neue Zeile der Datei bei. Verwenden Sie die Shell nur für git, Test- und Done when-Befehle, die optionalen Skripte und die von einem Skill benannten Dateibefehle (cp, chmod, mkdir -p, date, grep, cmp, mv und rm einer eigenen temporären Datei des Skills).

Backlog-Dateien sind TODO.md, CHANGELOG.md, docs/plans/PROJECT.md, docs/plans/<ROOT-ID>-*.md benannt nach einem Ref:, und die README-Zeilen Tests: und Base:, die von einem todo-*-Skill geschrieben wurden. README.md wird von einem Backlog-Commit nur gestaged, während git diff README.md genau diese Zeilen hinzufügt, optional nach einer Leerzeile; README-Änderungen, die ein Knoten im Rahmen von "Dokumentationsdrift" vornimmt, sind die Dateien dieses Knotens und werden mit ihm committet; jede andere README-Änderung ist die des Benutzers: Sie zählt für die Bereinigung des Baums und wird nie von einem Backlog-Commit gestaged. Backlog-Änderungen bleiben uncommittet bis zum nächsten Commit, den ein Skill auf einem todo/-Branch erstellt (in der Regel der Tree Claim), der sie durch expliziten Pfad staged. Neue Roots und jede Änderung an einem Knoten eines nicht beanspruchten Baums werden nur auf dem Basis-Branch vorgenommen; auf einem todo/-Branch lehnen die Skills sie ab und nennen den Basis-Branch. Die Bereinigung des Baums (reference/git-flow.md) ignoriert sie.

Direkte Verwendung

/todo allein ist schreibgeschützt: Befehle auflisten, die Invariantenprüfung auf TODO.md ausführen (falls vorhanden), berichten. Nichts ändern.

Befehl	Zweck
/todo-init	Bootstrap-Dateien, Testbefehl und Git erkennen, optionales Pre-Planning und CI-Setup, altes Format migrieren
/todo-plan	Arbeit in Spuren und einen Baum planen; den Plan jederzeit überarbeiten
/todo-add	Aufgabe hinzufügen oder eine Anfrage in einen Baum aufteilen
/todo-continue	Nächsten Aufgabenknoten ausführen, verifizieren, in seinen Elternknoten zusammenführen
/todo-update	Manuelle Zustands- und Feldänderungen
/todo-status	Schreibgeschützter Baum, Spuren, Historie und Suche
/todo-report	Interaktive HTML-Statusseite nach docs/status.html schreiben
/todo-release	[Unreleased] nach Bestätigung durch den Benutzer in eine Version umwandeln

Jeder Skill führt nur seinen eigenen Befehl aus und verknüpft sich nie unaufgefordert mit einem anderen.

Git-Modus

Zu Beginn jedes Befehls git rev-parse --is-inside-work-tree ausführen.

• Git-Repo: Jeder Knoten arbeitet auf seinem eigenen Branch oder Worktree (reference/git-flow.md). Der Basis-Branch ist der vom Benutzer genannte, ansonsten die README-Zeile Base:, ansonsten der erste existierende von main, master, trunk, develop; falls keiner vorhanden ist, einmal nachfragen. Wenn der Benutzer einen Basis-Branch nennt, der von diesem Standard abweicht, anbieten, Base: <branch> zur README hinzuzufügen (bei Zusage geschrieben; eine Backlog-Datei wie die Tests:-Zeile). Jeder Schritt, der in den Basis-Branch auscheckt oder mit ihm zusammenführt (Tree Claim, Claim-Release, Base-Merge, Release), wird im Haupt-Checkout (dem ersten Eintrag von git worktree list) ausgeführt: von einem verknüpften Worktree aus zuerst cd dorthin; wenn es auf einem anderen Branch mit Änderungen ist, anhalten und die Befehle ausgeben.
• Kein Git-Repo: Einmal pro Befehl warnen: "Dies ist kein Git-Repository. Die todo-Skills funktionieren trotzdem, aber ohne Branches, Worktrees, Commits oder Merges gibt es keine Isolation und keine Historie. Führen Sie git init aus, um sie zu aktivieren." Dann den No-Git-Modus verwenden: Jeden Git-Schritt überspringen, Fortschritt in State: verfolgen (einschließlich files:), Marker trotzdem aktualisieren und in CHANGELOG.md drainen. Die Verifizierung bleibt unverändert.

Nie taggen, force-pushen, hart reseten oder cleanen. Der einzige erzwungene Branch-Löschvorgang betrifft einen Branch, der nur den eigenen, nicht veröffentlichten Claim-Commit des Skills enthält (reference/git-flow.md, Tree Claim Schritte 2 und 5). Die eigenen Git-Befehle der Skills berühren niemals das Netzwerk: kein Fetch, Pull oder Push. Das Teilen von Commits ist Gits Aufgabe und Ihre. Ein Testbefehl kann Abhängigkeiten herunterladen; wenn er aufgrund fehlender Netzwerkverbindung fehlschlägt, mit diesem Grund blockieren, anstatt es erneut zu versuchen.

TODO.md Schema

# Active Backlog

## 🌳 Task Tree

Genau diese Überschrift und ein Abschnitt. Keine Abschnitte In Progress, Ready oder Blocked: Der Marker an jeder Aufgabe ist ihr Zustand. Ein leerer Baum besteht aus den beiden Überschriften und keinen Aufgaben.

Eine Aufgabe besteht aus 2 bis 4 Zeilen: Was zu tun ist, wie validiert wird, optionale Links und Status.

- [ ] **FEAT-002** · P1 · mid · XL · Token-Refresh zum Auth-Dienst hinzufügen
  - Done when: alter Token nach Refresh abgelehnt; `npx jest tests/auth`; regression: `npm test`
  - Links: Ref: docs/auth.md#refresh · Depends: TASK-001 · From: FIX-001
  - State: branch todo/FEAT-002-add-token-refresh-auth from main; next: build children
  - [ ] **FEAT-002.1** · mid · Refresh-Endpunkt
    - Done when: Endpunkt durch Integrationstest abgedeckt; `npx jest tests/auth/refresh.test.ts`
    - [/] **FEAT-002.1.1** · high · Token-Store-Interface
      - Done when: Store führt einen Token round-trip durch; `npx jest tests/auth/store.test.ts`
      - State: attempts 1/3; baseline 42 passing; branch todo/FEAT-002.1.1-token-store-interface from todo/FEAT-002.1-refresh-endpoint; next: build

Teil	Regel
Kopfzeile	- [m] **ID** · [P0-P2, nur bei Roots ·] KOMPLEXITÄT [· GRÖSSE] · was zu tun ist, ein Satz: Komplexität low, mid oder high (erforderlich); Größe S, M, L oder XL (optional)
Done when:	Erforderlich. Kriterien, dann ; und mindestens ein genauer Befehl in Backticks. Optional ; regression: \cmd``; ohne ist die Regression die gesamte Suite des Projekts
Links:	Optional. Ref: <pfad#anker>, Depends: <IDs>, From: <ID>, Lane: <name> (nur Roots), getrennt durch ·
State:	Optional, überlebt einen Kontext-Reset. Elemente getrennt durch ; , jedes höchstens einmal, in dieser Reihenfolge: attempts n/3, baseline <n> passing (oder none, oder red: <fehlgeschlagene test-ids, kommagetrennt>), `tier: <low
Blocked:	Bei [!]-Aufgaben, anstelle von State und an dessen Stelle (die letzte Feldzeile): <grund> → <befehl in backticks> <fehler, höchstens 5 zeilen mit " / " verbunden> → <erforderliche aktion>. Ein manueller Block schreibt in der Mitte n/a (manual)

Nur diese vier Felder existieren; eine Aufgabe hat nie sowohl State als auch Blocked. Mehr als 4 Zeilen sind Prosa zum Design und gehören in docs/ (mit Ref: verlinken). Wenn eine Aufgabe mehr benötigt, teilen Sie sie auf.

Marker: [ ] offen, [/] aktiv (höchstens eine in der Datei), [!] blockiert, [x] verifiziert und in den Elternknoten zusammengeführt (oder wird gerade zusammengeführt), wartet darauf, dass sein Root drainiert.

Baum, Ebenen und Komplexität

Ein Knoten auf Ebene L hat seine Kopfzeile um 2L Leerzeichen eingerückt und seine Felder um 2L+2. Maximal 3 Ebenen.

Umfangsregel. Jedes Blatt ist eine Änderung, die in einen Kontextfenster passt und höchstens 5 Dateien berührt; größere Arbeit wird in Kinder aufgeteilt (/todo-add). Ein Knoten, der noch zu groß zum Aufteilen ist, behält State: next: decompose, bis /todo-continue ihn aufschlüsselt.

Größe (optional, nach der Komplexität) zeichnet den Umfang auf, wenn er dem Leser hilft; wenn vorhanden, muss sie zum Baum passen, und das Hinzufügen oder Entfernen eines Knotens aktualisiert die Größe jedes Vorfahren:

Größe	Bedeutung	Wo
S	Eine Änderung, höchstens 2 Dateien	Blatt
M	Ein Kontextfenster, höchstens 5 Dateien	Blatt
L	Hat Kinder, alle Blätter	Elternknoten
XL	Hat Enkelkinder	Elternknoten

Ein Blatt mit State: next: decompose darf L/XL tragen.

Komplexität gibt an, wie schwierig die Überlegung ist, nicht wie groß die Änderung ist, damit ein Agent ein passendes Modell auswählen kann:

Komplexität	Bedeutung	Beispiele
low	Mechanisch: Ursache und Änderung sind bereits bekannt, keine Untersuchung	Umbenennung, Doku, Konfiguration, eine Wächter- oder kleine Funktion, deren Lösung die Aufgabenzeile angibt
mid	Normale Arbeit, die etwas Untersuchung oder Design erfordert (Standard)	Ein neuer Endpunkt, ein Fehler, dessen Ursache gefunden werden muss
high	Schwierige Überlegung oder hohes Risiko	Nebenläufigkeit, Sicherheit, Datenmigration, unklare Spezifikation, Design über Module hinweg, knifflige Algorithmen

Ein Elternknoten wird nur anhand seines Integrationsschritts bewertet (normalerweise low oder mid); seine Kinder tragen ihre eigenen Stufen. Roots tragen die Priorität und die Spur; Kinder erben beides.

Modell-Routing (optional)

Ein Projekt ordnet Ebenen Modellen mit einer README-Zeile zu, zum Beispiel Models: low=haiku, mid=sonnet, high=opus (alle Namen, die der Agent versteht). Ohne diese Zeile oder ohne ein Subagenten-Tool ist die Komplexität nur ein Hinweis und die Arbeit läuft im aktuellen Modell. Mit beidem:

• /todo-continue --delegate und Spurdurchläufe geben jedem Knoten (oder Spuren-Root, bei seiner höchsten Komplexität) einen Subagenten auf dem zugeordneten Modell.
• Der Prüfer läuft auf der Stufe des Knotens oder höher.
• Eskalation: Nach einem fehlgeschlagenen Verifizierungsversuch läuft der nächste Versuch eine Stufe höher (low → mid → high), aufgezeichnet in State: als tier:. Ein falsches low-Label kostet einen billigen Versuch, keinen blockierten Knoten.

IDs

• Roots <PREFIX>-<NNN>, eine globale Sequenz, 3-stellig. Kinder hängen .n an: FEAT-002.1, FEAT-002.1.2. Punkte entsprechen der Ebene.
• IDs werden nie wiederverwendet. Nächste Root-Nummer = höchste gefundene FEAT-/FIX-/TASK-Nummer in TODO.md, CHANGELOG.md (einschließlich IDs nach Includes:), docs/plans/*.md und, im Git-Modus, Commit-Betreffen (git log --all --format=%s, die verworfene IDs nennen), plus 1. Nächste Kind-Nummer = die höchste Kind-Nummer unter diesem Elternknoten, die an denselben Stellen gefunden wurde, plus 1.

Präfix	Bedeutung	CHANGELOG-Überschrift	Commit-Typ
FEAT	Neue Fähigkeit	### Added	feat
FIX	Fehler oder Regression	### Fixed	fix
TASK	Refactoring, Chore, Doku, Test, Perf, Build	### Changed	was passt

Kinder verwenden das Präfix ihres Roots.

Welcher Knoten ist als nächstes dran

Ein Knoten ist bearbeitbar, wenn: er [ ] ist; jedes Kind [x] ist; jede Depends:-ID erfüllt ist (in CHANGELOG.md als Eintrags-ID oder nach Includes:, auch in git show <base>:CHANGELOG.md im Git-Modus, oder [x] in TODO.md; wenn nur das CHANGELOG des Basis-Branch es erfüllt, führt /todo-continue vor dem Start des Knotens Schritt 3 durch, indem es den Basis-Branch in den Branch zusammenführt, von dem der Knoten starten wird; schreibgeschützte Befehle melden "wartet auf einen Base-Merge"); kein Vorfahre ist [!]; und, im Git-Modus, sein Root nicht von einem anderen Branch beansprucht wird. Ein Root ist beansprucht, wenn sein State: im TODO.md des Basis-Branch (git show <base>:TODO.md) einen Branch nennt; sein Baum ist nur von einem Branch dieser Familie (todo/<ROOT-ID>-… oder todo/<ROOT-ID>.…) aus bearbeitbar. Ein übersprungener, beanspruchter Baum wird als beansprucht von <branch> gemeldet; wenn dieser Branch in diesem Clone existiert, füge "wenn dies Ihre Arbeit ist: git switch <branch> (oder cd zu seinem Worktree) und erneut ausführen, um fortzusetzen" hinzu. Ein Branch in diesem Clone kann zu einer anderen Sitzung gehören, daher wird nie automatisch vom Basis-Branch aus fortgesetzt. Wenn Backlog-Dateien uncommittete Änderungen auf dem Basis-Branch enthalten, schlägt git switch zu diesem Branch fehl: sagen Sie dies und bieten Sie zuerst git stash push -- <backlog-pfade> und git stash pop zurück auf dem Basis-Branch an.

Unterbrochene Arbeit zuerst (Git-Modus). Auf einem Tree-Branch (einem beliebigen todo/-Branch) die Branches des Baums auflisten (git branch --list 'todo/<ROOT-ID>-*' 'todo/<ROOT-ID>.*') und den Knoten jedes Branches in git show <branch>:TODO.md lesen. Ein Knoten, der [x] auf einem Branch ist, der noch nicht in den Branch seines Elternknotens zusammengeführt wurde (git merge-base --is-ancestor <branch> <parent branch> schlägt fehl), wurde vor seiner Zusammenführung gestoppt: diese Zusammenführung abschließen und nichts anderes tun (/todo-continue Schritt 2). Ein Knoten, der [/] ist, wird fortgesetzt, zuerst der tiefste. Ein Knoten, der [!] auf einem der Branches des Baums ist, gilt überall als [!] (nicht bearbeitbar; seine Vorfahren warten), selbst wenn ein anderer Branch ihn noch als [ ] anzeigt; ein Branch, dessen Knoten nicht mehr im TODO.md seines Eltern-Branch enthalten ist (verworfen), wird ignoriert; ein Branch, der bereits in den Branch seines Eltern-Knotens zusammengeführt wurde, wird mit git branch -d gelöscht. Diesen Schritt auf dem Basis-Branch überspringen.

Spuren

Eine Spur ist ein benannter Pfad von Root-Bäumen, die ein Agentenkontext allein und der Reihe nach bearbeitet. Lane: <name> (ein Kleinbuchstabe, dann Kleinbuchstaben, Ziffern oder Bindestriche) auf einem Root setzt seinen gesamten Baum in diese Spur; Kinder erben sie, und ein Root ohne sie ist in der Spur main (also --lane main wählt diese Roots aus). Spuren sind Kontext, nicht Aufgaben: Eine Spur kann eine Aufgabe oder viele enthalten, Spuren laufen parallel zueinander (/todo-continue --lane <name> startet die nächste offene Aufgabe dieser Spur). Lanes nutzen dasselbe Bearbeitbarkeitsmodell; ein Agent, der eine Spur bearbeitet, sieht nur deren Roots und deren Bäume. /todo-status listet Roots nach Spur gruppiert auf, mit einem leeren Eintrag für jede Spur, die noch keine Roots hat. Das Hinzufügen einer Spur

…

[fortsetzung folgt]