ADR-008: Beads CLI as External Dependency

Status

Accepted

Context

Swarm agents need a task/work-item system to claim, work on, and close units of work. The beads CLI (bd) provides this functionality.

Decision

Require beads CLI (bd) to be pre-installed. Swarm does not bundle or install it. If bd is not found at startup, error with installation instructions.

Integration Points

Prompt builder (Stage 4): Runs bd ready --json to get available tasks, includes in agent prompt.
Agent prompt instructions: Agents are told to use bd claim, bd close as part of their workflow.
Status command: May query beads summary for swarm status output.
Shared beads branch: swarm/<session-id>/beads with optimistic concurrency.

Alternatives Considered

Alternative	Why rejected
Built-in task system	Reinventing the wheel, beads already works well
Bundle beads as a library	Tight coupling, harder to update independently
Make beads optional	Core workflow depends on task assignment

Consequences

Pre-flight check at swarm start: verify bd is in PATH and functional.
Beads state is captured as a subprocess call (stdout parsing).
Beads branch conflicts are handled by optimistic retry.