SKILL.md

$27

Treat live bd reads as authoritative. Use bd show, bd ready, bd list, and bd export to inspect current tracker state. Do not treat .beads/issues.jsonl as the primary decision source when live bd data is available.

Treat .beads/issues.jsonl as a git-friendly export artifact. If the repo tracks .beads/issues.jsonl and you mutate tracker state, refresh it explicitly with bd export -o .beads/issues.jsonl.

After closing or materially updating a child issue, reconcile the open parent in the same session. Update stale "remaining gap" notes immediately, and close the parent when the child resolved the parent's last real gap.

Before closing a child issue, include scoped closure proof in the bd close --reason text.

Name the touched files or explicit no-file evidence artifact, validation command(s), and parent

reconciliation outcome. Do not use generic closure reasons such as "done" or "implemented" for child beads.

If bd ready returns a broad umbrella issue, do not implement directly against vague parent wording. First narrow the remaining gap into an execution-ready child issue, then land the child and reconcile the parent.

Normalize stale queue items instead of silently skipping them. Rewrite broad or partially absorbed beads to the actual remaining gap.

Use this post-mutation sequence when tracker state changed:

bd ...                              # mutate tracker state

bd export -o .beads/issues.jsonl    # if tracked in git

bd vc status

bd dolt commit -m "..."             # if tracker changes are pending

bd dolt push                        # only if a Dolt remote is configured

Prerequisites

bd CLI: Version 0.34.0+ installed and in PATH

Git Repository: Current directory must be a git repo

Initialization: bd init run once (humans do this, not agents)

Examples

Skill Loading from /vibe

User says: /vibe

What happens:

Agent loads beads skill automatically via dependency

Agent calls bd show <id> to read issue metadata

Agent links validation findings to the issue being checked

Output references issue ID in validation report

Result: Validation report includes issue context, no manual bd lookups needed.

Skill Loading from /implement

User says: /implement ag-xyz-123

What happens:

Agent loads beads skill to understand issue structure

Agent calls bd show ag-xyz-123 to read issue body

Agent checks dependencies with bd output

Agent closes issue with bd close ag-xyz-123 after completion

Result: Issue lifecycle managed automatically during implementation.

br (beads_rust) Quick Reference

br is the Rust rewrite of bd. Commands match bd except git handling is explicit.

# Lifecycle

br create "Title" -p 1 -t task       # Create (priority 0-4)

br update <id> --status in_progress  # Claim work

br close <id> --reason "Done"        # Complete

br ready --json                      # Actionable work (not blocked)

br list --json                       # All issues

br show <id> --json                  # Issue details

# Dependencies

br dep add <child> <parent>          # child depends on parent

br dep cycles                        # MUST be empty

br dep tree <id>                     # Visualize dependencies

# Sync (EXPLICIT — never automatic)

br sync --flush-only                 # DB → JSONL (before git commit)

br sync --import-only                # JSONL → DB (after git pull)

Session ending pattern (br):

git pull --rebase

br sync --flush-only

git add .beads/ &#x26;&#x26; git commit -m "Update issues"

git push

bv Graph Triage

NEVER run bare bv. Always use --robot-* flags.

Command

Use When

bv --robot-triage

What should I work on? Full recommendations + blockers + health

bv --robot-next

Just the single top pick

bv --robot-plan

What can run concurrently? Parallel execution tracks

bv --robot-insights

Deep analysis: metrics, cycles, density, k-core

bv --robot-priority

Am I prioritizing wrong? Misalignment detection

bv --robot-alerts

Stale issues, blocking cascades, priority mismatches

Key metrics: PageRank = everything depends on this (fix first). Betweenness = bottleneck (blocks multiple paths). High both = critical bottleneck, drop everything.