beads-workflow

The beads-workflow is a specialized methodology designed for developers and AI engineers managing multi-agent software development cycles. It acts as the critical bridge between abstract planning (large markdown files) and mechanical execution by agent swarms (like Claude Code, Codex, or Gemini). By decomposing long-form architectural plans into self-contained, atomic tasks known as 'beads,' this workflow ensures that each task is self-documenting, context-rich, and dependency-aware. This approach eliminates the need for agents to constantly reference a primary plan, reducing context window noise and significantly lowering the probability of implementation drift or architectural fragmentation.

• Converts high-level architectural markdown plans into granular, machine-optimized task structures.

• Integrates explicit dependency management to define execution order and blocking constraints.

• Provides standardized prompt templates for initial conversion and iterative 'polishing' rounds to refine task logic.

• Ensures total self-containment for each bead, including background, reasoning, technical justifications, and requirements for unit/e2e testing.

• Facilitates horizontal scaling of development by allowing interchangeable, fungible agents to pick up tasks from the task graph.

• Utilize the provided exact prompts for 'Plan to Beads' conversion and multi-round polishing sessions to achieve steady-state task quality.

• Best deployed alongside the Beads Viewer (bv) tool to visualize task graphs, metrics like PageRank or betweenness, and overall project progress.

• Employs an iterative 'check N times, implement once' philosophy, where N refers to the number of polishing rounds performed in 'plan space'.

• Constraints: Requires consistent usage of the 'br' binary to create and modify beads; avoids manual task drift by embedding all context directly into the bead markdown.

• Ideal for complex refactors, new feature development, and large-scale architectural migration where keeping multiple agents synchronized is a common failure point.