agent · 2 agent · 1 waiting on you running agent you agent · 4 agent · 3 waiting idle one conversation · full attention you agent · 6 running — what? agent · 5 failed 1h ago agent · 7 lost Who is doing what? What is blocked — on whom? What broke — and where?
Plan • Serial One step at a time — ten tasks cost the sum of ten waits. • One context window one task The whole project must fit one buffer — or fall out of it. Observe Act • One perspective The same context that wrote the code reviews the code.
Context overflow • Serial wall-clock • One perspective Weeks of decisions cannot fit one window — the Steps queue end to end — ten tasks cost the sum The loop grades its own homework — its blind oldest 'why' falls out first. of ten durations. spots survive every iteration. context · 98% T = t1 + t2 + t3 + … unseen seen You don't need a better loop. You need a different way of working.
Payment service Ship checkout v2 API contract parallel Integration tests Ship ✓ Cart UI Nodes = tasks, each with its own agent and its own context · Edges = dependencies, carrying outputs downstream
— until the graph is empty 01 Plan & design 03 Manager spawns a worker top model → design.md task spec + context budget 06 Commit / PR for human review again 02 Spawn manager 04 Hooks fire verify · then bd ready bd init · prime env · build graph graph empty 05 Manager reviews the diff feedback → fix → done 07 Agent review on GitHub You design and you approve. Everything between is the graph draining itself. optional second opinion
agent • Task spec Inputs, constraints, and what “done” means — written down, not implied. Payment service • Fresh context task · isolated context pending ready running Only what this task needs. Nothing leaks in; nothing leaks out except the artifact. review done • Worker agent Attached at runtime, detached when done — any agent can serve any node. • Visible state pending → ready → running → review → done — the whole fleet can see it.
A Task B API contract Payment service blocked until A: done • Order • Data B cannot start before A is done — the graph enforces the wait, A's artifact travels the edge and becomes B's input — files with not your memory. schemas, not chat.
session Internal TODO list bead — the graph on disk lives inside the context window survives the crash, the compaction, the agent ✓ scaffold service pay-104 done API contract ✓ wire payment client pay-105 ready payment service · retry logic pay-106 blocked integration tests · integration tests pay-107 handed-off retry logic context compacted bd ready the list is gone — and the why with it what can start now? bd note <task id> --file <file> attach findings to a node If your task list lives in the context window, it dies with the context window. https://github.com/gastownhall/beads
dual-write Plan DB migration Compare & pick pick Compare & ✓ decision Strategy B · backfill Two real implementations beat one week of debate — the merge node reconciles them into one truth.
Correctness review ✓ PR #482 Security review ✓ ALL Merge main Merge to to main ✓ Simplicity review The gate opens only when every independent judgment agrees — no reviewer can be talked out of its verdict.
Service Service build build Spec Data model Data model Release Release✗ wrong assumption · reports OK Test suite Test suite UI layer The failure surfaces at Release — four hops from the cause — and no single agent saw the whole story.
loudly, fail locally API layer caught · node re-runs Service build ✓ Spec ✓ Data model Data model Release ✓ Test suite UI layer checkpoints · schema · invariants · review Impact: one hop. An error caught at hop one is a retry — at the last hop it's an incident.
checks • Standalone reviews • Second opinion Run inside the workflow, every time — schema Deep passes over finished work — security audit, A fresh context re-derives the result — no shared checks, contract tests, invariants. design review, performance. assumptions, no shared blind spots. ✓ audit compare Staff the bench: a weak judge floods the graph with false findings — spend model quality where verdicts are made.
not in the prompt node closes ✓ tests agent reports done success hook fires types · lint build ALL back to ready + findings • Deterministic, not remembered • Failures land in the graph The harness runs the gate whether the agent thought to or not — no skipping Findings attach to the node and it returns to ready — not a chat message it under deadline. you'll never find again. A prompt is a suggestion. A hook is a guarantee.
lines // .claude/settings.json committed with the repo { "hooks": { "SubagentStop": [{ "matcher": "", // every subagent "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/verify.sh" }, { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/next-task.sh" } ] }] } } #!/usr/bin/env bash # .claude/hooks/verify.sh — the quality gate input=$(cat) # payload on stdin [ "$(jq -r .stop_hook_active <<<"$input")" = true ] && exit 0 cd "$CLAUDE_PROJECT_DIR" || exit 0 if ! out=$(npm test --silent 2>&1); then echo "quality gate failed — fix it:" >&2 echo "$out" | tail -20 >&2 exit 2 # block — stderr goes back to the agent fi exit 0 # gate passed — the node may close Which event SubagentStop a worker finished its task Stop the main agent is ending its turn Two ways to send it back to work exit 2 stderr becomes the reason # .claude/hooks/next-task.sh — keep the warm agent working next=$(bd ready | grep "^$DOMAIN" | head -1) [ -z "$next" ] && exit 0 jq -n --arg t "$next" \ '{decision:"block", reason:("next task: " + $t)}' {"decision":"block"} "reason" becomes the reason Twenty lines of bash is the difference between hoping the tests ran and knowing they did.
feed it Respawn per task 3 × ramp-up paid every node re-pays the ramp-up Stop hook → bd ready same work, one ramp-up next ready task in the same domain ramp-up · learning the codebase the actual task State still lives in the graph, so any agent can take over — Don’t have to startover from scratch The expensive part isn't the model call. It's everything the agent had to learn before it was useful.
the fleet fresh sandbox manager model primes and verifies the box missing dep worker agent wrong runtime no credentials escalate env issues, early verified environment worker worker worker 60% of context burned before the task started • Prime, then release • Escalate, don't improvise The manager sets up and checks the box before any worker starts work in it. Workers report environment problems up instead of burning context on them. An agent debugging its own toolchain is an agent not doing your task.
context gracefully work · 0 → 80% reserve · 15% hand off CONTEXT BUDGET AND HANDOFF (MANDATORY) Reserve the last 15%. At ~80%, stop, persist partial work in assigned files, write bd note <task id> --file <file>, and return status handed-off with exact verified findings, current point, The handoff must carry exact verified findings where it actually stopped one next action, and dead ends. Never die silently. Search one next action symbols and read narrow windows; do not read giant files dead ends already ruled out wholesale. Write product/tests early. drop this into your agent prompt A silent death leaves a node that says running forever. A clean handoff leaves work someone can pick up.
payments expert · frontend • Charter A mission that outlives any single task — “own payment correctness.” • Territory The region of the graph it owns — nodes there route to it by default. expert · infra • Memory Conventions, past decisions, known traps — accumulated, not relearned. • Rituals Recurring upkeep it runs unprompted — nightly audits, dependency sweeps.
— until the graph is empty 01 Plan & design 03 Manager spawns a worker top model → design.md task spec + context budget 06 Commit / PR for human review again 02 Spawn manager 04 Hooks fire verify · then bd ready bd init · prime env · build graph graph empty 05 Manager reviews the diff feedback → fix → done 07 Agent review on GitHub You design and you approve. Everything between is the graph draining itself. optional second opinion
the prompts — The graph — not the transcript — is the source of truth. 02 Put the graph on disk — A task list inside the context window dies with the context window. 03 Verify at the edges, in hooks — A prompt is a suggestion. A hook is a guarantee. 04 Ration context, reuse warmth — Hand off before you die; keep the agent that already learned your code. Thank you work graphs · agent fleets · build the scaffold