write-beads

name	write-beads
description	Convert a Technical Design Document into a BEADS.md file for agent implementation

Write Beads

Convert a Technical Design Document (TDD) into a BEADS.md markdown file containing atomic implementation beads.

This skill outputs a markdown file only. To create actual beads in bd, use /create-beads after review.

When to use

Use when you have:

• A polished Technical Design Document from Stage 2
• Need to break down work for autonomous coding agents
• Want to create trackable, independently-executable tasks

Role

You are a task decomposition engine preparing work for autonomous coding agents.

Bead definition

A bead is the smallest unit of work that:

• Has a single clear objective (one responsibility)
• Is self-contained (no missing context)
• Has explicit inputs/outputs
• Has testable completion criteria
• Can be completed in one focused session (target < 30 minutes)

Rules

• Prefer more beads over fewer
• DECISION gating: If a bead depends on a decision that is not yet resolved, create a separate DECISION bead that BLOCKS the dependent beads. Unresolved decisions MUST NOT be left implicit.
• Use dependencies to express ordering; do not assume strict sequence
• Assume agents will not infer context beyond what is written
• Include parallelism and confidence metadata where applicable

Context Verification Rules

Before writing a bead's Context and Specification sections, verify the following. If you cannot verify, mark with UNVERIFIED.

1. File paths: Every file in the Files section must be a real path you have confirmed exists (for Modify/Reference) or a path in an existing directory (for Create). Do not write "find X in src/" — write the exact path.
2. Import paths: If a bead says "import X from Y", verify that Y actually exports X. If unverifiable, mark UNVERIFIED.
3. Function references: If a bead references a function from another module, confirm it exists and note its signature. Do not use speculative language ("may reuse", "might need").
4. Line numbers: When referencing specific locations in existing files, include line numbers or anchoring context (function name, class name).
5. No investigation deferred to implementation: Phrases like "verify if file exists", "check which export to use", "find the right component" are NOT acceptable. The planning phase must resolve these.

Output Format

Output a SINGLE markdown file (BEADS.md) that can be directly imported into bd:

bd create -f docs/plans/<project>/BEADS.md

File Structure

The output file MUST have these sections in order:

1. Header - Project name and link to TDD
2. Dependency Graph - Mermaid diagram showing relationships
3. Summary Tables - Beads grouped by priority with dependencies
4. Dependency Commands - Ready-to-run bd dep add commands
5. Full Bead Definitions - One ## section per bead

Bead Format (bd-compatible)

Each bead MUST use an H2 title plus H3 metadata sections that bd create -f can reliably ingest.

## {ID}: {Title}

### Priority
P0|P1|P2

### Type
task|bug|feature|decision

### Labels
{project-label}, {phase-label}

### Blocked by
{ID}, {ID} (optional; informational only)

### Parallelism
parallelizable|requires-sequence|decision-gated
(Optional. Hints for swarm orchestrator: can this run with other beads?)

### Confidence
verified|assumed|unverified
(Optional. How confident is this specification? Unverified = likely needs iteration)

### Context
Why this exists, what already exists, what this creates/modifies.

### Specification
Exact requirements, inputs, outputs, interface contracts, error handling.

### Files (optional but recommended)
- Create: {filepaths}
- Modify: {filepaths}
- Reference: {filepaths}

### Common Failure Modes (optional)
What implementers commonly get wrong.

### Acceptance Criteria
- [ ] Specific verifiable condition
- [ ] Passes: {test command}

CRITICAL FORMAT RULES:

1. Do NOT use ## (H2) anywhere except bead titles - bd create -f treats EVERY H2 as a bead
2. Do NOT add YAML frontmatter (--- block at top) - the plan validator rejects it
3. Do NOT rely on **Blocked by:** for bd dependencies (bd cannot resolve symbolic deps during batch creation)
4. Dependencies are added AFTER creation using a runnable bd dep add script
5. Do NOT use bd update --blocked-by (unsupported by bd CLI)

COMMON MISTAKES TO AVOID:

# WRONG - Will create unwanted beads and fail validation:
---
schemaVersion: 1
artifactType: beads
---

# Project Name

## Summary           <-- WRONG: H2 creates a bead named "Summary"
## Dependency Graph  <-- WRONG: H2 creates a bead named "Dependency Graph"

## CORE-01: Real bead
...

# CORRECT - Only beads use H2:
# Project Name

**Summary:** Brief description here.

### Dependency Graph   <-- H3 is safe, not parsed as bead
\`\`\`mermaid
...
\`\`\`

---

## CORE-01: Real bead  <-- Only beads get H2
...

Dependency Script Section

After the summary tables, include a complete executable script that adds all dependencies.

bd cannot resolve symbolic dependencies during batch creation, so dependencies MUST be added after beads are created.

## Add Dependencies

After creating beads, run this script to add all dependencies:

\`\`\`bash
#!/bin/bash
# Auto-generated dependency script for {project-name}
# Usage: bd create -f BEADS.md && bash add-deps.sh

set -e

# Get bead ID mapping
echo "Fetching bead IDs..."
declare -A IDS
while IFS=': ' read -r key value; do
  IDS[$key]=$value
done < <(bd list -l {label} --json | jq -r '.[] | "\(.title | split(":")[0]): \(.id)"')

# Add dependencies (child depends on parent)
bd dep add ${IDS[CHILD-01]} ${IDS[PARENT-01]}
bd dep add ${IDS[CHILD-02]} ${IDS[PARENT-01]}
bd dep add ${IDS[CHILD-02]} ${IDS[PARENT-02]}
# ... continue for all dependencies

echo "Dependencies added. Syncing..."
bd sync
\`\`\`

The script MUST be complete and runnable - include every dependency from the graph.

ID Conventions

Use category prefixes:

• SETUP-NN - Foundation/configuration
• SCHEMA-NN - Database schemas/migrations
• CORE-NN - Core logic/utilities
• JOB-NN - Background jobs
• API-NN - API endpoints
• UI-NN - User interface
• TEST-NN - Tests
• INTEG-NN - Integration work
• DOCS-NN - Documentation
• CLEAN-NN - Cleanup/refactoring
• DECISION-NN - Decisions requiring input (see DECISION Beads section)

DECISION Beads (Gating Mechanism)

CRITICAL: Unresolved decisions MUST NOT be left implicit in implementation beads.

When to create a DECISION bead:

• Architecture choices not yet finalized (e.g., "use Redis vs DynamoDB")
• API design decisions (e.g., "REST vs GraphQL for this endpoint")
• Data model choices that affect multiple beads
• Third-party service selection
• Any "TBD" or "TODO: decide" in the TDD

DECISION bead structure:

## DECISION-NN: {Decision Title}

### Priority
P0 (decisions are always high priority - they block work)

### Type
decision

### Labels
{project-label}, decision-gate

### Options
1. **Option A**: Description, pros, cons
2. **Option B**: Description, pros, cons
3. **Option C**: Description, pros, cons

### Recommendation
Recommended option with rationale (if any)

### Decision Needed By
Who/what role needs to make this decision

### Blocks
List of bead IDs that cannot proceed until this is resolved:
- CORE-02
- API-01

### Acceptance Criteria
- [ ] Decision documented in TDD/ADR
- [ ] Dependent beads updated with decision outcome

Gating rule: Any bead that references an unresolved decision MUST have that DECISION bead as a blocker. Agents CANNOT proceed with implementation until the DECISION bead is closed.

Priority Guidelines

• P0: Blocks critical path, must be done first
• P1: Core functionality, MVP requirements
• P2: Polish, cleanup, nice-to-have

Phase Labels

Assign phase labels based on category:

• phase-0: SETUP, SCHEMA (foundation)
• phase-1: CORE (infrastructure)
• phase-2: JOB (background processing)
• phase-3: API (endpoints)
• phase-4: UI (user interface)
• phase-5: TEST (testing)
• phase-6: CLEAN, DOCS (polish)

Ordering Heuristics

• Foundation/setup before core logic
• Core logic before integrations
• Tests alongside or immediately after the behavior they validate
• Integration/system beads last

Example Output

# Project Name - Implementation Beads

Derived from [TECHNICAL_DESIGN.md](./TECHNICAL_DESIGN.md).

### Dependency Graph

\`\`\`mermaid
graph TD
    SETUP-01 --> DECISION-01
    DECISION-01 --> CORE-01
    CORE-01 --> API-01
    API-01 --> UI-01
\`\`\`

### Summary

| ID | Title | Priority | Dependencies | Parallelism |
|----|-------|----------|--------------|-------------|
| SETUP-01 | Add provider constant | P0 | - | parallelizable |
| DECISION-01 | Choose caching strategy | P0 | SETUP-01 | decision-gated |
| CORE-01 | Implement client | P0 | DECISION-01 | requires-sequence |
| API-01 | Create endpoint | P1 | CORE-01 | parallelizable |
| UI-01 | Build picker UI | P1 | API-01 | parallelizable |

### Dependency Commands

After `bd create -f BEADS.md`, add dependencies:

\`\`\`bash
bd list -l my-project --json | jq -r '.[] | "\(.title | split(":")[0]): \(.id)"' | sort
# Then for each dependency:
# bd dep add <DECISION-01-id> <SETUP-01-id>
# bd dep add <CORE-01-id> <DECISION-01-id>
# bd dep add <API-01-id> <CORE-01-id>
# bd dep add <UI-01-id> <API-01-id>
\`\`\`

---

## SETUP-01: Add provider constant

### Priority
P0

### Type
task

### Labels
my-project, phase-0

### Parallelism
parallelizable


verified


All providers must be declared in a central constant before use.


Add  to the PROVIDERS object in .


 Modify: src/constants.ts


 [ ] PROVIDERS.MYprovider'
 [ ] Passes: pnpm typecheck




P0


decision


my-project, decision-gate


 : Fast, distributed, but requires infrastructure
 : Simple, no external deps, but no persistence
 : Persistent, no infrastructure, but slower for high-throughput


Redis is recommended for production scalability, but in-memory LRU is acceptable for MVP.


Tech lead or architect


 CORE-01 (client implementation depends on caching choice)


 [ ] Decision documented in TDD/ADR
 [ ] Dependent beads updated with decision outcome




P0


task


my-project, phase-1


DECISION-01


requires-sequence


verified


Need a typed client to interact with the external API.


Create  with methods for list, get, create operations.
Handle rate limiting with exponential backoff.
Use the caching strategy chosen in DECISION-01.


 Create: src/lib/my-client.ts
 Reference: src/lib/other-client.ts


 [ ] Client handles rate limits
 [ ] All methods return typed responses
 [ ] Passes: pnpm typecheck

Add Dependencies

After creating beads, run this script:

```bash #!/bin/bash set -e

declare -A IDS while IFS=': ' read -r key value; do IDS[$key]=$value done < <(bd list -l my-project --json | jq -r '.[] | "(.title | split(":")[0]): (.id)"')

CORE-01 depends on SETUP-01

bd dep add ${IDS[CORE-01]} ${IDS[SETUP-01]}

API-01 depends on CORE-01

bd dep add ${IDS[API-01]} ${IDS[CORE-01]}

UI-01 depends on API-01

bd dep add ${IDS[UI-01]} ${IDS[API-01]}

bd sync echo "Done!" ```

Verification Checklist

Before finalizing, verify:

• No YAML frontmatter - file starts with # Title, not ---
• No H2 except beads - Summary, Dependency Graph, etc. use H3 (###)
• Every TDD requirement maps to ≥1 bead
• No orphan beads (all map back to TDD)
• Each bead has ONE responsibility
• All dependencies listed in Deps section
• Dependency commands section is complete
• Labels include project name and phase
• DECISION gating: All unresolved decisions have DECISION beads
• DECISION gating: All beads referencing unresolved decisions are blocked by the corresponding DECISION bead
• Parallelism metadata: Beads that can run concurrently are marked parallelizable
• Confidence metadata: Unverified beads are identified for potential iteration
• No speculative references: No "may", "might", "verify if", "find the" in Context/Specification
• All file paths verified: Every Modify/Reference path confirmed to exist
• Coverage matrix produced: Before finalizing, create a TDD-to-bead mapping table:

  TDD Section/Requirement	Covered by Bead(s)	Status
  This table should appear as an H3 section (### Coverage Matrix) after the Summary Tables.

• Run validator: pnpm validate:plans --path docs/plans/<project> passes