create-plan

# Skill: Create Plan

## What This Skill Does

Creates a complete implementation plan with all associated artifacts. This documentation shall serve Agents and Humans when working in consecutive sessions with the project:

1. **Plan** (`plans/<name>/plan.md`) - Objective, requirements, DoD, phases overview
2. **Phases** (`plans/<name>/phases/phase-N.md`) - Scope definition per phase (what/why)
3. **Implementation Plans** (`plans/<name>/implementation/phase-N-impl.md`) - Technical approach per phase (how)
4. **Todo List** (`plans/<name>/todo.md`) - Trackable items with status
5. Creates the directory structure for future **Handovers**

## When to Use

- When the user wants to plan a feature, refactoring, or migration before implementing
- When a task is too large for a single session and needs phasing
- When the user asks to "create a plan" or "plan this feature"

Do NOT use for simple, one-shot tasks that don't need formal planning.

## Execution Model (Recommended)

- Preferred: the primary agent runs this skill and writes artifacts under `plans/<name>/`.
- Rationale: plans are conversation-anchored (requirements, trade-offs, sequencing, DoD). Moving authorship to a subagent risks losing intent and introducing gaps.
- Use `doc-explorer` for codebase impact/symbol analysis when the plan touches existing code (doc-explorer writes findings to `docs/`, keeping analysis out of the primary's context).
- Optional (edge cases): use `doc-explorer` only to materialize/format a large set of plan files after the primary has finalized content and structure.

## Workflow

### Step 1: Understand the Objective

Gather requirements from the user using the `question` tool:

- What is the goal? (feature, bugfix, refactoring, migration)
- What are the functional requirements?
- What are the non-functional requirements? (performance, compatibility, etc.)
- What is explicitly out of scope?
- What defines "done"? (Definition of Done)
- What testing strategy is expected?

If the user provided a detailed brief, extract these from the brief and confirm with the `question` tool.

### Step 2: Analyze the Codebase (if applicable)

If the plan involves changes to existing code:

- Use the Task tool with `doc-explorer` to analyze the affected modules and symbols (results are written to `docs/`)
- Read existing project documentation (`docs/overview.md`, module docs) if available
- Identify dependencies and potential risks

### Step 3: Design the Phase Structure

Determine if phasing is needed:

**Single-phase plans** (simple features):
- One phase covering the entire scope
- One implementation plan
- Still create the full directory structure for consistency

**Multi-phase plans** (complex features):
- Each phase must be completable in a single session
- Phases should have clear boundaries - no phase should depend on "half-done" work from another phase
- Each phase should produce a testable, committable result
- Order phases by dependency (foundational first, then building on top)

Guidelines for phase sizing:
- A phase should represent roughly one focused work session
- If a phase requires reading/modifying more than ~15-20 files, consider splitting
- Each phase should end with passing tests and a clean commit

### Step 4: Create the Plan Document

Create `plans/<name>/plan.md`:

- Clear objective statement
- Motivation (why is this needed)
- Functional and non-functional requirements
- Scope (in/out)
- Definition of Done
- Testing strategy
- Phases table with titles and brief descriptions
- Risks and open questions
- Initialize the changelog

### Step 5: Create Phase Documents

For each phase, create `plans/<name>/phases/phase-N.md`:

- Phase objective (What and Why)
- Scope: what this phase includes and explicitly excludes
- Prerequisites (what must be true before starting)
- Deliverables (concrete outputs)
- Acceptance criteria (how to verify the phase is done)
- Dependencies on other phases

### Step 6: Create Implementation Plans

For each phase, create `plans/<name>/implementation/phase-N-impl.md`:

- Technical approach (How)
- Affected modules with expected changes
- **Required Context**: list files the implementing agent must read before starting (module docs, relevant code files, API specs). This is critical for session continuity.
- Implementation steps (ordered, each with what/where/why)
- Testing plan for this phase
- Rollback strategy
- Open technical decisions

If project documentation exists (`docs/modules/`), reference it in both the affected modules section and the Required Context section.

### Step 7: Create the Todo List

Create `plans/<name>/todo.md`:

- Populate with items from Phase 1 (the starting phase)
- All items start as "Pending"
- Fill in the Phase Context section with links to phase doc, implementation plan, and relevant module docs
- Initialize the changelog with the plan creation entry

### Step 8: Create the Handover Directory

Create `plans/<name>/handovers/` directory with a `.gitkeep` file.

### Step 9: Review with User

Present the plan summary to the user:

- Total phases with brief descriptions
- Key requirements and DoD
- Identified risks

Use the `question` tool to confirm the plan or gather adjustments.

## Rules

1. **File-based interface**: All artifacts go into `plans/<name>/` directory structure. The directory name should be lowercase, hyphenated, descriptive.
2. **Phase independence**: Each phase must end in a stable state. No phase should leave the codebase broken.
3. **Phase describes scope, implementation plan describes approach**: Keep these concerns separated. The phase says what/why, the implementation plan says how.
4. **Reference, don't duplicate**: Implementation plans reference module docs and phase docs. Don't repeat requirements from the plan in each phase.
5. **Realistic sizing**: Phases must be completable in a single session. When in doubt, make phases smaller.
6. **No built-in explore agent**: Do NOT use the built-in `explore` subagent type in this framework.
7. **Use `doc-explorer` for codebase analysis**: Delegate deep symbol/dependency analysis via the Task tool. Results are written to `docs/`, not returned as text.
8. **Always ask for confirmation**: Use the `question` tool to validate requirements, phase structure, and scope with the user before creating artifacts.
9. **Initialize changelog**: The plan's changelog should document its creation with the current date.
10. **Create all directories**: Ensure the full directory structure exists: `plans/<name>/`, `phases/`, `implementation/`, `handovers/`.

## Templates

This skill includes normative templates as bundled files. Only read the templates when processing them. Output MUST follow the template headings and frontmatter keys:

- `tpl-plan.md` - Structure for the plan document
- `tpl-phase.md` - Structure for phase documents
- `tpl-implementation-plan.md` - Structure for implementation plans
- `tpl-todo.md` - Structure for the todo list