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 trackingCreate 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
- Ask the user what they want to build and at what VSDD intensity level
- Create
vsdd/tracking directory - Enter Phase 1 — load references/phase1-spec.md
- 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
- Spec Supremacy — the spec is the highest authority below the human. Nothing exists without tracing to the spec
- Red Before Green — no implementation until a failing test demands it. Do NOT write implementation and tests simultaneously
- Anti-Slop Bias — the first "correct" version is assumed to contain hidden debt. Trust is earned through adversarial survival
- Fresh-Context Adversary — adversarial reviews use sub-agents with no prior conversation context to prevent politeness drift
- Four-Dimensional Convergence — not done until specs, tests, implementation, and verification have all independently survived review
- 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
- 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 ResultAt any point, answer: *"Why does this line of code exist?"* by tracing back to a spec requirement.