plan-to-beads

name	plan-to-beads
description	Decompose an approved implementation plan into self-contained beads issues with zero guesswork. Use when breaking down a plan file into actionable beads tasks.

Plan to Beads

You are taking an approved implementation plan and decomposing it into beads (bd) issues. Apply beads-best-practices throughout. Each bead must be 100% self-contained so that any agent picking it up has zero questions and needs zero assumptions. However it should also reference the plan file(s) and other relevant resources it was based on.

Workflow

1. Find the plan

If the user provided a specific file as an argument, use that. Otherwise use the most recently referenced plan in the existing conversation. If no such plan exists, ask the user to provide one.

Read the plan thoroughly before proceeding.

2. Explore the codebase if needed

Before proposing beads, check how detailed the plan is in terms of:

• The files that will be modified
• Existing patterns, functions, and utilities that should be reused
• The current state of code related to the plan
• Test patterns used in similar features

If these are already established in the plan, then they should be used directly.

Otherwise, explore the codebase to discover them. This detail is critical — beads need concrete file paths and function references, not vague descriptions.

3. Propose Beads

Break the plan into granular implementation tasks. For each proposed bead, show:

[1] <title>
    Depends on: (none | bead numbers)
    Files: <file paths>
    Summary: <2-3 sentences>

[2] <title>
    Depends on: [1]
    Files: <file paths>
    Summary: <2-3 sentences>

4. Refine with User

Present the proposed beads and ask for feedback if anything is not clear:

• Should any beads be split further?
• Should any be merged?
• Are dependencies correct?
• Missing anything?
• Does this set warrant an epic parent (see step 6)?

Iterate until the user approves.

5. Choose a Feature Label

Before creating beads, choose a short, kebab-case label (e.g., fiscal-host, project-collections) that will be applied to every bead in this set.

The label MUST be new. Verify it doesn't already exist:

bd list --label <feature-slug>

If any results are returned, choose a different label (e.g., append a version: fiscal-host-v2). Reusing an existing label would mix unrelated beads together.

6. Decide Whether to Create an Epic

The label is mandatory. An epic parent is optional and additional — decide per plan. See Choose Grouping Deliberately for the general tradeoffs.

Create an epic when the plan is a bounded deliverable that benefits from:

• A place to hold the narrative (goal, design decisions, overall acceptance criteria) beyond what a label can carry
• Queryable roll-up progress via bd epic status
• The whole feature participating in the dependency graph as one node (e.g. another issue is blocked by "the whole of feature X")

Skip the epic when the plan is small (roughly <5 beads), or is a set of loosely related cleanups with no single done-condition. The label alone is enough.

7. Create Beads

If using an epic, create it first:

cat << 'BEAD_EOF' | bd create "Feature X" --type epic --priority 2 --labels <feature-slug> --body-file -
## Goal
...

## Plan
Based on `path/to/plan.md`.

## Acceptance Criteria
[Feature-level, not task-level.]
BEAD_EOF

For each approved bead, create it using --body-file - to pipe the multi-line description. Every bead must carry the feature label. Add --parent <epic-id> when an epic was created — children inherit the parent's labels, so --labels may then be omitted (keep it explicit if you prefer).

Do NOT heredoc into bd create directly — it does not read stdin without --body-file -.

cat << 'BEAD_EOF' | bd create "Bead title" --type task --priority 2 --labels <feature-slug> --body-file -
## Context
...

## Task
...

## Files
...

## Acceptance Criteria
...
BEAD_EOF

Then set dependencies with bd dep add.

This applies even when an epic is used: parenting imposes no ordering, so children of the same epic still need their inter-dependencies wired explicitly. See Hierarchy Is Not Dependency.

Bead Quality Standard

Every bead MUST follow these rules. No exceptions.

100% Self-contained

A bead includes ALL context an agent needs to complete the work without reading the plan, without asking questions, and without exploring the codebase to figure out what to do. The bead IS the spec for that task.

References relevant context

The bead should reference the plan file(s) and other relevant resources it was based on or needs.

No assumptions

Bad: "Update the service to handle the new field"

Good: "In src/services/user/UserService.ts, add a displayName parameter (type: string, max 50 chars) to the updateProfile method.""

No guesswork

Bad: "Add validation for the input"

Good: "In src/routes/api/user.ts, add validation to the request body using the existing userUpdateSchema from src/lib/schemas/user.ts. On validation failure, return HTTP 400 with a structured error response using the project's error helper. Test: send a request with displayName exceeding 50 chars and verify 400 response."

Clear dependencies

Bad: "This needs the database migration to be done first"

Good: "Depends on bead proj-abc123 (Add display_name column to users table). This bead expects the display_name column (type: varchar(50), nullable, default null) to exist on the users table."

Acceptance criteria

Bad: "Implement the feature"

Good: "Done when: (1) POST /api/user with { displayName: 'Test' } updates the display_name column in the database, (2) GET /api/user returns the displayName field in the response, (3) Sending displayName longer than 50 chars returns HTTP 400, (4) Unit test covers all three cases and passes, (5) All changes committed to git as logically grouped commit(s)."

Scoped to one concern

If a bead touches multiple files for different reasons, split it. A schema migration is one bead. The service change is another. The API route change is another. The tests are another (or colocated with the service bead if tightly coupled).

Bead Description Template

Every bead description MUST follow this structure:

## Context

[Why this task exists. Reference the broader goal and any relevant issue IDs and resources.]

## Task

[Exactly what to do. Specific files, functions, line numbers where known, exact changes.]

## Files

[Every file path that will be read or modified, with what happens to each:]
- `src/path/to/file.ts` — modify: add X method
- `src/path/to/other.ts` — read: reference existing Y pattern
- `test/path/to/file.test.ts` — create: tests for X

## Dependencies

[What must be complete before this. What this produces for downstream beads:]
- Depends on: <bead-id> (<title>) — needs <specific thing>
- Produces: <what downstream beads will consume>

## Acceptance Criteria

[Concrete, testable conditions. Not "implement X" but "when Y happens, Z results":]
1. <specific testable condition>
2. <specific testable condition>
3. <specific testable condition>
4. All changes committed to git as logically grouped commit(s)

Rules

• NEVER create vague beads — if you can't fill in the template with specifics, you haven't explored the codebase enough
• ALWAYS include relevant issue references in each bead's Context section when available
• ALWAYS include the plan file path in each bead's Context section for traceability
• Use bd create --type task --priority 2 --labels <feature-slug> as the default. Adjust priority based on dependency order (earlier = higher priority)
• NEVER express ordering via --parent — hierarchy is not dependency; all ordering goes in bd dep add, including between children of the same epic
• ALWAYS apply a consistent, unique label (short kebab-case feature name) to every bead in the set, whether or not an epic is used
• Create an epic parent only for a bounded deliverable with a feature-level done-condition; otherwise the label alone suffices
• Every bead MUST have at least one label — beads without labels are rejected
• After creating all beads, show a summary with bead IDs, titles, labels, and dependency graph