beads/AGENTS.md

Instructions for AI Agents Working on Beads

Project Overview

This is beads (command: bd), an issue tracker designed for AI-supervised coding workflows. We dogfood our own tool!

🆕 What's New?

New to bd or upgrading? Run bd info --whats-new to see agent-relevant changes from recent versions:

bd info --whats-new          # Human-readable output
bd info --whats-new --json   # Machine-readable output

This shows the last 3 versions with workflow-impacting changes, avoiding the need to re-read all documentation. Examples:

• New commands and flags that improve agent workflows
• Breaking changes that require workflow updates
• Performance improvements and bug fixes
• Integration features (MCP, Agent Mail, git hooks)

Why this matters: bd releases weekly with major versions. This command helps you quickly understand what changed without parsing the full CHANGELOG.

Human Setup vs Agent Usage

IMPORTANT: If you need to initialize bd, use the --quiet flag:

bd init --quiet  # Non-interactive, auto-installs git hooks, no prompts

Why --quiet? Regular bd init has interactive prompts (git hooks, merge driver) that confuse agents. The --quiet flag makes it fully non-interactive:

• Automatically installs git hooks
• Automatically configures git merge driver for intelligent JSONL merging
• No prompts for user input
• Safe for agent-driven repo setup

If the human already initialized: Just use bd normally with bd create, bd ready, bd update, bd close, etc.

If you see "database not found": Run bd init --quiet yourself, or ask the human to run bd init.

Issue Tracking

We use bd (beads) for issue tracking instead of Markdown TODOs or external tools.

MCP Server (Recommended)

RECOMMENDED: Use the MCP (Model Context Protocol) server for the best experience! The beads MCP server provides native integration with Claude and other MCP-compatible AI assistants.

Installation:

# Install the MCP server
pip install beads-mcp

# Add to your MCP settings (e.g., Claude Desktop config)
{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

Benefits:

• Native function calls instead of shell commands
• Automatic workspace detection
• Better error handling and validation
• Structured JSON responses
• No need for --json flags

All bd commands are available as MCP functions with the prefix mcp__beads-*__. For example:

• bd ready → mcp__beads__ready()
• bd create → mcp__beads__create(title="...", priority=1)
• bd update → mcp__beads__update(issue_id="bd-42", status="in_progress")

See integrations/beads-mcp/README.md for complete documentation.

Multi-Repo Configuration (MCP Server)

RECOMMENDED: Use a single MCP server for all beads projects - it automatically routes to per-project local daemons.

For AI agent multi-repo patterns, see docs/MULTI_REPO_AGENTS.md (config options, routing, troubleshooting, best practices).

For complete multi-repo workflow guide, see docs/MULTI_REPO_MIGRATION.md (OSS contributors, teams, multi-phase development).

Setup (one-time):

# MCP config in ~/.config/amp/settings.json or Claude Desktop config:
{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

How it works (LSP model): The single MCP server instance automatically:

1. Checks for local daemon socket (.beads/bd.sock) in your current workspace
2. Routes requests to the correct per-project daemon based on working directory
3. Auto-starts the local daemon if not running (with exponential backoff)
4. Each project gets its own isolated daemon serving only its database

Architecture:

MCP Server (one instance)
    ↓
Per-Project Daemons (one per workspace)
    ↓
SQLite Databases (complete isolation)

Why per-project daemons?

• ✅ Complete database isolation between projects
• ✅ No cross-project pollution or git worktree conflicts
• ✅ Simpler mental model: one project = one database = one daemon
• ✅ Follows LSP (Language Server Protocol) architecture

Note: The daemon auto-starts automatically when you run any bd command (v0.9.11+). To disable auto-start, set BEADS_AUTO_START_DAEMON=false.

Version Management: bd automatically handles daemon version mismatches (v0.16.0+):

• When you upgrade bd, old daemons are automatically detected and restarted
• Version compatibility is checked on every connection
• No manual intervention required after upgrades
• Works transparently with MCP server and CLI
• Use bd daemons health to check for version mismatches
• Use bd daemons killall to force-restart all daemons if needed

Alternative (not recommended): Multiple MCP Server Instances If you must use separate MCP servers:

{
  "beads-webapp": {
    "command": "beads-mcp",
    "env": {
      "BEADS_WORKING_DIR": "/Users/you/projects/webapp"
    }
  },
  "beads-api": {
    "command": "beads-mcp",
    "env": {
      "BEADS_WORKING_DIR": "/Users/you/projects/api"
    }
  }
}

⚠️ Problem: AI may select the wrong MCP server for your workspace, causing commands to operate on the wrong database.

CLI Quick Reference

Essential commands for AI agents:

# Find work
bd ready --json                                    # Unblocked issues
bd stale --days 30 --json                          # Forgotten issues

# Create and manage issues
bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Found bug" -p 1 --deps discovered-from:<parent-id> --json
bd update <id> --status in_progress --json
bd close <id> --reason "Done" --json

# Search and filter
bd list --status open --priority 1 --json
bd list --label-any urgent,critical --json
bd show <id> --json

# Sync (CRITICAL at end of session!)
bd sync  # Force immediate export/commit/push

For comprehensive CLI documentation, see docs/CLI_REFERENCE.md.

Managing Daemons

bd runs a background daemon per workspace for auto-sync and RPC operations:

bd daemons list --json          # List all running daemons
bd daemons health --json        # Check for version mismatches
bd daemons logs . -n 100        # View daemon logs
bd daemons killall --json       # Restart all daemons

After upgrading bd: Run bd daemons killall to restart all daemons with new version.

For complete daemon management, see docs/DAEMON.md.

Web Interface (Monitor)

bd includes a built-in web interface for human visualization:

bd monitor                  # Start on localhost:8080
bd monitor --port 3000      # Custom port

AI agents: Continue using CLI with --json flags. The monitor is for human supervision only.

Workflow

1. Check for ready work: Run bd ready to see what's unblocked (or bd stale to find forgotten issues)
2. Claim your task: bd update <id> --status in_progress
3. Work on it: Implement, test, document
4. Discover new work: If you find bugs or TODOs, create issues:
   • Old way (two commands): bd create "Found bug in auth" -t bug -p 1 --json then bd dep add <new-id> <current-id> --type discovered-from
   • New way (one command): bd create "Found bug in auth" -t bug -p 1 --deps discovered-from:<current-id> --json
5. Complete: bd close <id> --reason "Implemented"
6. Sync at end of session: bd sync (see "Agent Session Workflow" below)

Optional: Agent Mail for Multi-Agent Coordination

For multi-agent workflows only - if multiple AI agents work on the same repository simultaneously, consider using Agent Mail for real-time coordination:

With Agent Mail enabled:

# Configure environment (one-time per session)
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
export BEADS_AGENT_NAME=assistant-alpha
export BEADS_PROJECT_ID=my-project

# Workflow (identical commands)
bd ready                                    # Shows available work
bd update bd-42 --status in_progress       # Reserves issue instantly (<100ms)
# ... work on issue ...
bd close bd-42 "Done"                       # Releases reservation automatically

Without Agent Mail (git-only mode):

# No environment variables needed
bd ready                                    # Shows available work
bd update bd-42 --status in_progress       # Updates via git sync (2-5s latency)
# ... work on issue ...
bd close bd-42 "Done"                       # Updates via git sync

Key differences:

• Latency: <100ms (Agent Mail) vs 2-5s (git-only)
• Collision prevention: Instant reservation (Agent Mail) vs eventual consistency (git)
• Setup: Requires server + env vars (Agent Mail) vs zero config (git-only)

When to use Agent Mail:

• ✅ Multiple agents working concurrently
• ✅ Frequent status updates (high collision risk)
• ✅ Real-time coordination needed

When to skip:

• ✅ Single agent workflows
• ✅ Infrequent updates (low collision risk)
• ✅ Simplicity preferred over latency

See docs/AGENT_MAIL_QUICKSTART.md for 5-minute setup, or docs/AGENT_MAIL.md for complete documentation. Example code in examples/python-agent/AGENT_MAIL_EXAMPLE.md.

Issue Types

• bug - Something broken that needs fixing
• feature - New functionality
• task - Work item (tests, docs, refactoring)
• epic - Large feature composed of multiple issues (supports hierarchical children)
• chore - Maintenance work (dependencies, tooling)

Hierarchical children: Epics can have child issues with dotted IDs (e.g., bd-a3f8e9.1, bd-a3f8e9.2). Children are auto-numbered sequentially. Up to 3 levels of nesting supported. The parent hash ensures unique namespace - no coordination needed between agents working on different epics.

Priorities

• 0 - Critical (security, data loss, broken builds)
• 1 - High (major features, important bugs)
• 2 - Medium (nice-to-have features, minor bugs)
• 3 - Low (polish, optimization)
• 4 - Backlog (future ideas)

Dependency Types

• blocks - Hard dependency (issue X blocks issue Y)
• related - Soft relationship (issues are connected)
• parent-child - Epic/subtask relationship
• discovered-from - Track issues discovered during work (automatically inherits parent's source_repo)

Only blocks dependencies affect the ready work queue.

Note: When creating an issue with a discovered-from dependency, the new issue automatically inherits the parent's source_repo field. This ensures discovered work stays in the same repository as the parent task.

Duplicate Detection & Merging

AI agents should proactively detect and merge duplicate issues to keep the database clean:

Automated duplicate detection:

# Find all content duplicates in the database
bd duplicates

# Automatically merge all duplicates
bd duplicates --auto-merge

# Preview what would be merged
bd duplicates --dry-run

# During import
bd import -i issues.jsonl --dedupe-after

Detection strategies:

1. Before creating new issues: Search for similar existing issues

   bd list --json | grep -i "authentication"
   bd show bd-41 bd-42 --json  # Compare candidates
   

2. Periodic duplicate scans: Review issues by type or priority

   bd list --status open --priority 1 --json  # High-priority issues
   bd list --issue-type bug --json             # All bugs
   

3. During work discovery: Check for duplicates when filing discovered-from issues

   # Before: bd create "Fix auth bug" --deps discovered-from:bd-100
   # First: bd list --json | grep -i "auth bug"
   # Then decide: create new or link to existing
   

Merge workflow:

# Step 1: Identify duplicates (bd-42 and bd-43 duplicate bd-41)
bd show bd-41 bd-42 bd-43 --json

# Step 2: Preview merge to verify
bd merge bd-42 bd-43 --into bd-41 --dry-run

# Step 3: Execute merge
bd merge bd-42 bd-43 --into bd-41 --json

# Step 4: Verify result
bd dep tree bd-41  # Check unified dependency tree
bd show bd-41 --json  # Verify merged content

What gets merged:

• ✅ All dependencies from source → target
• ✅ Text references updated across ALL issues (descriptions, notes, design, acceptance criteria)
• ✅ Source issues closed with "Merged into bd-X" reason
• ❌ Source issue content NOT copied (target keeps its original content)

Important notes:

• Merge preserves target issue completely; only dependencies/references migrate
• If source issues have valuable content, manually copy it to target BEFORE merging
• Cannot merge in daemon mode yet (bd-190); use --no-daemon flag
• Operation cannot be undone (but git history preserves the original)

Best practices:

• Merge early to prevent dependency fragmentation
• Choose the oldest or most complete issue as merge target
• Add labels like duplicate to source issues before merging (for tracking)
• File a discovered-from issue if you found duplicates during work:

  bd create "Found duplicates during bd-X" -p 2 --deps discovered-from:bd-X --json
  

Development Guidelines

Code Standards

• Go version: 1.21+
• Linting: golangci-lint run ./... (baseline warnings documented in docs/LINTING.md)
• Testing: All new features need tests (go test -short ./... for local, full tests run in CI)
• Documentation: Update relevant .md files

File Organization

beads/
├── cmd/bd/              # CLI commands
├── internal/
│   ├── types/           # Core data types
│   └── storage/         # Storage layer
│       └── sqlite/      # SQLite implementation
├── examples/            # Integration examples
└── *.md                 # Documentation

Testing Workflow

IMPORTANT: Never pollute the production database with test issues!

For manual testing, use the BEADS_DB environment variable to point to a temporary database:

# Create test issues in isolated database
BEADS_DB=/tmp/test.db ./bd init --quiet --prefix test
BEADS_DB=/tmp/test.db ./bd create "Test issue" -p 1

# Or for quick testing
BEADS_DB=/tmp/test.db ./bd create "Test feature" -p 1

For automated tests, use t.TempDir() in Go tests:

func TestMyFeature(t *testing.T) {
    tmpDir := t.TempDir()
    testDB := filepath.Join(tmpDir, ".beads", "beads.db")
    s := newTestStore(t, testDB)
    // ... test code
}

Warning: bd will warn you when creating issues with "Test" prefix in the production database. Always use BEADS_DB for manual testing.

Before Committing

1. Run tests: go test -short ./... (full tests run in CI)
2. Run linter: golangci-lint run ./... (ignore baseline warnings)
3. Update docs: If you changed behavior, update README.md or other docs
4. Commit: Issues auto-sync to .beads/issues.jsonl and import after pull

Git Workflow

Auto-sync provides batching! bd automatically:

• Exports to JSONL after CRUD operations (30-second debounce for batching)
• Imports from JSONL when it's newer than DB (e.g., after git pull)
• Daemon commits/pushes every 5 seconds (if --auto-commit / --auto-push enabled)

The 30-second debounce provides a transaction window for batch operations - multiple issue changes within 30 seconds get flushed together, avoiding commit spam.

Git Integration

Auto-sync: bd automatically exports to JSONL (30s debounce), imports after git pull, and optionally commits/pushes.

Protected branches: Use bd init --branch beads-metadata to commit to separate branch. See docs/PROTECTED_BRANCHES.md.

Git worktrees: Daemon mode NOT supported. Use bd --no-daemon for all commands. See docs/GIT_INTEGRATION.md.

Merge conflicts: Rare with hash IDs. If conflicts occur, use git checkout --theirs/.beads/beads.jsonl and bd import. See docs/GIT_INTEGRATION.md.

Landing the Plane

When the user says "let's land the plane", follow this clean session-ending protocol:

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. Sync and PUSH everything to remote - Work methodically to ensure both local and remote are synchronized:

   # 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
   
   # CRITICAL: Push everything to remote
   git push
   
   # Verify push succeeded
   git status  # Should show "up to date with origin/main"
   

   CRITICAL: The plane has NOT landed until git push completes successfully. If you don't push, the work is still on the runway!
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]"

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. Sync and PUSH everything
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       # CRITICAL - Must push!
git status     # 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)
• Recommended prompt for next session

Agent Session Workflow

IMPORTANT for AI agents: When you finish making issue changes, always run:

bd sync

This immediately:

1. Exports pending changes to JSONL (no 30s wait)
2. Commits to git
3. Pulls from remote
4. Imports any updates
5. Pushes to remote

Example agent session:

# Make multiple changes (batched in 30-second window)
bd create "Fix bug" -p 1
bd create "Add tests" -p 1
bd update bd-42 --status in_progress
bd close bd-40 --reason "Completed"

# Force immediate sync at end of session
bd sync

# Now safe to end session - everything is committed and pushed

Why this matters:

• Without bd sync, changes sit in 30-second debounce window
• User might think you pushed but JSONL is still dirty
• bd sync forces immediate flush/commit/push

STRONGLY RECOMMENDED: Install git hooks for automatic sync (prevents stale JSONL problems):

# One-time setup - run this in each beads workspace
bd hooks install

This installs:

• pre-commit - Flushes pending changes immediately before commit (bypasses 30s debounce)
• post-merge - Imports updated JSONL after pull/merge (guaranteed sync)
• pre-push - Exports database to JSONL before push (prevents stale JSONL from reaching remote)
• post-checkout - Imports JSONL after branch checkout (ensures consistency)

Why git hooks matter: Without the pre-push hook, you can have database changes committed locally but stale JSONL pushed to remote, causing multi-workspace divergence. The hooks guarantee DB ↔ JSONL consistency.

Note: Hooks are embedded in the bd binary and work for all bd users (not just source repo users).

Current Project Status

Run bd stats to see overall progress.

Active Areas

• Core CLI: Mature, but always room for polish
• Examples: Growing collection of agent integrations
• Documentation: Comprehensive but can always improve
• MCP Server: Implemented at integrations/beads-mcp/ with Claude Code plugin
• Migration Tools: Planned (see bd-6)

1.0 Milestone

We're working toward 1.0. Key blockers tracked in bd. Run:

bd dep tree bd-8  # Show 1.0 epic dependencies

Common Tasks

Adding a New Command

1. Create file in cmd/bd/
2. Add to root command in cmd/bd/main.go
3. Implement with Cobra framework
4. Add --json flag for agent use
5. Add tests in cmd/bd/*_test.go
6. Document in README.md

Adding Storage Features

1. Update schema in internal/storage/sqlite/schema.go
2. Add migration if needed
3. Update internal/types/types.go if new types
4. Implement in internal/storage/sqlite/sqlite.go
5. Add tests
6. Update export/import in cmd/bd/export.go and cmd/bd/import.go

Adding Examples

1. Create directory in examples/
2. Add README.md explaining the example
3. Include working code
4. Link from examples/README.md
5. Mention in main README.md

Questions?

• Check existing issues: bd list
• Look at recent commits: git log --oneline -20
• Read the docs: README.md, ADVANCED.md, EXTENDING.md
• Create an issue if unsure: bd create "Question: ..." -t task -p 2

Important Files

• README.md - Main documentation (keep this updated!)
• EXTENDING.md - Database extension guide
• ADVANCED.md - JSONL format analysis
• CONTRIBUTING.md - Contribution guidelines
• SECURITY.md - Security policy

Pro Tips for Agents

• Always use --json flags for programmatic use
• Always run bd sync at end of session to flush/commit/push immediately
• Link discoveries with discovered-from to maintain context
• Check bd ready before asking "what next?"
• Auto-sync batches changes in 30-second window - use bd sync to force immediate flush
• Use --no-auto-flush or --no-auto-import to disable automatic sync if needed
• Use bd dep tree to understand complex dependencies
• Priority 0-1 issues are usually more important than 2-4
• Use --dry-run to preview import changes before applying
• Hash IDs eliminate collisions - same ID with different content is a normal update
• Use --id flag with bd create to partition ID space for parallel workers (e.g., worker1-100, worker2-500)

Checking GitHub Issues and PRs

IMPORTANT: When asked to check GitHub issues or PRs, use command-line tools like gh instead of browser/playwright tools.

Preferred approach:

# List open issues with details
gh issue list --limit 30

# List open PRs
gh pr list --limit 30

# View specific issue
gh issue view 201

Then provide an in-conversation summary highlighting:

• Urgent/critical issues (regressions, bugs, broken builds)
• Common themes or patterns
• Feature requests with high engagement
• Items that need immediate attention

Why this matters:

• Browser tools consume more tokens and are slower
• CLI summaries are easier to scan and discuss
• Keeps the conversation focused and efficient
• Better for quick triage and prioritization

Do NOT use: browser_navigate, browser_snapshot, or other playwright tools for GitHub PR/issue reviews unless specifically requested by the user.

Building and Testing

# Build
go build -o bd ./cmd/bd

# Test (short - for local development)
go test -short ./...

# Test with coverage (full tests - for CI)
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run locally
./bd init --prefix test
./bd create "Test issue" -p 1
./bd ready

Version Management

IMPORTANT: When the user asks to "bump the version" or mentions a new version number (e.g., "bump to 0.9.3"), use the version bump script:

# Preview changes (shows diff, doesn't commit)
./scripts/bump-version.sh 0.9.3

# Auto-commit the version bump
./scripts/bump-version.sh 0.9.3 --commit
git push origin main

What it does:

• Updates ALL version files (CLI, plugin, MCP server, docs) in one command
• Validates semantic versioning format
• Shows diff preview
• Verifies all versions match after update
• Creates standardized commit message

User will typically say:

• "Bump to 0.9.3"
• "Update version to 1.0.0"
• "Rev the project to 0.9.4"
• "Increment the version"

You should:

1. Run ./scripts/bump-version.sh <version> --commit
2. Push to GitHub
3. Confirm all versions updated correctly

Files updated automatically:

• cmd/bd/version.go - CLI version
• .claude-plugin/plugin.json - Plugin version
• .claude-plugin/marketplace.json - Marketplace version
• integrations/beads-mcp/pyproject.toml - MCP server version
• README.md - Documentation version
• PLUGIN.md - Version requirements

Why this matters: We had version mismatches (bd-66) when only version.go was updated. This script prevents that by updating all components atomically.

See scripts/README.md for more details.

Release Process (Maintainers)

Automated (Recommended):

# One command to do everything (version bump, tests, tag, Homebrew update, local install)
./scripts/release.sh 0.9.3

This handles the entire release workflow automatically, including waiting ~5 minutes for GitHub Actions to build release artifacts. See scripts/README.md for details.

Manual (Step-by-Step):

1. Bump version: ./scripts/bump-version.sh <version> --commit
2. Update CHANGELOG.md with release notes
3. Run tests: go test -short ./... (CI runs full suite)
4. Push version bump: git push origin main
5. Tag release: git tag v<version> && git push origin v<version>
6. Update Homebrew: ./scripts/update-homebrew.sh <version> (waits for GitHub Actions)
7. Verify: brew update && brew upgrade bd && bd version

See docs/RELEASING.md for complete manual instructions.

---

Remember: We're building this tool to help AI agents like you! If you find the workflow confusing or have ideas for improvement, create an issue with your feedback.

Happy coding! 🔗

Issue Tracking with bd (beads)

IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

Why bd?

• Dependency-aware: Track blockers and relationships between issues
• Git-friendly: Auto-syncs to JSONL for version control
• Agent-optimized: JSON output, ready work detection, discovered-from links
• Prevents duplicate tracking systems and confusion

Quick Start

FIRST TIME? Just run bd init - it auto-imports issues from git:

bd init --prefix bd

OSS Contributor? Use the contributor wizard for fork workflows:

bd init --contributor  # Interactive setup for separate planning repo

Team Member? Use the team wizard for branch workflows:

bd init --team  # Interactive setup for team collaboration

Check for ready work:

bd ready --json

Create new issues:

bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json

Claim and update:

bd update bd-42 --status in_progress --json
bd update bd-42 --priority 1 --json

Complete work:

bd close bd-42 --reason "Completed" --json

Issue Types

• bug - Something broken
• feature - New functionality
• task - Work item (tests, docs, refactoring)
• epic - Large feature with subtasks
• chore - Maintenance (dependencies, tooling)

Priorities

• 0 - Critical (security, data loss, broken builds)
• 1 - High (major features, important bugs)
• 2 - Medium (default, nice-to-have)
• 3 - Low (polish, optimization)
• 4 - Backlog (future ideas)

Workflow for AI Agents

1. Check ready work: bd ready shows unblocked issues
2. Claim your task: bd update <id> --status in_progress
3. Work on it: Implement, test, document
4. Discover new work? Create linked issue:
   • bd create "Found bug" -p 1 --deps discovered-from:<parent-id>
5. Complete: bd close <id> --reason "Done"

Auto-Sync

bd automatically syncs with git:

• Exports to .beads/issues.jsonl after changes (5s debounce)
• Imports from JSONL when newer (e.g., after git pull)
• No manual export/import needed!

MCP Server (Recommended)

If using Claude or MCP-compatible clients, install the beads MCP server:

pip install beads-mcp

Add to MCP config (e.g., ~/.config/claude/config.json):

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

Then use mcp__beads__* functions instead of CLI commands.

Managing AI-Generated Planning Documents

AI assistants often create planning and design documents during development:

• PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
• DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
• TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files

Best Practice: Use a dedicated directory for these ephemeral files

Recommended approach:

• Create a history/ directory in the project root
• Store ALL AI-generated planning/design docs in history/
• Keep the repository root clean and focused on permanent project files
• Only access history/ when explicitly asked to review past planning

Example .gitignore entry (optional):

# AI planning documents (ephemeral)
history/

Benefits:

• ✅ Clean repository root
• ✅ Clear separation between ephemeral and permanent documentation
• ✅ Easy to exclude from version control if desired
• ✅ Preserves planning history for archaeological research
• ✅ Reduces noise when browsing the project

Important Rules

• ✅ Use bd for ALL task tracking
• ✅ Always use --json flag for programmatic use
• ✅ Link discovered work with discovered-from dependencies
• ✅ Check bd ready before asking "what should I work on?"
• ✅ Store AI planning docs in history/ directory
• ❌ Do NOT create markdown TODO lists
• ❌ Do NOT use external issue trackers
• ❌ Do NOT duplicate tracking systems
• ❌ Do NOT clutter repo root with planning documents

For more details, see README.md and QUICKSTART.md.