solo-plan
Use when "plan this feature", "create implementation plan", "write a spec", "battle plan", describing a feature/bug/refactor, or need task breakdown before building. Do NOT use for idea validation (/validate) or execution (/build).
How do I install this agent skill?
npx skills add https://github.com/fortunto2/solo-factory --skill solo-planIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a planning tool designed to analyze codebases and generate implementation plans. It is functionally safe, but like many skills that process user-defined task descriptions, it presents a surface for indirect prompt injection where malicious inputs could influence the generated plans.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1/1 file flagged
What does this agent skill do?
/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 historysymbol_search("<words>")— find reusable code across projects (symbol names, every project; Grep inside one)- Grep — imports and callers of the files you will change
project_info(name)— architecture overview: stack, languages, directory layers, key patterns, top dependencies, files with the most definitionskb_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, orbuild.gradle.ktsexists 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_ROOTbased on detected context. All subsequent file paths use$PLAN_ROOT. - Detected by:
-
Load project context (parallel reads):
CLAUDE.md— architecture, constraints, Do/Don'tdocs/prd.md— what the product does (if exists)docs/workflow.md— TDD policy, commit strategy (if exists)package.jsonorpyproject.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
- Contains "fix", "bug", "broken", "error", "crash" →
-
Research phase — explore the codebase to understand what needs to change:
a. Get architecture overview (if MCP available — do this FIRST):
project_info(name="{project name from CLAUDE.md or directory name}")Gives you: stack, languages, directory layers, key patterns, top dependencies, files with the most definitions.
c. 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
d. Precedent retrieval (context graph pattern — search past solutions BEFORE planning):
- Search past sessions (if MCP available):
Look for: how similar tasks were solved, what went wrong, what patterns worked.session_search(query="{task description keywords}") - Search KB for relevant methodology:
Check for: harness patterns, architectural constraints, quality scores.kb_search(query="{task type}: {keywords}")
e. Search code across projects (if MCP available):
symbol_search("<words>")f. Check dependencies of affected files — Grep their imports, and Grep for the module name to find who imports them.
g. Read existing tests in the affected area — understand testing patterns used.
h. Read CLAUDE.md architecture constraints — understand boundaries and conventions.
- Check for harness section: module boundaries, data validation rules, lint configs.
- Read
docs/ARCHITECTURE.mdanddocs/QUALITY_SCORE.mdif they exist.
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/nullIf found, read them to understand deploy targets. Include a deploy phase in the plan with concrete commands.
-
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/nullFor each existing plan found:
- Read its
spec.mdSummary and Acceptance Criteria - Compare scope with the new task description
- Check if tasks overlap (>50% of files or acceptance criteria in common)
If overlap detected:
- 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
If no overlap: proceed normally.
- Read its
-
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}/
- Project context:
-
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, 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:
- 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?"
- Phase headers:
-
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.
/buildwill 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:
| 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
/buildparses:## Phase N:,- [ ] Task N.Y:. /buildreadsdocs/workflow.mdfor TDD policy and commit strategy (if exists).- If
docs/workflow.mdmissing,/builduses 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/fortunto2/solo-factory/solo-plan">View solo-plan on skillZs</a>