SuperSpec

March 12, 2026 · View on GitHub

SuperSpec

Spec-driven development (SDD) for AI-powered coding assistants.

Why SuperSpec?

AI coding assistants are powerful but often produce inconsistent, undocumented code when requirements are vague.

OpenSpec Pain Points

#	OpenSpec Pain Point	SuperSpec Solution
1	No spec size control — specs grow unbounded, eating AI context window	First Principles + `lint` (target 300 / hard 400 lines), auto-split via `/ss-specs`
2	Validation inconsistency — `validate --strict` passes but `archive` fails	Unified validation pipeline: `lint` → `validate` → `checklist` → `archive`
3	No implementation↔spec verification — spec drift after coding	`sync` collects git diff into `context.md`, `/ss-resume` cross-references with spec
4	No context restoration workflow — context lost when switching AI conversations	`sync` + `context.md` + `/ss-resume` restores full spec context in new sessions
5	No dependency management between specs	`depends_on` frontmatter + `deps add`/`deps list`/`deps remove`
6	No search across specs and archived changes	`search` with `--archived`, `--artifact`, `--regex` filters
7	No progress tracking or status visibility	`status` shows all changes with per-artifact status (Draft → Ready → Done)
8	Single mode — same overhead for simple fixes and large features	Standard mode (lightweight) vs Boost mode (full US/FR/AC + checklist)
9	No project-level configuration for AI context rules	`superspec.config.json` with `strategy`, `context`, `limits`, `branchTemplate` etc.
10	No cross-reference validation (US↔FR↔AC↔tasks)	`validate --check-deps` ensures full traceability
11	No i18n — English only	`--lang zh\|en`, full Chinese templates + CLI prompts
12	No task granularity control	Boost mode: each task < 1 hour, phased with parallel markers `[P]`
13	No automatic branch creation — inconsistent naming for change branches	`superspec create` auto-creates git branches from `branchTemplate`, with customizable `branchPrefix` / `branchTemplate` / `changeNameTemplate`

Spec-Kit Pain Points

#	Spec-Kit Pain Point	SuperSpec Solution
1	Commands consume a large number of tokens, severely eating into the context window	Slash commands are file-based templates, loaded on-demand (zero idle cost)
2	Creates "illusion of work" — generates excessive documentation	First Principles: every sentence must inform a decision, signal-over-noise
3	Can't update/refine existing specs — always creates new branches	In-place spec evolution: edit proposal/spec/tasks directly, `/ss-clarify` for iterations
4	Ignores existing project structure and conventions	`strategy: follow` reads `context` files as constraints, matches existing patterns
5	Generates hundreds of unhelpful tests	No auto-test generation — task verification is developer-controlled
6	Poor for incremental development / small tasks	Standard mode for quick features; Boost only when needed (`-b`)
7	Python-based install (`uv tool`) — mismatched with JS/TS ecosystem	npm/pnpm/yarn install, native to Node.js ecosystem
8	No spec dependency management between changes	`depends_on` + `deps add`/`deps list` with dependency graph
9	No context restoration workflow	`sync` → `context.md` → `/ss-resume` for seamless continuation
10	Fails when initialized in subfolders	Works anywhere — `superspec.config.json` at project root, `specDir` configurable
11	No spec archiving with context preservation	`archive` moves completed changes, `search --archived` still finds them
12	Incompatible with latest AI tool upgrades	Editor-agnostic `AGENTS.md` + per-editor rules via `--ai` flag
13	Single mode and rigid configuration — no flexible switching between lightweight and Boost modes	SuperSpec lets you freely switch between Standard and Boost modes, with highly customizable `boost`, `strategy`, `branchTemplate` and more in `superspec.config.json`
14	No creative/exploration mode	`strategy: create` (`-c`) allows proposing new architectures with documented trade-offs

Installation

# npm
npm install -g @superspec/cli

# pnpm
pnpm add -g @superspec/cli

# yarn
yarn global add @superspec/cli

Requires Node.js >= 18.0.0

Quick Start

cd your-project

superspec init                  # Default (English templates)
superspec init --lang zh        # Chinese templates
superspec init --ai claude      # Specify AI assistant type (cursor|claude|gemini|copilot|windsurf|qwen|opencode|codex|codebuddy|qoder)
superspec init --force          # Force overwrite existing config
superspec init --no-git         # Skip git initialization

Core Workflow

Standard:  create (proposal → checklist ✓) → tasks → apply → [vibe: sync → resume] → archive
Boost:     create -b (proposal → spec → [auto: split? design?] → checklist ✓) → tasks → apply → ...

Standard mode: AI generates proposal.md (requirements + technical solution) → auto checklist (/10) → tasks.md — enough for simple features and bug fixes.

Boost mode: AI generates proposal.md (requirements background) → spec.md (US/FR/AC details) → auto complexity assessment (split? design?) → auto checklist (/25) → tasks.md — for large features requiring design review and cross-validation.

Vibe coding phase: after apply, use sync to collect git changes and /ss-resume to restore context in new AI conversations.

Slash Commands (AI Agent)

These are the primary commands you use with AI assistants. Type them directly in your AI chat:

Main Flow

Command	Flags	What it does
`/ss-create <feature>`	`-b` boost, `-c` creative, `-d <desc>`, `--no-branch`, `--spec-dir <dir>`, `--branch-prefix <prefix>`, `--branch-template <tpl>`, `--change-name-template <tpl>`, `--intent-type <type>`, `--user <user>`, `--lang <lang>`	Create folder + branch, AI generates proposal (boost: + spec + design) with auto checklist gate
`/ss-tasks`	—	Generate task list from proposal
`/ss-apply`	—	Implement tasks one by one
`/ss-resume`	—	Restore spec context for vibe coding (runs sync → reads context.md)
`/ss-archive [name]`	`--all`	Archive completed change

Quality & Discovery

Command	Mode	Flags	What it does
`/ss-clarify`	Both	—	Resolve ambiguity, record decisions
`/ss-checklist`	Both	—	Quality gate: Standard (/10 after proposal) or Boost (/25 after spec). Auto-invoked by /ss-create
`/ss-lint [name]`	Both	—	Check artifact sizes
`/ss-validate [name]`	Boost	`--check-deps`	Cross-reference consistency check (US↔FR↔AC↔tasks)
`/ss-status`	Both	—	View all changes and their status
`/ss-search <q>`	Both	`--archived`, `--artifact <type>`, `--limit <n>`, `-E`/`--regex`	Full-text search across changes
`/ss-link <name>`	Both	`--on <other>`	Add spec dependency
`/ss-unlink <name>`	Both	`--on <other>`	Remove spec dependency
`/ss-deps [name]`	Both	—	View dependency graph

Usage Example

You:  /ss-create add user authentication @jay
AI:   → runs `superspec create addUserAuth --intent-type feature`
      → generates proposal.md (with requirements + technical solution)
      → auto-runs checklist (/10) → pass
      → prompts to run /ss-tasks

You:  /ss-tasks
AI:   → reads proposal.md → generates phased tasks

You:  /ss-apply
AI:   → implements tasks one by one, marks each ✅

You:  /ss-resume    (new conversation / after a break)
AI:   → runs sync → reads context.md → continues where you left off

superspec init                  # Default (English templates)
superspec init --lang zh        # Chinese templates
superspec init --ai claude      # Specify AI assistant type (cursor|claude|gemini|copilot|windsurf|qwen|opencode|codex|codebuddy|qoder)
superspec init --force          # Force overwrite existing config
superspec init --no-git         # Skip git initialization

Core Workflow

`superspec create <feature>`

Create a change folder and git branch. Artifacts are generated on demand by AI via /ss-create.

superspec create add-dark-mode                              # Standard mode
superspec create add-auth -b                                # Boost mode (spec + design + checklist)
superspec create redesign-ui -c                             # Creative mode (explore new patterns)
superspec create new-arch -b -c --no-branch                 # Boost + creative + skip branch
superspec create add-auth -d "OAuth2 integration"           # With description
superspec create add-auth --spec-dir specs                  # Custom spec folder
superspec create add-auth --branch-prefix feature/          # Custom branch prefix
superspec create add-auth --branch-template "{prefix}{date}-{feature}-{user}"    # Custom branch name template
superspec create add-auth --change-name-template "{date}-{feature}-{user}"       # Custom folder name template
superspec create add-auth --intent-type hotfix              # Intent type (feature|hotfix|bugfix|refactor|chore)
superspec create add-auth --user jay                        # Developer identifier
superspec create add-auth --lang zh                         # SDD document language (en|zh)

`superspec archive [name]`

Archive completed changes.

superspec archive add-auth      # Archive a specific change
superspec archive --all         # Archive all completed changes

`superspec update`

Refresh agent instructions and templates to latest version.

superspec update

Quality & Validation

`superspec lint [name]`

Check artifact sizes against configured limits.

superspec lint add-auth         # Lint a specific change
superspec lint                  # Lint all active changes

`superspec validate [name]`

Cross-reference consistency check (US↔FR↔AC↔tasks).

superspec validate add-auth                 # Validate a specific change
superspec validate add-auth --check-deps    # Validate with dependency check
superspec validate                          # Validate all active changes

Search & Discovery

`superspec search <query>`

Full-text search across all changes.

superspec search "JWT authentication"               # Search active changes
superspec search "login flow" --archived             # Include archived changes
superspec search "refresh token" --artifact tasks    # Filter by artifact type (proposal|spec|tasks|clarify|checklist)
superspec search "auth" --limit 10                   # Limit results count (default: 50)
superspec search "user\d+" -E                        # Use regex pattern matching

`superspec status`

View all active changes and their artifact statuses.

superspec status

Dependencies

`superspec deps add <name>`

superspec deps add add-auth --on setup-database

`superspec deps remove <name>`

superspec deps remove add-auth --on setup-database

`superspec deps list [name]`

superspec deps list add-auth    # View deps for a specific change
superspec deps list             # View all dependency relationships

Vibe Coding (Post-SDD)

`superspec sync [name]`

Generate/refresh context.md summary with git diff (zero AI tokens — pure CLI).

superspec sync add-auth                 # Sync a specific change
superspec sync add-auth --base develop  # Sync with custom base branch
superspec sync add-auth --no-git        # Skip git diff collection
superspec sync                          # Sync all active changes

Strategy: follow vs create

Each change has a strategy that controls how the AI agent approaches implementation:

	`follow` (default)	`create` (`-c`)
Reads project rules	Yes, as constraints	Yes, as awareness
Architecture	Must align with existing	May propose alternatives
File structure	Match existing patterns	May introduce new patterns
Use case	Regular features, bug fixes	Refactoring, new modules, UX innovation

Configure project rule files in superspec.config.json:

{
  "context": [".cursor/rules/coding-style.mdc", "AGENTS.md", "docs/conventions.md"]
}

First Principles

Inspired by LeanSpec

#	Principle	Rule
I	Context Economy	< 300 lines per artifact, 400 hard limit
II	Signal-to-Noise	Every sentence must inform a decision
III	Intent Over Implementation	Focus on why and what, not how
IV	Progressive Disclosure	Start minimal, expand only when needed
V	Required Sections	Metadata, Problem, Solution, Success Criteria, Trade-offs

Configuration

superspec init generates superspec.config.json:

Field	Default	Description
`lang`	`"en"`	Template language (`zh` / `en`). Also controls CLI prompt language
`specDir`	`"superspec"`	Spec folder name
`branchPrefix`	`"spec/"`	Git branch prefix
`boost`	`false`	Enable boost mode by default
`strategy`	`"follow"`	`follow` = obey project rules, `create` = explore freely
`context`	`[]`	Files AI should read for project conventions
`limits.targetLines`	`300`	Target max lines per artifact
`limits.hardLines`	`400`	Hard max lines per artifact
`archive.dir`	`"archive"`	Archive subdirectory
`archive.datePrefix`	`true`	Prefix archive folder with date

Project Structure

SuperSpec/
├── package.json                 # monorepo root
├── pnpm-workspace.yaml
├── tsconfig.json
└── packages/
    └── cli/                     # @superspec/cli
        ├── package.json
        ├── tsup.config.ts
        ├── src/
        │   ├── index.ts         # Library exports
        │   ├── cli/             # CLI entry (commander)
        │   ├── commands/        # create / archive / init / update / lint / validate / search / deps / status / sync
        │   ├── core/            # config / template / frontmatter / lint / validate / context
        │   ├── prompts/         # Agent rules installer
        │   ├── ui/              # Terminal output (chalk)
        │   └── utils/           # fs / git / date / paths / template
        ├── templates/
        │   ├── zh/              # Chinese templates
        │   └── en/              # English templates
        └── prompts/
            ├── rules.md         # Rules.md template
            └── agents.md        # AGENTS.md template

Tech Stack

Language: TypeScript
Build: tsup
Package Manager: pnpm (monorepo)
Runtime: Node.js >= 18
Dependencies: commander, chalk

Development

pnpm install          # Install dependencies
pnpm build            # Build all packages
pnpm dev              # Watch mode
pnpm --filter @superspec/cli typecheck   # Type check

Acknowledgments

License

MIT

SuperSpec

SuperSpec

Why SuperSpec?

OpenSpec Pain Points

Spec-Kit Pain Points

Installation

Quick Start

Core Workflow

Slash Commands (AI Agent)

Main Flow

Quality & Discovery

Usage Example

CLI Commands

Setup

`superspec init`

Core Workflow

`superspec create <feature>`

`superspec archive [name]`

`superspec update`

Quality & Validation

`superspec lint [name]`

`superspec validate [name]`

Search & Discovery

`superspec search <query>`

`superspec status`

Dependencies

`superspec deps add <name>`

`superspec deps remove <name>`

`superspec deps list [name]`

Vibe Coding (Post-SDD)

`superspec sync [name]`

Strategy: follow vs create

First Principles

Configuration

Project Structure

Tech Stack

Development

Acknowledgments

License