/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

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

4. 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

5. 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.