bd-workflow

name	bd-workflow
description	How to use bd (beads) for issue tracking, ready work, status updates, and comments in this repo.

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.