Help us improve
Share bugs, ideas, or general feedback.
From agentops
Converts markdown plans into structured beads with tasks, subtasks, and dependency links for implementation or swarm execution. Includes polishing protocol and lifecycle disciplines.
npx claudepluginhub boshu2/agentops --plugin agentopsHow this skill is triggered — by the user, by Claude, or both
Slash command
/agentops:beads-workflowThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- TOC: Quick Start | Conversion Prompt | Polishing | bd → br Migration | Quality Checklist | Lifecycle Disciplines | When Beads Are Ready | Validation | References -->
Persistent graph-based issue tracker that survives conversation compaction. Track issues with bd/br CLI, triage with bv, and export to git-friendly JSONL.
Guides using Beads (bd) distributed git-backed issue tracker for task management, dependency tracking, AI agent workflows, and multi-branch parallel development.
Guides using Beads (bd), a distributed git-backed graph issue tracker for managing tasks, tracking dependencies, AI agent workflows, and multi-branch git development.
Share bugs, ideas, or general feedback.
Core Principle: "Check your beads N times, implement once" — where N is as many as you can stomach.
Beads are so detailed and polished that you can mechanically unleash a big swarm of agents to implement them, and it will come out just about perfectly.
This skill is the conversion and shaping doctrine — plan → beads, dependency/wave shaping, polish, lifecycle. It does NOT re-document the br/bv command surface: both binaries self-describe (br --help, bv --help, plus the beads_rust README and the beads-br / beads-bv skills). One hard rule worth front-loading: never run bare bv — it launches an interactive TUI; agents use bv --robot-* surfaces only.
br init # 1. Initialize beads in project
# 2. Convert plan to beads (THE EXACT PROMPT below)
# 3. Polish iteratively, 6-9 rounds, until steady-state
br dep cycles # 4. Validate: must be empty
bv --robot-insights # ...and check graph health
bv --robot-next # 5. Begin implementation: get first bead
OK so now read ALL of [YOUR_PLAN_FILE].md; please take ALL of that and elaborate on it and use it to create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid, with detailed comments so that the whole thing is totally self-contained and self-documenting (including relevant background, reasoning/justification, considerations, etc.-- anything we'd want our "future self" to know about the goals and intentions and thought process and how it serves the over-arching goals of the project.). The beads should be so detailed that we never need to consult back to the original markdown plan document. Remember to ONLY use the `br` tool to create and modify the beads and add the dependencies. Use ultrathink.
What this creates: tasks and subtasks with clear scope, dependency links (what blocks what), detailed descriptions with background/reasoning/considerations — self-contained, so the original plan is never needed again.
All other exact prompts — the short conversion variant, the polish prompts, and the fresh-session re-establish-context sequence — live in PROMPTS.md. What a well-formed bead looks like (required elements, description guidelines, anti-patterns) is BEAD-ANATOMY.md.
Operating in "plan space" is far cheaper than correcting in implementation space — that is the rationale for the whole loop:
br/bv, then resume polishing. Exact prompts in PROMPTS.md.Use this when you see legacy bd references in AGENTS.md or docs.
Behavioral difference (only one): br sync never runs git commands. After br sync --flush-only, you must git add .beads/, git commit (and git push) yourself.
Transform checklist (order matters):
bd commands → br commandsbd sync → br sync --flush-only + git add .beads/ + git commitbd-* → br-* — the prefix is configurable (often remains bd-*).Verify:
grep -c '`bd ' file.md # must be 0
grep -c 'bd sync' file.md # must be 0
grep -c 'br sync --flush-only' file.md # must be > 0
Before implementation, verify each bead:
br dep cycles returns emptyBefore claiming a bead for dispatch, confirm no other actor already holds it (br show <id> — check assignee/status). A race-claim on an already-claimed bead creates two workers on the same task — one of them will silently lose work. The ledger is the lock: if the bead is claimed, coordinate via Agent Mail (use the bead ID as the thread ID and reservation reason), do not dispatch a second worker.
A bead is durable only when its branch is merged to trunk and the commit visible on the canonical store. br close without a merge is a protection-off state — the work will recur as an incident (it did, 2026-06-09). For assurance-close contexts the gate cp-hxp6 enforces this; for other contexts, apply it as a practice: confirm git log --oneline origin/main includes the commit SHA before closing.
When a close leaves a residual (un-merged work, deferred scope, a known gap), route the residual to a successor bead in the same turn — never accept-silently, never hold the parent open as a zombie. The pressure lives in the successor's priority, not in the open parent. Use br close <id> --reason "Residual → <new-id>". Close-with-residual is honest; a zombie parent that never closes is the failure mode.
br update <id> --notes is an append operation — it adds to the notes, it does NOT replace existing notes. When adding a progress note, pass only the new content; the flag accumulates. A --notes call that silently replaces prior notes erases audit history — the same silent-destruction class as the close-eater (cp-8720) and the split-brain (cp-4gkz).
When a correction, idea, or complaint arrives mid-session, file the bead in the same turn with the verbatim words. Corrections that live only in chat evaporate. The feed IS the product.
Your beads are ready for implementation when:
br dep cycles returns emptybr dep cycles # must be empty
bv --robot-insights | jq '.Cycles' # graph health
bv --robot-insights | jq '.bottlenecks' # wave shaping: what gates the most work
br list --json | jq '.issues[]? | select(.description == "")' # no empty descriptions
After any bead mutation session, flush and commit: br sync --flush-only && git add .beads/ && git commit.
For worktree/sync-branch errors, health checks, and full diagnostics, see TROUBLESHOOTING.md. Quick health check: br config list, br dep cycles, which br.
| Topic | Reference |
|---|---|
| All prompts (conversion, polish, fresh-session) | PROMPTS.md |
| Bead structure | BEAD-ANATOMY.md |
| Troubleshooting | TROUBLESHOOTING.md |
| br command reference | br --help or beads_rust README |
| BV triage / robot surfaces | bv --help; beads-bv skill |
| Coordination (reservations, threads) | agent-mail skill |