agentleFS
fortunto2fortunto2/solo-factory/skills/plan/SKILL.md

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

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

    If MCP tools are not available, fall back to Glob + Grep + Read.

    line 32
  2. Distinctive:

    If empty, ask via AskUserQuestion: "What feature, bug, or refactor do you want to plan?"

    line 37
  3. Distinctive:

    Search for keywords from the task description

    line 74
  4. Distinctive:

    Look at directory structure to understand architecture

    line 75
  5. Distinctive:

    Search past sessions (if MCP available):

    line 79
  6. Distinctive:

    Look for: how similar tasks were solved, what went wrong, what patterns worked.

    line 83
  7. Distinctive:

    Search KB for relevant methodology:

    line 84
  8. Distinctive:

    Check for: harness patterns, architectural constraints, quality scores.

    line 88
  9. Distinctive:

    Check for harness section: module boundaries, data validation rules, lint configs.

    line 101
  10. Very specific:

    Read docs/ARCHITECTURE.md and docs/QUALITY_SCORE.md if they exist.

    line 102
  11. Distinctive:

    If found, read them to understand deploy targets.

    line 108
  12. Very specific:

    Read its spec.md Summary and Acceptance Criteria

    line 117
  13. Distinctive:

    Check if tasks overlap (>50% of files or acceptance criteria in common)

    line 119
  14. Very specific:

    If existing plan is incomplete ([ ] tasks remain): recommend extending it instead of creating a new track.

    line 122
  15. Very specific:

    If existing plan is complete ([x] all tasks): proceed with new track but reference the prior track in spec.md Dependencies

    line 123
  16. Distinctive:

    If multiple existing plans overlap with each other: recommend consolidating them into one track before proceeding

    line 124
  17. Very specific:

    All tasks use [ ] (unchecked), [~] (in progress), [x] (done)

    line 176
  18. Distinctive:

    Every task mentions specific file paths (from research).

    line 257
  19. Distinctive:

    Harness-aware: if the task introduces new patterns, include a task to update lint rules or CLAUDE.md constraints.

    line 263
  20. Distinctive:

    After writing plan.md, create TaskCreate entries so progress is trackable:

    line 267
  21. Very specific:

    If superpowers:writing-plans skill is available, follow its granularity format: bite-sized tasks (2-5 minutes each), complete code in task …

    line 272
  22. Very specific:

    If "Edit plan": tell user to edit $PLAN_ROOT/plan.md manually, then run /build.

    line 280
  23. Very specific:

    If docs/workflow.md missing, /build uses sensible defaults (moderate TDD, conventional commits).

    line 318

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/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
  • symbol_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 definitions
  • 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):

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

    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.md and docs/QUALITY_SCORE.md if 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/null

    If found, read them to understand deploy targets. Include a deploy phase in the plan with concrete commands.

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

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

  7. Generate track ID:
    • Extract a short name (2-3 words, kebab-case) from task description.
    • Format: {shortname}_{YYYYMMDD} (e.g., user-auth_20260209).
  8. Create track directory:
    mkdir -p $PLAN_ROOT
    • Project context: docs/plan/{trackId}/
    • KB context: docs/plan/{shortname}/
  9. 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}
  10. 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?"
  11. 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:

ThoughtReality
"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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.