Spec Driven Development

Spec-Driven Development for AI Software Factories

A methodology for building software where specifications are the executable input to an AI code generation pipeline. The factory model: specs are blueprints, AI agents are the assembly line, verification is quality control, and gates catch defects before they compound.

Pipeline Overview

INCEPTION → [SPECIFY] → REVIEW → [DECOMPOSE] → REVIEW → [IMPLEMENT] → REVIEW → [VERIFY] → DELIVER
                 ↑         ↑          ↑            ↑           ↑           ↑          ↑         ↓
            Phase 1    Gate 1    Phase 2       Gate 2    Phase 3      Gate 3    Phase 4   Gate 4

Each phase passes through a gate before the next begins. A defect caught at Gate 1 costs minutes to fix; the same defect found at Gate 4 costs hours.

SDD Core Principles

1. Precision over clarity. A precise-but-dense spec is better than a readable-but-ambiguous one. The AI cannot ask for clarification — it implements one interpretation at random.
2. Completeness over brevity. Every missing acceptance criterion is a missing feature. Specifying an edge case upfront costs minutes; discovering it in production costs hours or days.
3. Testability over descriptiveness. An AC that cannot produce CLEAR PASS or CLEAR FAIL is not an AC — it's a hope.
4. Gates catch defects early. A Gate 1 (spec review) fix costs minutes. A Gate 4 (acceptance review) fix costs hours — the entire implementation may need to be discarded.
5. Spec is the single source of truth. Every downstream artifact traces back to the spec. Deviations are defects unless explicitly documented.
6. Spec IS the test (when possible). Gherkin-style ACs serve double duty as test cases. No separate test writing required.

Loading Guide

Methodology Quick-Pick

Not sure which spec methodology fits your situation? Use this quick reference table (load references/methodology-matrix.md for full depth):

Composite approach: Most systems need 3-4 of these working together. REST APIs get OpenAPI, event streams get AsyncAPI, critical behavior gets Gherkin scenarios, and cross-team interface boundaries get DbC assertions.

Templates

Scripts

Trigger Conditions

Load this skill when:

• You're building a software factory — a system where AI agents produce code from structured specifications through a gated pipeline
• You're designing or refining an AI code generation pipeline where specs drive implementation
• You need to write a specification that an AI agent (not just a human) will consume
• You're evaluating spec methodologies (BDD, Formal, OpenAPI-first) for a project
• You need templates for SPEC.md, TASK-PLAN.md, REVIEW.md, or VERIFICATION.md
• You're reviewing or verifying AI-generated code against its specification

Quick Reference: Pipeline Steps

For deeper methodology context, load references/sdd-overview.md (philosophy) or references/ai-factory-pipeline.md (full pipeline detail with parallel execution).

Pipeline Mode & Entry Points

Where to Enter the Pipeline

You don't always start at SPECIFY. Enter at the phase matching what you already have:

Which Pipeline Mode to Use

Not every change needs all 4 gates. Choose your mode:

Rule of thumb: If you know the fix in under 60 seconds and it touches one file, use Lightweight mode. If you're not sure what the right solution is, use Full mode — the gates will catch your mistakes early.

Gate Recovery & Revision

What happens when a gate rejects your artifact? The pipeline doesn't stop — it iterates.

The Revision Loop

Artifact submitted → Gate review → REJECTED or CONDITIONS
                                         ↓
                              Return to current phase
                                         ↓
                              Patch specific findings
                                         ↓
                              Resubmit for re-review
                                         ↓
                              APPROVED → next phase

How to Patch, Not Rewrite

Each finding identifies a narrow, fixable defect. Patch at the finding's location:

Re-Review Scope

After patching, the reviewer determines scope:

• Full re-review: Required when REJECTED verdict. The entire artifact is re-evaluated, not just patched sections.
• Targeted re-review: Possible with CONDITIONS verdict. Only the affected findings and surrounding context are reviewed.

Risk of partial fixes: Fixing only BLOCKING findings and ignoring CRITICAL ones guarantees re-rejection at the same gate. The CRITICAL findings that cost minutes to fix at Gate 1 will cost hours if caught at Gate 4.

Common Revision Patterns

When not to use

• A single small change with a clear goal — skip the spec pipeline and implement directly; classify the work first (see bmad).
• You need the control-plane protocol around a pipeline — who owns intent, how work is classified, when autonomy is safe, how failure routes between layers: use bmad for intent contracts, work classification, autonomy gating, and failure routing. SDD supplies the spec format and gate mechanics; bmad supplies the protocol that runs the whole effort.
• The problem itself is unvalidated — route to product-discovery before authoring a spec on top of an unexamined idea.

Tool-Agnostic Design

This skill describes the methodology, not a specific tool. The pipeline works with:

• Claude Code — use CLAUDE.md as spec context, plan-then-implement mode
• Cursor — Plan Mode + .cursorrules for spec context, Agent Mode for implementation
• Hermes Agent — native SDD pipeline (authoring → review → decomposition → verification)
• Devin / OpenHands — task-based implementation from spec-derived task plans
• GitHub Copilot Workspace — issue-driven with spec as structured issue body
• droid (Factory) — task cards from spec decomposition

The templates are format-agnostic (markdown). Adapt the handoff mechanism (CLAUDE.md, .cursorrules, AGENTS.md) to your tool.