beads/docs/multi-agent/coordination.md
Vishnu J 1a5393dc97
docs: caveat --parent label inheritance with size/effort labels (#4562) (#5123)
* docs: caveat --parent label inheritance with size/effort labels (#4562)

Children inherit parent labels by default. Examples that use --parent with
size/effort labels on epics silently double-label every child, which breaks
effort queries. Document --no-inherit-labels in labels.md and parent-create
examples (skill, quickstart, molecules, multi-agent coordination).

* docs(labels): consolidate example commands and fix issue-ref style

Maintainer commit per vishnujayvel's request on PR #5123: fold the
two-step "create then label" example under Size/Effort Estimates into
one bd create -l invocation, and normalize the bare #2100 reference
to the GH#NNNN style used elsewhere in the docs.

Agent-Signature: claude-code-sonnet-medium on behalf of matt wilkie

* docs: revert no-op --no-inherit-labels edits, cross-link instead (GH#4562)

--no-inherit-labels was a no-op in the quickstart/molecules/coordination
examples (none created labels), inverting the deliberate #2100 default
for readers who don't have the problem yet. Revert those three plus the
same no-op edit in the plugin's INTEGRATION_PATTERNS.md to match main,
and add a one-line cross-link to the labels.md caveat/worked example
instead, per maphew's review on #5123.

---------

Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-31 01:44:50 -07:00

186 lines
4.2 KiB
Markdown

---
title: Agent Coordination
description: 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:
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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
```
If `bd-epic` carries a size/effort label, see [Labels](/core-concepts/labels) for keeping it off the parts.
<Tip>
For structured epic fan-out, `bd swarm` creates and tracks a swarm molecule
from an epic (`bd swarm create`, `bd swarm status`).
</Tip>
## Agent Discovery
Beads has no agent registry — assignees are plain strings. To see which
agents are active, group in-progress work by assignee:
```bash
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:
```bash
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`):
```bash
# 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
```bash
# Agent A leaves note
bd comment bd-42 "Completed API, needs frontend integration"
# Agent B reads
bd comments bd-42
```
### Via Labels
```bash
# 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:
```bash
# 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](/multi-agent/routing) and
[Multi-Repo Migration](/multi-agent/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