Zum Inhalt springen

Inbox, Aufgaben und Journal

docs/ai/ ist das gemeinsame Arbeitsgedächtnis von dir und dem Assistenten. Alles darin ist eine einfache Datei, eine Datei pro Eintrag, versioniert mit dem Projekt. Übersichten wie das Board werden aus diesen Dateien erzeugt und nie von Hand gepflegt.

Ordner Enthält Geschrieben von
docs/ai/inbox/ alles, was auf einen Menschen wartet dir und dem Assistenten
docs/ai/proposals/ vorgeschlagene Regeländerungen, die auf eine Entscheidung warten dem Assistenten
docs/ai/work/tasks/ offene Aufgaben dem Assistenten
docs/ai/work/backlog/ Ideen und Änderungswünsche, die noch nicht gebaut sind dem Assistenten
docs/ai/work/ledger/ das Journal, ein Eintrag pro Schritt dem Assistenten
docs/ai/work/archive/ erledigte Einträge, die das Projekt behält (siehe Archiv) dem Assistenten
docs/ai/concept/ eine Ideen-Datei pro Person dir

Worker (Sub-Agenten) schreiben nie in docs/ai/; das tut nur der Haupt-Assistent (siehe Rollen). Die Projektdoku unter docs/project/ ordnet R-docs-order: eine README.md mit einer Zeile je Datei und Unterordner in jedem Ordner ab fünf Einträgen, ein Thema pro Datei, und eine Konzeptdatei wird archiviert, sobald sie entschieden oder umgesetzt ist: entries.py archive <Pfad> verschiebt sie nach docs/ai/work/archive/, act-compact faltet sie in ihre Monatsdatei, erst dann ist sie weg (siehe Konfiguration).

Die Inbox ist der eine Ort, an dem etwas auf dich wartet. Jede Datei beginnt mit YAML-Frontmatter zwischen zwei ----Zeilen (id, kind, for, status, created), sodass Markdown-Editoren und Forges die Felder als Metadaten zeigen, und hat eine von vier Arten. Aufgaben, Backlog-Einträge, Journal-Einträge und das Archiv nutzen dasselbe Frontmatter; Einträge in der älteren schlichten Kopfform werden weiter gelesen, und act-update schreibt vorhandene einmal um. Vorschläge unter docs/ai/proposals/ werden ebenfalls mit Frontmatter geschrieben (author, date, target); ältere schlichte werden gelesen, aber nicht umgeschrieben:

kind Id Was es ist Statusverlauf
question Q12 eine Entscheidung oder Frage an dich; du antwortest unter ihrer Zeile **Antwort:** open → answered → done
todo U3 ein Schritt, den nur ein Mensch tun kann, angelegt, sobald er ansteht open → done
report keine der schreibgeschützte Bericht eines Werkzeugs, zum Beispiel von doctor oder einer Übernahme open → done (gelesen)
note keine deine eigene Notiz; der Assistent antwortet darunter open → answered → done

Ein Eintrag ohne kind zählt als todo. Das Feld for: sagt, an wen ein Eintrag gerichtet ist: all oder die Workspace-Identität einer Person. Ein Eintrag mit done wird archiviert, egal welcher Art (siehe Archiv). Eine Antwort, die der Assistent versprochen hat, oder eine Gegenprüfung, die er von einer anderen Sitzung erwartet, wird als todo angelegt, mit for: für die Person oder Stelle, auf die es wartet (oder all); so überlebt das Versprechen die Sitzung. act-commit fragt vor dem Bericht „Wartet jemand?“.

Eine Chat-Nachricht, die mit todo:, note: oder idea: beginnt (Groß-/Kleinschreibung egal), ist ein Quick Capture: Bei eingeschaltetem quick-capture (Standard) legt der Hook UserPromptSubmit sie ohne Modell-Durchlauf ab, sie kostet also keine Token und unterbricht keine laufende Aufgabe. todo: und note: werden Inbox-Einträge mit triage: open; idea: wird ein neuer Abschnitt in deiner Ideen-Datei (unten). Der Assistent bearbeitet jeden Eintrag mit triage: open direkt nach den beantworteten: Er entscheidet, für wen ein Todo ist, oder macht daraus einen Backlog-Eintrag, oder er antwortet unter einer Notiz. Wo der Hook nicht läuft, legt der Assistent die Nachricht selbst ab (Regel R-human-capture), mit entries.py new todo|note --triage, das dieselbe Zeile triage: open schreibt.

Eine Frage ist eine Datei je Frage. Ihre Überschrift ist die Frage selbst und endet mit einem Fragezeichen. Darunter steht ein Hinweis von höchstens drei Sätzen ohne Liste; Hintergrund und Gründe bleiben im Backlog-Eintrag oder Konzept, das er nennt. Dann folgen 2-5 Optionen als Zeilen - **a)** … (keine nummerierte Liste), je ein bis zwei Zeilen mit dem Aufwand, und je eine Leerzeile davor, dazwischen und danach. Eine empfohlene Option steht immer vorn, als a), und beginnt mit dem fetten Etikett **Empfehlung:** (**Recommended:** bei language-docs: en); ihre Begründung schließt die Zeile in einem Satz. Eine Frage ohne sinnvolle Optionen bleibt Freitext. Ein Update ersetzt die Inbox-README eines bestehenden Projekts nicht; sie kann also noch die ältere Form zeigen. entries.py new question schließt sie mit einer leeren Zeile **Antwort:** (**Answer:** bei nicht deutschem language-docs); die Antwort steht darunter, und vor dem Verbuchen liest der Assistent die Datei erneut, damit sie nie unter einer zweiten Zeile landet. Auch eine Frage, die unter einer vorgegebenen --id (oder --formerly) angelegt wird, bekommt die Zeile; ein Text, der schon eine Antwortzeile am Zeilenanfang trägt, auf Englisch oder Deutsch, oder eine Frage mit --status answered bekommt keine zweite.

Der Assistent legt Einträge mit python .act/scripts/entries.py new <kind> <title> an; die Script-Referenz listet alle Optionen.

Auf Notizen antwortet der Assistent in einem angehängten Block von höchstens drei Textzeilen, nie innerhalb deiner eigenen Worte. Deine Worte werden nie bearbeitet oder gelöscht, nur darunter kommentiert.

  • Aufgaben (T7): eine Datei pro offener Aufgabe mit Ziel und Prüfkriterien. Die erste Arbeitsstand-Zeile (entries.py state T7 <text>) oder entries.py start T7 schreibt started: ins Frontmatter; das Board markiert die Aufgabe dann als laufend (oder wartend, siehe unten). Der aktuelle Arbeitsstand selbst liegt im per gitignore ausgeschlossenen .act-local/state/, nicht in der Aufgabendatei. Das Feld for: sagt, wessen Aufgabe es ist; all oder kein Feld bedeutet geteilt.
  • Backlog (B5): eine Idee oder ein Änderungswunsch, der noch nicht gebaut ist. Er wird zur Aufgabe, sobald die Arbeit daran beginnt. Mit inbox-decisions: at-start kann ein Eintrag bis zum Arbeitsbeginn decision: open tragen (siehe Konfiguration).
  • Journal: eine Datei pro Schritt, benannt YYYY-MM-DD-<slug>.md. Journal-Einträge bekommen nie eine kurze Id. Alte werden später in monatliche Sammeldateien zusammengeführt (siehe Archiv).

Nichts verlässt docs/, bevor es in seiner Monatsdatei steht: Ein erledigter Eintrag wird nie gelöscht, nur archiviert und später von act-compact gefaltet. Der frühere Schlüssel done-entries und der Befehl entries.py purge sind entfallen (eine übrig gebliebene Zeile wird übergangen und vom Update entfernt, ein Aufruf von purge gibt einen Hinweis aus), und ein Projekt mit done-entries: delete archiviert wie jedes andere. Erledigte Aufgaben, Backlog-Einträge, bearbeitete Inbox-Einträge, entschiedene Vorschläge und entschiedene oder umgesetzte Konzeptdateien wandern unter ihrem alten Namen nach docs/ai/work/archive/, damit die Historie lesbar und die Übersichten erzeugt bleiben. Der Assistent erledigt das, wenn er eine abgenommene Aufgabe abschließt (act-commit); eine Aufgabe, ein Backlog-Eintrag, ein Inbox-Eintrag oder eine Konzeptdatei geht in einem Schritt mit entries.py archive <id|Datei> (Links auf ein Konzept ziehen mit), ein Inbox-Eintrag bekommt status: done und eine Aufgabe finished: <Zeitstempel> unter started: (sonst unter created:). Einen entschiedenen Vorschlag verschiebt man von Hand nach docs/ai/work/archive/proposals/. Bilder und andere Dateien, die der Eintrag neben sich verlinkt (ein eingefügtes img.png), wandern mit, allgemeine oder schon vergebene Namen bekommen die Id des Eintrags vorangestellt (Q12-img.png), und Links werden umgeschrieben. Eine Datei, die eine andere Markdown-Datei unter docs/ noch verlinkt, wird kopiert statt verschoben. Alles wird vor dem ersten Schreiben geplant, ein Fehler hinterlässt also nichts Halbfertiges. doctor meldet Dateien unter docs/ai/inbox/ und docs/ai/concept/, die keine Markdown-Datei verlinkt (Art orphan-file), zum Beispiel ein Bild, das nach dem Archivieren von Hand liegen blieb.

Tausend einzelne Dateien in einem Ordner sind in einer IDE nicht mehr lesbar. Sagt archive-compact in docs/ai/config.md § Archive es so, meldet der Sitzungsstart, dass das Verdichten fällig ist, und nennt die Zahl der zusammenzuführenden Einträge; der Skill act-compact läuft an der nächsten Aufgabengrenze (im Team-Modus nur auf dem Default-Branch). Kein Worker wirkt mit. Der Hinweis zählt die Einträge so, wie entries.py compact sie datiert (nach dem Tag, an dem Git sie archiviert hat), und zählt daher nie Einträge mit, die compact liegen ließe. entries.py compact führt archivierte und Journal-Einträge, die älter als eine Woche sind, zu einer Datei je Art und Monat zusammen (Q-2026-09.md, ledger-2026-09.md …, Konzeptdateien in other-2026-09.md), mit einem verankerten Abschnitt pro Eintrag, jeweils wortgetreu. Links werden auf die Anker umgeschrieben, der Dateikopf nennt den Commit, der den vollen Text noch enthält, --plan zeigt eine Vorschau, und ein zweiter Lauf ändert nichts. Der Befehl verweigert sich, solange eine zu verschmelzende Datei nicht committet ist. Für jeden Monat mit einem Q-, T-, B- oder U-Abschnitt schreibt er außerdem die Übersicht archive/YYYY-MM.md selbst: eine Zeile je Eintrag mit Link auf den Abschnitt, Titel und Status. Eine vorhandene Übersicht, auch eine von Hand geschriebene, bekommt nur die Zeilen der Einträge, die sie noch nicht nennt. Gekürzt wird nichts. compact_check.py vergleicht jeden Abschnitt mit dem Original in git: Ids, Hashes, Versionen, Daten, Pfade, Zahlen und jede Zeile, die du geschrieben hast, markiert oder nicht, müssen erhalten bleiben; eine Zeile darf auch als der Link dastehen, zu dem compact sie umgeschrieben hat. Nach einem reinen Zusammenführen meldet es nichts; ein Befund weist auf eine Handänderung oder einen Fehler. Ein von Hand gelöschter Abschnitt wird gemeldet, und --restore stellt einen Abschnitt in voller Länge wieder her. Deine Worte bleiben auch hier unangetastet. Der volle Text jedes Eintrags bleibt in git.

Jede Person hat ihre eigene Datei docs/ai/concept/ideas-<identity>.md, wobei <identity> der Kurzname in .act-local/identity.json ist. Der Sitzungsstart legt .act-local/identity.json aus git config user.name an, wenn sie fehlt oder kein identity enthält (frischer Klon, zweiter Rechner); python .act/scripts/board.py --identity <name> setzt oder ändert den Namen. Du schreibst jede Idee als eigenen Abschnitt ## <title>; nur du schreibst dort Einträge, sodass nie zwei Personen dieselbe Datei bearbeiten. Der nächste Sitzungsstart bemerkt, was neu oder geändert ist, und lässt es bearbeiten:

  • Der Assistent antwortet unter dem Eintrag, nur wo etwas von dir gebraucht wird, in höchstens drei Zeilen und höchstens drei Blöcken pro Eintrag.
  • Eine Überschrift mit „Entwurf” bekommt nur eine kurze erste Reaktion. Entfernst du das Wort, wird der Eintrag vollständig analysiert.
  • Eine Entscheidung, die nur du treffen kannst, wird zur Inbox-Frage.
  • Ein bearbeiteter Eintrag wandert wortgetreu in den Backlog-Eintrag oder das Konzept, aus dem er wurde, und verlässt die Datei.

Das Board ist ein erzeugter Schnappschuss: Branch, jüngste Journal-Einträge, was auf dich wartet, offene Aufgaben, offene Entscheidungen im Backlog und das Backlog selbst. Unter Status führt es außerdem ein Template-Update auf, das noch eingespielt werden muss (Template update available: 2.4.0). Ein critical-Advisory zur installierten Template-Version steht direkt unter dem Titel (siehe Advisories). Es wird beim Sitzungsstart neu geschrieben und nach Git-Befehlen, die den ausgecheckten Stand ändern. Wohin es geht, hängt vom Schlüssel board ab: docs (Standard, docs/ai/board.md, per gitignore ausgeschlossen), shared (zusätzlich ein versioniertes docs/ai/board-<identity>.md, beim Commit geschrieben) oder local (unter .act-local/). Eine zweite erzeugte Datei, .act-local/inbox-<identity>.md, sammelt den vollen Text jedes offenen Eintrags, der an dich gerichtet ist, sodass eine Datei zum Lesen genügt.

Die Statuszeile von Claude Code zeigt eine Zeile unter dem Chat, zum Beispiel act · Q103 Q104 · tasks: 1 run, 1 wait, 4 new · ctx 127k. ctx ist die Größe des Kontexts der Sitzung. Wartet ein Template-Update auf die Installation, steht vor ctx update: 2.4.0 (auf dem Channel latest update: <Datum> des neueren Commits, als DD.MM.YYYY, wenn language-docs de ist, sonst YYYY-MM-DD; der kurze Hash, wo sich das Datum nicht ohne Netz lesen lässt). Ein critical-Advisory zur installierten Version steht ganz vorn, direkt nach act, als ⚠ A<n>. Eine begonnene Aufgabe gilt als wartend, und das Board markiert sie mit „(waiting)“, wenn ihre letzte Arbeitsstand-Zeile mit entries.py state <id> --wait geschrieben wurde, älter als task-wait-hours ist oder ein offenes Todo oder eine offene Frage sie nennt (siehe Konfiguration). Offene Fragen und Todos erscheinen mit Id, Berichte und Notizen als Anzahl pro Art. Um sie dauerhaft abzuschalten, setze in .claude/settings.json einen eigenen statusLine-Befehl; das Template ersetzt nie einen Eintrag, den sie nicht selbst erzeugt hat.

Proben, Wegwerfprojekte, Klone und Arbeitsdateien entstehen nur, wenn die Arbeit sie braucht, und nur unter .act-local/tmp/<task-id>-<slug>/ (.act-local/tmp/<YYYYMMDD>-<slug>/ für Arbeit ohne Aufgabe, etwa einen Skill-Lauf oder einen Doctor-Bericht): nie im temporären Verzeichnis des Systems und nie direkt unter .act-local/ (R-work-throwaway). Wer sie anlegt, entfernt sie nach Gebrauch; ein Worker sagt das in seinem Ergebnis, und .act-local/tmp/ steht jedem Worker offen, gleich welchen Write scope: er hat. Eine Probe setzt nie ein Zugriffsrecht, das ihr Eigentümer nicht allein zurücknehmen könnte, und nimmt jedes gesetzte Recht wieder zurück. Beim Commit einer Aufgabe entfernt act-commit deren Ordner (act_local_tidy.py --task <id>). Den Rest räumt act-local-tidy beim Sitzungsstart nach 7 Tagen auf, es sei denn, der Name beginnt mit der Id einer offenen Aufgabe oder act-local-keep führt ihn auf, siehe Konfiguration.

Der Schlüssel mode (solo oder team) ändert genau eines: wann ein Eintrag seine kurze Id bekommt.

  • solo: Der Assistent vergibt die Id sofort.
  • team: Die Id vergibt nur, wer den Eintrag auf dem Standard-Branch ablegt (entries.py assign), sodass zwei Personen nie dieselbe Nummer vergeben. Bis dahin zitierst du den Dateinamen, zum Beispiel T-<identity>-<YYYYMMDD-HHMM>-<slug>.md.

Dateinamen, Orte und Formate sind in beiden Fällen gleich, du kannst also jederzeit wechseln; bereits vergebene Ids bleiben. Siehe Im Team arbeiten.