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.
❌ Without SuperSpec
|
✅ With SuperSpec
|
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 |
# 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.
| 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 |
┌─────────────────────────────────────────────────────────────────────┐
│ 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 │
│ │
└─────────────────────────────────────────────────────────────────────┘
proposal.mddesign.mdspecs/*.mdSystem SHALL...)WHEN/THEN — each becomes a test)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
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
superspec archive <id> # Archive completed change
superspec archive <id> --yes # Skip confirmation
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 |
| 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 |
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
# 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
Specification Test
─────────────────────────────────────────────────────────────────────
#### Scenario: Successful Login → test('Successful Login', () => {
- WHEN valid credentials const result = login(validCreds);
- THEN grants access expect(result.granted).toBe(true);
});
─────────────────────────────────────────────────────────────────────
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 │
└────────────────────────────────────────┘
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 │
│ │
└────────────────────────────────────────────────────────────────┘
| 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 |
SuperSpec supports optional code review by external AI models (Codex/Gemini). Configure different providers for frontend vs backend tasks.
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
Implementation (TDD)
↓
[Task type detection]
│
├─→ Frontend task → Gemini review
│
└─→ Backend task → Codex review
│
↓
Hallucination check (CRITICAL!)
↓
Apply validated fixes only
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 |
npm install -g superspec
git clone https://github.com/HankLiu447/superspec.git
cd superspec
npm install
npm run build
npm link
We welcome contributions! Please see our Contributing Guide for details.
git checkout -b feature/amazing-feature)npm test)git commit -m 'feat: add amazing feature')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
FAQs
SuperSpec - Unified spec-driven development framework
The npm package superspec receives a total of 16 weekly downloads. As such, superspec popularity was classified as not popular.
We found that superspec demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST disclosed an unreleased AI tool called V-etalon and opened a broad inquiry into NVD modernization after years of automation plans produced no public enrichment system.
Security News
In his AI Council 2026 talk, Feross Aboukhadijeh covers recent package compromises, vulnerability discovery, and a more automated security model.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.