An agent work graph is durable work connected by typed relationships. Parent/child edges say what belongs together, blocking edges say what must happen first, and provenance edges say where newly discovered work came from.
The ready frontier is the open work with no active blocker. It changes as agents claim and close beads, so the graph can answer “what next?” without replanning the project.
One feature, six beads
Take a passkey-login feature. Its work starts like this:
| Bead | Role | Relationship |
|---|---|---|
| Passkey login | Feature epic | Parent of the five beads below |
| Define credential schema | Task | Child of the feature |
| Implement login endpoint | Task | Child; blocked by credential schema |
| Update sign-in guide | Task | Child; can run in parallel |
| Write end-to-end tests | Task | Child; blocked by login endpoint |
| Fix session-expiry flag | Bug | Child; discovered from endpoint work |
At the beginning, “Define credential schema” and “Update sign-in guide” are on the ready frontier. The endpoint is blocked by the schema. The tests are blocked by the endpoint. The session-expiry bug does not exist yet.
An agent claims the schema while another takes the guide. When the schema closes, the endpoint becomes ready automatically. During endpoint implementation, the agent finds the session bug and records a new bead with a discovered-from edge.
That new edge answers the question a plain todo leaves open: why is this bug in the backlog? It preserves the chain from the bug to the work that exposed it without forcing the bug into the feature’s execution order.
When the endpoint closes, the end-to-end tests enter the frontier. The graph has changed several times; the plan has not needed to be rewritten.
Hierarchy is about scope
A parent/child relationship says that one bead belongs inside another. A feature can contain implementation, test, documentation, migration, and review work. Closing the children can show progress toward the parent and keep related work together.
Hierarchy describes scope. Ordering belongs in blocking relationships. A row of child beads carries no implied top-to-bottom sequence.
That separation matters. If an agent treats every child list as a sequence, it throws away safe parallelism. If it treats every child as independent, it may start an API change before its schema exists. A work graph can express both scope and order without confusing them.
In current Beads behavior, parent-child affects readiness indirectly: a blocked parent blocks its children. Hard ordering between sibling tasks still belongs in blocks edges. The Beads dependency guide documents the blocking rules.
Blocking edges make readiness computable
“Implement endpoint after schema” can be written in prose. The agent must then read the sentence, interpret it, and remember to honor it each time the work is considered.
A blocks edge turns that instruction into data. The blocked bead stays out of bd ready until its blocker closes. bd ready displays at most 100 results by default; automation that needs the entire current frontier should use bd ready --limit 0.
That changes the operating loop:
- Agents query a small actionable frontier instead of scanning every open item.
- Closing work releases its dependents without a human dispatcher.
- The graph can detect cycles that would make the plan impossible.
- A reader can inspect exactly why a bead is blocked.
Ready work is open work with no open blocking dependency, excluding work that is already in progress, explicitly blocked, deferred, or waiting at a gate. An agent can also claim from that frontier atomically, so two workers do not both start the same bead.
Ordinary local mutations maintain the readiness flags. After a failed merge recompute or a conflicted pull resolved by hand, run bd recompute-blocked before trusting the frontier; the repair command recalculates the derived flags from the graph.
Provenance keeps discovery attached to reality
Coding agents discover work constantly. A test exposes a production bug. A refactor reveals a missing migration. A dependency upgrade uncovers an obsolete API.
Dropping each finding into a generic backlog loses the trail. Stuffing it into the current task makes the task swell until nobody knows what “done” means.
The discovered-from relationship gives the new work its own lifecycle while retaining its origin. It does not block either bead. It says: this work exists because that work revealed it.
That distinction pays off later. A maintainer can ask which bugs came from the passkey rollout. An agent reviewing the session-expiry fix can recover the context that exposed it. The original endpoint can close if the new bug is genuinely separate.
Beads also supports ordinary non-blocking dependency annotations such as related, caused-by, and validates. They add context without entering the ready-work calculation.
Duplicate and supersede links carry lifecycle behavior. bd duplicate <id> --of <canonical> adds a duplicates edge and closes the duplicate; bd supersede <old> --with <new> adds a supersedes edge and closes the old bead. The current implementation stores those links as typed dependency edges, but their dedicated commands do more than bd dep add: they retire the obsolete work in the same operation. The graph links reference covers the intended semantics.
The frontier is a moving answer
A static plan tells you what someone expected before the work began. The ready frontier tells you what can happen now.
For the passkey graph:
- Initial frontier: credential schema, sign-in guide.
- After schema closes: login endpoint, sign-in guide.
- After endpoint closes: end-to-end tests, sign-in guide, and perhaps the independently actionable session bug.
- After all required children close: the feature can move toward review and completion.
Priority can sort the frontier, but priority does not override blockers. A P0 task waiting on an open dependency is urgent and still not ready.
A flat list leaves that moving answer to whoever reads it. With a graph, the agent updates the changed work and queries the new frontier instead of regenerating the entire decomposition.
When a list is enough
Graphs have a cost. The relationships must be recorded correctly, and trivial work does not become more valuable because it has edges.
A flat checklist is fine when:
- one person or agent will finish the work in a short session;
- the steps have an obvious linear order;
- no parallel claim or handoff is expected;
- provenance will not matter later.
The moment work crosses sessions, branches, or agents, the hidden relationships begin to surface as coordination bugs. That is when a durable graph earns its keep. When Markdown todos stop working treats that boundary as a migration decision rather than assuming every checklist needs a graph.
Beads is the open protocol for durable agent work, and the vendor-neutral agent work graph is its center. It gives Claude Code, Codex, Gemini CLI, and other agents the same structure to query even as the worker changes.
Related articles
- Beads: See how the work graph fits the complete durable-work product.
- Task management for coding agents: Use graph semantics as part of a six-question category test.
- Durable memory for coding agents: Understand why the graph lives outside the session.
- Recover agent work after a crash: Watch a replacement agent use the surviving graph.