beads

---
name: beads
description: Track issues with bd/br, triage with bv, and convert plans to beads.
license: Apache-2.0
---

# 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](references/composition-over-invention.md)). Full catalogs ship in [CLI_REFERENCE.md](references/CLI_REFERENCE.md) (bd), [BR_REFERENCE.md](references/BR_REFERENCE.md) (br), and [BV_TRIAGE.md](references/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:

```bash
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):**

```bash
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](references/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.
4. 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.
5. Wire dependencies with `br dep add` / `bd dep add`. Do not hand-edit JSONL or
   database files.
6. Polish iteratively (usually 6-9 passes) until steady-state. Check for lost
   features, oversimplification, missing tests, unclear boundaries, missing e2e
   coverage, and weak logging.
7. 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`.
8. 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](references/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](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/ANTI_PATTERNS.md)
- [references/BOUNDARIES.md](references/BOUNDARIES.md)
- [references/composition-over-invention.md](references/composition-over-invention.md) — Run `bd <subcmd> --help` before specifying enforcement commands; compose primitives, don't invent
- [references/BR_REFERENCE.md](references/BR_REFERENCE.md)
- [references/BV_TRIAGE.md](references/BV_TRIAGE.md)
- [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md)
- [references/DEPENDENCIES.md](references/DEPENDENCIES.md)
- [references/INTEGRATION_PATTERNS.md](references/INTEGRATION_PATTERNS.md)
- [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md)
- [references/MIGRATION.md](references/MIGRATION.md)
- [references/MOLECULES.md](references/MOLECULES.md)
- [references/PATTERNS.md](references/PATTERNS.md)
- [references/PLAN_TO_BEADS.md](references/PLAN_TO_BEADS.md)
- [references/RESUMABILITY.md](references/RESUMABILITY.md)
- [references/ROUTING.md](references/ROUTING.md)
- [references/STATIC_DATA.md](references/STATIC_DATA.md)
- [references/tracker-migration-and-triage.md](references/tracker-migration-and-triage.md)
- [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md)
- [references/WORKFLOWS.md](references/WORKFLOWS.md)