aiskillstore/using-beads-bv

Using Beads and bv

Overview

Beads provides a lightweight, dependency-aware issue database. The bd CLI manages tasks, while bv provides graph metrics and execution planning.

Project: steveyegge/beads

When to Use

• Coordinating multi-agent work with dependencies
• Finding ready work (no blockers)
• Priority management and task sequencing
• Understanding project graph metrics

Don't use: Simple single-session tasks (use TodoWrite instead).

Quick Reference

| Command | Description | |---------|-------------| | bd ready | Show issues ready to work (no blockers) | | bd list --status=open | All open issues | | bd list --status=in_progress | Active work | | bd show <id> | Issue details with dependencies | | bd create --title="..." --type=task | Create new issue | | bd update <id> --status=in_progress | Claim work | | bd close <id> | Mark complete |

bv Robot Flags (AI Sidecar)

CRITICAL: Always use --robot-* flags. The interactive TUI will block your session!

bv --robot-help          # All AI-facing commands
bv --robot-insights      # JSON graph metrics (PageRank, critical path, cycles)
bv --robot-plan          # JSON execution plan with parallel tracks
bv --robot-priority      # Priority recommendations with reasoning
bv --robot-recipes       # List available recipes
bv --robot-diff --diff-since <commit>  # Changes since commit/date

Example: Get Execution Plan

bv --robot-plan

Returns JSON with:

• Parallel tracks (what can run concurrently)
• Items per track
• Unblocks lists (what each completion frees up)

Common Workflows

Starting Work

bd ready                                  # Find available work
bd show <id>                              # Review issue details
bd update <id> --status=in_progress       # Claim it

Completing Work

bd close <id1> <id2> ...                  # Close completed issues
bd sync                                   # Push to remote

Creating Dependent Work

bd create --title="Implement feature X" --type=feature --priority=P2
bd create --title="Write tests for X" --type=task --priority=P2
bd dep add <tests-id> <feature-id>        # Tests depend on feature

Priority Levels

Use numeric priorities (NOT "high"/"medium"/"low"):

| Priority | Use Case | |----------|----------| | P0 | Critical - blocking everything | | P1 | High - needs immediate attention | | P2 | Medium - standard work | | P3 | Low - nice to have | | P4 | Backlog - future consideration |

Conventions

• Single source of truth: Use Beads for task status/priority/dependencies
• Shared identifiers: Use beads issue ID (e.g., agent-relay-123) in commit messages
• Message subjects: Prefix with [agent-relay-123] for traceability

Session Close Protocol

Before ending any session:

bd sync                 # Commit beads changes
git add <files>         # Stage code changes
git commit -m "..."     # Include bd-### in message
bd sync                 # Commit any new beads changes
git push                # Push to remote

Anti-Patterns

| Mistake | Fix | |---------|-----| | Using bv without robot flags | Always use --robot-* flags | | Managing tasks in markdown | Use bd as single task queue | | Missing issue IDs in commits | Always include bd-### | | Using high/medium/low priority | Use P0-P4 numeric format |