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

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.

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](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:

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.