solo-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

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.

1. Detect context — determine where plan files should be stored: Project context (normal project with code): Knowledge base context (documentation-centric project): Set $PLAN_ROOT based on detected context. All subsequent file paths use $PLAN_ROOT.

- Detected by: package.json, pyproject.toml, Cargo.toml, *.xcodeproj, or build.gradle.kts exists in working directory - Plan path: docs/plan/{trackId}/ - 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)

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

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

1. 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. Get RepoMap (if MCP available): codegraph_repomap(project="{project name from CLAUDE.md or directory name}") Gives you a YAML map of the most important files and their exported symbols (classes/functions). c. Find relevant files — Glob + Grep for patterns related to the task: d. Precedent retrieval (context graph pattern — search past solutions BEFORE planning): e. Search code across projects (if MCP available): project_code_search(query="{relevant pattern}") f. Check dependencies of affected files (if MCP available): codegraph_query(query="MATCH (f:File {path: '{file}'})-[:IMPORTS]->(dep) RETURN dep.path") g. Read existing tests in the affected area — understand testing patterns used. h. Read CLAUDE.md architecture constraints — understand boundaries and conventions. i. 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 'wrangler.toml' -o -name 'sst.config.ts' \) -type f 2>/dev/null If found, read them to understand deploy targets. Include a deploy phase in the plan with concrete commands.

- Search for keywords from the task description - Look at directory structure to understand architecture - Identify files that will need modification - 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. - Check for harness section: module boundaries, data validation rules, lint configs. - Read docs/ARCHITECTURE.md and docs/QUALITY_SCORE.md if they exist.

1. Detect overlapping plans — before creating a new track, check for existing plans that cover similar scope: ls docs/plan/*/plan.md docs/plan/*/spec.md 2>/dev/null For each existing plan found: If overlap detected: If no overlap: proceed normally.

- Read its spec.md Summary and Acceptance Criteria - Compare scope with the new task description - Check if tasks overlap (>50% of files or acceptance criteria in common) - If existing plan is incomplete ([] tasks remain): recommend extending it instead of creating a new track. Show the user: "Existing track {trackId} covers similar scope ({overlap description}). Extend it or create a separate track?" - If existing plan is complete ([x] all tasks): proceed with new track but reference the prior track in spec.md Dependencies - If multiple existing plans overlap with each other: recommend consolidating them into one track before proceeding

1. Generate track ID:

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

1. Create track directory: mkdir -p $PLAN_ROOT

- Project context: docs/plan/{trackId}/ - KB context: docs/plan/{shortname}/

1. 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}
2. 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): # 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, wrangler.toml, sst.config.ts, 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 ## Context Handoff _Summary for /build to load at session start — keeps context compact._ ### Session Intent {1 sentence: what this track accomplishes} ### Key Files {list of files that will be modified, from research} ### Decisions Made {key architecture decisions from research phase — why X over Y} ### Risks {known risks or edge cases discovered during research} --- _Generated by /plan. Tasks marked [~] in progress and [x] complete by /build._ Plan quality rules:

- 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) - 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". - Criteria-task coverage: every acceptance criterion in spec.md MUST map to at least one task in plan.md. After generating both files, cross-check: list each criterion and verify a task addresses it. If a criterion has no corresponding task — add one. Uncovered criteria are the #1 cause of "plan complete but spec not met" failures. - 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?"

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

1. 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:

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

Common Issues

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.