beads

Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction.

Overview

bd and br (beads_rust) replace markdown task lists with a dependency-aware graph stored in git. bv adds graph-aware triage using PageRank and betweenness centrality.

Key Distinction:

• bd/br: Multi-session work, dependencies, survives compaction, git-backed
• bv: Graph analysis, priority triage, bottleneck detection, parallel execution planning
• Task tools (TaskCreate/TaskUpdate/TaskList): Single-session tasks, status tracking, conversation-scoped

Decision Rule: If resuming in 2 weeks would be hard without bd, use bd.

br vs bd: br is the Rust rewrite. Commands are the same except: br never auto-commits (git is your job), and bd sync becomes br sync --flush-only. Use whichever is installed.

bv safety: NEVER run bare bv — it launches interactive TUI and blocks the terminal. Always use --robot-* flags.

Don't re-learn the command surface here. bd --help / br --help (and per-subcommand --help) self-describe every command and flag — run them before specifying enforcement commands; compose primitives, don't invent (composition-over-invention.md). Full catalogs ship in CLI_REFERENCE.md (bd), BR_REFERENCE.md (br), and BV_TRIAGE.md (bv robot flags). This skill carries the operating doctrine.

Operating Rules

• 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.
• Before selecting new ready work after CI, release, or rollout activity, prefer ao reconcile --json when available. Treat bd ready as planning input only after high-severity main/release/bead evidence findings are resolved or explicitly superseded.
• 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

Session ending pattern (br — sync is EXPLICIT, never automatic):

git pull --rebase
br sync --flush-only                # DB → JSONL (reverse: --import-only after pull)
git add .beads/ && git commit -m "Update issues"
git push

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

User says: /validate

This skill loads via dependency: the agent reads issue metadata with bd show <id>, links validation findings to the issue under check, and cites the issue ID in the validation report — no manual bd lookups.

User says: /implement ag-xyz-123

This skill loads to manage the issue lifecycle: bd show ag-xyz-123 for the body, check dependencies, and bd close ag-xyz-123 (with scoped closure proof) after completion.

bv Graph Triage

NEVER run bare bv. Always use --robot-* flags (--robot-triage, --robot-next, --robot-plan, --robot-insights, --robot-priority, --robot-alerts — selection guide in BV_TRIAGE.md).

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

Plan-to-Beads Workflow

Convert a markdown plan into fully dependency-wired beads:

1. Read the full plan, AGENTS.md, README, linked intent issue, and acceptance criteria.
2. Create beads with br create for each issue, including full context in the description.
3. For every feature, bug, or product-facing behavior, include a fenced gherkin

block or link to a filled intent issue. Mechanical chores may omit Gherkin only when their acceptance criteria are fully command/file based.

1. Include the hexagon: boundary block from

docs/architecture/intent-to-loop-hexagon.md for substantial beads: inbound port, bounded context, adapters, context packet, and done state.

1. Wire dependencies with br dep add / bd dep add. Do not hand-edit JSONL or

database files.

1. Polish iteratively (usually 6-9 passes) until steady-state. Check for lost

features, oversimplification, missing tests, unclear boundaries, missing e2e coverage, and weak logging.

1. Validate: br dep cycles must be empty; run bv --robot-insights for graph

health; use bv --robot-next for the first bead. Never run bare bv.

1. Sync explicitly before commit: br sync --flush-only, then git add .beads/

and commit tracker changes when appropriate.

Beads should be so detailed that a fresh agent can implement without consulting the original plan. Ready-to-implement beads have clear scope, explicit dependencies, BDD or mechanical acceptance, unit/e2e test expectations, detailed logging expectations, a named done state, and no dependency cycles.

Troubleshooting

Symptom → fix table (command not found, not-a-git-repo, init missing, ID prefix errors, bv hangs, dependency cycles, sync direction confusion): TROUBLESHOOTING.md. The two most common: a hung bv means a robot flag was omitted; br sync confusion means the direction (--flush-only vs --import-only) wasn't specified.

Reference Documents

• references/beads.feature — Executable spec: bd-mandatory tracker, create-before-code, ready-detection, discovered-from links, live-reads-authoritative (soc-qk4b)

• references/ANTI_PATTERNS.md
• references/BOUNDARIES.md
• references/composition-over-invention.md — Run bd <subcmd> --help before specifying enforcement commands; compose primitives, don't invent
• references/BR_REFERENCE.md
• references/BV_TRIAGE.md
• references/CLI_REFERENCE.md
• references/DEPENDENCIES.md
• references/INTEGRATION_PATTERNS.md
• references/ISSUE_CREATION.md
• references/MIGRATION.md
• references/MOLECULES.md
• references/PATTERNS.md
• references/PLAN_TO_BEADS.md
• references/RESUMABILITY.md
• references/ROUTING.md
• references/STATIC_DATA.md
• references/tracker-migration-and-triage.md
• references/TROUBLESHOOTING.md
• references/WORKFLOWS.md