beads-workflow

name	beads-workflow
description	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.
license	MIT
metadata	{"author":"oakoss","version":"1.1"}

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