SDD — Spec-Driven Development

A Claude Code plugin that implements Spec-Driven Development for structured, spec-first feature delivery.

SDD guides you through a gated workflow: capture requirements → design UX and architecture → break into tasks → implement with verification → consolidate learnings. Every phase produces artifacts that feed the next, keeping specs and code in sync.

Install

Via npx (any project, global by default):

npx @appswithlove/sdd@latest

You'll be prompted for scope — global (~/.claude) or project (./.claude). Non-interactive:

npx @appswithlove/sdd@latest --global   # or --project, or -y to auto-detect
npx @appswithlove/sdd@latest --dry-run   # preview without writing

This installs the SDD skills, team steering (~/.claude/sdd/steering/), and merges the SDD hooks into settings.json. Updating = re-run the same command (npm @latest resolves the newest version; the installer is idempotent).

Via Claude marketplace plugin (namespaced /sdd:*): see the plugin section below.

Quick Start

# 1. Install the plugin (via Claude Code plugin registry — coming soon)

# 2. Bootstrap SDD in your project
/sdd:0-init

# 3. Start your first feature
/sdd:1-req user-auth

# 4. Design (parallel)
/sdd:2-ux user-auth
/sdd:2-tech user-auth

# 5. Plan and break into tasks
/sdd:2-plan user-auth
/sdd:2-tasks user-auth

# 6. Build
/sdd:3-implement user-auth   # repeat until all tasks done

# 7. Verify and ship
/sdd:3-review user-auth
/sdd:3-verify user-auth
/sdd:4-consolidate user-auth

Flow

/sdd:0-init ─── once per project
    │
/sdd:1-req ─── capture requirements ─── sets READY_SET
    │
    ├── /sdd:2-ux ────── UX discovery      ┐
    ├── /sdd:2-tech ──── tech design        ├── parallel
    └── /sdd:2-research ─ library docs      ┘  (optional)
    │
/sdd:2-plan ─── synthesize plan
    │
/sdd:2-tasks ── task breakdown ──────── sets READY_GO
    │
    ├── /sdd:3-implement ─ build tasks  ┐
    ├── /sdd:3-check ───── drift detect ├── implementation loop
    └── /sdd:3-review ──── code review  ┘
    │
/sdd:3-verify ── acceptance gate ────── sets DONE
    │
/sdd:4-consolidate ── archive & handover

Commands

Core Flow

| Command | Phase | Purpose | |---|---|---| | /sdd:0-init | 0 | Bootstrap .project/product/ (once per project) | | /sdd:1-req <feature> | 1 | Capture requirements → sets READY_SET | | /sdd:2-ux <feature> | 2 | UX specification (screens, flows, components) | | /sdd:2-tech <feature> | 2 | Technical design (architecture, APIs, data model) | | /sdd:2-research <feature> | 2 | External library documentation (optional) | | /sdd:2-plan <feature> | 2 | Synthesize implementation plan from all specs | | /sdd:2-tasks <feature> | 2 | Break plan into tasks + test plan → sets READY_GO | | /sdd:3-implement <feature> | 3 | Implement next task (run repeatedly) | | /sdd:3-check <feature> | 3 | Detect spec drift (advisory, run anytime) | | /sdd:3-review <feature> | 3 | Code review against specs and standards | | /sdd:3-verify <feature> | 3 | Final acceptance gate → sets DONE | | /sdd:4-consolidate <feature> | 4 | Archive specs, write handover, update product/ |

Utility

| Command | Purpose | |---|---| | /sdd:status | Project dashboard — all features, gates, progress | | /sdd:health | Structural validation of SDD artifacts | | /sdd:help | Flow cheatsheet | | /sdd:help <skill> | Detailed help for a specific skill |

Gates

Three gates control progression:

| Gate | Set by | Unlocks | |---|---|---| | READY_SET | /sdd:1-req | Phase 2 skills (design, research) | | READY_GO | /sdd:2-tasks | Phase 3 skills (implementation) | | DONE | /sdd:3-verify | Phase 4 (consolidation) |

Gates are behavioral — each skill checks prerequisites and blocks if not met. No separate runtime or CI hook.

Project Structure

SDD generates artifacts in .project/ within your repository:

.project/
  product/                    ← permanent, project-wide
    constitution.md           ← mission, goals, constraints
    tech-stack.md             ← platform, frameworks, libraries
    adrs.md                   ← architecture decision records
    nfrs.md                   ← non-functional requirements
    anti-patterns.md          ← lessons learned
    overview.md               ← repo structure, modules
    handovers/<feature>.md    ← completed feature records
  specs/
    <feature>/                ← per-feature, ephemeral
      req.md                  ← requirements
      ux.md                   ← UX specification
      tech.md                 ← technical design
      research.md             ← library research (optional)
      plan.md                 ← implementation plan
      tasks.md                ← task breakdown
      task-index.json         ← machine-readable task state
      test-plan.md            ← test strategy
    _archive/                 ← completed features
  steering/                   ← conventions (auto-loaded)
    _loader.md                ← steering system loader
    product-context.md        ← always-load product files

Steering System

Steering files are convention documents that load automatically based on scope and trigger mode:

• Global (~/.claude/steering/) — personal conventions across all projects
• Team (plugins/sdd/steering/) — ships with the plugin
• Workspace (.project/steering/) — project-specific

Modes: always (every invocation) or conditional (when match value found in tech-stack.md).

See docs/steering-system.md for details.

Documentation

| Document | Contents | |---|---| | docs/gate-system.md | Gate state machine, validation logic, feature resolution | | docs/steering-system.md | Steering scopes, modes, loader mechanics | | docs/artifact-lifecycle.md | Permanent vs ephemeral artifacts, archival rules | | docs/skill-manifest.md | SKILL.md format, field definitions, context budgets | | docs/decisions.md | Design decisions not captured in individual skills | | docs/troubleshooting.md | Common errors and fixes |

Contributing

SDD is built by Apps with Love AG. Contributions welcome.

Plugin Structure

plugins/sdd/
  .claude-plugin/plugin.json    ← plugin manifest
  skills/<skill>/SKILL.md       ← skill definition + instructions
  skills/<skill>/references/    ← output templates
  skills/<skill>/help.md        ← per-skill help content
  steering/                     ← team-scope conventions

Adding or Editing Skills

1. Edit plugins/sdd/skills/<skill>/SKILL.md
2. Keep frontmatter fields accurate (name, description, trigger phrases)
3. Keep body metadata accurate (Phase, Gate requires/sets, Reads, Writes)
4. Update help.md alongside the skill
5. Add templates in references/ if the skill produces structured output
6. Ensure trigger phrases don't overlap with other skills (see docs/skill-manifest.md)

Key Design Principles

• No runtime. Skills are system prompt injections — gate validation is behavioral, not programmatic.
• 1M context. With Claude Opus 4.6's 1M context window, single-agent execution handles full spec + codebase in one pass.
• Specs are ephemeral. Feature specs live in specs/<feature>/ during development, then archive to _archive/. Only product/ files are permanent.
• Sequential consolidation. Multiple features can be in-flight, but /sdd:4-consolidate runs one at a time.

License

Proprietary — Apps with Love AG.