asteroid-belt-llc/superplan

Superplan: Comprehensive Feature Planning

Overview

Superplan creates detailed, executable implementation plans that enable parallel agent execution. Each plan includes everything needed to implement a feature: requirements, architecture, code changes, tests, and acceptance criteria.

When to Use Superplan

• Starting a new feature or epic
• Complex tasks requiring multiple phases
• Tasks that could benefit from parallel execution by multiple agents
• When you need comprehensive documentation of implementation decisions

Core Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                         SUPERPLAN WORKFLOW                          │
├─────────────────────────────────────────────────────────────────────┤
│  1. INTAKE          →  Gather story/requirements from user          │
│  2. DETECT          →  Check CLAUDE.md/AGENTS.md, then scan         │
│  3. INTERVIEW       →  Ask clarifying questions                     │
│  4. RESEARCH        →  Look up best practices (BYPASS if docs OK)   │
│  5. EXPLORE         →  Understand existing codebase patterns        │
│  6. REFACTOR ASSESS →  Evaluate if refactoring should precede work  │
│  7. ARCHITECT       →  Design solution with diagrams                │
│  8. PHASE           →  Break into parallelizable phases + ESTIMATES │
│  9. DETAIL          →  Specify code deltas per phase                │
│ 10. TEST            →  Define failing tests per phase (TDD)         │
│ 11. DOCUMENT        →  Write plan to plans/NNN-feature/plan.md │
└─────────────────────────────────────────────────────────────────────┘

---

Reference Index - MUST READ Before Each Phase

References are loaded on demand. Read BEFORE starting the relevant phase.

| When | Reference | What You Get | |------|-----------|--------------| | Before ANY parallel operation | Sub-Agent Syntax | Exact prompts for launching parallel agents | | Phase 3: Interview | Interview Guide | Question templates by feature size | | Phase 5: Explore | Explore Prompts | Exact prompts for codebase exploration agents | | Phase 6: Refactor | Refactoring Research | Mikado, Strangler Fig, Branch by Abstraction | | Phase 7: Architect | Architecture Templates | API, data model, component tree templates | | Phase 9: Detail | Task Micro-Structure | 5-step TDD format for each task | | Phase 10: Test | TDD Discipline | TDD rules, rationalizations, red flags | | Phase 10: Test | Testing Pyramid | Unit/integration/E2E examples | | Phase 10: Test | Command Outputs | Expected test output format | | Phase 11: Document | Plan Template | Complete plan file structure |

DO NOT SKIP REFERENCES. They contain exact prompts, templates, and formats that are NOT duplicated here.

---

CRITICAL: Parallel Execution with Sub-Agents

YOU MUST USE SUB-AGENTS for parallelizable operations.

STOP. Read Sub-Agent Syntax NOW before launching any parallel operation.

| Operation | Action | |-----------|--------| | Independent file reads | Multiple Read tasks in single message | | Code searches | Parallel Explore agents | | Parallel phases (1A, 1B, 1C) | Parallel general-purpose agents |

---

Poker Planning Estimates

All phases MUST include Fibonacci estimates: 1, 2, 3, 5, 8, 13, 21

| Size | Meaning | Example | |------|---------|---------| | 1 | Trivial | Config value, typo fix | | 2 | Small | Single file, simple function | | 3 | Medium | Multi-file, new component | | 5 | Large | Feature module, API endpoint | | 8 | X-Large | Complex feature with dependencies | | 13 | Epic chunk | Major subsystem change | | 21 | Too big | Split into smaller tasks |

---

Phase 1: INTAKE - Gather Requirements

Ask the user to provide their story/requirements:

• Copy/paste story text directly
• Provide a link to a ticket (Jira, Linear, GitHub Issue)
• Use an MCP tool to fetch the story
• Describe the feature verbally

Output: Source, Type (User Story/Technical Task/Bug Fix/Epic), Raw Requirements, Initial Understanding.

---

Phase 2: DETECT - Technology Stack Analysis

Step 1: Check for CLAUDE.md or AGENTS.md

If found AND complete (all boxes checked), BYPASS codebase scan AND Phase 4 Research.

Completeness checklist:

• [ ] Primary language(s) identified
• [ ] Major framework(s) identified
• [ ] Build/package tools identified
• [ ] Quality tools identified (linter, formatter, type checker)
• [ ] Test framework identified

Step 2: Detection (if needed)

Launch parallel Explore agents to detect: Languages, Frameworks, Build Tools, Quality Tools, Testing Tools.

Output: Tech stack summary, bootstrap requirements, research bypass status.

---

Phase 3: INTERVIEW - Clarifying Questions

Ask 3-5 questions, then WAIT FOR ANSWERS.

Required Questions:

1. "What is the MVP? What can we defer to v2?"
2. "What is explicitly OUT of scope?"
3. "Are there performance/security requirements?"
4. "What test coverage do you expect?"

STOP. Read Interview Guide NOW for question templates before asking.

---

Phase 4: RESEARCH - Best Practices Lookup

BYPASS if DETECT found complete tech stack in CLAUDE.md/AGENTS.md.

Otherwise, launch parallel web searches:

• [Language] [YEAR] best practices
• [Framework] [YEAR] patterns
• [Framework] security guidelines

Output: Sources consulted, key findings, specific recommendations.

---

Phase 5: EXPLORE - Codebase Analysis

STOP. Read Explore Prompts NOW for exact agent prompts before launching.

Launch 3 parallel Explore agents:

1. Pattern Discovery - Find similar implementations
2. Integration Points - Identify files to modify
3. Technical Debt Scan - Check for issues in affected areas

Output: Similar implementations table, integration points table, technical debt table.

---

Phase 6: REFACTOR/REWRITE ASSESSMENT

Evaluate if refactoring should precede feature work.

STOP. Read Refactoring Research NOW for methodologies before assessing.

Confidence Levels

| Level | Description | Action | |-------|-------------|--------| | LOW | Code is clean | Proceed to ARCHITECT | | MEDIUM | Some smells present | Note debt, ask user preference | | HIGH | Significant issues | Recommend refactor phases | | CRITICAL | Major rewrite needed | Propose Mikado/Strangler Fig |

If HIGH or CRITICAL, ask permission to add refactoring phases.

---

Phase 7: ARCHITECT - Solution Design

STOP. Read Architecture Templates NOW for templates before designing.

For each component, answer:

• [ ] What new components are being added?
• [ ] How do they connect to existing components?
• [ ] What is the data flow?

Required outputs:

• System context diagram
• API design (if applicable) with all response codes
• Data model (if applicable) with migration scripts
• Component tree (if UI)

---

Phase 8: PHASE - Parallel Work Breakdown

Break work into phases with poker estimates that can be executed in parallel.

Phase Design Principles

1. Independence: Phases executable without waiting for others
2. Testability: Each phase independently testable
3. Estimated Size: Target 3-8 points per phase
4. Quality Gated: Each phase includes Definition of Done
5. Context Managed: Each phase ends with a CHECKPOINT for compaction

CHECKPOINT: Context Compaction Between Phases

EVERY phase MUST end with a CHECKPOINT instruction. This enables /superbuild to run /compact automatically in BUILD-ALL mode, preserving context across long implementations.

CHECKPOINT Format

- [ ] **CHECKPOINT: Run `/compact focus on: [Phase N] complete, [key artifacts], [Phase N+1] goals`**

CHECKPOINT Focus Points

The focus directive tells /compact what to preserve:

• Completed work: What was built, key decisions made
• Key artifacts: File paths, API contracts, data models created
• Next phase goals: What the upcoming phase needs to accomplish
• Blockers/dependencies: Any issues that affect future phases

Example Phase with CHECKPOINT

## Phase 1: Authentication System
- [ ] Task 1.1: Create auth models in `src/models/auth.ts`
- [ ] Task 1.2: Implement JWT handling in `src/services/jwt.ts`
- [ ] Task 1.3: Add auth middleware in `src/middleware/auth.ts`
- [ ] **CHECKPOINT: Run `/compact focus on: Phase 1 complete, auth models and JWT service created, Phase 2 needs API endpoints`**

## Phase 2: API Endpoints
- [ ] Task 2.1: Create `/api/auth/login` endpoint
...

Output: Phase dependency diagram + table with estimates:

| Phase | Name | Depends On | Parallel With | Estimate | Status | |-------|------|------------|---------------|----------|--------|

---

Phase 9: DETAIL - Code Deltas Per Phase

STOP. Read Task Micro-Structure NOW for 5-step TDD format before detailing tasks.

Code Delta Format

• path/to/file.ts (CREATE) - new file with full content
• path/to/file.ts:45-67 (MODIFY) - existing file with line range and diff

NEVER use pseudocode, // ... rest of file, or vague descriptions.

---

Phase 10: TEST - TDD Acceptance Criteria

STOP. Read Command Outputs NOW for expected output format before writing tests.

Testing Pyramid

• Unit Tests (80%): Business logic, utilities
• Integration Tests (15%): API contracts, database
• E2E Tests (5%): Critical user journeys only

Test-First Workflow

For each task:

1. Write test (will fail)
2. Run test, confirm failure with expected output
3. Implement code
4. Run test, confirm pass with expected output
5. All existing tests still pass

Also read Testing Pyramid for unit/integration/E2E examples.

---

Definition of Done - REQUIRED PER PHASE

Every phase MUST include this checklist:

### Definition of Done
- [ ] Code passes linter
- [ ] Code passes formatter
- [ ] Code passes type checker
- [ ] All new tests pass
- [ ] All existing tests pass
- [ ] Test coverage >= 80% for new code
- [ ] No new warnings introduced

---

Phase Completion: Conventional Commit Message

At the end of EVERY phase, output (but do not commit):

PHASE [X] COMPLETE - Conventional Commit Message:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

<type>(<scope>): <short summary>

<body - detailed description>

Files changed:
- path/to/file.ts (CREATE/MODIFY/DELETE)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  DO NOT COMMIT - User will handle git operations

---

Phase 11: DOCUMENT - Write the Plan

Directory Naming Convention

Plans live in numbered subdirectories under plans/:

plans/
  001-auth-system/
    plan.md
  002-user-dashboard/
    plan.md
  003-api-caching/
    plan-1.md        # Large plan split across files
    plan-2.md

To determine the next number:

1. List existing directories in plans/
2. Find the highest NNN prefix
3. Increment by 1, zero-padded to 3 digits
4. If no plans/ exists, start at 001

Slug format: lowercase, hyphen-separated short name (e.g., 001-auth-system, 002-add-search)

Write the Plan

mkdir -p plans/NNN-feature-short-name/

Write the complete plan to plans/NNN-feature-short-name/plan.md.

STOP. Read Plan Template NOW for complete structure before writing.

Execution Handoff

After saving, present options:

PLAN COMPLETE: plans/NNN-feature-short-name/plan.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXECUTION OPTIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Option 1: Execute Now (This Session)
  Run `/superbuild plans/NNN-feature-short-name/plan.md`

Option 2: Execute in Fresh Session
  Start new session and run `/superbuild plans/NNN-feature-short-name/plan.md`

Option 3: Review First
  Read through the plan, suggest modifications, then execute

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Which option would you like?

Multi-File Strategy

If plan exceeds ~4,000 lines, split into files within the same directory:

• plan-1.md: Overview, Requirements, Architecture
• plan-2.md: Implementation Phases
• plan-N.md: Remaining phases, Appendix

---

Quick Reference

See Reference Index at top of this document for when to read each reference.

| Phase | Key Action | Must Read Before Starting | |-------|------------|---------------------------| | 1-2 | Gather requirements, detect stack | - | | 3 | Interview (WAIT for answers) | Interview Guide | | 4 | Research (if needed) | - | | 5 | Explore codebase | Explore Prompts | | 6 | Refactor assessment | Refactoring Research | | 7 | Architecture design | Architecture Templates | | 8-9 | Phase breakdown + code deltas | Task Micro-Structure | | 10 | TDD tests | TDD Discipline, Testing Pyramid, Command Outputs | | 11 | Write plan + handoff | Plan Template | | ANY | Parallel operations | Sub-Agent Syntax |