superplan

What this skill does

# 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
- When the team needs to understand the full scope before committing

## Core Workflow

```
┌─────────────────────────────────────────────────────────────────────┐
│                         SUPERPLAN WORKFLOW                          │
├─────────────────────────────────────────────────────────────────────┤
│  1. INTAKE          →  Gather story/requirements from user          │
│  2. DETECT          →  Check CLAUDE.md/AGENTS.md first, then scan   │
│                        (BYPASS codebase scan if docs complete)      │
│  3. INTERVIEW       →  Ask clarifying questions                     │
│  4. RESEARCH        →  Look up best practices for DETECTED STACK    │
│                        (BYPASS if CLAUDE.md/AGENTS.md was complete) │
│  5. EXPLORE         →  Understand existing codebase patterns        │
│                        (ALWAYS runs - never bypassed)               │
│  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/<feature>-plan.md         │
└─────────────────────────────────────────────────────────────────────┘
```

---

## CRITICAL: Parallel Execution with Sub-Agents

**YOU MUST USE SUB-AGENTS OR PARALLEL TASKS** for every parallelizable operation:

| Operation | How to Execute |
|-----------|---------------|
| Independent file reads | Launch multiple Read tasks in single message |
| Code searches | Use Task tool with multiple Explore agents in parallel |
| Parallel phases (1A, 1B, 1C) | Execute using parallel sub-agents |
| Independent test suites | Run unit/integration/e2e concurrently |

**Example**: "Launch 3 sub-agents in parallel to implement Phases 1A, 1B, and 1C"

**IMPORTANT**: Each sub-agent MUST return its conventional commit message upon completion. The main agent MUST output all commit messages to the user. See [Phase Completion: Conventional Commit Message](#phase-completion-conventional-commit-message---required-per-phase).

---

## Poker Planning Estimates

All tasks and 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

### What You're Doing
Collecting the feature requirements from the user through story input.

### Actions

1. **Ask the user to provide their story/requirements** using one of these methods:
   - Copy/paste the story text directly
   - Provide a link to a ticket/story (Jira, Linear, GitHub Issue, etc.)
   - Use an MCP tool to fetch the story if available
   - Describe the feature verbally

2. **Capture the raw input** exactly as provided

3. **Identify the story type**:
   - User Story (`As a <role>, I want <capability>, so that <benefit>`)
   - Technical Task (implementation-focused)
   - Bug Fix (problem/solution)
   - Epic (large feature with sub-stories)

### Output
Document: Source, Type, Raw Requirements, Initial Understanding (1-2 sentences).

---

## Phase 2: DETECT - Technology Stack Analysis

### What You're Doing
Identifying the technology, programming language, and major frameworks to inform best practices research and quality gate setup.

### Detection Flow

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         DETECT PHASE FLOW                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│  1. CHECK for CLAUDE.md or AGENTS.md in project root                        │
│     ├─ Found & Complete? → BYPASS codebase scanning for tech stack          │
│     │                   → BYPASS internet research (Phase 4)                │
│     │                   → Proceed directly to INTERVIEW (Phase 3)           │
│     └─ Not Found or Incomplete? → Continue with Detection Actions below     │
│                                                                             │
│  NOTE: This does NOT bypass EXPLORE phase (Phase 5) - always scan codebase  │
│        for patterns and integration points regardless of CLAUDE.md presence │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Step 1: Check for Project Documentation Files

**FIRST**, check for `CLAUDE.md` or `AGENTS.md` at project root:

```bash
# Check for these files (in priority order):
1. CLAUDE.md   # Claude Code's project documentation
2. AGENTS.md   # Codex's project documentation
```

**If found**, parse for these tech stack elements:

| Element | What to Look For |
|---------|-----------------|
| Languages | "TypeScript", "Python", "Go", etc. in project description |
| Frameworks | Framework mentions: React, Next.js, FastAPI, Django, etc. |
| Build Tools | Package manager, bundler references: npm, pnpm, vite, etc. |
| Quality Tools | Linter/formatter/type checker config mentions |
| Testing Tools | Test framework references: jest, pytest, vitest, etc. |
| Dependencies | Key libraries and their versions |

### Completeness Check

A project documentation file is **COMPLETE** for tech stack if it answers ALL of:

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

**If ALL boxes can be checked from the file** → Skip to Step 3 (output) and mark RESEARCH phase (Phase 4) as BYPASSED

**If ANY box is missing** → Continue with Step 2 (codebase detection)

### Step 2: Detection Actions (USE PARALLEL SUB-AGENTS)

**Only execute if CLAUDE.md/AGENTS.md is missing or incomplete.**

Launch **parallel Explore agents** to detect:

1. **Languages** - Primary language(s): TypeScript, Python, Go, Rust, Java, etc.
2. **Frameworks** - Major frameworks: React, Next.js, FastAPI, Django, Express, etc.
3. **Build Tools** - Package managers, bundlers: npm, pnpm, yarn, webpack, vite, etc.
4. **Quality Tools** - Existing linters, formatters, type checkers:
   - Linters: eslint, ruff, golint, pylint
   - Formatters: prettier, black, gofmt, rustfmt
   - Type checkers: tsc (TypeScript), mypy (Python), go vet
5. **Testing Tools** - Test frameworks: jest, pytest, go test, vitest, playwright

### Quality Tools Assessment

| Tool Type | If Present | If Missing |
|-----------|------------|------------|
| Linter | Note config path | Add to Phase 0 Bootstrap |
| Formatter | Note config path | Add to Phase 0 Bootstrap |
| Type Checker | Note config path | Add to Phase 0 Bootstrap |
| Test Framework | Note config path | Add to Phase 0 Bootstrap |

### Step 3: Output

Document:
- **Source**: CLAUDE.md/AGENTS.md or codebase scan
- **Languages**, frameworks, build tools, quality tools (present/missing), testing setup
- **Bootstrap requirements**
- **Research bypass status**: If CLAUDE.md/AGENTS.md provided complete info, note "RESEARCH PHASE BYPASSED - tech stack from