superspec

Every Scenario becomes a test. Every test traces back to a Scenario.

Quick Start · Documentation · CLI Reference · Contributing

Why SuperSpec?

Most development workflows suffer from specification drift — where documentation, tests, and code gradually become misaligned. SuperSpec solves this by establishing specifications as the single source of truth and enforcing bidirectional traceability between specs and tests.

❌ Without SuperSpec Specs written once, then forgotten Tests don't match requirements "It works" without verification Changes break unknown features Documentation always outdated

✅ With SuperSpec Specs are living documents Every scenario = a test case Evidence-based completion Impact analysis before changes Documentation auto-maintained

✨ Key Features

Spec-First Specifications as single source of truth	TDD Enforced Write tests first, then implement	AI-Powered Claude Code skills integration	Verified Evidence before completion claims
Context-Aware Phase Protocol prevents AI drift	Gate-Verified Entry/Exit gates ensure nothing skipped	Phase-Based Structured multi-phase execution	Subagent-Driven Parallel task execution with reviews

🚀 Quick Start

# Install globally
npm install -g superspec

# Initialize in your project
cd your-project
superspec init

# Start developing with Claude Code
/superspec:kickoff

That's it! SuperSpec will guide you through the entire development workflow.

📖 Documentation

The Four Iron Rules

Rule	Principle
TDD Rule	No production code without a failing test first
Spec Rule	Specs are truth. Changes are proposals.
SuperSpec Rule	Every Scenario becomes a test. Every test traces to a Scenario.
Verification Rule	No completion claims without fresh verification evidence

Workflow Overview

┌─────────────────────────────────────────────────────────────────────┐
│  Choose Your Path                                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  🚀 FAST TRACK (small-medium features)                              │
│     /superspec:kickoff  →  All-in-one: brainstorm + validate + plan │
│                                                                     │
│  📋 FULL WORKFLOW (large features, team review)                     │
│     /superspec:brainstorm  →  Progressive 4-phase design            │
│     superspec validate     →  CLI validation + team review          │
│     /superspec:plan        →  Create TDD implementation plan        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Implementation (both paths)                                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│     /superspec:execute        →  Subagent-driven TDD implementation │
│     /superspec:verify         →  Verify implementation matches specs│
│     /superspec:finish-branch  →  Complete branch (merge/PR)         │
│     /superspec:archive        →  Archive changes, apply delta       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Four-Phase Brainstorming

Phase 1: EXPLORE — Understand the problem

• Free exploration and discovery
• Ask clarifying questions
• Visualize ideas and constraints
• No commitments yet

Phase 2: PROPOSE — Define scope → proposal.md

• Why: Problem or opportunity statement
• What Changes: List of modifications
• Capabilities: New or modified features
• Impact: Affected areas of the system

Phase 3: DESIGN — Technical approach → design.md

• Compare 2-3 technical approaches
• Document trade-offs
• Select and justify the recommended approach

Phase 4: SPEC — Requirements & scenarios → specs/*.md

• Define Requirements (System SHALL...)
• Define Scenarios (WHEN/THEN — each becomes a test)

💻 CLI Commands

Project Management

superspec init [path]         # Initialize SuperSpec in a project
superspec view                # Dashboard overview
superspec list                # List all changes
superspec list --specs        # List all specifications
superspec show <item>         # Show details of a change or spec

Validation & Verification

superspec validate <id>           # Validate a specification
superspec validate <id> --strict  # Strict mode (warnings = errors)
superspec verify <id>             # Verify implementation matches specs
superspec verify <id> --verbose   # Show detailed matching info

Archiving

superspec archive <id>        # Archive completed change
superspec archive <id> --yes  # Skip confirmation

🤖 Claude Code Integration

SuperSpec provides skills that integrate seamlessly with Claude Code:

Skill	Description
/superspec:kickoff	Fast-track: brainstorm → validate → plan in one session
/superspec:brainstorm	Full workflow with 4-phase progressive design
/superspec:plan	Create TDD implementation plan
/superspec:execute	Subagent-driven TDD implementation
/superspec:verify	Verify implementation matches specifications
/superspec:finish-branch	Complete branch (merge, PR, or keep)
/superspec:archive	Archive changes and apply deltas to main specs

Additional Skills

Skill	Description
phase-protocol	Prevents context drift during long sessions
external-review	External AI code review (Codex/Gemini)
codex	OpenAI Codex CLI integration
gemini	Google Gemini CLI integration
tdd	TDD cycle with anti-pattern awareness
git-worktree	Isolated development with git worktrees
systematic-debugging	Root cause analysis methodology
code-review	Two-phase review (spec compliance + quality)
verification-before-completion	Evidence-based completion claims

📁 Project Structure

your-project/
├── superspec/
│   ├── project.yaml              # Project configuration
│   │
│   ├── specs/                    # 📚 Main specifications (source of truth)
│   │   └── <capability>/
│   │       └── spec.md
│   │
│   └── changes/                  # 📝 Change management
│       ├── <change-id>/          # Active changes
│       │   ├── proposal.md       # Why + What
│       │   ├── design.md         # How (technical approach)
│       │   ├── specs/            # Delta specifications
│       │   ├── plan.md           # TDD implementation plan
│       │   └── tasks.md          # Task tracking
│       │
│       └── archive/              # Completed changes
│           └── YYYY-MM-DD-<id>/
│
└── src/                          # Your application code

📝 Spec Format

# Feature Name

## Purpose
Brief description of what this feature does and why it exists.

## Requirements

### Requirement: User Authentication
The system SHALL authenticate users with email and password.

#### Scenario: Successful Login
- **WHEN** user submits valid credentials
- **THEN** system grants access and returns session token

#### Scenario: Invalid Credentials
- **WHEN** user submits invalid credentials
- **THEN** system denies access with error message

Spec → Test Mapping

Specification                          Test
─────────────────────────────────────────────────────────────────────
#### Scenario: Successful Login    →   test('Successful Login', () => {
- WHEN valid credentials                 const result = login(validCreds);
- THEN grants access                     expect(result.granted).toBe(true);
                                       });
─────────────────────────────────────────────────────────────────────

🔄 Two-Phase Review

SuperSpec enforces a two-phase review process:

┌────────────────────────────────────────┐
│  Phase 1: Spec Compliance Review       │
│  ──────────────────────────────────    │
│  ✓ Every Requirement implemented?      │
│  ✓ Every Scenario has a test?          │
│  ✓ No extra/missing features?          │
└────────────────────────────────────────┘
                    │
                    ▼ Pass to proceed
┌────────────────────────────────────────┐
│  Phase 2: Code Quality Review          │
│  ──────────────────────────────────    │
│  ✓ Error handling                      │
│  ✓ Type safety                         │
│  ✓ SOLID principles                    │
│  ✓ Test quality                        │
└────────────────────────────────────────┘

🔄 Phase Protocol (Context Drift Prevention)

AI assistants often forget tasks during long development sessions as context gets compressed. SuperSpec's Phase Protocol solves this with a structured approach:

┌────────────────────────────────────────────────────────────────┐
│  PHASE PROTOCOL                                                 │
├────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ENTRY (start of each phase):                                   │
│    1. Read phase-protocol skill (refresh context)               │
│    2. Read tasks.md (get task list)                             │
│    3. CREATE TODO IMMEDIATELY ← Before reading other docs!      │
│    4. Gate: Verify TODO completeness                            │
│    5. Read plan.md, design.md, specs/*.md                       │
│    6. Gate: Output key understanding                            │
│    7. Begin implementation                                      │
│                                                                  │
│  EXIT (end of each phase):                                      │
│    1. Update tasks.md                                           │
│    2. Git commit                                                │
│    3. Re-read phase-protocol skill ← Loop back!                 │
│    4. Create next phase TODO                                    │
│                                                                  │
└────────────────────────────────────────────────────────────────┘

Why This Works

Mechanism	Purpose
TODO created early	Survives context compression — won't be forgotten
Gate verification	Ensures nothing skipped before proceeding
Exit Gate re-read	Forces context refresh at phase boundaries
Structured loop	Exit → Re-read → Entry → Exit → continues automatically

🤖 External AI Review (Optional)

SuperSpec supports optional code review by external AI models (Codex/Gemini). Configure different providers for frontend vs backend tasks.

Configuration

In superspec/project.yaml:

review:
  enabled: true                      # Enable external AI review

  frontend:                          # For UI/component tasks
    provider: gemini                 # gemini | codex | none
    model: gemini-3-pro-preview

  backend:                           # For API/logic tasks
    provider: codex                  # codex | gemini | none
    model: gpt-5.2-codex

How It Works

Implementation (TDD)
        ↓
[Task type detection]
        │
        ├─→ Frontend task → Gemini review
        │
        └─→ Backend task → Codex review
        │
        ↓
Hallucination check (CRITICAL!)
        ↓
Apply validated fixes only

Hallucination Check

Before applying ANY external AI suggestion:

Check	Why
File exists?	AI may reference non-existent files
Function exists?	AI may suggest changes to phantom code
Makes sense?	Must align with project architecture
Not duplicate?	May suggest already-implemented features

Prerequisites

• Codex CLI installed and authenticated
• Gemini CLI installed and authenticated

🛠 Installation

From npm

npm install -g superspec

From Source

git clone https://github.com/HankLiu447/superspec.git
cd superspec
npm install
npm run build
npm link

Requirements

• Node.js ≥ 18.0.0
• npm ≥ 8.0.0
• Claude Code (for AI-powered skills)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Run tests (npm test)
• Commit your changes (git commit -m 'feat: add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⬡ SuperSpec — Spec-Driven Development with TDD Discipline

Report Bug · Request Feature · Discussions

Made with precision by Hank Liu