Agent Instructions

Beads Version Compatibility

Check compatibility:

• Changelog: https://github.com/steveyegge/beads/blob/main/CHANGELOG.md
• Run bd --version to check installed version

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
• Database-backed: Dolt (MySQL protocol) with version history
• Agent-optimized: JSON output, ready work detection, discovered-from links
• Prevents duplicate tracking systems and confusion

Quick Start

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
# Create and link in one command (new way - preferred)
bd create "Issue title" -t bug -p 1 --deps discovered-from:<parent-id> --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 --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. Finish work: Close completed issues with bd close <id>

Storage

bd uses Dolt (MySQL protocol) as its database backend:

• Data stored in .beads/*.db with full version history
• Use bd dolt push / bd dolt pull to sync with remote
• No manual JSONL export needed — Dolt handles versioning

GitHub Copilot Integration

If using GitHub Copilot, also create .github/copilot-instructions.md for automatic instruction loading. Run bd prime to get the content, or see step 2 of the onboard instructions.

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, PRODUCT-REQUIREMENTS-SPECIFICATION.md, SPEC.md and similar files

Best Practice: Use a dedicated directory for these ephemeral files

Recommended approach:

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

Example .gitignore entry (optional):

# AI planning documents (ephemeral)
docs/

Benefits:

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

CLI Help

Run bd <command> --help to see all available flags for any command. For example: bd create --help shows --parent, --deps, --assignee, etc.

Get more info from reference: https://github.com/steveyegge/beads/raw/refs/heads/main/docs/CLI_REFERENCE.md

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 docs/ directory
• ✅ Run bd <cmd> --help to discover available flags
• ❌ Do NOT create markdown files as 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.

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

Branch Strategy: Feature branches merge into main unless the project uses a different strategy (check CLAUDE.md for project-specific branching).

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   # Only sync dolt if remote is NOT localhost:
   bd dolt remote list --json  # check remote URL
   # If remote URL contains "localhost" or "127.0.0.1" → skip dolt push (local DB, no sync needed)
   # If remote URL is external (e.g., hosted dolt) → run: bd dolt push
   git push
   git status  # MUST show "up to date with origin"

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally
• NEVER say "ready to push when you are" - YOU must push
• If push fails, resolve and retry until it succeeds