beads-workflow
Installation
SKILL.md
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] |