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