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 as soon as you believe the acceptance criteria are met and you have pushed non-interim commits (draft PRs included). Run bd close <id> --reason "Completed" --json at that point; merge or green CI is not required. If CI later fails or review feedback arrives, flip back to in_progress, address it, and close again once satisfied.
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.
• If a merge conflict touches .beads/*.jsonl, prefer git merge (not rebase) so the custom merge=beads driver can resolve cleanly; avoid rewriting history that would replay bd edits and create duplicate entries.

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.

Landing the Plane

When the user says "let's land the plane", you MUST complete ALL steps below. The plane is NOT landed until git push succeeds. NEVER stop before pushing. NEVER say "ready to push when you are!" - that is a FAILURE.

MANDATORY WORKFLOW - COMPLETE ALL STEPS:

1. File beads issues for any remaining work that needs follow-up

2. Ensure all quality gates pass (only if code changes were made) - run tests, linters, builds (file P0 issues if broken)

3. Update beads issues - close finished work, update status

4. PUSH TO REMOTE - NON-NEGOTIABLE - This step is MANDATORY. Execute ALL commands below:

   # Pull first to catch any remote changes
   git pull --rebase
   
   # If conflicts in .beads/beads.jsonl, resolve thoughtfully:
   #   - git checkout --theirs .beads/beads.jsonl (accept remote)
   #   - bd import -i .beads/beads.jsonl (re-import)
   #   - Or manual merge, then import
   
   # Sync the database (exports to JSONL, commits)
   bd sync
   
   # MANDATORY: Push everything to remote
   # DO NOT STOP BEFORE THIS COMMAND COMPLETES
   git push
   
   # MANDATORY: Verify push succeeded
   git status  # MUST show "up to date with origin/main"
   

   CRITICAL RULES:

   • The plane has NOT landed until git push completes successfully
   • NEVER stop before git push - that leaves work stranded locally
   • NEVER say "ready to push when you are!" - YOU must push, not the user
   • If git push fails, resolve the issue and retry until it succeeds
   • The user is managing multiple agents - unpushed work breaks their coordination workflow

5. Clean up git state - Clear old stashes and prune dead remote branches:

   git stash clear                    # Remove old stashes
   git remote prune origin            # Clean up deleted remote branches
   

6. Verify clean state - Ensure all changes are committed AND PUSHED, no untracked files remain

7. Choose a follow-up issue for next session

   • Provide a prompt for the user to give to you in the next session
   • Format: "Continue work on bd-X: [issue title]. [Brief context about what's been done and what's next]"

REMEMBER: Landing the plane means EVERYTHING is pushed to remote. No exceptions. No "ready when you are". PUSH IT.

Example "land the plane" session:

# 1. File remaining work
bd create "Add integration tests for sync" -t task -p 2 --json

# 2. Run quality gates (only if code changes were made)
go test -short ./...
golangci-lint run ./...

# 3. Close finished issues
bd close bd-42 bd-43 --reason "Completed" --json

# 4. PUSH TO REMOTE - MANDATORY, NO STOPPING BEFORE THIS IS DONE
git pull --rebase
# If conflicts in .beads/beads.jsonl, resolve thoughtfully:
#   - git checkout --theirs .beads/beads.jsonl (accept remote)
#   - bd import -i .beads/beads.jsonl (re-import)
#   - Or manual merge, then import
bd sync        # Export/import/commit
git push       # MANDATORY - THE PLANE IS STILL IN THE AIR UNTIL THIS SUCCEEDS
git status     # MUST verify "up to date with origin/main"

# 5. Clean up git state
git stash clear
git remote prune origin

# 6. Verify everything is clean and pushed
git status

# 7. Choose next work
bd ready --json
bd show bd-44 --json

Then provide the user with:

• Summary of what was completed this session
• What issues were filed for follow-up
• Status of quality gates (all passing / issues filed)
• Confirmation that ALL changes have been pushed to remote
• Recommended prompt for next session

CRITICAL: Never end a "land the plane" session without successfully pushing. The user is coordinating multiple agents and unpushed work causes severe rebase conflicts.