Plans To Beads

Convert Plan to Implementation Plan with Beads

Transform a (1) Plan into a (2) Implementation Plan with beads for cross-session tracking and parallel execution.

Arguments

$ARGUMENTS - Optional path to plan file. Defaults to most recent in ~/.claude/plans/

Process Overview

1. Find and parse the source plan
2. Think hard to identify tasks, dependencies, complexity, verification
3. Create beads with proper dependency relationships
4. Output implementation plan with full task details

Detailed Instructions

Use the Task tool with subagent_type='general-purpose' and model='opus' to perform the conversion. The agent requires high creativity for dependency inference and verification generation.

Agent Instructions

Phase 1: Find and Parse Plan

1. Locate the plan file:

   • If argument provided, use that path
   • Otherwise: ls -t ~/.claude/plans/*.md | head -1

2. Read and parse the plan structure:

   • Title: First # Plan: or # heading
   • Summary: Content under ## Summary or ## Goal or ## Overview
   • Sections: Each ### Phase N:, ### N., or ### Step N: section
   • File references: Note any files mentioned for modification

Phase 2: Think Hard - Task Analysis

Analyze the plan deeply before creating any beads:

1. Identify discrete tasks

   • Break phases into atomic, independently-completable tasks
   • Each task should be achievable in one focused session
   • Avoid tasks that are too broad ("implement feature") or too narrow ("add import")

2. Build dependency graph

   • Check for explicit dependencies (e.g., (depends: 1, 2) markers)
   • Infer dependencies from content:
     • Task mentions file created in another task → dependency
     • Task uses API/function defined in another task → dependency
     • Task tests functionality from another task → dependency
   • Identify parallel opportunities (tasks with no dependencies between them)

3. Assign complexity/model

   Complexity	Model	Indicators
   High	opus	Architecture decisions, ambiguous requirements, complex refactors
   Standard	sonnet	Clear implementation, defined requirements, moderate complexity
   Mechanical	haiku	Simple edits, renames, boilerplate, config changes

4. Generate verification criteria For each task, create specific, runnable checks:

   • Build check: cargo build / npm run build / etc.
   • File existence: New files that should exist
   • Test check: Relevant test commands
   • Grep checks: Patterns that should/shouldn't exist
   • Runtime checks: Endpoints, CLI commands (if applicable)

Phase 3: Create Beads

1. Create epic for the overall plan:

   br create "[Plan Title]" -t epic -p 1 -d "[summary]. Source: [plan path]" --json
   

2. Create task beads for each identified task:

   br create "[Task title]" -t task -p 2 -d "[description]" --json
   

3. Add dependencies based on the graph:

   br dep add <dependent-task> <dependency-task>
   

4. Link tasks to epic:

   br dep add <task> <epic> -t parent-child
   

Phase 4: Output Implementation Plan

Write to docs/plans/YYYY-MM-DD-[slug]-implementation.md with this structure:

# Implementation: [Plan Title]

**Source Plan:** [path to (1) plan]
**Epic:** [bead-id]
**Created:** [date]

## Dependency Graph

[ASCII representation showing task dependencies] [bead-id] (Task name) └── [bead-id] (Dependent task) └── [bead-id] (Further dependent)

[bead-id] (Parallel task) [no deps]

## Tasks

### Task 1: [Title]
**Bead:** [bead-id]
**Status:** NOT_STARTED
**Model:** [opus/sonnet/haiku]
**Dependencies:** [list or "none"]

[Task description - first paragraph from plan section]

**Verify:**
- [ ] [Specific verification check]
- [ ] [Another check]
- [ ] [etc.]

---

[Repeat for each task]

Phase 5: Return Summary

Return a concise summary (not raw command output):

Created implementation plan from: [filename]

Epic: [title] ([epic-id])

Dependency Graph:
  [visual representation]

Tasks: [N] total
  - [M] ready (no dependencies)
  - [K] blocked

Implementation plan: docs/plans/[filename]
Run `br ready` to see unblocked tasks.

Task Status Values

Notes

• Original (1) plan is preserved - never modify it
• Implementation plan is the working document for execution
• Task descriptions use first paragraph only (keeps them scannable)
• Verification criteria should be runnable commands where possible
• The dependency graph enables parallel execution of independent tasks

Reference

For detailed design rationale, see: references/design-rationale.md