SuperSpec - Unified spec-driven development framework
npm install superspec







Every Scenario becomes a test. Every test traces back to a Scenario.
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 | $3- Specs are living documents |
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 |
``bashInstall globally
npm install -g superspec
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`)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