Spec Driven Design

Overview

Turn an existing application into business specifications, fix its architectural problems at the specification level, and regenerate the application from those specifications alone.

The Spec Driven Design (SDD) pipeline is delivered as five agent skills that run in a coding agent (Claude Code or Kiro) against a live vFunction MCP connection. This guide covers the five skills in the order they execute: what each one needs, what it produces, and what to type to invoke it.

Pipeline at a Glance

The five SDD Pipeline Agent Skills are:

  1. sdd-extract-specs. This is a required step that takes specs from code
  2. sdd-fix-architecture. This is an optional step that fixes smells in specs
  3. sdd-sanitize-specs This is a required step that de-biases the tree
  4. sdd-codegen. This is a required step that takes code from specs
  5. sdd-apply-changes. This is an as-needed step that applies pending fixes

Put another way, these five SDD Pipeline Agent Skills do the following:

# Skill Turns this Into this vFunction MCP needed
1 sdd-extract-specs Application code and runtime analysis A specs tree Yes
2 sdd-fix-architecture A specs tree and vFunction TODOs Proposed change deltas Yes
3 sdd-sanitize-specs A raw specs tree A de-biased copy, ready for generation No
4 sdd-codegen A sanitized specs tree A runnable codebase No
5 sdd-apply-change One delta and generated code The code with that change made No

Prerequisites

See the full list of prerequisites.

SDD Pipeline Skills 1-5

Rules That Hold Across The Pipeline

  • One specs root, everywhere. Every stage of Step 1 must use the identical directory, or later stages cannot find what earlier ones produced.
  • Fix before sanitize. See Step 2. This is the one ordering constraint that is easy to get wrong and expensive to notice late.
  • Deltas are proposals until Step 5. sdd-fix-architecture writes them, sdd-sanitize-specs carries them through, sdd-codegen deliberately ignores them, and sdd-apply-change is the only step that makes one real. If you expected generated code to contain a fix and it does not, that is by design. Check the pending list.
  • Quoted reasons matter. Where a skill reports something it could not resolve, it quotes rather than paraphrases. Those quotes are the content of the decision you now have to make; a summary of a blocker is not something anyone can act on.

Quick Reference

What each skill asks you for
Skill Inputs
sdd-extract-specs Specs root; domain name (one-domain mode only)
sdd-fix-architecture Specs tree; codebase (required); which smells to cover (default: all four)
sdd-sanitize-specs Specs tree; output location; codebase (optional); report path
sdd-codegen Specs tree; which technology-decisions file governs; workspace for the generated code
sdd-apply-change Generated repository; specs tree; the change’s slug
Where each artifact comes from
Artifact Written by Read by
<domain>/ artifact sets Step 1, stage 1 Steps 2, 3, 4
ubiquitous-language.md (root) Step 1, stage 2 Steps 3, 4
technology-decisions*.md Step 1, stage 3 Steps 3, 4
changes/pending/<slug>/ Step 2 Steps 3, 5
Sanitized specs tree Step 3 Step 4
openspec/changes-applied.md Steps 4, 5 Step 5
openspec/implementation-map/ Steps 4, 5 Step 5

Troubleshooting

Symptom Cause Fix
Codegen refuses the tree Step 3 was skipped Sanitize it yourself, or run sdd-sanitize-specs and point codegen at the copy
Fixers fall back to reading the codebase Step 2 was run after Step 3 Fix the raw tree, then sanitize
Generated code lacks an expected fix The fix is pending, by design Apply it with Step 5
“No prompt obtainable” on a finding Stale TODO or lookup failure Re-run the vFunction analysis and retry
Glossary looks incomplete Stage 2 ran on a partial tree Extract the rest, delete the consolidated glossary, and rerun stage 2
A skill is not offered at all Skills are not installed in this project Run vf_mcp download-skill from the project root, then reload the agent

Updated on 06 Oct 2026