Verified Spec-Driven Development (VSDD)

Specs define what. Tests enforce how. Adversarial verification ensures nothing was missed.

Pipeline Overview

Phase 1: Spec Crystallization ─── define the contract, verification strategy, adversarial spec review
    │
Phase 2: TDD Implementation ──── red → green → refactor, strict test-first discipline
    │
Phase 3: Adversarial Roast ────── Claude sub-agent tears apart spec fidelity, test quality, code quality
    │
Phase 4: Feedback Loop ────────── route flaws back to the right phase, iterate
    │
Phase 5: Formal Hardening ─────── mutation testing, fuzzing, static analysis, optional formal proofs
    │
Phase 6: Convergence ──────────── exit when adversary hallucinates flaws, mutation score ≥ 95%

Each phase is a gate. Do not advance until the current phase's exit criteria are met.

Roles

Role	Entity	Function
Architect	Human	Strategic vision, domain expertise, acceptance authority
Builder	Claude (primary)	Spec authorship, test generation, implementation, refactoring
Adversary	Claude (sub-agent, fresh context)	Hyper-critical reviewer. Zero tolerance. Fresh context every pass

Tracking

Track all VSDD artifacts in a local vsdd/ directory at the project root:

vsdd/
├── spec.md          # Behavioral spec + verification strategy
├── review-log.md    # Adversarial review findings and resolutions
└── status.md        # Phase status and convergence tracking

Create vsdd/ at the start of Phase 1. Update status.md at each phase transition.

Phase Details

Each phase has detailed instructions in a reference file. Load the relevant reference when entering that phase.

Phase	Reference	Load when
Phase 1: Spec Crystallization	references/phase1-spec.md	Starting a new VSDD cycle
Phase 2: TDD Implementation	references/phase2-tdd.md	Spec is approved, ready to write tests
Phase 3-4: Adversarial Review & Feedback	references/phase3-4-adversarial.md	All tests green, ready for roast
Phase 5-6: Hardening & Convergence	references/phase5-6-hardening.md	Adversarial review converged, ready to harden

Quick Start

1. Ask the user what they want to build and at what VSDD intensity level
2. Create vsdd/ tracking directory
3. Enter Phase 1 — load references/phase1-spec.md
4. Progress through phases sequentially, loading references as needed

Intensity Levels

Not every feature needs full ceremony. Ask the user or infer from context:

Level	Phases	When
Full	1 → 2 → 3 → 4 → 5 → 6	Correctness-critical: finance, security, infrastructure
Standard	1 → 2 → 3 → 4 (mutation testing only from Phase 5)	Most production features
Light	1 (spec only) → 2 → quick adversarial pass	Rapid development with guardrails

Default to Standard unless the user specifies otherwise or the domain demands Full.

Core Principles

1. Spec Supremacy — the spec is the highest authority below the human. Nothing exists without tracing to the spec
2. Red Before Green — no implementation until a failing test demands it. Do NOT write implementation and tests simultaneously
3. Anti-Slop Bias — the first "correct" version is assumed to contain hidden debt. Trust is earned through adversarial survival
4. Fresh-Context Adversary — adversarial reviews use sub-agents with no prior conversation context to prevent politeness drift
5. Four-Dimensional Convergence — not done until specs, tests, implementation, and verification have all independently survived review
6. No Redundant Tests — do not test what the type system already ensures. Tests should cover runtime behavior, invariants, and edge cases that types cannot express; avoid asserting facts that are already in the type signature
7. Testing Trophy — most tests should be integration tests (most bang for buck). Fewer unit tests; fewer e2e tests reserved for critical user journeys. Use mutation testing (e.g. Stryker for TypeScript/JavaScript) in Phase 5 to verify tests actually catch bugs

Contract Chain

Every artifact must be traceable:

Spec Requirement → Test Case → Implementation → Adversarial Review → Verification Result

At any point, answer: "Why does this line of code exist?" by tracing back to a spec requirement.