version: "1.0.1" name: create-plan description: Create a persistent structured plan (plan.md, phases/, todo.md) when work needs multi-phase or multi-session coordination, durable tracking, or an explicitly requested plan. license: MIT compatibility: opencode metadata: category: planning phase: initial

Skill: Create Plan

What This Skill Does

Creates a complete plan with the artifacts required to execute work in phases. This documentation shall serve Agents and Humans when working in consecutive sessions with the project:

1. Plan (plans/<name>/plan.md) - Problem/context, target outcome, guiding decisions, requirements, DoD, phases overview
2. Phases (plans/<name>/phases/phase-N.md) - Scope definition per phase (what/why)
3. Todo List (plans/<name>/todo.md) - Trackable items with status
4. Creates the directory structure for future Handovers

This skill intentionally does not author per-phase implementation plans (plans/<name>/implementation/phase-N-impl.md).

Default next step (second pass): use author-and-verify-implementation-plan to author/verify the per-phase implementation plan against current repo reality.

When to Use

• When work is multi-phase or too large for a single session.
• When the user explicitly requests a persistent plan.
• When durable coordination or tracking is needed across agents, contributors, or sessions.

Do NOT use for a single bounded work package that can be gated with an inline brief containing its task, DoD, constraints, and final verification. Significance or non-triviality alone does not require plans/ persistence.

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.

Routing Matrix (Who does what)

• Writes: plans/<name>/plan.md, plans/<name>/phases/**, plans/<name>/todo.md, and creates directories under plans/<name>/.
• Does NOT write: plans/<name>/implementation/** (use author-and-verify-implementation-plan).
• Primary: owns requirements, scope, DoD, phase breakdown, gating.
• doc-explorer: optional for repo-anchored analysis persisted into docs/** and/or mechanical plan materialization.
• implementer: never used for plan authoring.

Workflow

Step 1: Understand the Objective

Gather requirements from the user using the question tool:

• What is the goal? (feature, bugfix, refactoring, migration)
• What problem or current state motivates the change, and what target outcome should replace it?
• Which user-approved decisions and constraints bind the solution?
• 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?
• Are there assumptions that materially bound scope or acceptance?

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
• Carry decision-relevant context into the plan, but reference detailed architecture documentation instead of reproducing it.

Step 3: Design the Phase Structure

Determine if phasing is needed:

Single-phase plans (work that otherwise warrants persistence):

• One phase covering the entire scope
• Still create the full directory structure for consistency
• Create this structure only because the work needs persistent coordination or tracking, or the user requested it; a single-phase shape alone is not a reason to create a plan.

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:

• Concise problem/current-state context and target outcome
• Binding guiding decisions and constraints
• Assumptions only when they materially bound scope or acceptance
• 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 and why the phase exists
• How the phase contributes to the plan goal
• 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 the Implementation Directory (Second Pass Follows)

Create the implementation directory structure (no files yet):

• plans/<name>/implementation/

Then, as the default second pass (before execution), author and verify per-phase implementation plans via author-and-verify-implementation-plan.

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 the phase doc and relevant module docs
• Add an implementation plan link placeholder (to be created by author-and-verify-implementation-plan before execution)
• 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: Keep phase docs focused on what/why and acceptance criteria. The per-phase implementation approach (how) is authored later via author-and-verify-implementation-plan.
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. Two-pass default for implementation plans: Implementation plans are authored/verified separately via author-and-verify-implementation-plan before executing a phase.
9. Always ask for confirmation: Use the question tool to validate requirements, phase structure, and scope with the user before creating artifacts.
10. Initialize changelog: The plan's changelog should document its creation with the current date.
11. Create all directories: Ensure the full directory structure exists: plans/<name>/, phases/, implementation/, handovers/.
12. Preserve framing without duplication: Include the problem/current state, target outcome, and binding guiding decisions needed to interpret scope. Reference detailed architecture docs rather than turning the plan into an architecture inventory.
13. Material assumptions only: Record an assumption only when it constrains scope, acceptance, or a later decision.

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-todo.md - Structure for the todo list