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)

session_search(query) — find similar past work in Claude Code chat history project_code_search(query, project) — find reusable code across projects codegraph_query(query) — check dependencies of affected files codegraph_explain(project) — architecture overview: stack, languages, directory layers, key patterns, top dependencies, hub files kb_search(query) — search knowledge base for relevant methodology If MCP tools are not available, fall back to Glob + Grep + Read.

Steps

• 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.
• 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.
• 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
• 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
• 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}")
• Gives you: stack, languages, directory layers, key patterns, top dependencies, hub files.
• 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}")
• Look for: how similar tasks were solved, what went wrong, what patterns worked.
• Search KB for relevant methodology:
• kb_search(query="{task type}: {keywords}")
• Check for: harness patterns, architectural constraints, quality scores.
• 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
• If found, read them to understand deploy targets. Include a deploy phase in the plan with concrete commands.
• Generate track ID:
• Extract a short name (2-3 words, kebab-case) from task description.
• Format: {shortname}_{YYYYMMDD} (e.g., user-auth_20260209).
• Create track directory:
• mkdir -p $PLAN_ROOT
• Project context: docs/plan/{trackId}/
• KB context: docs/plan/{shortname}/
• 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}
• 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](./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?"
• 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.
• 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: ThoughtReality"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

Plan format must match what /build parses: ## Phase N:, - [ ] Task N.Y:. /build reads docs/workflow.md for TDD policy and commit strategy (if exists). If docs/workflow.md missing, /build uses sensible defaults (moderate TDD, conventional commits).

Plan has too many tasks

Cause: Feature scope too broad or tasks not atomic enough. Fix: Target 5-15 tasks across 2-4 phases. Split large features into multiple tracks.

Context detection wrong (project vs KB)

Cause: Directory has both code manifests and KB-style directories. Fix: Project context takes priority if package.json/pyproject.toml exists.

Research phase finds no relevant code

Cause: New project with minimal codebase or MCP tools unavailable. Fix: Skill falls back to Glob + Grep. For new projects, the plan will rely more on CLAUDE.md architecture and stack conventions.