superspec
v0.1.6
Published
SuperSpec - Unified spec-driven development framework
Maintainers
hankliu447Readme
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
🚀 Quick Start
# Install globally
npm install -g superspec
# Initialize in your project
cd your-project
superspec init
# Start developing with Claude Code
/superspec:kickoffThat'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
- Free exploration and discovery
- Ask clarifying questions
- Visualize ideas and constraints
- No commitments yet
- Why: Problem or opportunity statement
- What Changes: List of modifications
- Capabilities: New or modified features
- Impact: Affected areas of the system
- Compare 2-3 technical approaches
- Document trade-offs
- Select and justify the recommended approach
- 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 specValidation & 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 infoArchiving
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 messageSpec → 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-codexHow It Works
Implementation (TDD)
↓
[Task type detection]
│
├─→ Frontend task → Gemini review
│
└─→ Backend task → Codex review
│
↓
Hallucination check (CRITICAL!)
↓
Apply validated fixes onlyHallucination 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 superspecFrom Source
git clone https://github.com/HankLiu447/superspec.git
cd superspec
npm install
npm run build
npm linkRequirements
- 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