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 docs/superplan/YYYY-mm-dd-feature-short-name/plan.md │
└─────────────────────────────────────────────────────────────────────┘

Reference Index - MUST READ Before Each Phase

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

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.

Poker Planning Estimates

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

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

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 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 date-stamped feature directories under docs/superplan/:

docs/superplan/
  YYYY-mm-dd-auth-system/
    plan.md
  YYYY-mm-dd-user-dashboard/
    plan.md
  YYYY-mm-dd-api-caching/
    plan-1.md        # Large plan split across files
    plan-2.md

Use the current date for YYYY-mm-dd, followed by a lowercase, hyphen-separated feature slug (for example, 2026-09-06-auth-system). If a directory for the same date and slug already exists, choose a more specific slug; do not add a numeric sequence.

Write the Plan

mkdir -p docs/superplan/YYYY-mm-dd-feature-short-name/

Write the complete plan to docs/superplan/YYYY-mm-dd-feature-short-name/plan.md.

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

Execution Handoff

After saving, present options:

PLAN COMPLETE: docs/superplan/YYYY-mm-dd-feature-short-name/plan.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXECUTION OPTIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Option 1: Execute Now (This Session)
  Run `/superbuild docs/superplan/YYYY-mm-dd-feature-short-name/plan.md`

Option 2: Execute in Fresh Session
  Start new session and run `/superbuild docs/superplan/YYYY-mm-dd-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.