solo-plan

name	solo-plan
description	Explore codebase and create spec + phased implementation plan with file-level task breakdown. Use when user says "plan this feature", "create implementation plan", "write a spec", "battle plan", or describes a feature/bug/refactor. Zero questions — researches code instead. Do NOT use for idea validation (use /validate) or execution (use /build).
license	MIT
metadata	{"author":"fortunto2","version":"2.2.1","openclaw":{"emoji":"📋"}}
allowed-tools	Read, Grep, Bash, Glob, Write, Edit, AskUserQuestion, mcp__solograph__session_search, mcp__solograph__project_code_search, mcp__solograph__codegraph_query, mcp__solograph__codegraph_explain, mcp__solograph__kb_search, mcp__solograph__web_search, mcp__context7__resolve-library-id, mcp__context7__query-docs
argument-hint	<task description>

/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}")
   

• "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

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