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 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.
license	MIT
metadata	{"author":"oakoss","version":"1.0"}

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