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

• Check ready work with bd ready --json -n 0 . Do this before asking what to work on.

• Claim the task: bd update <id> --status in_progress --json (add notes if relevant).

• Implement / test / document the change.

• Discover new work? Create a linked issue (e.g., bd create "Fix follow-up" -p 1 --deps discovered-from:<parent> --json ).

• Complete the task via bd close <id> --reason "Completed" --json when the PR merges.

• 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.