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

Install

npx skills add guwenqing/spec-driven

Requires Superpowers for brainstorming, planning, and implementation.

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"

Loads your living docs → brainstorms (via Superpowers) → produces doc diffs → self-reviews → presents for your approval.

3. Apply and implement

/spec-apply

Applies your approved diffs, commits them, then hands off to Superpowers for implementation planning, TDD, and verification.

How It Composes with Superpowers

spec-driven is a wrapper, not a replacement. It adds a living docs layer around Superpowers:

Phase	Handled By
Load living doc context	spec-driven
Brainstorming	Superpowers brainstorming (unchanged)
Reframe as doc diffs	spec-driven
Self-review (3 parallel agents)	spec-driven
Human review	You
Apply diffs + commit	spec-driven
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 as doc diffs
spec-apply	/spec-apply	Apply approved diffs, transition to implementation

License

MIT