Beads Prime

Beads quick reference

Minimal quick reference when context is constrained. For session lifecycle, prefer action commands: beads-orient (start), beads-checkpoint (wind-down). For comprehensive reference: beads (complete workflows, concepts, and operations).

Command index

• beads-init - Initial setup for beads issue tracking
• beads-seed - Generate issues from architecture documentation
• beads-orient - Session start diagnostics and work selection
• beads-evolve - Issue graph refactoring patterns
• beads-checkpoint - Session wind-down and handoff prep
• beads-audit - Database health check and validation

Manual sync workflow

After git operations that modify beads state (pull, checkout, merge, rebase):

# Import changes from git into beads database
bd sync --import-only

Before committing beads changes:

# Run pre-commit validation
bd hooks run pre-commit

# Commit beads changes
git add .beads/issues.jsonl
git commit -m "chore(issues): ..."

Additional sync flags:

bd sync --flush-only    # Only export to JSONL (useful for pre-commit)
bd sync --check         # Pre-sync integrity check
bd sync --dry-run       # Preview sync without changes

Orient

bd status                   # quick human-readable summary (~20 lines)
bd epic status              # epic progress
bv --robot-next             # minimal JSON: just the single top pick

Select work

# Top pick (small JSON, safe for direct consumption)
bv --robot-next

# Show ready-to-work issues (no blockers, open or in_progress)
bd ready

# Show blocked issues
bd blocked

# Full dependency context (upstream + downstream)
bd dep tree <id> --direction both

# Issue details
bd show <id>

For deeper analysis (redirect to file to avoid context pollution):

REPO=$(basename "$(git rev-parse --show-toplevel)")
TRIAGE=$(mktemp "/tmp/bv-${REPO}-triage.XXXXXX.json")
bv --robot-triage > "$TRIAGE"
jq '.recommendations[:3]' "$TRIAGE"
rm "$TRIAGE"

During work

# Create discovered issue (priority: 0=highest, 4=lowest, default=2)
bd create "Found: ..." -t bug -p 2
bd dep add <new-id> <current-id> --type discovered-from

# Add blocker
bd create "Need X first" -t task -p 1
bd dep add <blocker-id> <current-id>

Complete work

bd close <id> --reason "Implemented in commit $(git rev-parse --short HEAD)"
bd epic close-eligible --dry-run

Health

bd dep cycles               # must be zero
bd doctor                   # check and fix installation health
bd lint                     # check issues for missing template sections

Key patterns

• bv --robot-triage is the single entry point — unified counts, recommendations, health
• bv --robot-next for minimal context — just top pick with claim command
• bd ready / bd blocked for quick work selection without JSON parsing
• bd dep tree <id> --direction both shows full context (blockers + what completing it unblocks)
• Always close with --reason referencing the implementation
• Use --type discovered-from when creating issues found during other work
• After bd modifications: git add .beads/issues.jsonl && git commit -m "chore(beads): sync issues"

Other useful robot flags:

• bv --robot-plan - Dependency-respecting execution plan
• bv --robot-insights - Graph analysis