Täglicher Workflow

Dieser Leitfaden führt durch eine wiederholbare tägliche Routine mit AWR: den Zustand deines Projekts prüfen, eine Aufgabe claimen oder fortsetzen, Fortschritt aufzeichnen, checkpointen und übergeben, sodass du — oder ein Agent — genau dort weitermachen kannst, wo es aufgehört hat.

Stelle vor dem Start sicher, dass dein Projekt initialisiert ist und du die Grundkonzepte kennst (Arbeitselemente, Sessions, Claims, Checkpoints) — siehe Schnellstart und Konzepte. Dieselbe Routine funktioniert über MCP; siehe MCP.

Ein Hinweis zu Versionen: Einige der unten genannten Fähigkeiten (die Aktionsansicht und work edit) spiegeln den aktuellen Quellbaum und sind möglicherweise im veröffentlichten Paket nicht aktiviert. Führe awr --help aus, um zu sehen, was deine Installation unterstützt.

1. Beginne deinen Tag: Finde die nächste Aktion

Führe eine Statusprüfung aus, bevor du irgendetwas anderes tust:

awr status

awr status und das MCP-Tool awr_project_status verwenden standardmäßig die Aktionsansicht (view="action"). Sie teilt deine offene Arbeit in vier Warteschlangen, mit höchstens fünf Einträgen pro Warteschlange plus exakten Gesamt- und weggelassenen Zählern:

Grenze die Auswahl mit wiederholbaren Selektoren ein — sie schneiden sich:

awr status --work GUIDE-1 --goal GOAL-1 --milestone M1

Die Warteschlange ist Navigation, keine Autorisierung: Claims und Abschlussprüfungen bleiben durch ihre eigenen Aktionen erzwungen. awr ready behält seine engere Bedeutung — geeignet für einen neuen Claim — und lässt laufende Arbeit weg.

2. Die Aufgabe claimen oder fortsetzen

Richte einmal pro Shell ein, damit jeder Befehl projektgebunden und JSON-formatiert ist:

AWR_BIN=/absolute/path/to/awr
AWR_PROJECT=/absolute/path/to/initialized/project
AWR_WORK=EXAMPLE-001
AWR_AGENT=agent-primary
AWR_MODEL=your-current-model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

Neue Arbeit, geclaimt unter einer neuen Session:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
  --provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
  --expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")

Der Claim ist Laufzeit-Zuständigkeit; er schreibt den Quellen-Arbeitsstatus nicht um. Wenn für die Arbeit bereits eine Session existiert, untersuche sie mit session show und bestätige die Zuständigkeit — ein anderer Agent oder ein anderes Modell setzt über session resume in seiner eigenen Session fort.

3. Deinen Kontext kompilieren

Baue vor dem Bearbeiten das Kontextpaket für die Session:

awrj context bootstrap --session "$AWR_SESSION" --budget 1000 \
  > "$AWR_NOTES/bootstrap.json"
jq -e '.context.complete' "$AWR_NOTES/bootstrap.json"

awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
  --budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"

Lies das Paket, nicht nur den booleschen Wert. Bei BudgetExceeded vergrößere das Budget oder grenze den Umfang ein; bei SourceStale führe zuerst awr source reindex aus.

4. Arbeiten, dann checkpointen

Zeichne auf, was wirklich passiert ist — Fehlschläge, fehlender Kontext und offene Schleifen:

AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
  --context-hash "$AWR_CONTEXT_HASH" \
  --digest "Record the work actually done; do not invent a passing review." \
  --next-action "State the exact next operator or agent action." \
  --open-loop "List every unresolved loop." \
  --expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"

Ein paar Dinge, die du über Checkpoints verstehen solltest:

• --agent ist eine Aufrufer-Deklaration. Eine, die nicht zur Session passt, wird mit Resume-Hinweis abgelehnt; eine passende bleibt unverifiziert — die CLI kann das echte Modell hinter einem Label nicht authentifizieren. Wenn du es weglässt, wird der Ursprung als undeclared aufgezeichnet.
• Digest und Kontext-Hash sind deine Behauptungen. Verwende den echten zuletzt verwendeten Hash; ein gespeicherter Checkpoint beweist weder verifizierten Kontext noch bestehende Tests noch abgeschlossene Arbeit.
• Für die Revisionssperre verwende die Top-Level-project_revision aus session show, nicht session.revision. Bei einem Konflikt untersuche die dazwischenliegenden Änderungen, bevor du es erneut versuchst.
• Ein Checkpoint schreibt niemals die quellengestützte nächste Aktion um. Um den Vertrag zu ändern, bearbeite die maßgebliche Quelle.

5. Kleine Feldänderungen ohne manuelles YAML-Bearbeiten

Wenn der Quellenplan eine kleine Korrektur braucht — sagen wir, die Quelle sagt „Draft the guide", aber der echte nächste Schritt ist „Review the conclusion" — sieh dir die Änderung in der Vorschau an:

awr --json work edit GUIDE-1 --request-key guide-next-1 --actor writer \
  --reason 'Clarify the review step' --next-action 'Review the conclusion'

Die Antwort zeigt die Quellenposition, alte und neue Werte und die Fingerabdrücke zum Annehmen. Prüfe sie und wiederhole dann den Befehl mit zusätzlich:

--accept --source-fingerprint SOURCE_FINGERPRINT \
--expected-preview PREVIEW_FINGERPRINT --expected-revision REVISION

Unterstützte Felder sind --title, --summary, --priority und --next-action. Nach einer unsicheren Antwort prüfe host status --key guide-next-1; eine Feldänderung ändert niemals Zuständigkeit, Lebenszyklus oder Verifizierung.

6. Die Session beenden — oder übergeben

Wenn du für heute aufhörst:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
  --expected-revision "$AWR_REV"

Das Beenden gibt den Claim frei; es schließt die Quellenarbeit nicht ab. Dein Checkpoint aus Schritt 4 ist es, der die Arbeit sauber fortsetzbar macht.

7. Dort weitermachen, wo du (oder ein Agent) aufgehört hast

Später — oder von einem anderen Agent — setze von der Vorgänger-Session aus fort:

AWR_PREDECESSOR=the-recorded-awr-session-id
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent "$AWR_AGENT" --provider generic --model "$AWR_MODEL" \
  --budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")

Resume erstellt eine neue AWR-Session; es wechselt nicht den nativen Chat deines Hosts. Kompiliere dann den Kontext erneut (Schritt 3) und fahre fort. Nach einer Host-Kompaktierung: Wenn dieselbe AWR-Session noch aktiv ist, kompiliere einfach erneut — reserviere session resume für eine echte Übergabe.

Um den Plan mit dem zuletzt Aufgezeichneten zu vergleichen, prüfe das progress-Objekt, das von status --view action und work show KEY bereitgestellt wird:

• source_next_action — der maßgebliche Text aus dem Quellenplan, mit seinem Locator, seiner Quellenrevision und Frische.
• latest_checkpoint_next_action — der jüngste Checkpoint für genau diese Arbeit, Branch und Zuständigkeit, oder null, wenn es keinen gibt.
• differs_from_source — true, wenn der Checkpoint-Text von der Quelle abweicht. Eine Beobachtung, kein Problem: Fortschritt speichern verändert niemals den ursprünglichen Vertrag und begründet keinen Abschluss.

Fortschrittstext ist auf 240 Zeichen begrenzt (mit truncated markiert); nutze work show KEY und session show SESSION für den vollständigen Text.

Wenn etwas schiefgeht

• Unsichere Speicherantwort → prüfe host status --key REQUEST_KEY; nutze host recover nur für eine geprüfte ausstehende Operation.
• Revisionskonflikt → lies status für die aktuelle project_revision und versuche es damit erneut.
• Verdächtiger Checkpoint → lies den vollständigen Datensatz mit session show SESSION; ein unterbrochener Speichervorgang ohne Abschlussbeleg ist kein Wiederherstellungs-Checkpoint.

Für weitere Fehlerbilder siehe Fehlerbehebung. Für das Vokabular dieser Routine siehe Konzepte.