--- name: beads-workflow description: AI-native issue tracking with Beads. Use when managing work items, tracking issues, or coordinating tasks in multi-agent workflows. Covers bd commands, dependencies, and sync patterns. allowed-tools: Read, Bash, Glob, Grep, mcp__github__* --- # Beads Workflow ## Overview Beads is an AI-native issue tracker designed for agent workflows. Issues live in your repo, sync via git, and require no web UI. ## MCP Tools **GitHub** (remote collaboration): - Link Beads issues to GitHub PRs - Create GitHub issues for team visibility - Track PR status for blocked work - Auto-close Beads issues when PRs merge ## Core Commands ### Issue Management ```bash # Create a new issue bd create "Title" -t feature -p 2 # List open issues bd list --status open # View issue details bd show # Update issue bd update --status in_progress bd update --assignee claude # Close issue bd close --reason "Completed: description" ``` ### Finding Work ```bash # Get unblocked issues (no dependencies blocking) bd ready --sort hybrid # Filter by priority bd list --priority 1 --status open # Filter by labels bd list --label backend ``` ### Dependencies ```bash # Add dependency (X blocks Y) bd dep add

--type blocks # View dependency tree bd dep tree # Remove dependency bd dep rm

``` ### Syncing ```bash # Sync with git remote bd sync # Force flush to JSONL bd flush ``` ## GitHub Integration Patterns ### Linking Issues to PRs 1. Create Beads issue: `bd create "Feature X"` 2. Implement and create PR via GitHub MCP 3. Reference Beads ID in PR description 4. When PR merges, close Beads issue: `bd close ` ### Syncing Status ```bash # Check if related PR is merged (use GitHub MCP) # Then update Beads status accordingly bd update --status done ``` ### Team Visibility For issues that need team visibility: 1. Create in Beads for local tracking 2. Use GitHub MCP to create corresponding GitHub issue 3. Link both in descriptions 4. Keep Beads as source of truth for agents ## Workflow Patterns ### Starting a Session 1. **Check ready work**: `bd ready --sort hybrid` 2. **Check GitHub**: Use GitHub MCP to verify no blocking PRs 3. **Claim an issue**: `bd update --status in_progress` 4. **Review dependencies**: `bd dep tree ` 5. **Begin implementation** ### During Implementation 1. **Track sub-tasks**: `bd create "Sub-task" --parent ` 2. **Add blockers**: `bd dep add --type blocks` 3. **Update progress**: `bd comment "Progress update"` 4. **Create PR**: Use GitHub MCP when ready ### Completing Work 1. **Verify completion**: All acceptance criteria met 2. **PR status**: Use GitHub MCP to check CI\/review status 3. **Close issue**: `bd close --reason "Implemented X, PR #123"` 4. **Sync**: `bd sync` 5. **Check next**: `bd ready` ### Multi-Agent Coordination ```bash # See who's working on what bd list --status in_progress --json | jq '.[] | {id, title, assignee}' # Avoid conflicts - check before claiming bd show # Check assignee field # Hand off work bd update --assignee other-agent bd comment "Handoff: context and next steps" ``` ## Issue Types | Type | When to Use | |------|-------------| | `feature` | New functionality | | `bug` | Defect fixes | | `task` | General work items | | `spike` | Research\/investigation | | `chore` | Maintenance, cleanup | ## Priority Levels | Priority | Meaning | |----------|---------| | 0 | Critical - Drop everything | | 1 | High - Next up | | 2 | Medium - Normal flow | | 3 | Low - When time permits | | 4 | Backlog - Future consideration | ## Status Flow ``` open -> in_progress -> done |-> blocked -> in_progress ``` ## Best Practices 1. **One issue per logical unit**: Don't combine unrelated work 2. **Clear titles**: Should explain what, not how 3. **Use dependencies**: Makes ready work visible 4. **Sync frequently**: Keep other agents informed 5. **Close promptly**: Don't leave stale in_progress issues 6. **Link to GitHub**: Create GitHub issues for team-visible work ## Integration with Swarm When working in a swarm: 1. **Check active work**: `bd list --status in_progress` 2. **Claim before editing**: Update status before touching code 3. **Document blockers**: Create issues for discovered blockers 4. **Handoff cleanly**: Update assignee and add context 5. **Sync before ending**: `bd sync` to share state 6. **Create PRs**: Use GitHub MCP for review visibility ## Troubleshooting ```bash # Check daemon health bd daemons health # View daemon logs bd daemons logs # Force reimport from JSONL bd import --force # Check for conflicts bd sync --dry-run ```