Beads Workflow
Beads are epics, tasks, and subtasks with dependency structure, optimized for AI coding agents. They function like Jira or Linear but designed for machines. This skill covers the full lifecycle: converting markdown plans into beads, iteratively polishing them across multiple rounds and models, and coordinating parallel execution via Claude Code agent teams. Use this when you have a markdown plan and need to produce self-contained, implementation-ready tasks. Do not use this for the planning phase itself; use a planning skill for that.
Core Principle: "Check your beads N times, implement once" -- where N is as many as you can stomach.
Quick Reference
| Workflow |
What It Does |
Key Detail |
| Plan to beads |
Converts a markdown plan into granular beads with dependencies |
Use the full or short conversion prompt with bd tool |
| Polish beads |
Iteratively reviews and improves bead quality |
Run 6-9 rounds until steady-state; use full or standard prompt |
| Fresh session |
Breaks out of polishing plateaus |
Start new session, re-establish context, then resume polishing |
| Cross-model review |
Gets alternative perspectives on bead quality |
Run final pass with a different model (Codex, Gemini CLI) |
| Add test coverage |
Creates unit test and e2e test beads |
Use the test coverage prompt to audit and fill gaps |
| bd CLI basics |
Create, update, depend, close beads |
Always use bd tool; never run bare bv (interactive TUI) |
| Robot mode |
Machine-readable bv output for agents |
bv --robot-triage, --robot-next, --robot-plan, --robot-insights |
| Agent team execution |
Coordinate parallel bead execution via Claude Code agent teams |
Beads = persistent truth; team tasks = ephemeral dispatch |
Common Mistakes
| Mistake |
Correct Pattern |
| Oversimplifying bead descriptions to short bullet points |
Beads must be verbose and self-documenting with background, reasoning, and considerations |
| Stopping after one polish round |
Keep polishing until steady-state (typically 6-9 rounds); start a fresh session if progress flatlines |
| Omitting test coverage beads |
Every feature bead should have associated unit test and e2e test beads with detailed logging |
| Not making all blocking relationships explicit |
Use bd depend to declare every dependency; agents cannot infer implicit ordering |
| Losing features from the original plan |
Cross-check every plan section against beads; everything must be embedded so the plan is never consulted again |
Running bare bv without flags |
Always use bv --robot-* flags; bare bv launches an interactive TUI that blocks agents |
| Teammates editing the same files |
Assign exclusive file ownership per teammate; work same-file beads sequentially |
Delegation
- Create initial beads from a markdown plan: Use
Task agent with the plan-to-beads prompt and bd tool access
- Polish beads across multiple rounds: Use
Task agent with the standard polish prompt, repeating until steady-state
- Review bead graph for cycles and missing dependencies: Use
Explore agent to run bv --robot-insights and validate the dependency structure
- Add test coverage beads: Use
Task agent with the test coverage prompt
- Execute beads in parallel: Use agent teams -- lead discovers parallel tracks via
bd ready/bv --robot-plan, spawns teammates with bead-scoped prompts, verifies and closes beads after completion
References
- Plan to Beads -- Converting markdown plans into beads, exact prompts, what gets created
- Polishing Workflow -- Polishing protocol, fresh session technique, cross-model review, quality checklist
- Agent Integration -- bd CLI commands, robot mode, agent team execution, test coverage beads
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: beads-workflow3description: Converts markdown plans into beads (tasks with dependencies) and polishes them until implementation-ready. The bridge between planning and agent team execution. Use when converting a plan to beads, polishing bead descriptions, adding test coverage beads, reviewing bead dependencies, or preparing tasks for parallel agent team execution.4license: MIT5---67# Beads Workflow89Beads are epics, tasks, and subtasks with dependency structure, optimized for AI coding agents. They function like Jira or Linear but designed for machines. This skill covers the full lifecycle: converting markdown plans into beads, iteratively polishing them across multiple rounds and models, and coordinating parallel execution via Claude Code agent teams. Use this when you have a markdown plan and need to produce self-contained, implementation-ready tasks. Do not use this for the planning phase itself; use a planning skill for that.1011> **Core Principle:** "Check your beads N times, implement once" -- where N is as many as you can stomach.1213## Quick Reference1415| Workflow | What It Does | Key Detail |16| -------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |17| Plan to beads | Converts a markdown plan into granular beads with dependencies | Use the full or short conversion prompt with `bd` tool |18| Polish beads | Iteratively reviews and improves bead quality | Run 6-9 rounds until steady-state; use full or standard prompt |19| Fresh session | Breaks out of polishing plateaus | Start new session, re-establish context, then resume polishing |20| Cross-model review | Gets alternative perspectives on bead quality | Run final pass with a different model (Codex, Gemini CLI) |21| Add test coverage | Creates unit test and e2e test beads | Use the test coverage prompt to audit and fill gaps |22| bd CLI basics | Create, update, depend, close beads | Always use `bd` tool; never run bare `bv` (interactive TUI) |23| Robot mode | Machine-readable bv output for agents | `bv --robot-triage`, `--robot-next`, `--robot-plan`, `--robot-insights` |24| Agent team execution | Coordinate parallel bead execution via Claude Code agent teams | Beads = persistent truth; team tasks = ephemeral dispatch |2526## Common Mistakes2728| Mistake | Correct Pattern |29| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |30| Oversimplifying bead descriptions to short bullet points | Beads must be verbose and self-documenting with background, reasoning, and considerations |31| Stopping after one polish round | Keep polishing until steady-state (typically 6-9 rounds); start a fresh session if progress flatlines |32| Omitting test coverage beads | Every feature bead should have associated unit test and e2e test beads with detailed logging |33| Not making all blocking relationships explicit | Use `bd depend` to declare every dependency; agents cannot infer implicit ordering |34| Losing features from the original plan | Cross-check every plan section against beads; everything must be embedded so the plan is never consulted again |35| Running bare `bv` without flags | Always use `bv --robot-*` flags; bare `bv` launches an interactive TUI that blocks agents |36| Teammates editing the same files | Assign exclusive file ownership per teammate; work same-file beads sequentially |3738## Delegation3940- **Create initial beads from a markdown plan**: Use `Task` agent with the plan-to-beads prompt and `bd` tool access41- **Polish beads across multiple rounds**: Use `Task` agent with the standard polish prompt, repeating until steady-state42- **Review bead graph for cycles and missing dependencies**: Use `Explore` agent to run `bv --robot-insights` and validate the dependency structure43- **Add test coverage beads**: Use `Task` agent with the test coverage prompt44- **Execute beads in parallel**: Use agent teams -- lead discovers parallel tracks via `bd ready`/`bv --robot-plan`, spawns teammates with bead-scoped prompts, verifies and closes beads after completion4546## References4748- [Plan to Beads](references/plan-to-beads.md) -- Converting markdown plans into beads, exact prompts, what gets created49- [Polishing Workflow](references/polishing-workflow.md) -- Polishing protocol, fresh session technique, cross-model review, quality checklist50- [Agent Integration](references/agent-integration.md) -- bd CLI commands, robot mode, agent team execution, test coverage beads5152---53> Converted and distributed by [TomeVault](https://tomevault.io/claim/jbabin91) — claim your Tome and manage your conversions.54<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io