Agent Instructions

Issue Tracking

This project uses bd (beads) for issue tracking. Run bd prime for workflow context, or install hooks (bd hooks install) for auto-injection.

Quick reference:

• bd ready - Find unblocked work
• bd create "Title" --type task --priority 2 - Create issue
• bd close <id> - Complete work
• bd sync - Sync with git (run at session end)

For full workflow details: bd prime

Beads Workflow Integration

This project uses beads_viewer for issue tracking. Issues are stored in .beads/ and tracked in git.

Essential Commands

# View issues (launches TUI - avoid in automated sessions)
bv

# CLI commands for agents (use these instead)
bd ready              # Show issues ready to work (no blockers)
bd list --status=open # All open issues
bd show <id>          # Full issue details with dependencies
bd create --title="..." --type=task --priority=2
bd update <id> --status=in_progress
bd close <id> --reason="Completed"
bd close <id1> <id2>  # Close multiple issues at once
bd sync               # Commit and push changes

Workflow Pattern

1. Start: Run bd ready to find actionable work
2. Claim: Use bd update <id> --status=in_progress
3. Work: Implement the task
4. Complete: Use bd close <id>
5. Sync: Always run bd sync at session end

Key Concepts

• Dependencies: Issues can block other issues. bd ready shows only unblocked work.
• Priority: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
• Types: task, bug, feature, epic, question, docs
• Blocking: bd dep add <issue> <depends-on> to add dependencies

Session Protocol

Before ending any session, run this checklist:

git status              # Check what changed
git add <files>         # Stage code changes
bd sync                 # Commit beads changes
git commit -m "..."     # Commit code
bd sync                 # Commit any new beads changes
git push                # Push to remote

Best Practices

• Check bd ready at session start to find available work
• Update status as you work (in_progress → closed)
• Create new issues with bd create when you discover tasks
• Use descriptive titles and set appropriate priority/type
• Always bd sync before ending session