plan

name	plan
description	Break down medium-to-large tasks into phased plans in docs/plans/. Planning only — does not implement. Use for new features, multi-file refactors, or architectural changes — not small fixes. Triggers: "plan this", "break this down".

Plan

Produce implementation plans grounded in project principles. Write plans to docs/plans/. Do NOT implement anything — the plan is the deliverable.

Use Tasks to track progress. Create a task for each step (TaskCreate), mark each in_progress when starting and completed when done (TaskUpdate). Check TaskList after completing each step.

Step 0 — Triage Complexity

Before running the full planning workflow, assess whether this task actually needs a plan:

Trivially small (1–2 files, obvious approach): Tell the user this task doesn't need a plan and suggest implementing directly without the plan skill. Stop here — do not implement.

Needs planning (proceed to Step 1):

• The change spans 3+ files or introduces new architecture
• There are multiple valid approaches and the user should weigh in
• The task has unclear scope or cross-cutting concerns
• The user explicitly asks for a plan

Step 1 — Load Principles

Read docs/principles.md. Follow every [[wikilink]] and read each linked principle file. These principles govern all plan decisions — refer back to them throughout.

Do NOT skip this. Do NOT use memorized principle content — always read fresh.

Step 2 — Define Scope and Constraints

Use AskUserQuestion to resolve ambiguity before exploring the codebase:

• What is in scope vs explicitly out of scope?
• Are there constraints (dependencies, platform requirements, existing patterns to preserve)?
• What does "done" look like?

Frame questions with concrete options. If the request is already clear, confirm scope boundaries briefly and move on.

Step 3 — Explore Context with Subagents

Always delegate exploration to subagents via the Task tool. Never do large-scale codebase exploration in the main context.

Spawn exploration agents (subagent_type: Explore) to:

• Read existing code in affected areas
• Identify patterns, conventions, and dependencies
• Map architecture relevant to the change
• Find tests, types, and related infrastructure

Run multiple agents in parallel when investigating independent areas.

Step 4 — Gather Domain Skills

Check installed skills (.agents/skills/, .claude/skills/) for any that match the plan's domain. Invoke matched skills — read their output and incorporate domain guidance into the plan.

If the plan touches a domain not covered by installed skills, use find-skills to search for a relevant skill. If one is found, install it (project-local) and incorporate its guidance. Note what was installed so the user can see it. After the plan is written, delete any one-off skills that won't be needed again.

Step 5 — Write the Plan

Create the plan directory and files manually:

1. Create docs/plans/NN-slug-name/overview.md (or a single file for simple plans)
2. Create phase files as needed
3. Update docs/plans/index.md with a link to the new plan

Phase sizing

• 1 function/type + tests per phase, or 1 bug fix — not "one file" or "one component" (too variable)
• Max 2-3 files touched per phase when possible
• Prefer 8-10 small phases over 3-4 large ones — small phases keep future options open
• If a phase lists >5 test cases or >3 functions, split it

For small plans, a single file at docs/plans/NN-plan-name.md is fine.

For plans with 3+ phases, create a directory:

docs/plans/42-mvp/
├── overview.md
├── phase-1-scaffold.md
├── phase-2-layout.md
├── phase-3-drawing.md
└── testing.md

Non-phase files (like testing.md) are fine alongside phases.

Overview file

Must include:

• Context — what problem this solves and why
• Scope — what's included, what's explicitly excluded
• Constraints — technical, platform, dependency, or pattern constraints
• Applicable skills — domain skills from Step 4 (list by name so implementers invoke them)
• Phases — ordered links to phase files: [[plans/42-mvp/phase-1-scaffold]]
• Verification — project-level verification commands

Phase files

Each phase file must include:

• Back-link: Back to [[plans/42-mvp/overview]]
• Goal — what this phase accomplishes
• Changes — which files are affected and what changes, described at a high level
• Data structures — name the key types/schemas before logic, but a one-line sketch is enough — don't write full definitions
• Verification — static and runtime checks for this phase (see Step 6)

Keep plans high-level. Describe what and why, not how at the code level. A phase should read like a brief to a senior engineer: goals, boundaries, key types, and verification — not code snippets or pseudocode.

Order phases per the sequencing principle: infrastructure and shared types first, features after. Each phase should be independently shippable.

Skill changes: If a phase involves creating or updating a skill (any file in .claude/skills/ or .agents/skills/), the phase must instruct the implementer to use the skill-creator skill during that phase.

Redesign check

For changes touching existing code, apply redesign-from-first-principles:

"If we were building this from scratch with this requirement, what would we build?"

Don't bolt changes onto existing designs — redesign holistically.

Alternatives check

For architectural decisions, briefly sketch 2-3 approaches in the overview's Constraints section. State which was chosen and why. This prevents premature commitment and documents the design space explored.

Step 6 — Verification Strategy

Every phase must have a verification section with both:

Static

• Type checking passes
• Linting passes
• Code follows project conventions
• Tests written and passing

Runtime

• What to test manually (launch the app, exercise the feature path)
• What automated tests to write (unit, integration, e2e)
• Edge cases to cover
• For UI: visual verification via screenshot

Per prove-it-works: "it compiles" is not verification. Every phase must describe how to prove the change works.

Step 7 — Update Plans Index

Update docs/plans/index.md with a wikilink to the new plan's overview.

Do NOT edit docs/index.md — the auto-index hook maintains it automatically.

Step 8 — Present to User

Summarize the plan: list the phases, scope boundaries, applicable skills, and verification approach. Ask the user to review the plan files in docs/plans/.

Stop here. Do not begin implementation. The user decides when and how to execute the plan.