Plan

/plan

This skill is self-contained — follow the steps below instead of delegating to external planning skills (superpowers, etc.).

Research the codebase and create a spec + phased implementation plan. Zero interactive questions — explores the code instead.

When to use

Creates a track for any feature, bug fix, or refactor with a concrete, file-level implementation plan. Works with or without /setup.

MCP Tools (use if available)

If MCP tools are not available, fall back to Glob + Grep + Read.

Steps

1. Parse task description from $ARGUMENTS. - If empty, ask via AskUserQuestion: "What feature, bug, or refactor do you want to plan?" - This is the ONE question maximum.

2. Detect context — determine where plan files should be stored:

Project context (normal project with code): - Detected by: package.json, pyproject.toml, Cargo.toml, *.xcodeproj, or build.gradle.kts exists in working directory - Plan path: docs/plan/{trackId}/

Knowledge base context (documentation-centric project): - Detected by: NO package manifest found, BUT directories like docs/, notes/, or structured numbered directories exist - Plan path: docs/plan/{shortname}/ - Note: the shortname is derived from the task (kebab-case, no date suffix for the directory)

Set $PLAN_ROOT based on detected context. All subsequent file paths use $PLAN_ROOT.

3. Load project context (parallel reads): - CLAUDE.md — architecture, constraints, Do/Don't - docs/prd.md — what the product does (if exists) - docs/workflow.md — TDD policy, commit strategy (if exists) - package.json or pyproject.toml — stack, versions, deps

3. Auto-classify track type from keywords in task description: - Contains "fix", "bug", "broken", "error", "crash" → bug - Contains "refactor", "cleanup", "reorganize", "migrate" → refactor - Contains "update", "upgrade", "bump" → chore - Default → feature

4. Research phase — explore the codebase to understand what needs to change:

a. Get architecture overview (if MCP available — do this FIRST):

      codegraph_explain(project="{project name from CLAUDE.md or directory name}")
      

b. Find relevant files — Glob + Grep for patterns related to the task: - Search for keywords from the task description - Look at directory structure to understand architecture - Identify files that will need modification

c. Precedent retrieval (context graph pattern — search past solutions BEFORE planning): - Search past sessions (if MCP available):

        session_search(query="{task description keywords}")
        

        kb_search(query="{task type}: {keywords}")
        

d. Search code across projects (if MCP available):

      project_code_search(query="{relevant pattern}")
      

e. Check dependencies of affected files (if MCP available):

      codegraph_query(query="MATCH (f:File {path: '{file}'})-[:IMPORTS]->(dep) RETURN dep.path")
      

f. Read existing tests in the affected area — understand testing patterns used.

g. Read CLAUDE.md architecture constraints — understand boundaries and conventions. - Check for harness section: module boundaries, data validation rules, lint configs. - Read docs/ARCHITECTURE.md and docs/QUALITY_SCORE.md if they exist.

h. Detect deploy infrastructure — search for deploy scripts/configs to include deploy phase in plan:

      find . -maxdepth 3 \( -name 'deploy.sh' -o -name 'Dockerfile' -o -name 'docker-compose.yml' -o -name 'fly.toml' -o -name 'wrangler.toml' \) -type f 2>/dev/null
      

5. Generate track ID: - Extract a short name (2-3 words, kebab-case) from task description. - Format: {shortname}_{YYYYMMDD} (e.g., user-auth_20260209).

6. Create track directory:

   mkdir -p $PLAN_ROOT
   

7. Generate $PLAN_ROOT/spec.md: Based on research findings, NOT generic questions.

   # Specification: {Title}
   Track ID: {trackId}
   Type: {Feature|Bug|Refactor|Chore}
   Created: {YYYY-MM-DD}
   Status: Draft
   ## Summary
   {1-2 paragraph description based on research}
   ## Acceptance Criteria
   - [ ] {concrete, testable criterion}
   - [ ] {concrete, testable criterion}
   {3-8 criteria based on research findings}
   ## Dependencies
   - {external deps, packages, other tracks}
   ## Out of Scope
   - {what this track does NOT cover}
   ## Technical Notes
   - {architecture decisions from research}
   - {relevant patterns found in codebase}
   - {reusable code from other projects}
   

8. Generate $PLAN_ROOT/plan.md: Concrete, file-level plan from research. Keep it tight: 2-4 phases, 5-15 tasks total.

Critical format rules (parsed by /build): - Phase headers: ## Phase N: Name - Tasks: - [ ] Task N.Y: Description (with period or detailed text) - Subtasks: indented - [ ] Subtask description - All tasks use [ ] (unchecked), [~] (in progress), [x] (done)

   # Implementation Plan: {Title}
   Track ID: {trackId}
   Spec: spec.md
   Created: {YYYY-MM-DD}
   Status: [ ] Not Started
   ## Overview
   {1-2 sentences on approach}
   ## Phase 1: {Name}
   {brief description of phase goal}
   ### Tasks
   - [ ] Task 1.1: {description with concrete file paths}
   - [ ] Task 1.2: {description}
   ### Verification
   - [ ] {what to check after this phase}
   ## Phase 2: {Name}
   ### Tasks
   - [ ] Task 2.1: {description}
   - [ ] Task 2.2: {description}
   ### Verification
   - [ ] {verification steps}
   {2-4 phases total}
   ## Phase {N-1}: Deploy (if deploy infrastructure exists)
   _Include this phase ONLY if the project has deploy scripts/configs (deploy.sh, Dockerfile, docker-compose.yml, fly.toml, wrangler.toml, vercel.json). Skip if no deploy infra found._
   ### Tasks
   - [ ] Task {N-1}.1: {concrete deploy step — e.g. "Run python/deploy.sh to push Docker image to VPS", "wrangler deploy", etc.}
   - [ ] Task {N-1}.2: Verify deployment — health check, logs, HTTP status
   ### Verification
   - [ ] Service is live and healthy
   - [ ] No runtime errors in production logs
   ## Phase {N}: Docs & Cleanup
   ### Tasks
   - [ ] Task {N}.1: Update CLAUDE.md with any new commands, architecture changes, or key files
   - [ ] Task {N}.2: Update README.md if public API or setup steps changed
   - [ ] Task {N}.3: Remove dead code — unused imports, orphaned files, stale exports
   ### Verification
   - [ ] CLAUDE.md reflects current project state
   - [ ] Linter clean, tests pass
   ## Final Verification
   - [ ] All acceptance criteria from spec met
   - [ ] Tests pass
   - [ ] Linter clean
   - [ ] Build succeeds
   - [ ] Documentation up to date
   ---
   _Generated by /plan. Tasks marked [~] in progress and [x] complete by /build._
   

Plan quality rules: - Every task mentions specific file paths (from research). - Tasks are atomic — one commit each. - Phases are independently verifiable. - Total: 5-15 tasks (not 70). - Last phase is always "Docs & Cleanup". - Harness-aware: if the task introduces new patterns, include a task to update lint rules or CLAUDE.md constraints. If it touches module boundaries, include verification of dependency direction. Think: "what harness change prevents future agents from breaking this?"

9. Create progress task list for pipeline visibility:

After writing plan.md, create TaskCreate entries so progress is trackable: - One task per phase: "Phase 1: {name}" with task list as description. - This gives the user and pipeline real-time visibility into what's planned. - /build will update these tasks as it works through them.

If superpowers:writing-plans skill is available, follow its granularity format: bite-sized tasks (2-5 minutes each), complete code in task descriptions, exact file paths, verification steps per task. This enhances the built-in format above.

10. Show plan for approval via AskUserQuestion: Present the spec summary + plan overview. Options: - "Approve and start" — ready for /build - "Edit plan" — user wants to modify before implementing - "Cancel" — discard the track

If "Edit plan": tell user to edit $PLAN_ROOT/plan.md manually, then run /build.

Output

Track created: {trackId}
  Type:   {Feature|Bug|Refactor|Chore}
  Phases: {N}
  Tasks:  {N}
  Spec:   $PLAN_ROOT/spec.md
  Plan:   $PLAN_ROOT/plan.md
Research findings:
  - {key finding 1}
  - {key finding 2}
  - {reusable code found, if any}
Next: /build {trackId}

Rationalizations Catalog

These thoughts mean STOP — you're skipping research:

| Thought | Reality | |---------|---------| | "I know this codebase" | You know what you've seen. Search for what you haven't. | | "The plan is obvious" | Obvious plans miss edge cases. Research first. | | "Let me just start coding" | 10 minutes of research prevents 2 hours of rework. | | "This is a small feature" | Small features touch many files. Map the blast radius. | | "I'll figure it out as I go" | That's not a plan. Write the file paths first. | | "70 tasks should cover it" | 5-15 tasks. If you need more, split into tracks. |

Compatibility Notes

Common Issues

Plan has too many tasks

Context detection wrong (project vs KB)

Research phase finds no relevant code