Kernkonzepte

AWR hält die Arbeitsfakten eines Projekts außerhalb jeder einzelnen Agent-Konversation, sodass die Arbeit Kontextverlust, Agent-Wechsel und Neustarts überlebt. Dieser Artikel erklärt die fünf Ideen hinter diesem Modell; die Befehle im Schnellstart und die Routinen im täglichen Workflow lesen sich dann ganz natürlich.

Das Kernprinzip: Deine Quelldateien (Ledger, Pläne) sind die maßgebliche Quelle, und alles, was die Laufzeit speichert — Sessions, Claims, Nachweise — ist eine prüfbare Projektion dieser Fakten. AWR erfindet niemals fehlende Absichten und lässt niemals zu, dass ein Konversationsprotokoll einen aufgezeichneten Fakt ersetzt.

Projektfakten: der Quellen-Ledger

Der Quellen-Ledger von AWR ist ein kleiner Arbeitsvertrag, den du in gewöhnlichen Projektdateien pflegst: ein YAML-Ledger wie work-ledger.yaml oder ein vorhandener Markdown-Ledger (*-ledger.md), der durch AWR schreibgeschützt bleibt und in seiner Originaldatei bearbeitet wird. Ein Ledger zeichnet zwei Arten von Fakten auf:

Ziele — was das Projekt erreichen will, mit Erfolgskriterien. Ziele können draft, candidate oder needs_confirmation sein, wenn unsicher, und active oder confirmed, wenn durch Quellmaterial oder Nutzeranweisung gestützt. AWR prüft die Deklaration; es bescheinigt nicht, dass das Ziel dem entspricht, was ein Mensch gemeint hat.
Arbeitselemente — die Aufgaben, unten beschrieben.

Ein minimaler Ledger sieht so aus:

goals:
  - id: search
    title: Let readers find documents
    status: active
    summary: The user requested search in the existing portal; see README.md.
    success_criteria: [Readers find a requested document]
work_items:
  - id: search-api
    title: Add document search
    status: ready
    goal: search
    acceptance: [A matching query returns the requested document]
    next_action: Implement the search handler using the current document index

Du stellst diese Dateien mit init unter die Verwaltung von AWR. Nichts wird geschrieben, bis du die Vorschau annimmst:

awr --project /absolute/project init
awr --project /absolute/project init --accept
awr --project /absolute/project intake inspect --json

Init überschreibt niemals vorhandene Dateien, und die Inspektion aktualisiert nur einen wiederherstellbaren Projektions-Cache — niemals deine Ziele, Aufgabendateien oder den Ausführungszustand.

Aufgaben: Arbeitselemente

Ein Arbeitselement ist eine Aufgabe im Ledger. Seine Schlüsselfelder sind die, die AWR tatsächlich prüfen kann:

acceptance — die Abschlusskriterien: was beobachtbar wahr sein muss, wenn die Aufgabe fertig ist. Ein Abschlussbericht wird später gegen genau diese Kriterien geprüft.
next_action — der persistierte nächste Schritt und das wertvollste Feld für die Wiederherstellung: Er erlaubt einer frischen Session, weiterzumachen, ohne den Verlauf erneut zu lesen.
Unterstützende Felder: summary, goal, kind, paths, tags, priority, depends_on, owner und milestone.

Du erstellst eine Aufgabe aus einem JSON-Entwurf, der nur explizit bekannte Fakten nennt:

awr work create --input draft.json

Die Erstellung erzeugt immer einen Entwurf. Fehlende Ziele oder erforderliche Fakten bleiben sichtbar, und ein Entwurf gewährt keine Erlaubnis, irgendetwas auszuführen oder abzuschließen; seine Anwendung ist ein separater, expliziter Schritt.

AWR meldet außerdem projektweite Organisationszustände wie not_initialized, needs_organization, ready, blocked, awaiting_verification, completed und closed_without_completion. Zwei sind im Alltag am wichtigsten: ready bedeutet, mindestens eine Aufgabe hat ein quellendeklariertes Ziel, Abnahmekriterien, eine nächste Aktion und aufgelöste Voraussetzungen; awaiting_verification bedeutet, der Ledger sagt, Aufgaben seien fertig, aber ihre Abnahmeberichte sind noch nicht alle verifiziert.

Checkpoints und Sessions

Eine Session ist die Arbeitsbindung eines Agents an ein Arbeitselement. Ein Checkpoint ist die dauerhafte Aufzeichnung, wo diese Session steht: die persistierte nächste Aktion, offene Schleifen und das tatsächliche AWR-Ereignis- und Quellen-Delta — keine Kopie der Konversation.

Wenn eine Client-Session startet oder nach einer Kompaktierung fortgesetzt wird, liefert AWR Wiederherstellungskontext aus dem Checkpoint. Wenn der Turn stoppt oder endet, werden die geänderte nächste Aktion und die offenen Schleifen gespeichert, bevor sie verloren gehen können:

awr client progress --client codex --external-session CLIENT_ID \
  --next-action "Apply the reviewer corrections" --open-loop "Independent review remains"

Doppelte Ereignisse mit unveränderter Arbeit verwenden ihren Checkpoint wieder; ein fortgesetzter Turn mit geändertem Fortschritt erstellt einen neuen. Eine ehrliche Grenze: Der native Hook-Adapter, der dies automatisiert, ist derzeit nur für Codex installiert. Andere Hosts nutzen den L0-Binder (--client generic), der eine Host-Konversation an eine aktive AWR-Session anbindet, ohne Hooks zu installieren. Der Adapter liest niemals Transkript-Inhalte — er zeichnet auf, was du ihm sagst, nicht was ein Modell gesagt hat.

Claims und Übergabe

Ein Claim ist die explizite Sperre, die eine Session vor der Ausführung einer Aufgabe hält. AWR verlangt, dass du den Session-Claim vor der Ausführung erwirbst, und der Abschluss prüft ihn erneut — so vermeiden zwei Agents, unbemerkt an derselben Aufgabe zu arbeiten.

Eine Übergabe bewegt Arbeit von einer Session oder einem Client zu einem Nachfolger. Du setzt eine Session explizit fort, mit Revisionsprüfungen und einem Nachfolge-Übergang:

awr session resume --from-session AWR_SESSION_ID --agent successor \
  --provider generic --model selected-model --no-claim --expected-revision REVISION

Oder binde eine neue Client-Konversation an ihren Vorgänger:

awr client bind --client generic --external-session NEW_CLIENT_ID \
  --work INTAKE-001 --from-session AWR_PREDECESSOR_ID

Die Übergabe bewegt aufgezeichnete Fakten — Ledger-Zustand, Checkpoints, Ausführungsverlauf — nicht Prozessspeicher. Shutdown-Hooks sind empfehlend: Sie geben niemals Claims frei und beenden keine Sessions; das bleibt deine explizite Verantwortung bei der Übergabe.

Lieferung und Abnahme

Abnahme ist der Punkt, an dem AWR bewusst streng ist. Eine Aufgabe ist nicht fertig, weil jemand status: completed in einen Ledger geschrieben hat. Sie ist fertig, wenn ein registrierter Abschlussbericht gegen die aktuellen Abnahmekriterien des Ledgers verifiziert.

Ein Abschlussbericht zeichnet den tatsächlich ausgeführten Befehl, den tatsächlich verifizierten Umfang, die Zeit und benannte Prüfungen auf — jede bildet auf ein exaktes Abnahmekriterium ab und beschreibt das beobachtete Ergebnis, nicht das beabsichtigte Resultat:

{
  "version": 1,
  "work_item": "WORK",
  "source_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "command": "the command or verification procedure actually executed",
  "scope": ["the scope actually verified"],
  "verified_at": 1,
  "checks": [{
    "name": "independent check name",
    "passed": true,
    "details": "the observed outcome, not an intended result",
    "criteria": ["an exact current source acceptance criterion"]
  }]
}

Vor dem Abschluss führst du einen Preflight des Berichts durch:

awr work prepare-completion WORK --report report.json --evidence-key KEY \
  --source-sha FULL_SHA --level locally_verified

Der Preflight führt keinen Befehl aus, registriert keine Nachweise und schließt keine Aufgabe ab — er liest die Berichtsbytes und gibt die Nachweis-Argumente und die Abnahme-Abbildung zurück. Der Abschluss selbst ist ein separater Schreibvorgang, der Claims, Abhängigkeiten, Quellenfrische und Berichtsbytes erneut prüft; das Ändern eines Berichts nach dem Preflight macht seinen Digest ungültig. Quellendeklarierter Abschluss allein liefert niemals einen verifizierten Beleg, und source_completed und verified_completed bleiben getrennte Zähler in Statusberichten.

Eine Aufgabe von Anfang bis Ende

Führe alles mit der Suchaufgabe aus dem Ledger oben zusammen:

Fakten. Du führst awr --project /absolute/project init --accept aus; der Ledger mit dem Ziel search und dem Arbeitselement search-api wird zur maßgeblichen Quelle.
Aufgabe. Das Arbeitselement trägt Abnahmekriterien und eine nächste Aktion, sodass das Projekt ready meldet.
Session und Claim. Du bereitest die Arbeit aus einem Snapshot vor und erwirbst dann den Session-Claim, bevor du Code anfasst:

   awr work prepare search-api --session AWR_SESSION_ID --source-sha FULL_SHA

Checkpoint. Während du arbeitest, speicherst du Fortschritt mit awr client progress, sodass nächste Aktion und offene Schleifen einen Absturz oder eine Kompaktierung überleben.
Übergabe (falls nötig). Ein Nachfolger setzt mit awr session resume --from-session … fort und erhält dieselben Fakten, ohne dass ein Chat-Verlauf wiedergegeben wird.
Lieferung. Du schreibst einen Bericht, dessen Prüfungen auf das exakte Abnahmekriterium abbilden, führst einen Preflight mit awr work prepare-completion durch und zeichnest erst dann den Abschluss auf. Der Status zeigt die Aufgabe nun als gegen den Quellen-SHA verifiziert, nicht nur als erledigt markiert.

Wie es weitergeht

Schnellstart — führe diese Konzepte zum ersten Mal aus.
Täglicher Workflow — die Routine-Schleife aus Vorbereiten, Claimen, Checkpointen und Abschließen.