spec-driven

Spec-driven development with living specification documents for Claude Code. Composes with Superpowers.

The Problem

Most spec-driven tools create throwaway per-feature specs. Feature 3's spec doesn't know what Feature 1 decided. The AI loses cross-feature context. Contradictions creep in.

The Approach

One evolving set of documents per concern — design, requirements, test specs — that accumulate knowledge across every feature. Every change is a diff to these living docs, reviewed by the human, before any code is written.

docs/
  design/
    _overview.md          # Architecture (stable backbone)
    auth.md               # Auth design (grows with every auth feature)
    billing.md            # Billing design (grows with every billing feature)
  requirements/
    _overview.md          # Product vision, cross-cutting requirements
    auth.md               # Auth requirements
    billing.md            # Billing requirements
  test-specs/
    _overview.md          # Testing strategy
    auth.md               # Auth test scenarios
    billing.md            # Billing test scenarios
  handoff/
    <feature-name>.md     # Implementation context per feature

Install

npx skills add guwenqing/spec-driven

Requires Superpowers for implementation planning and execution.

Usage

1. Initialize (once per project)

/spec-init

Scaffolds the doc structure. AI analyzes your codebase and drafts overview files. You review and refine.

2. Plan a change

/spec-plan "add team billing with Stripe webhooks"

Interactive design conversation through 7 phases: understand the current state, discuss and commit requirements, design, and test specs (each with self-review), run a coherence review, write a handoff summary, then delegate to Superpowers for implementation.

How It Composes with Superpowers

spec-driven handles the specification layer. Superpowers handles implementation.

Phase	Handled By
Understand current state	spec-driven (Phase 1)
Requirements discussion + commit	spec-driven (Phase 2)
Design discussion + commit	spec-driven (Phase 3)
Test spec discussion + commit	spec-driven (Phase 4)
Self-review (3 parallel agents)	spec-driven (after each phase)
Coherence review	spec-driven (Phase 5)
Handoff summary	spec-driven (Phase 6)
Human review	You (at every phase gate)
Implementation planning	Superpowers writing-plans
TDD + implementation	Superpowers subagent-driven-development + TDD
Verification	Superpowers verification-before-completion

Skills Included

Skill	Command	Purpose
spec-driven	(auto-triggers)	Living docs context, composition rules, gotchas
spec-init	/spec-init	One-time project setup
spec-plan	/spec-plan "..."	Plan a change through interactive design conversation

License

MIT