Philosophy

SuperSpec is built on core principles derived from observing AI-assisted development practices.

Spec-First

Principle

In the AI era, specifications matter more than code.

Code can be quickly generated by AI, but correct specifications ensure correct code.

Practice

Traditional: Requirements → Code → Docs (often skipped)
SuperSpec:   Requirements → Spec → Code (docs included)

Why It Works

1. Reduce ambiguity - Structured specs eliminate misunderstanding
2. Verifiable - Clear acceptance criteria
3. Traceable - Complete chain from requirements to code

Context Economy

Principle

AI context window is a scarce resource that must be used efficiently.

Practice

Constraint	Rule	Reason
File size	≤ 300 lines	Fits context window
File count	Minimize	Reduce switching
Content density	High information	Avoid redundancy

Why 300 Lines

Typical AI context: 8K-128K tokens
Optimal file size: 300 lines ≈ 1.5K tokens
Leaves room for: Chat history + code generation + tool output

Dual-Mode Workflow

Principle

Different tasks need different levels of specification.

Practice

Standard Mode - Quick iteration

• For: Bug fixes, small features, prototypes
• Artifacts: proposal.md + tasks.md
• Time: Minutes

Boost Mode - Complete specification

• For: Complex features, reviews, collaboration
• Artifacts: + spec.md + design.md + checklist.md
• Time: Hours

Selection Guide

Feature Complexity
    │
    ├─ Low ──→ Standard Mode
    │
    ├─ Medium ──→ Standard + manual additions
    │
    └─ High ──→ Boost Mode

Progressive Adoption

Principle

Tools should adapt to teams, not teams to tools.

Practice

Level 0: Proposal only

superspec create myFeature
# Just use proposal.md to capture ideas

Level 1: + Tasks

/ss-tasks
# Add task tracking

Level 2: Complete workflow

superspec create myFeature -b
# Use boost mode, full process

Level 3: Team collaboration

# Configure team templates
# Integrate CI/CD
# Automate checks

In-Context Learning Support

Principle

Cross-session context continuity is key to AI development.

Problem

Session 1: Implemented user auth
Session 2: AI doesn't know about Session 1
Session 3: Repeating explanations...

Solution

# End of session
superspec sync        # Save git changes to context.md

# Start of session
/ss-resume           # AI reads context.md, restores context

How It Works

context.md = git diff + git status + current task status

AI reads context.md to quickly understand:

• Current project state
• Completed work
• Pending tasks

Local-First

Principle

All data should be stored in the project, version controlled with code.

Practice

project/
├── .superspec/           # All SuperSpec data
│   ├── changes/          # Change records
│   └── archive/          # Historical archives
├── src/                  # Source code
└── .git/                 # Version control

Benefits

1. Privacy - Data never leaves local
2. Version Control - Managed with code
3. Portable - Project contains all info
4. Offline - No network required

Summary

SuperSpec's philosophy:

Spec-First + Context Economy + Dual-Mode + Progressive + In-Context Learning + Local-First

Together forming a toolkit optimized for AI-assisted development.

Next Steps

• Quick Start - Try it now
• Core Concepts - Learn more about SDD