Verification-Driven Development (VDD) Skill

TLDR: Closed-loop verification = build fast, with proof.

Coding agents love to say "done" after reading their own diff. VDD is a small skill that makes an agent earn that word: define executable checks up front, run the real operator path, inspect real outputs, and close with observed evidence — or honestly hand the last step to you.

This skill is great if you find yourself:

• pasting stack traces back to your coding agent
• getting code that compiles but doesn't match your spec
• being unsure if and what the agent actually ran

VDD is explicit opt-in. Invoke it by name when a task deserves proof; it stays out of the way otherwise.

What It Enforces

• No completion claims without executed commands and observed evidence.
• Checks planned up front in a small table (criterion → command → pass signal), and the closeout reports against that same table — no quietly moving the goalposts after seeing a result.
• Every check is seen failing once (red → green): a check that was never red may be passing for reasons unrelated to the change.
• Evidence as raw + reading: each verdict pairs the verbatim observed output with a one-line interpretation, so a human can audit it in seconds and a future agent session can re-run it as-is.
• Verification where the runtime lives: SSH for remote hosts, a real browser signal for UI claims, corroboration for screenshots.
• A cleanup gate: everything verification spawned gets torn down and the teardown proven, or the task closes BLOCKED.
• Honest terminal states: VERIFIED ✅, READY FOR HUMAN VERIFICATION 🧑‍🔬, or BLOCKED ⛔ — with a compact evidence block in chat, like:

Final State: VERIFIED ✅
Goal: /health returns readiness payload after fix
Results by Criterion:
  health endpoint ready → PASS
    check:    curl -sSf http://127.0.0.1:8000/health @ local
    red:      same command on pre-fix commit → HTTP 500
    observed: HTTP 200 {"status":"ready","migrations":"applied"}
    reading:  server reports ready and the new migration ran
Cleanup: COMPLETE — docker ps shows no verification containers
How YOU Can Run This:
  make serve && curl -sSf localhost:8000/health → expect HTTP 200

The whole skill is one SKILL.md plus an anti-pattern checklist the agent self-checks against before claiming any terminal state. No validators, manifests, or report pipelines — the agent spends its effort on evidence, not paperwork.

Install

Copy the skill folder into your agent's skills directory:

# Claude Code (user-level)
cp -r verification-driven-development ~/.claude/skills/

# Codex
cp -r verification-driven-development ~/.codex/skills/

For a single project, copy it into the project's .claude/skills/ (or equivalent) instead.

Invoke

Ask for it by name: VDD, $verification-driven-development, or /verification-driven-development depending on your tool.

Good Fit / Bad Fit

Good fit:

• API bugs where "200 OK" is not enough
• UI flows that need a real browser signal
• Docker or deploy work where readiness and cleanup matter
• Data or ML tasks that need grounded evaluation evidence
• Remote SSH work where the decisive behavior happens off-box

Bad fit:

• trivial copy edits and docs-only changes
• low-stakes static rewrites where no runtime claim is being made

License

Apache License 2.0. See LICENSE.