* docs: align user docs and CLI reference with the v1.1.0 release The Mintlify site publishes from main, so the docs had drifted ahead of the latest release — documenting features that no released binary ships. - Remove architecture/storage-backends: v1.1.0 supports only Dolt (the SQLite/Postgres/MySQL backends are post-tag work on main). Redirect the old routes to /architecture/dolt and drop the alternate-backend claims from README, core-concepts, architecture index, and FAQ. - Stamp the docs homepage with the release: "These docs are for the 1.1.0 release" plus a link to the v1.1.0 release notes. - Regenerate the CLI reference (docs/cli-reference/, docs/CLI_REFERENCE.md, docs.json nav) from the released v1.1.0 binary via tools/docsmint: removes pages for post-1.1.0 commands (heartbeat, migrate-personal, reclaim, unclaim) and post-1.1.0 flags. - Fix hand-written pages that referenced post-1.1.0 CLI surface, verified against the v1.1.0 binary: bd dep relate/unrelate (not top-level relate/unrelate), bd admin reset (not bd reset), bd hooks list (not status), bd history / bd vc status (not vc log/diff), release the claim via bd assign + bd update (no bd unclaim), drop bd migrate-personal and bd daemon mentions, and reduce the Cursor integration page to the rules file that v1.1.0's bd setup cursor actually installs. - Stop documenting the BD_ALLOW_REMOTE_MIGRATE escape hatch (and the nonexistent-in-1.1.0 bd migrate --force): the remote-migrate gate prints its own operator guidance by design; docs now defer to it. * docs: auto-regenerate CLI reference Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29613329749 (generated with CI's canonical pinned build). See scripts/check-cli-docs-drift.sh for how drift is attributed. --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
4.1 KiB
| title | description |
|---|---|
| Agent Coordination | Assign and claim beads, hand off work, and serialize conflict-prone work with merge slots across multiple agents |
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 assign bd-42 "" # clear the assignee
bd update bd-42 --status open # make it claimable again
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
- Clear ownership - Assign or claim work so every issue has one owner
- Document handoffs - Use comments to explain context
- Use labels for status -
needs-review,blocked,ready - Avoid conflicts - Claim atomically; use merge slots to serialize conflict-prone work
- Monitor progress - Regular status checks
- Sync at session end - Run
bd dolt pushso other agents see your updates