vsdd-factory

vsdd-factory

Verified Spec-Driven Development (VSDD) -- a dark factory for software, packaged as a Claude Code plugin.

---

What is VSDD?

Verified Spec-Driven Development is a software engineering methodology that fuses three proven paradigms into a single AI-orchestrated pipeline:

• Spec-Driven Development (SDD): Define the contract before writing implementation. Behavioral contracts, verification properties, and domain models are the product -- code is the disposable artifact that implements them.
• Test-Driven Development (TDD): Tests are written before code. Red, Green, Refactor. No implementation code exists until a failing test demands it.
• Verification-Driven Development (VDD): Subject all surviving artifacts to adversarial review until the reviewer is forced to hallucinate flaws. Convergence is measured quantitatively across five dimensions, not declared subjectively.

The methodology produces software with full traceability from product brief through domain model, behavioral contracts, acceptance criteria, test cases, implementation, and formal proofs. Every line of code can answer "why does this exist?" by tracing back to a spec requirement.

The VSDD contract chain traces every artifact through four specification levels:

L1 Product Brief
  -> L2 Domain Spec Capability (CAP-NNN)
    -> L3 Behavioral Contract (BC-S.SS.NNN)
      -> Story Acceptance Criterion (AC-NNN)
        -> Test Case
          -> Implementation
            -> L4 Verification Property (VP-NNN)
              -> Formal Proof

Quality is not declared by the builder -- it is measured by five independent convergence dimensions (spec, tests, implementation, verification, holdout), each gated by quantitative thresholds. The pipeline terminates when further adversarial review produces only hallucinated findings.

What does this plugin do?

The vsdd-factory plugin installs the complete VSDD pipeline into any Claude Code session:

• Brownfield ingestion -- analyze existing codebases before rebuilding or extending them
• Spec crystallization -- guided creation of product briefs, domain specs, PRDs, behavioral contracts, and architecture docs
• Story decomposition -- break specs into dependency-ordered, wave-scheduled implementation stories
• TDD delivery -- implement stories through specialist subagents (test-writer, implementer, demo-recorder, PR manager) with enforced Red Gate discipline
• Adversarial refinement -- fresh-context review by a different model family, iterated until convergence
• Holdout evaluation -- hidden acceptance scenarios evaluated by an information-asymmetric agent
• Formal hardening -- Kani proofs, fuzz testing, mutation testing, security scanning
• Convergence gating -- quantitative five-dimensional convergence assessment
• Release management -- changelog generation, merge to main, tagging, GitHub release

Quick start

Install from the marketplace

/plugin marketplace add drbothen/claude-mp
/plugin install vsdd-factory@claude-mp

Migrating from a pre-rc.7 install? The marketplace was at drbothen/vsdd-factory through rc.6 but suffered from a silent install bug (see docs/guide/plugin-marketplace-architecture.md for the full story). Run /plugin marketplace remove vsdd-factory first, then add drbothen/claude-mp and install via the new marketplace as shown above.

Update to latest version

/plugin marketplace update claude-mp
/plugin update vsdd-factory@claude-mp

Start every session with

/vsdd-factory:factory-health          # verify .factory/ worktree is mounted
/vsdd-factory:setup-env               # verify toolchain (first time or after changes)

Then read .factory/STATE.md to understand where the pipeline left off.

Local development mode

claude --plugin-dir ./plugins/vsdd-factory

Pipeline at a glance

graph TD
    P0["Phase 0\nBrownfield Ingest"]
    P1["Phase 1\nSpec Crystallization"]
    P2["Phase 2\nStory Decomposition"]
    P3["Phase 3\nTDD Implementation"]
    P4["Phase 4\nHoldout Evaluation"]
    P5["Phase 5\nAdversarial Refinement"]
    P6["Phase 6\nFormal Hardening"]
    P7["Phase 7\nConvergence & Release"]

    P0 -->|"existing codebase"| P1
    START(("New project")) -->|"greenfield"| P1
    P1 -->|"specs locked"| P2
    P2 -->|"stories ready"| P3
    P3 -->|"wave merged"| P4
    P4 -->|"holdout pass"| P5
    P5 -->|"findings fixed"| P3
    P5 -->|"converged"| P6
    P6 -->|"proofs pass"| P7
    P6 -->|"issues found"| P5
    P7 -->|"not converged"| P3
    P7 -->|"CONVERGED"| RELEASE(("Release"))