Provides structured specification management for AI coding agents like Claude Code, generating verifiable specs before writing code to prevent AI hallucinations. https://github.com/ChenJazzyBoss/superSpec… superSpec lets you generate a structured spec before writing code, then uses tools to verify that the code follows the spec. The entire process is divided into seven stages. The tool automatically runs validation and archiving; you only need to focus on brainstorming, planning, and implementation.

ChenJazzyBoss/superSpec

Source: https://github.com/ChenJazzyBoss/superSpec

superSpec

AI-native spec management for Claude Code. Turn natural language into executable specifications. Catch AI hallucinations before they become bugs.

License: MIT Tests TypeScript

English | 中文

The problem

You tell Claude Code: “Add batch export to the system.”

It writes 500 lines of code. Tests pass. You merge.

Three days later you discover:

• PDF export was never mentioned but Claude assumed it
• Error handling covers 2 of 7 failure modes
• The “edge case” tests are actually happy-path tests with different data

The spec was in your head. Claude couldn’t see it.

The solution

superSpec sits between your intent and Claude’s code. It forces a structured spec to exist before any code is written, then validates that the code actually matches.

flowchart LR
You["👤 You"] -- "batch export" --> BS["🧠 BrainstormRoute Evaluator"]
BS -->|"🚀 Lightweight"| GS["📋 generate-spec"]
BS -->|"📦 Full"| CH["📂 Change Dir"]
GS --> V["✅ validate-spec+ SkillGuard"]
CH --> V
V -->|"verified spec"| CC["🤖 Claude Code"]
CC -->|"code + evidence"| AR["📦 archive"]
AR --> LS["📜 Living Specs"]

Quick start

# 1. Clone and build superspec
git clone https://github.com/ChenJazzyBoss/superSpec.git
cd superSpec
npm install
npm run build
npm run bundle-validate

# 2. Go to YOUR project and initialize
cd /path/to/your-project
node /path/to/superSpec/bin/superspec.js init

This creates .superspec/ and .claude/ in your project. Then in Claude Code:

/generate-spec

Claude will ask you questions, generate a structured spec, and validate it — before writing any code.

What it does

📋 Structured specs — Requirements use SHALL/MUST, scenarios use Given/When/Then. No ambiguity.

✅ Auto-validation — 9 built-in rules catch missing scenarios, vague words, and incomplete coverage.

🔍 Deep analysis — Optional --deep mode detects logical contradictions between scenarios and coverage gaps in requirements.

📊 Auto diagrams — Add <!-- diagrams --> to your spec, and Mermaid diagrams are generated and embedded automatically.

🔗 Source tracking — Add <!-- source --> to link specs to code. Get warned when source files change but spec doesn’t.

🏷️ Scenario classification — Scenarios are auto-tagged as normal/error/boundary. Missing error scenarios trigger warnings.

🔄 Delta changes — Describe what changed, not the whole file. Merge conflicts become impossible.

🛡️ Anti-hallucination — Red flag tables and checklists prevent Claude from skipping steps or faking completion.

🔍 SkillGuard — Programmatic detection of AI skip patterns. Run superspec guard to verify skill configuration.

📋 Init Template — Collect human context before spec generation. Solves the “AI can’t read your mind” problem.

📦 Multi-artifact validation — Validate module lists with superspec validate-modules. Circular dependency detection included.

🤖 Subagent orchestration — Dual-review pipeline: implement → spec-check → code-review. Every task.

CLI Commands

superspec init

Initialize superSpec in your project.

superspec init                    # Default setup
superspec init --interactive       # Interactive configuration
superspec init --ci                # Include GitHub Actions workflow
superspec init --template web-api  # Use Web API template
superspec init --list-templates    # List available templates

Creates .superspec/ directory structure, injects CLAUDE.md, copies templates and scripts.

superspec validate <spec>

Validate a spec file.

superspec validate batch-export                        # By spec name
superspec validate .superspec/specs/batch-export/spec.md  # By file path
superspec validate batch-export --strict               # WARNING = failure
superspec validate batch-export --deep                 # Logical consistency analysis

Output (JSON):

{
  "valid": true,
  "issues": [],
  "summary": {
    "errors": 0,
    "warnings": 0,
    "info": 0
  },
  "scenarioTypes": {
    "requirements[0]": ["normal", "error", "boundary"]
  }
}

superspec ci

Batch validate all specs.

superspec ci                # Validate all specs
superspec ci --strict       # Strict mode
superspec ci --json         # JSON output

superspec generate <spec>

Generate test code skeleton from spec.

superspec generate batch-export            # TypeScript (default)
superspec generate batch-export -l python  # Python
superspec generate batch-export -o test/batch.test.ts  # Write to file

superspec update <spec>

Incrementally update a spec via Delta JSON.

cat delta.json | superspec update batch-export
superspec update batch-export -f delta.json

superspec diff <spec>

Compare current spec with historical version.

superspec diff batch-export              # Compare with latest snapshot
superspec diff batch-export --from 2026-06-01  # Compare with specific version

superspec history <spec>

List all historical snapshots of a spec.

superspec history batch-export

superspec archive <spec>

Archive a completed change.

superspec archive add-pdf-export

superspec changes

List in-progress changes.

superspec changes

superspec guard

Check skill file’s anti-hallucination configuration.

superspec guard src/skills/generate-spec/SKILL.md         # Check skill config
superspec guard src/skills/validate-spec/SKILL.md --json  # JSON output

Verifies that skill files have proper red flag tables and HARD-GATE tags configured.

superspec validate-modules

Validate module list files.

superspec validate-modules modules.md              # Validate module list
superspec validate-modules modules.md -p my-project # With project name
superspec validate-modules modules.md --json        # JSON output

Checks module structure, detects circular dependencies, validates naming conventions.

superspec pipeline show

Display the default workflow definition.

superspec pipeline show

Output:

📋 superSpec default workflow
Stage            Type       Dependency
──────────────── ────────   ──────────────────
brainstorm       optional   —
generate-spec    required   brainstorm
validate-spec    required   generate-spec
write-plan       required   validate-spec
implement        required   write-plan
verify           required   implement
archive          required   verify

superspec pipeline next <stage>

Query the recommended next step for a given stage.

superspec pipeline next brainstorm       # → generate-spec
superspec pipeline next validate-spec    # → write-plan
superspec pipeline next archive          # → "reached end of workflow"

superspec pipeline run <spec>

Run the pipeline for a spec — auto-executes programmatic stages (validate-spec, archive) and outputs guidance for AI stages.

superspec pipeline run batch-export              # Run from validate-spec
superspec pipeline run batch-export --from write-plan  # Resume from a specific stage

Execution records are persisted to .superspec/pipeline/<spec>.json.

superspec pipeline status [name]

View pipeline execution status.

superspec pipeline status                           # Latest execution
superspec pipeline status batch-export              # Latest for this spec
superspec pipeline status --exec                    # By execution id

superspec pipeline list

List all pipeline execution records.

superspec pipeline list

superspec pipeline resume <execution_id>

Resume a failed pipeline execution from the failed stage.

superspec pipeline resume batch-export-20260611100000

superspec change

Manage change lifecycle (unified model for new features and modifications).

superspec change create                         # Create change directory with proposal
superspec change create --why "..."             # With description
superspec change list                           # List all changes
superspec change status                         # Show change phase and capabilities
superspec change apply                          # Merge delta specs into main specs
superspec change apply --dry-run                # Validate without writing

superspec route

Evaluate user intent and recommend a path.

superspec route "add export button"                # → 🚀 Lightweight
superspec route "implement full auth" -c 3         # → 📦 Full
superspec route "modify export format"             # → 📦 Full (modification)
superspec route "export feature crashed"           # → 🔧 Debug

superspec uninstall

Remove all superSpec files from project.

superspec uninstall      # With confirmation
superspec uninstall -y   # Skip confirmation

Spec Format

A spec file uses structured Markdown:

# Feature Name

## Purpose
Description of what this feature does and why it's needed. Must be at least 50 characters.

## Requirements
### Requirement: Requirement Name
The system SHALL do something specific.

#### Scenario: Normal flow
Given some precondition
When some action
Then expected result

#### Scenario: Exception handling
Given some precondition
When an error occurs
Then error is handled gracefully

#### Scenario: Boundary condition
Given edge case data
When processing
Then system handles correctly

Spec Annotations

How it works

1. Generate a spec

/superspec:generate-spec

Claude asks about your requirements, then produces:

# Batch Export

## Purpose
System needs to export data in CSV, XLSX, and PDF formats for various business workflows...

## Requirements
### Requirement: Format Support
System SHALL support CSV, XLSX, and PDF export formats.

#### Scenario: Normal flow - CSV export
Given user is on the data list page
When selecting CSV format and clicking export
Then system generates and downloads a CSV file

#### Scenario: Exception - Export failure
Given user is on the data list page
When an error occurs during export
Then system displays error message and logs the issue

2. Validate

# Basic validation (format + rules + scenario classification)
node .superspec/scripts/validate.js .superspec/specs/batch-export/spec.md

# Deep validation (+ logical consistency analysis)
node .superspec/scripts/validate.js .superspec/specs/batch-export/spec.md --deep

 ✅ valid: true
 errors: 0, warnings: 0, info: 0
 scenarioTypes: requirements[0]: [normal, error, boundary]

3. Implement

/superspec:write-plan
/superspec:subagent-dev

Claude creates a detailed plan, then implements each task with dual review.

4. Run the pipeline

superspec pipeline run batch-export

Automatically executes programmatic stages (validate-spec, archive) and guides you through AI stages (write-plan, implement, verify). Execution state is persisted — you can resume anytime.

5. Archive

/superspec:archive

Changes are recorded. Specs grow. History is preserved.

Features

Why superSpec?

The workflow

flowchart TD
User["👤 User Input"] --> Router["🧭 Route Evaluator"]
Router -->|"🚀 Lightweight(simple feature)"| Spec["📋 generate-spec"]
Router -->|"📦 Full(complex / change)"| Change["📂 Change Dirproposal → delta-spec"]
Router -->|"🔧 Debug(bug / failure)"| Debug["🔍 debug"]
Change --> Spec
Spec --> Validate["✅ validate-spec(auto)"]
Validate -->|pass| Plan["📝 write-plan"]
Validate -->|fail| Spec
Plan --> Implement["🔨 implement"]
Implement --> Verify["🧪 verify"]
Verify -->|pass| Archive["📦 archive(auto)"]
Verify -->|fail| Implement

style Router fill:#f9f,stroke:#333
style Validate fill:#9f9,stroke:#333
style Archive fill:#9f9,stroke:#333
style Debug fill:#ff9,stroke:#333

Three adaptive paths based on complexity assessment. Programmatic stages (validate-spec, archive) run automatically via pipeline run. AI stages output guidance and wait for completion.

Running the pipeline

Use superspec pipeline run to automate the workflow:

# Start pipeline (auto-runs validate-spec)
superspec pipeline run batch-export
# Output shows stage status + next step guidance
#
# 📋 Pipeline Execution: batch-export-20260611100000
# ✅ validate-spec completed (150ms)
# ⏳ write-plan pending — needs AI
#
# 📍 Next Step Guidance:
# Stage: write-plan
# Skill: write-plan
# Action: After the plan is generated, run `superspec pipeline run --from implement` to continue the pipeline
#
# After AI completes write-plan, resume pipeline
superspec pipeline run batch-export --from implement

# Check pipeline status anytime
superspec pipeline status batch-export

Programmatic stages (validate-spec, archive) run automatically. AI stages output guidance and wait for completion.

PipelineGuardRunner

The pipeline integrates SkillGuard at runtime. Every stage execution goes through anti-hallucination checks:

Stage starts → SkillGuard.beforeExecute() → check red flag table & HARD-GATE
Stage runs → handler(context)
Stage output → SkillGuard.onOutput() → detect skip patterns & red flags
Stage ends → SkillGuard.onCompletion() → verify evidence

If a skill file lacks a red flag table, the stage is blocked — not warned, blocked.

Anti-hallucination design

Every high-risk skill has:

Red flag table — Common excuses and why they’re wrong:

Completion checklist — Must check every box before completion