# Plans To Beads

> This skill should be used when the user asks to "convert plan to beads", "create beads from plan", "break down plan into tasks", "create implementation plan", or has a plan file to track with beads. Transforms a plan into a tracked implementation plan with beads, dependency graph, and verification criteria.

- Skill: `amitkot/plans-to-beads` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add amitkot/plans-to-beads`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amitkot/plans-to-beads/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: amitkot (https://skillmd.com/u/amitkot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/amitkot/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:
   ```bash
   br create "[Plan Title]" -t epic -p 1 -d "[summary]. Source: [plan path]" --json
   ```

2. **Create task beads** for each identified task:
   ```bash
   br create "[Task title]" -t task -p 2 -d "[description]" --json
   ```

3. **Add dependencies** based on the graph:
   ```bash
   br dep add <dependent-task> <dependency-task>
   ```

4. **Link tasks to epic**:
   ```bash
   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:

```markdown
# 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

| Status | Meaning |
|--------|---------|
| `NOT_STARTED` | Initial state (set by this skill) |
| `IN_PROGRESS` | Agent working on it |
| `DONE` | Completed, verification passed |
| `ERROR` | Verification failed or blocker hit |
| `INVALIDATED` | Plan changed, task no longer relevant |
| `BLOCKED` | Dependencies not met |

## 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`