solo-plan
Skill18 starsChanged 4 months agoMITView on GitHub
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).
In this repository62 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- solo-android-releaseSkill
- solo-apple-app-iconSkill
- solo-auditSkill
- solo-boardSkill
- solo-buildSkill
- solo-community-outreachSkill
- solo-content-genSkill
- solo-creator-growthSkill
- solo-customer-finderSkill
- solo-deep-researchSkill
- solo-deploySkill
- solo-diagnoseSkill
- solo-domainSkill
- solo-factorySkill
- solo-github-outreachSkill
- solo-gmail-cliSkill
- solo-grillSkill
- solo-hackathonSkill
- solo-humanizeSkill
- solo-i18nSkill
- solo-index-youtubeSkill
- solo-initSkill
- solo-ios-devSkill
- solo-ios-releaseSkill
- solo-kaggle-gpuSkill
- solo-kindleSkill
- solo-knowledgeSkill
- solo-landing-genSkill
- solo-launchSkill
- solo-legalSkill
- solo-memory-auditSkill
- solo-metrics-trackSkill
- solo-mirrorSkill
- solo-model-shrinkSkill
- solo-music-reels-cutSkill
- solo-open-datasetSkill
- solo-paperSkill
- solo-pdf-printSkill
- solo-pipelineSkill
- solo-redditSkill
- solo-researchSkill
- solo-retroSkill
- solo-reviewSkill
- solo-scaffoldSkill
- solo-secretsSkill
- solo-seo-auditSkill
- solo-seo-cliSkill
- solo-setupSkill
- solo-sgrSkill
- solo-skill-auditSkill
- solo-skill-shelfSkill
- solo-stem-splitSkill
- solo-streamSkill
- solo-supervoxSkill
- solo-swiftui-design-systemSkill
- solo-transcribeSkill
- solo-validateSkill
- solo-video-editSkill
- solo-video-promoSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. About 0 are common, 15 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
If MCP tools are not available, fall back to Glob + Grep + Read.
- Distinctive: line 37
If empty, ask via AskUserQuestion: "What feature, bug, or refactor do you want to plan?"
- Distinctive: line 74
Search for keywords from the task description
- Distinctive: line 75
Look at directory structure to understand architecture
- Distinctive: line 79
Search past sessions (if MCP available):
- Distinctive: line 83
Look for: how similar tasks were solved, what went wrong, what patterns worked.
- Distinctive: line 84
Search KB for relevant methodology:
- Distinctive: line 88
Check for: harness patterns, architectural constraints, quality scores.
- Distinctive: line 101
Check for harness section: module boundaries, data validation rules, lint configs.
- Very specific: line 102
Read docs/ARCHITECTURE.md and docs/QUALITY_SCORE.md if they exist.
- Distinctive: line 108
If found, read them to understand deploy targets.
- Very specific: line 117
Read its spec.md Summary and Acceptance Criteria
- Distinctive: line 119
Check if tasks overlap (>50% of files or acceptance criteria in common)
- Very specific: line 122
If existing plan is incomplete ([ ] tasks remain): recommend extending it instead of creating a new track.
- Very specific: line 123
If existing plan is complete ([x] all tasks): proceed with new track but reference the prior track in spec.md Dependencies
- Distinctive: line 124
If multiple existing plans overlap with each other: recommend consolidating them into one track before proceeding
- Very specific: line 176
All tasks use [ ] (unchecked), [~] (in progress), [x] (done)
- Distinctive: line 257
Every task mentions specific file paths (from research).
- Distinctive: line 263
Harness-aware: if the task introduces new patterns, include a task to update lint rules or CLAUDE.md constraints.
- Distinctive: line 267
After writing plan.md, create TaskCreate entries so progress is trackable:
- Very specific: line 272
If superpowers:writing-plans skill is available, follow its granularity format: bite-sized tasks (2-5 minutes each), complete code in task …
- Very specific: line 280
If "Edit plan": tell user to edit $PLAN_ROOT/plan.md manually, then run /build.
- Very specific: line 318
If docs/workflow.md missing, /build uses sensible defaults (moderate TDD, conventional commits).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

