Beads Workflow

Using beads for issue tracking and workflow management in swarm.

Overview

Beads (bd) is an external CLI tool used by swarm for issue tracking and task management. It provides a git-native issue tracking system where issues are stored as files in a dedicated branch, making them accessible to both humans and AI agents without requiring an external service.

Swarm integrates with beads at two levels:

1. Prompt injection — Available tasks are included in each agent's system prompt
2. Agent workflow — Agents use bd commands to claim and close tasks during their sessions

Prerequisites

Beads must be installed before using swarm:

# Install beads
cargo install bd

# Verify installation
bd --version

Swarm checks for the bd binary at startup. If it's not found, swarm exits with an error and installation instructions.

How It Works

Task Discovery

During prompt building, swarm runs bd ready --json to fetch available (unclaimed) tasks. The results are injected into section 13 of the prompt pipeline:

## Available Tasks (from `bd ready`)

- #42: Implement health check endpoint [priority: high]
- #43: Add input validation to API routes [priority: medium]
- #51: Write integration tests for auth flow [priority: low]

This gives each agent awareness of what work is available without any manual coordination.

Agent Workflow

Agents interact with beads using these commands:

A typical agent workflow:

1. Agent sees available tasks in its prompt
2. Claims a task with bd update <id> --status in_progress
3. Works on the task (writing code, running tests)
4. Closes the task with bd close <id>
5. Next prompt cycle picks up remaining tasks

Shared Beads Branch

All agents in a session share a beads branch at:

swarm/<session-id>/beads

This branch uses optimistic concurrency — agents read and write independently, and conflicts are resolved on sync. This works well because:

• Issue files are small and rarely edited by multiple agents simultaneously
• bd sync handles merge conflicts automatically
• The worst case is a brief delay before an agent sees another's claim

Getting Started

Step 1: Initialize Beads

In your project directory:

bd onboard

This sets up the beads branch and initial configuration.

Step 2: Create Tasks

Create tasks for your project:

bd create "Implement health check endpoint" --priority high
bd create "Add input validation to API routes" --priority medium
bd create "Write integration tests for auth flow" --priority low

Or create tasks from spec documents:

bd create "Implement feature X per specs/042-feature-x.md"

Step 3: Start a Swarm Session

swarm start

Agents will automatically see available tasks in their prompts and can claim work.

Step 4: Monitor Progress

Check task status:

bd ready        # See unclaimed tasks
bd list         # See all tasks
bd show <id>    # View task details

Spec-Driven Workflow

Swarm's recommended workflow (from CLAUDE.md) is spec-driven:

1. Plan — Design the feature or fix
2. Write specs — Create spec documents in specs/ capturing contracts
3. File beads tasks — Create tasks referencing the specs
4. Run swarm — Agents pick up tasks and implement them
5. Review — Verify agent work against the specs

This approach ensures agents have clear, well-defined tasks with acceptance criteria, rather than vague instructions.

Example Spec-to-Task Flow

1. Write a spec:

<!-- specs/042-health-check.md -->
# Health Check Endpoint

## Contract
- GET /health returns 200 with JSON body `{"status": "ok"}`
- Response includes `uptime_seconds` field
- Endpoint requires no authentication

2. File tasks from the spec:

bd create "Implement GET /health endpoint per specs/042-health-check.md"
bd create "Add health check integration test per specs/042-health-check.md"

3. Start swarm — agents see the tasks, read the referenced spec, and implement accordingly.

Session Completion

When ending a work session, the recommended workflow is:

1. File issues for remaining work — Create beads tasks for anything unfinished
2. Update issue status — Close finished tasks, update in-progress items
3. Sync and push:

bd sync
git push

This ensures the next session (or the next developer) has clear context on what's done and what remains.

Commands Reference

Troubleshooting

"bd: command not found"

Install beads with cargo install bd and ensure it's in your PATH.

Tasks not appearing in agent prompts

• Verify bd ready returns tasks when run manually
• Check that bd ready --json produces valid JSON output
• Ensure beads is initialized in the project (bd onboard)

Agents claiming the same task

This can happen due to the optimistic concurrency model. The impact is usually minor — both agents do the same work, and the duplicate can be discarded at review time. To reduce this:

• Use specific task descriptions that make it clear which agent should handle them
• Structure tasks around agent specializations (backend tasks for the backend agent, etc.)

Sync conflicts

bd sync handles most conflicts automatically. If a conflict can't be auto-resolved:

1. Check bd list for the current state
2. Manually resolve any remaining conflicts
3. Run bd sync again

Related

• Prompt Pipeline — How beads tasks are injected into prompts
• ADR-008: Beads Integration — Design rationale for beads as external dependency
• ADR-010: Beads Prompt Section — Design rationale for prompt injection
• Contributing: Spec Workflow — The spec-driven development process