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.

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

$3 - 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

``bash


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

$3

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

$3

`
┌─────────────────────────────────────────────────────────────────────┐
│ 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 │
│ │
└─────────────────────────────────────────────────────────────────────┘
`




$3

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

$3

`bash
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 # Show details of a change or spec
`

$3

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

$3

`bash
superspec archive # Archive completed change
superspec archive --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 |

$3

| 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)
│ │ └── /
│ │ └── spec.md
│ │
│ └── changes/ # 📝 Change management
│ ├── / # 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-/
│
└── src/ # Your application code
`




📝 Spec Format

`markdown


Feature Name

Purpose

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

Requirements

$3

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
`

$3

`
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 │
│ │
└────────────────────────────────────────────────────────────────┘
`

$3

| 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.

$3

In superspec/project.yaml:

`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
`

$3

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

$3

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 |

$3

- Codex CLI installed and authenticated
- Gemini CLI installed and authenticated




🛠 Installation

$3

`bash
npm install -g superspec
`

$3

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

$3

- 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (npm test)
4. Commit your changes (git commit -m 'feat: add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature`)
6. Open a Pull Request

📄 License

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

---