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 integrating with the bd CLI and Agent Mail for swarm execution. 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 Mail integration |
Coordinate multi-agent bead execution |
Use bead ID as thread_id; prefix subjects with [bd-XXX] |
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 |
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
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 Mail integration, test coverage beads
1---
2name: beads-workflow
3description: 'Converts markdown plans into beads (tasks with dependencies) and polishes them until implementation-ready. The bridge between planning and agent swarm execution. Use when converting a plan to beads, polishing bead descriptions, adding test coverage beads, reviewing bead dependencies, or preparing tasks for agent swarm execution.'
4license: MIT
5metadata:
6 author: oakoss
7 version: '1.0'
8---
9
10# Beads Workflow
11
12Beads 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 integrating with the bd CLI and Agent Mail for swarm execution. 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.
13
14> **Core Principle:** "Check your beads N times, implement once" -- where N is as many as you can stomach.
15
16## Quick Reference
17
18| Workflow | What It Does | Key Detail |
19| ---------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
20| Plan to beads | Converts a markdown plan into granular beads with dependencies | Use the full or short conversion prompt with `bd` tool |
21| Polish beads | Iteratively reviews and improves bead quality | Run 6-9 rounds until steady-state; use full or standard prompt |
22| Fresh session | Breaks out of polishing plateaus | Start new session, re-establish context, then resume polishing |
23| Cross-model review | Gets alternative perspectives on bead quality | Run final pass with a different model (Codex, Gemini CLI) |
24| Add test coverage | Creates unit test and e2e test beads | Use the test coverage prompt to audit and fill gaps |
25| bd CLI basics | Create, update, depend, close beads | Always use `bd` tool; never run bare `bv` (interactive TUI) |
26| Robot mode | Machine-readable bv output for agents | `bv --robot-triage`, `--robot-next`, `--robot-plan`, `--robot-insights` |
27| Agent Mail integration | Coordinate multi-agent bead execution | Use bead ID as `thread_id`; prefix subjects with `[bd-XXX]` |
28
29## Common Mistakes
30
31| Mistake | Correct Pattern |
32| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
33| Oversimplifying bead descriptions to short bullet points | Beads must be verbose and self-documenting with background, reasoning, and considerations |
34| Stopping after one polish round | Keep polishing until steady-state (typically 6-9 rounds); start a fresh session if progress flatlines |
35| Omitting test coverage beads | Every feature bead should have associated unit test and e2e test beads with detailed logging |
36| Not making all blocking relationships explicit | Use `bd depend` to declare every dependency; agents cannot infer implicit ordering |
37| Losing features from the original plan | Cross-check every plan section against beads; everything must be embedded so the plan is never consulted again |
38| Running bare `bv` without flags | Always use `bv --robot-*` flags; bare `bv` launches an interactive TUI that blocks agents |
39
40## Delegation
41
42- **Create initial beads from a markdown plan**: Use `Task` agent with the plan-to-beads prompt and `bd` tool access
43- **Polish beads across multiple rounds**: Use `Task` agent with the standard polish prompt, repeating until steady-state
44- **Review bead graph for cycles and missing dependencies**: Use `Explore` agent to run `bv --robot-insights` and validate the dependency structure
45- **Add test coverage beads**: Use `Task` agent with the test coverage prompt
46
47## References
48
49- [Plan to Beads](references/plan-to-beads.md) -- Converting markdown plans into beads, exact prompts, what gets created
50- [Polishing Workflow](references/polishing-workflow.md) -- Polishing protocol, fresh session technique, cross-model review, quality checklist
51- [Agent Integration](references/agent-integration.md) -- bd CLI commands, robot mode, Agent Mail integration, test coverage beads
oakoss