create-plan

name	create-plan
description	Use when a feature or change needs an implementation plan with concrete tasks, file paths, and test steps before coding begins

Create Plan

Turn an approved design into a structured implementation plan with independent, commitable tasks.

Write for a dumb agent. The executing agent has no memory of your conversation, no knowledge of intent, and no ability to infer what you meant. Every task must be self-contained and complete enough that a capable but context-free agent can execute it without guessing. If something is ambiguous, spell it out. If something could be done multiple ways, specify which way. Leave nothing to interpretation.

When to Use

• After brainstorming/design is complete and user has approved the approach
• When work is large enough to benefit from task breakdown (2+ tasks)

Don't use when:

• Idea isn't fleshed out yet — use brainstorming first
• Change is small enough to implement directly (single file, obvious fix)

Input

This skill expects an approved design spec. The spec comes from the conversation — it was already presented and approved during brainstorming. Do NOT read from a file unless one was explicitly saved earlier.

Plan Format

Write to docs/plans/YYYY-MM-DD-<feature>.md:

# [Feature] Plan

**Goal:** One sentence
**Architecture:** 2-3 sentences
**Tech Stack:** Key technologies

---

### Task N: [Name]

**Context:**
A short paragraph explaining *why* this task exists, what problem it solves, and how it fits into the overall feature. Include any decisions already made and why. Do not assume the agent knows anything about the conversation.

**Files:**
- Create: `exact/path/file.ext`
- Modify: `exact/path/existing.ext`
- Test: `tests/path/test.ext`

**What to implement:**
A precise description of the change. Include:
- Exact function/struct/module names to add or modify
- Exact signatures, types, or field names where relevant
- Any specific logic, conditions, or edge cases to handle
- What NOT to change (if there's a risk of over-engineering)

**Steps:**
- [ ] Write failing test for [specific behavior] in `tests/path/test.ext`
- [ ] Run `[exact test command]`
  - Did it fail with [expected error]? If it passed unexpectedly, stop and investigate why.
- [ ] Implement [specific thing] in `exact/path/file.ext`
- [ ] Run `[exact test command]`
  - Did all tests pass? If not, fix the failures and re-run before continuing.
- [ ] Run `[exact format command]` (e.g. `cargo fmt`)
  - Did it succeed? If not, fix and re-run before continuing.
- [ ] Run `[exact build command]` (e.g. `cargo build`)
  - Did it succeed? If not, fix and re-run before continuing.
- [ ] Commit with message: "[suggested commit message]"

**Acceptance criteria:**
- [ ] [Specific, verifiable outcome]
- [ ] [Another specific outcome]

Each task must be independently commitable. The agent executing it has no context beyond what is written here — be exhaustive.

After Plan is Written

Dispatch the reviewer subagent to review the plan (use review type: "plan"). Fix issues (max 3 rounds).

Then update docs/plans/README.md:

1. Add the new plan to the appropriate category table with status 🚧 IN PROGRESS
2. Increment the Total Plans count in Quick Stats
3. If this plan supersedes an older one, move the old entry to the Superseded Plans section

CRITICAL: Do NOT begin implementing any tasks in the plan. The create-plan skill ends once the plan is vetted and presented to the user. You must wait for explicit user approval before transitioning to implementation/execution.

Then tell the user the plan is ready and ask them to say when they're ready to start implementing:

"The implementation plan is ready. When you're ready, just say the word and I'll load the execute-plan skill to turn this spec into an implementation plan."

When the user confirms, load the execute-plan skill and invoke it — do not start planning on your own. The execute-plan skill handles the entire planning process.

Clear the todo list — use manage_todo_list to remove all entries now that planning is complete.

Common Mistakes

Mistake	Fix
Tasks that depend on each other's uncommitted work	Make each task independently commitable
Vague file paths ("update the config")	Use exact paths: src/config/auth.ts
Skipping TDD steps in task template	Every task needs failing test → implement → pass
Planning before design is agreed	Use brainstorming first to align on approach
Too many tasks (10+)	Group related changes; aim for 3-7 tasks