Spec First Development Enforcer

The Problem

Your AI coding agent generates 200 lines of code, declares victory, and you discover at review time that it missed three edge cases, ignored input validation, and built the wrong interface. By then, you've spent more time reviewing bad code than writing a spec would have taken. The agent never wrote a test — because nothing forced it to.

What You Get

• Pre-hook gate that blocks code edits until a test file or spec document exists for the feature being built
• Spec validation engine that checks edge case coverage, behavioral completeness, and internal consistency before implementation begins
• Spec-anchored implementation — every code change maps to exactly one spec item, keeping agent output contractually bounded
• Post-implementation audit that runs the full test suite, checks for regressions, and verifies every code path has a matching spec entry
• Multi-language enforcement — works with TypeScript (describe/it), Python (pytest), Go (testing.T), Rust (#[test]), and Java (@Test) test frameworks
• Anti-retrofit detection — identifies when an agent writes code first and backfills tests, which is TDD theater, not real TDD

Why This Beats Prompting It Yourself

"Write tests first" is the most ignored instruction in AI coding. The agent acknowledges it, then writes code anyway because nothing structurally prevents it. This skill inserts a hard gate — no spec, no code — so compliance isn't optional. Without it, your prompt becomes a suggestion the agent forgets by line 10.

Example Session

You: "Add a payment processor that handles Visa, Mastercard, and AMEX with idempotency"

Agent: "Before implementing, I need a spec. Here's what I'm creating:

• tests/test_payment_processor.py with 5 test cases:
  1. Valid card charges successfully
  2. Expired card raises CardExpiredError
  3. Insufficient funds raises InsufficientFundsError
  4. Duplicate transaction IDs are rejected (idempotency)
  5. Zero-amount transactions raise ValueError
• Spec document defining interface: process_payment(transaction) -> PaymentResult
• Each implementation change maps to one test. Implementation proceeds only after spec validation passes."

Use Cases

• Starting a new API endpoint where input validation edge cases matter
• Building data processing pipelines that must handle malformed input gracefully
• Enforcing TDD discipline on a team where AI agents generate 50%+ of code
• Adding payment, auth, or other security-critical features that demand exhaustive coverage
• CI/CD integration where test coverage is a merge gate and you need spec-level accountability

Known Limitations

This skill adds a thinking step before every implementation — for trivial one-line fixes or config changes, it will slow you down. Skip it for tasks under 20 lines where the behavioral contract is obvious. The spec document format works best for imperative code; highly reactive or event-driven architectures may need adapted spec formats.