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

1. Capture the raw input exactly as provided

1. Identify the story type:

• User Story (As a , I want , so that )
• 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:

# 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

1. 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 project documentation"

---

Phase 3: INTERVIEW - Clarifying Questions

What You're Doing

Asking targeted questions to fill gaps in requirements before planning.

Question Categories

Ask questions in these categories (select relevant ones):

1. Scope & Boundaries - MVP, out of scope, related features
2. User Experience - Primary users, user flow, mockups/designs
3. Technical Constraints - Performance, security, compliance, integrations
4. Data & State - Data sources, storage, migrations
5. Testing & Validation - Success criteria, test scenarios, sign-off
6. Dependencies - Blockers, external services, sequencing
7. Quality Gates - Existing CI/CD, required checks, coverage thresholds

How to Interview

Ask 3-5 most relevant questions, then wait for answers before proceeding.

See [Interview Guide](references/INTERVIEW-GUIDE.md) for comprehensive question templates and strategies by feature size.

---

Phase 4: RESEARCH - Best Practices Lookup

What You're Doing

Researching current best practices as of TODAY'S DATE for the DETECTED technology stack.

BYPASS Condition

If DETECT phase found complete tech stack info in CLAUDE.md or AGENTS.md, this phase is BYPASSED.

Skip directly to EXPLORE (Phase 5). The project documentation provides authoritative tech stack information.

Otherwise, proceed with research actions below.

Research Actions (USE PARALLEL WEB SEARCHES)

Launch parallel web searches targeting the detected stack:

1. [Language] [YEAR] best practices - e.g., "TypeScript 2025 best practices"
2. [Framework] [YEAR] patterns - e.g., "React 2025 patterns"
3. [Framework] security guidelines - e.g., "Next.js security OWASP"
4. [Language] testing best practices - e.g., "Python pytest 2025"

Research Areas

1. Industry Standards - Current best practices, security (OWASP), accessibility (WCAG)
2. Technology-Specific - Framework patterns, library versions, known gotchas
3. Architecture Patterns - Recommended patterns, anti-patterns, scalability
4. Quality Tool Configs - Recommended linter/formatter configs for detected stack

Output

Document: Sources consulted, key findings by topic, specific recommendations for this feature.

---

Phase 5: EXPLORE - Codebase Analysis

What You're Doing

Understanding existing patterns, conventions, and integration points in the codebase.

Exploration Targets

1. Existing Patterns - How similar features are implemented, conventions, testing patterns
2. Integration Points - Files/modules to touch, API contracts, shared utilities
3. Technical Debt - Areas needing refactoring, known issues affecting this work

Output

Document: Relevant files table, patterns to follow, integration points, technical debt notes.

---

Phase 6: REFACTOR/REWRITE ASSESSMENT

What You're Doing

Evaluating whether the feature/fix would benefit from refactoring or rewriting existing code BEFORE implementation. This phase synthesizes your research on best practices with your exploration of the codebase to make a data-driven refactoring decision.

CRITICAL: Be Bold

This phase empowers you to proactively recommend refactoring. Don't be timid—if the code needs work, say so. Use the Q&A system to discuss major refactoring opportunities with the user.

Assessment Process (USE PARALLEL WEB SEARCHES)

Step 1: Research Refactoring for Detected Stack

Launch parallel web searches for stack-specific refactoring:

• [Language] refactoring patterns 2025 - e.g., "TypeScript refactoring patterns 2025"
• [Framework] code smells - e.g., "React code smells anti-patterns"
• [Dependency] migration guide - For major dependencies that may need updating

Step 2: Apply Code Smell Detection

Using your exploration results, check for these smells in affected areas:

| Category | Smells to Check | |----------|-----------------| | Bloaters | Long methods, large classes, primitive obsession, data clumps | | OO Abusers | Switch statements on types, parallel inheritance hierarchies | | Change Preventers | Divergent change, shotgun surgery | | Dispensables | Duplicate code, dead code, speculative generality | | Couplers | Feature envy, inappropriate intimacy, message chains |

Step 3: AI Slop Analysis (Optional Enhancement)

Check if the slop-or-not skill is available to enhance refactor detection:

1. Check Availability: Attempt to invoke /slop-or-not

• If not installed, inform the user:

> "The slop-or-not skill can enhance refactor assessment by detecting > AI-generated code anti-patterns (hallucinations, cross-language contamination, > security vulnerabilities). Install from: https://github.com/asteroid-belt/skills > > Would you like to pause to install it? (y/n)"

• If user says yes: Wait for installation, then re-check
• If user says no or skill unavailable: Skip to Step 4, note "Slop analysis: SKIPPED (skill not installed)"

1. Run Slop Scan: If available, invoke /slop-or-not targeting:

• Files identified in EXPLORE phase as modification candidates
• Areas flagged with code smells in Step 2

1. Apply Reciprocal Rank Fusion: Combine modification paths with slop findings:

`` RRF_score(file) = 1/(60 + modification_rank) + 1/(60 + slop_rank) `` Files appearing in BOTH lists (need modification AND contain AI slop) score highest.

1. Output Combined Priority List: Rank refactor candidates by RRF score, noting:

• Modification necessity (from architect analysis)
• Slop confidence level (CRITICAL/HIGH/MEDIUM/LOW)
• Specific anti-patterns detected (hallucinations, cross-language, security, etc.)

Step 4: Architecture Assessment

Evaluate:

• Does the current architecture cleanly support this feature?
• Will implementing this feature increase technical debt?
• Are there architectural patterns being violated?
• Is there a cleaner abstraction that would help?

Step 5: Future Roadmap Interview

ASK THE USER about upcoming features that might tip the scales toward refactoring:

> "Before I finalize the plan, I want to understand your roadmap: > 1. What other features are planned for this area in the next 6 months? > 2. How often does this part of the codebase change? > 3. Are there pain points here that slow down development? > 4. What's your risk tolerance for refactoring vs. shipping fast?"

This information is CRITICAL for making the right refactoring decision.

Decision Framework

| Scenario | Recommendation | |----------|----------------| | Feature adds code to messy area | Refactor first | | Modification path has HIGH/CRITICAL AI slop | Refactor first | | Feature touches well-structured code | Implement directly | | Multiple upcoming features need same area | Refactor first | | Team struggles to understand the code | Refactor first | | One-off change to stable code | Implement directly | | Tight deadline, low complexity | Implement, document debt | | Tight deadline, high complexity | Discuss trade-offs with user |

Refactoring Confidence Levels

Based on your assessment, declare a confidence level:

| Level | Description | Action | |-------|-------------|--------| | LOW | Code is clean, feature fits naturally | Proceed to ARCHITECT | | MEDIUM | Some smells present, feature workable | Note debt, ask user preference | | HIGH | Significant issues, feature will worsen debt | Recommend refactor phases | | CRITICAL | Major rewrite needed, current approach unsustainable | Propose rewrite with Mikado/Strangler Fig |

When Confidence is HIGH or CRITICAL

If you determine refactoring should precede the feature work:

1. Ask permission explicitly:

> "Based on my analysis, I recommend refactoring [specific area] BEFORE implementing [feature]. This would involve: > - [Refactoring task 1] > - [Refactoring task 2] > > Benefits: [list benefi

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adamos486
• Source: adamos486/skills
• License: MIT

Install and usage instructions live in the source repository linked above.