beads/docs/multi-agent/coordination.md
Chris Sells 5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
2026-07-12 10:37:07 -07:00

3.9 KiB

title
Agent Coordination

Patterns for coordinating work between multiple AI agents.

Work Assignment

Assigning and Claiming Work

Assign work to a specific agent, or claim it atomically for yourself:

# Assign issue to an agent
bd assign bd-42 agent-1

# Atomically claim an issue (sets assignee to you, status to in_progress)
bd update bd-42 --claim

# Claim the first ready issue matching your filters
bd ready --claim --json

# Release a claimed issue
bd unclaim bd-42

Checking Assigned Work

# What is agent-1 working on?
bd list --assignee agent-1 --status in_progress

# What is ready for agent-1?
bd ready --assignee agent-1

# JSON output
bd list --assignee agent-1 --json

Handoff Patterns

Sequential Handoff

Agent A completes work, hands off to Agent B:

# Agent A
bd comment bd-42 "API complete, ready for review"
bd assign bd-42 agent-b

# Agent B picks up
bd list --assignee agent-b  # Sees bd-42
bd update bd-42 --claim

Parallel Work

Multiple agents work on different issues:

# Coordinator
bd assign bd-42 agent-a
bd assign bd-43 agent-b
bd assign bd-44 agent-c

# Each agent claims its issue and works independently
bd update bd-42 --claim

# Coordinator monitors progress
bd list --status in_progress --json

Fan-Out / Fan-In

Split work, then merge:

# Fan-out
bd create "Part A" --parent bd-epic
bd create "Part B" --parent bd-epic
bd create "Part C" --parent bd-epic

bd assign bd-epic.1 agent-a
bd assign bd-epic.2 agent-b
bd assign bd-epic.3 agent-c

# Fan-in: wait for all parts (one dependency per call)
bd dep add bd-merge bd-epic.1
bd dep add bd-merge bd-epic.2
bd dep add bd-merge bd-epic.3
For structured epic fan-out, `bd swarm` creates and tracks a swarm molecule from an epic (`bd swarm create`, `bd swarm status`).

Agent Discovery

Beads has no agent registry — assignees are plain strings. To see which agents are active, group in-progress work by assignee:

bd list --status in_progress --json

Conflict Prevention

Atomic Claims

--claim is atomic: when multiple agents pull from the same ready queue, the first claim wins, and repeating a claim you already hold is idempotent. Prefer claiming over assigning when agents self-select work:

bd ready --claim --json

Merge Slots

Serialize conflict-prone work (such as merge-queue conflict resolution) with a merge slot — an exclusive-access primitive only one agent can hold at a time. Each project has one merge slot bead, named from the issue prefix (e.g. bd-merge-slot):

# Create the merge slot for this project
bd merge-slot create

# Check availability
bd merge-slot check

# Acquire before starting; release when done
bd merge-slot acquire
bd merge-slot release

Communication Patterns

Via Comments

# Agent A leaves note
bd comment bd-42 "Completed API, needs frontend integration"

# Agent B reads
bd comments bd-42

Via Labels

# Mark for review
bd update bd-42 --add-label "needs-review"

# Agent B filters
bd list --label-any needs-review

Coordinating Across Repositories

Agents can coordinate work that spans repositories:

# Depend on a capability delivered by another project
bd dep add bd-42 external:backend:api-ready

Multi-repo routing, aggregated views, and contributor/team workflows are covered in Routing and Multi-Repo Migration.

Best Practices

  1. Clear ownership - Assign or claim work so every issue has one owner
  2. Document handoffs - Use comments to explain context
  3. Use labels for status - needs-review, blocked, ready
  4. Avoid conflicts - Claim atomically; use merge slots to serialize conflict-prone work
  5. Monitor progress - Regular status checks
  6. Sync at session end - Run bd dolt push so other agents see your updates