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

On a first install 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 (<base>/sdd/steering/ — the base you chose), and merges the SDD hooks into settings.json.

Updating = re-run the same command (npm @latest resolves the newest version; the installer is idempotent). An existing install is detected automatically: no scope question — SDD updates in place, shows the version delta and what it will refresh, and asks a single confirm (-y skips it). Your .project/ artifacts are never touched.

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. Break into tasks (resolves UX↔tech conflicts, writes the manual test checklist)
/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 → tech.md Decision Log)
    │
/sdd:2-tasks ── resolve UX↔tech conflicts + 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

Agency projects (discovery upfront): client work often runs phase 0–1 as a batch instead of one feature at a time: /sdd:0-roadmap → /sdd:1-req loop (one spec per epic) → /sdd:1-estimate offer (release-wide offer CSV) → client acceptance → /sdd:1-handoff (PM→Dev handover) → per-epic dev flow as above. No new gates — see docs/gate-system.md "Agency Flow".

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 → tech.md Decision Log) | | /sdd:2-tasks <feature> | 2 | Resolve UX↔tech conflicts, break into tasks + manual test checklist → 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:go [feature] | Advance the flow — resolves the next legal step and runs it (the one command to remember) | | /sdd:quick <change> | Fast lane for small fixes (≤2 files, no new surface) — same gates, one sitting | | /sdd:status | Project dashboard — all features, gates, progress | | /sdd:health | Structural validation of SDD artifacts | | /sdd:realign | Fix structural drift that /sdd:health reports | | /sdd:sync | Sync specs with a GitLab issue tracker — push specs, pull client comments/acceptances (see docs/issue-sync.md) | | /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.

DONE is enforced, not self-reported (v0.2). Beyond review-approved + tests-green, /sdd:3-verify requires an integration smoke (real device/simulator against a real backend, backed by reproducible evidence) and a contract check (every endpoint has a consumer and vice versa; shared sentinels/enums/models from one source). A check passes only with an artifact a third party can re-run — no "I confirm it passes". See docs/gate-system.md and the rationale in docs/lean-flow.md.

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 + Decision Log
      tasks.md                ← task breakdown + manual test checklist
      task-index.json         ← machine-readable task state (generated from tasks.md)
    _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 (<base>/sdd/steering/, source plugins/sdd/steering/) — ships with the plugin, installed into whichever base you chose
• 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.