---

name: using-superspec description: | Use at the start of any conversation - establishes how to find and use SuperSpec skills. Combines development discipline with spec-driven documentation.

Using SuperSpec

SuperSpec combines development discipline with spec-driven documentation.

Core Principles

The Unified Workflow

Copy┌─────────────────────────────────────────────────────────────────────────┐
│  FULL WORKFLOW (large features, team review needed)                      │
├─────────────────────────────────────────────────────────────────────────┤
│  /superspec:brainstorm   →  Progressive design (Explore → Propose → Spec)│
│          ↓                                                               │
│  superspec validate      →  Validate specs (CLI) + team review           │
│          ↓                                                               │
│  /superspec:plan         →  Create TDD implementation plan               │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│  FAST TRACK (small-medium features, solo development)                    │
├─────────────────────────────────────────────────────────────────────────┤
│  /superspec:kickoff      →  All-in-one: brainstorm + validate + plan     │
└─────────────────────────────────────────────────────────────────────────┘

          ↓ (both paths continue with)

/superspec:execute         →  Subagent-driven TDD implementation
        ↓
/superspec:verify          →  Verify implementation matches specs
        ↓
/superspec:finish-branch   →  Complete branch (merge/PR)
        ↓
/superspec:archive         →  Archive change, apply deltas

Brainstorm Phases

Copy/superspec:brainstorm
        │
        ├─→ Phase 1: EXPLORE
        │   • Free exploration
        │   • Clarifying questions
        │   • Visualize ideas
        │
        ├─→ Phase 2: PROPOSE
        │   • Define Why + What Changes
        │   • Define Capabilities + Impact
        │   • Output: proposal.md
        │
        ├─→ Phase 3: DESIGN
        │   • 2-3 approaches comparison
        │   • Technical decisions
        │   • Output: design.md
        │
        └─→ Phase 4: SPEC
            • Define Requirements
            • Define Scenarios (→ tests)
            • Output: specs/*.md

How to Access Skills

In Claude Code: Use the Skill tool. When you invoke a skill, its content is loaded - follow it directly.

The Rule

Invoke relevant skills BEFORE any response or action.

Even a 1% chance a skill might apply means invoke it to check.

Skill Categories

Design Phase

Planning Phase

Implementation Phase

Quality & Discipline Phase

Review Phase

Completion Phase

Red Flags - STOP and Check Skills

Skill Priority

When multiple skills could apply:

1. Process skills first (brainstorm) - determine approach through 4 phases
2. Implementation skills second (tdd, subagent-development) - guide execution
3. Completion skills last (verify, archive) - finalize work

Document Outputs

Validation Checkpoints

After Spec Phase

Copysuperspec validate [change-id] --strict

• Every Requirement has at least one Scenario
• Scenario format is correct (#### Scenario:)
• MODIFIED includes full content
• REMOVED includes Reason and Migration

After Execute Phase

Copysuperspec verify [change-id]

• Every Scenario has corresponding test
• All tests pass
• No features outside of Specs

Before Archive

• All validation passes
• Final code review approved
• Tests green

The Iron Laws

TDD Law

CopyNO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before test? Delete it. Start over.

Spec Law

CopySPECS ARE TRUTH. CHANGES ARE PROPOSALS.

No implementation without a Spec. No Spec without a Proposal.

SuperSpec Law

CopyEVERY SCENARIO BECOMES A TEST. EVERY TEST TRACES TO A SCENARIO.

Spec → Test → Implementation → Verification. Full traceability.

Verification Law

CopyNO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

"It should work" is not evidence. Run the test. Show the output. Then claim completion.

Quick Reference

Copy# CLI Commands
superspec init                    # Initialize project
superspec list                    # List changes
superspec list --specs            # List specs
superspec show [item]             # Show details
superspec validate [id] --strict  # Validate specs
superspec verify [id]             # Verify implementation
superspec archive [id] --yes      # Archive change

# Slash Commands (AI Assistant)
/superspec:kickoff                # Fast track: brainstorm + validate + plan
/superspec:brainstorm             # Full workflow: progressive design only
/superspec:plan                   # Create TDD plan (after brainstorm)
/superspec:execute                # Execute with subagents
/superspec:verify                 # Verify implementation
/superspec:finish-branch          # Complete branch (merge/PR)
/superspec:archive                # Archive change