Beads Workflow

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

Common Mistakes

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

Agent Integration

bd CLI Basics

bd init

bd create "Implement user authentication" -t feature -p 1

bd depend BD-123 BD-100  # BD-123 depends on BD-100

bd update BD-123 --status in_progress

bd close BD-123 --reason "Completed and tested"

bd ready --json

Key commands:

Robot Mode for Agents

Never run bare `bv` -- it launches an interactive TUI that blocks agents. Always use --robot-* flags.

bv --robot-triage

bv --robot-next

bv --robot-plan

bv --robot-insights

Check for cycles before implementation:

bv --robot-insights | jq '.Cycles'

An empty result means the dependency graph is clean.

Agent Mail Integration

When multiple agents work on beads in parallel, use Agent Mail conventions to coordinate.

Conventions

• Use the bead ID as the Mail thread_id: send_message(..., thread_id="bd-123")
• Prefix subjects with the bead ID: [bd-123] Starting auth refactor
• Include the bead ID in file reservation reasons: file_reservation_paths(..., reason="bd-123")

Typical Agent Flow

bd ready --json

file_reservation_paths(project_key, agent_name, ["src/**"], reason="bd-123")

send_message(..., thread_id="bd-123", subject="[bd-123] Starting work")

Work on the bead, then complete:

bd close bd-123 --reason "Completed"

release_file_reservations(project_key, agent_name)

Test Coverage Beads

Use the following prompt to audit test coverage and create beads for any gaps.

Do we have full unit test coverage without using mocks/fake stuff? What about complete e2e integration test scripts with great, detailed logging? If not, then create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid with detailed comments.

This prompt:

• Audits existing test coverage across the project
• Identifies gaps in both unit tests and e2e tests
• Creates granular beads for missing test coverage with full dependency structure
• Emphasizes real implementations over mocks and detailed logging for debugging

Plan to Beads

Why Convert Plans to Beads?

A markdown plan fits in a context window and lets a model reason about the entire system at once. But plans are not executable by agent swarms. Beads bridge this gap: each bead is a self-contained task that any agent can pick up independently.

Key properties of well-formed beads:

• Self-contained -- Never need to refer back to the original markdown plan
• Self-documenting -- Include background, reasoning, justifications, considerations
• Dependency-aware -- Explicit structure of what blocks what
• Rich descriptions -- Long markdown descriptions, not short bullet points

Conversion Prompt (Full Version)

Replace YOUR_PLAN_FILE.md with the actual filename.

OK so now read ALL of YOUR_PLAN_FILE.md; please take ALL of that and elaborate on it and use it to create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid, with detailed comments so that the whole thing is totally self-contained and self-documenting (including relevant background, reasoning/justification, considerations, etc.-- anything we'd want our "future self" to know about the goals and intentions and thought process and how it serves the over-arching goals of the project.). The beads should be so detailed that we never need to consult back to the original markdown plan document. Remember to ONLY use the `bd` tool to create and modify the beads and add the dependencies. Use ultrathink.

Conversion Prompt (Short Version)

Use when the plan is already in context (for example, you just discussed it).

OK so please take ALL of that and elaborate on it more and then create a comprehensive and granular set of beads for all this with tasks, subtasks, and dependency structure overlaid, with detailed comments so that the whole thing is totally self-contained and self-documenting (including relevant background, reasoning/justification, considerations, etc.-- anything we'd want our "future self" to know about the goals and intentions and thought process and how it serves the over-arching goals of the project.) Use only the `bd` tool to create and modify the beads and add the dependencies. Use ultrathink.

What Conversion Creates

The conversion prompt produces:

• Tasks and subtasks with clear, non-overlapping scope
• Dependency links declaring what must complete before what
• Detailed descriptions containing:
• Background context explaining why this work matters
• Reasoning and justification for the chosen approach
• Technical considerations and constraints
• How it serves the overarching project goals

Example Bead Structure

A well-formed bead after conversion looks like this:

ID: BD-123
Title: Implement OAuth2 login flow
Type: feature
Priority: P1
Status: open

Dependencies: [BD-100 (User model), BD-101 (Session management)]
Blocks: [BD-200 (Protected routes), BD-201 (User dashboard)]

Description:
Implement OAuth2 login flow supporting Google and GitHub providers.

## Background

This is the primary authentication mechanism for the application.
Users should be able to sign in with existing Google/GitHub accounts
to reduce friction.

## Technical Approach

- Use NextAuth.js for OAuth2 implementation
- Store provider tokens encrypted in Supabase
- Create unified user record on first login
- Handle account linking for multiple providers

## Success Criteria

- User can click "Sign in with Google/GitHub"
- OAuth flow completes and redirects to dashboard
- User record created/updated in database
- Session cookie set correctly
- Logout clears session properly

## Test Plan

- Unit: Token encryption/decryption
- Unit: User record creation
- E2E: Full OAuth flow (mock provider)
- E2E: Account linking scenario

## Considerations

- Handle provider API rate limits
- Graceful degradation if provider is down
- GDPR compliance for EU users

Tips for Better Conversions

• Ensure the plan file is complete before converting; partial plans produce incomplete beads
• Use "ultrathink" in the prompt to encourage deeper reasoning about structure
• After conversion, immediately run a polish pass to catch gaps
• Check that every section of the original plan maps to at least one bead

Polishing Workflow

Why Polish?

Even after initial conversion, beads continue to improve with review. Each round catches missing dependencies, oversimplified descriptions, lost features, and missing test coverage. You get incremental improvements even at round 6+.

Polish Prompt (Full Version)

Use when you still have the original plan file available. Replace YOUR_PLAN_FILE.md with the actual filename.

Reread AGENTS dot md so it's still fresh in your mind. Then read ALL of YOUR_PLAN_FILE.md . Use ultrathink. Check over each bead super carefully-- are you sure it makes sense? Is it optimal? Could we change anything to make the system work better for users? If so, revise the beads. It's a lot easier and faster to operate in "plan space" before we start implementing these things! DO NOT OVERSIMPLIFY THINGS! DO NOT LOSE ANY FEATURES OR FUNCTIONALITY! Also make sure that as part of the beads we include comprehensive unit tests and e2e test scripts with great, detailed logging so we can be sure that everything is working perfectly after implementation. It's critical that EVERYTHING from the markdown plan be embedded into the beads so that we never need to refer back to the markdown plan and we don't lose any important context or ideas or insights into the new features planned and why we are making them.

Polish Prompt (Standard Version)

Use when beads are the primary source of truth and the plan is no longer needed.

Reread AGENTS dot md so it's still fresh in your mind. Check over each bead super carefully-- are you sure it makes sense? Is it optimal? Could we change anything to make the system work better for users? If so, revise the beads. It's a lot easier and faster to operate in "plan space" before we start implementing these things!

DO NOT OVERSIMPLIFY THINGS! DO NOT LOSE ANY FEATURES OR FUNCTIONALITY!

Also, make sure that as part of these beads, we include comprehensive unit tests and e2e test scripts with great, detailed logging so we can be sure that everything is working perfectly after implementation. Remember to ONLY use the `bd` tool to create and modify the beads and to add the dependencies to beads. Use ultrathink.

Polishing Protocol

1. Run the polish prompt 2. Review changes the model made 3. Repeat until steady-state (typically 6-9 rounds) 4. If progress flatlines, use the fresh session technique below 5. Optionally run a final pass with a different model

Fresh Session Technique

When polishing starts producing diminishing returns, start a brand new session to break out of the plateau.

Step 1 -- Re-establish context:

First read ALL of the AGENTS dot md file and README dot md file super carefully and understand ALL of both! Then use your code investigation agent mode to fully understand the code, and technical architecture and purpose of the project. Use ultrathink.

Step 2 -- Review existing beads:

We recently transformed a markdown plan file into a bunch of new beads. I want you to very carefully review and analyze these using `bd` and `bv`.

Step 3 -- Follow up with the standard polish prompt.

The fresh session brings a clean context window, which often catches issues that accumulated context obscured.

Cross-Model Review

For extra polish, have different models review the beads. Each model brings a different perspective.

When Beads Are Ready

Beads are ready for implementation when:

1. Steady-state reached -- Multiple polishing rounds yield minimal changes 2. Cross-model reviewed -- At least one alternative model has reviewed 3. No cycles -- bv --robot-insights shows no dependency cycles 4. Tests included -- Each feature bead has associated test beads 5. Dependencies clean -- The dependency graph makes logical sense

Quality Checklist

Before handing beads off for implementation, verify each one:

• Self-contained -- Can be understood without external context
• Clear scope -- One coherent piece of work
• Dependencies explicit -- Links to blocking and blocked beads
• Testable -- Clear success criteria
• Includes tests -- Unit tests and e2e tests in scope
• Preserves features -- Nothing from the plan was lost
• Not oversimplified -- Complexity preserved where needed