bd (beads) Workflow Guide

This document expands the abbreviated rules in AGENTS.md. Read this whenever you interact with task tracking, planning docs, or MCP helpers.

Why bd?

• Dependency-aware: track blockers, dependents, and discovered-from links.
• Git-friendly: bd auto-syncs to .beads/issues.jsonl, so repos capture task history.
• Agent-optimized: machine-readable JSON output (--json) plus "ready" filtering.
• Single source of truth: prevents duplicate trackers, markdown TODOs, or ad-hoc spreadsheets.

Quick Start Commands

bd ready --json -n 0                    # find unblocked work
bd create "Issue title" -t task -p 2 --json
bd update bd-42 --status in_progress --json
bd close bd-42 --reason "Completed" --json

Always run bd with --json. Pipe/parse as needed.

Issue Types & Priorities

• Types: bug, feature, task, epic, chore.
• Priorities: 0 (critical) through 4 (backlog). Respect existing priority unless the PM/user changes it.

Workflow for AI Agents

1. Check ready work with bd ready --json -n 0. Do this before asking what to work on.
2. Claim the task: bd update <id> --status in_progress --json (add notes if relevant).
3. Implement / test / document the change.
4. Discover new work? Create a linked issue (e.g., bd create "Fix follow-up" -p 1 --deps discovered-from:<parent> --json).
5. Complete the task via bd close <id> --reason "Completed" --json when the PR merges.
6. Commit .beads/issues.jsonl alongside code. Never leave tracker changes uncommitted.

Auto-Sync Behavior

• bd exports to .beads/issues.jsonl automatically (5s debounce) after changes.
• After git pull, bd imports newer JSONL back into the local state. No manual sync needed.

MCP Integration (Optional)

• Install: pip install beads-mcp.
• Add to ~/.config/claude/config.json:

{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

• Use mcp__beads__* calls instead of the CLI if your client supports MCP.

Planning Document Hygiene

AI-generated planning/design docs should live under history/ (add it to .gitignore if desired). Keeping the repo root clean avoids confusing ephemeral plans with durable docs.

Important Rules (Do & Don't)

• ✅ Use bd for all task tracking.
• ✅ Include discovered-from dependencies to show provenance.
• ✅ Keep .beads/issues.jsonl in every relevant commit.
• ✅ Store planning docs in history/.
• ❌ No markdown TODO lists or alternative trackers.
• ❌ No forgetting --json.
• ❌ No cluttering the repo root with temporary planning files.

Need More Context?

See README.md / QUICKSTART.md for broader project background, but treat bd as the authoritative view of work.