Chapter 3: The SDD Maturity Spectrum: From Disposable Specs to Executable Code

By Muhammad Riaz

Evolution, Not Revolution

Adopting Spec-Driven Development is not an all-or-nothing proposition. You do not need to pause production for a month to completely rewrite your team's engineering practices, retool your CI/CD pipelines, or mandate bespoke CLI frameworks overnight.

Instead, SDD exists on a Maturity Spectrum.

Organizations and individual developers progress through this spectrum naturally as their codebases grow and their reliance on AI agents increases. Moving up the maturity ladder is simply a process of turning implicit developer knowledge into explicit, persistent artifacts that AI models can read, follow, and verify.

     MATURITY LEVEL 0            MATURITY LEVEL 1            MATURITY LEVEL 2            MATURITY LEVEL 3
┌───────────────────────────┐ ┌───────────────────────────┐ ┌───────────────────────────┐ ┌───────────────────────────┐
│     Ad-Hoc Prompting      │ │        Spec-First         │ │       Spec-Anchored       │ │      Spec-as-Source       │
├───────────────────────────┤ ├───────────────────────────┤ ├───────────────────────────┤ ├───────────────────────────┤
│ • Conversational chat     │ │ • Markdown planning files │ │ • Checked into Git        │ │ • Executable pipeline     │
│ • No persistent artifacts │ │ • Discarded post-merge    │ │ • Linked to PR reviews    │ │ • Multi-agent orchestration│
│ • High Ambiguity Tax      │ │ • Zero long-term debt     │ │ • Living documentation    │ │ • CI/CD automated gates   │
└───────────────────────────┘ └───────────────────────────┘ └───────────────────────────┘ └───────────────────────────┘

Understanding where you—and your organization—currently sit on this spectrum is the first step toward building a predictable, scalable AI engineering workflow.

Level 0: Ad-Hoc Conversational Prompting (The Baseline)

How It Works

At Level 0, developers interact with AI through ephemeral chat windows inside IDEs (like Cursor or Windsurf) or web interfaces (like Claude or ChatGPT). Prompts are typed off-the-cuff, and context is fed on an ad-hoc basis by tagging files (@filename.ts) or highlighting lines of code.

Practical Reality

• Artifact Lifetime: Zero seconds after the chat window is closed.

• Reproducibility: None. Prompting the same assistant tomorrow with the exact same question yields different code.

• Team Synergy: Non-existent. What Developer A prompts the AI in their private chat window is invisible to Developer B who has to maintain that code two weeks later.

When It Breaks

Level 0 works fine for single-file utility functions, regex crafting, or quick syntax translations. However, as soon as a feature touches multiple services or requires strict adherence to internal domain patterns, Level 0 incurs an exorbitant Ambiguity Tax.

Level 1: Spec-First (The Disposable Blueprint)

How It Works

Before opening an AI chat or running a coding agent, the developer takes 5 to 10 minutes to write a scratchpad specification document in markdown (e.g., temp_spec.md).

This document explicitly defines three things:

1. The Target Outcome: What success looks like.

2. Technical Constraints: Which libraries, DB models, or existing helper utility functions must be used.

3. Out-of-Scope Boundaries: What the AI is forbidden from touching or generating.

The developer feeds this scratchpad file into the AI tool as the primary context prompt, receives the generated code, verifies it locally, and deletes (or ignores) the scratchpad file before committing the feature code to Git.

Practical Case Study: Refactoring a Microservice Route

A developer needs to update a legacy user-settings service to support multi-factor authentication (MFA) preferences.

Instead of typing "Update settings route to support MFA", the developer creates a temporary mfa_spec.md file:

# Temporary Spec: Add MFA Preferences to User Settings

## Goal
Extend `/api/v1/user/settings` to store and return MFA configuration flags.

## Constraints

- MUST use existing `UserPreference` PostgreSQL model in `src/db/models/user.ts`.

- DO NOT create new database migrations; use the existing `metadata` JSONB column.

- Response payloads MUST conform to `UserResponseDTO` in `src/types/user.dto.ts`.

## Out of Scope

- DO NOT implement QR code generation or SMS sending logic in this PR.

The developer prompts their AI agent: "Execute the requirements in mfa_spec.md."

Because the boundaries were clear, the AI generates precisely the code needed in a single pass without introducing unneeded dependencies or unnecessary database migrations.

Practical Reality

• Artifact Lifetime: Ephemeral (used during development, then discarded).

• Impact: Cuts downstream refactoring time by up to 70%.

• Best Used For: Solo developers, quick bug fixes, or small feature additions in established codebases.

Level 2: Spec-Anchored (Persistent & Version-Controlled)

How It Works

At Level 2, specifications are no longer disposable. They are committed directly into the project’s Git repository inside a dedicated folder structure (such as .specs/ or docs/specs/).

The specification lives alongside the source code it describes. During code reviews (Pull Requests), reviewers check both the implementation code and the specification document to ensure they match. If requirements change mid-sprint, the specification file is updated first, and the AI agent is instructed to refactor the code to align with the updated specification.

Practical Case Study: Team-Wide Feature Development

An engineering team is building a subscription tier management system across three microservices.

  project-root/
├──    .specs/
│    └──    004-subscription-tiers.md  <-- Version-controlled spec
├──    src/
│    └── ...

1. The Tech Lead drafts .specs/004-subscription-tiers.md during sprint refinement and submits it as a PR.

2. The team reviews and merges the specification file before any code is generated.

3. Multiple developers use the merged spec file as the baseline context for their respective AI coding agents.

4. During code review, reviewers evaluate the PR against the specification contract: "Does the generated code fulfill every requirement in

   .specs/004-subscription-tiers.md?"

Practical Reality

• Artifact Lifetime: Permanent (lives in Git as living documentation).

• Impact: Eliminates pattern fragmentation across teams; ensures human architects remain in complete control of project direction.

• Best Used For: Engineering teams, enterprise projects, and cross-functional feature builds.

Level 3: Spec-as-Source (Executable & Agentic Orchestration)

How It Works

At Level 3, the human developer transitions fully from a code-writer to a system architect and evaluator. Specifications are written in structured, machine-parsable formats using standardized toolkits (such as GitHub Spec Kit (specify), BMAD, or agentic framework configs).

The specification document is not merely read by an AI assistant in an editor; it is fed into an automated, multi-agent orchestration pipeline.

┌─────────────────────────────────────────────────────────────────────────────┐
│                       LEVEL 3 EXECUTION PIPELINE                            │
│                                                                             │
│ [ Human Spec ] ──> [ Architect Agent ] ──> Generates Plan & Task Breakdown  │
│                           │                                                 │
│                           ▼                                                 │
│                    [ Coder Agent ]     ──> Implements Code in Isolation     │
│                           │                                                 │
│                           ▼                                                 │
│                    [ Tester Agent ]    ──> Runs Unit & Integration Tests    │
│                           │                                                 │
│                           ▼                                                 │
│                    [ Human Review ]    ──> Final Approval & Merge           │
└─────────────────────────────────────────────────────────────────────────────┘

1. Parser & Planner: The CLI toolkit parses the .spec.md file and spawns a Plan Agent to build a plan.md file mapping out file structural impacts.

2. Task Execution: A Coder Agent executes atomic items sequentially from a tasks.md breakdown.

3. Automated Gate: A Reviewer/Verifier Agent runs test suites, checks security invariants, and attempts to break the generated code before presenting a final Pull Request to the human developer.

Practical Reality

• Artifact Lifetime: Executable source of truth; code is a generated artifact of the spec.

• Impact: Hyper-accelerated feature output with continuous automated compliance and near-zero Ambiguity Tax.

• Best Used For: Advanced engineering orgs, autonomous agent workflows, and large-scale application architecture.

Comparing the Spectrum Levels

Practical Exercises: Assessing Your Current Maturity

1. Determine Your Baseline Level: Reflect on your team's last three completed features. Which level on the spectrum best describes how those features were delivered?

2. Execute a Level 1 Upgrade: On your next task, refrain from opening an AI chat window immediately. Spend 10 minutes writing a scratchpad .md file detailing goals, hard constraints, and explicit exclusions. Prompt your AI tool using only that file and measure the difference in first-pass accuracy.

3. Plan Your Level 2 Migration: Create a .specs/ folder in your primary project repository. Establish a convention for naming spec files (e.g., 001-feature-name.spec.md) and discuss anchored reviews with your team.

Next Steps

To execute Spec-Driven Development at Level 2 or Level 3 effectively, you need a concrete blueprint for organizing your work.

In Chapter 4, we will introduce the core operational backbone of SDD: The Artifact Triad —mastering the structure, purpose, and interconnections between .spec.md, .plan.md, and .tasks.md.