Case Study · Developer Tooling
Forespec
A standalone, tool-agnostic engine that forces domain foresight before you build a feature, then verifies what actually got built against that foresight — so the expensive discoveries surface in week one, not month three.
The problem
The failure isn't bad code. It's foresight arriving too late.
AI coding tools answer the literal ask. Nothing in the moment forces a stop to interrogate the non-obvious requirements of a feature. Depth is available but not automatic — and under time pressure it biases even harder toward “just answer it.”
You ask for a checkout. You don't know to ask for an atomic stock hold, so it isn't added. Months later, after Stripe is wired and taking real money, the race condition bites.
Now you're doing surgery on a live payment flow to retrofit something that would have been trivial to design in on day one. Forespec's job isn't more horsepower — it's making that interrogation forced, structured, and live.
The loop it keeps live
Point → build → verify → remember — and the foresight stays alive the whole way.
A prompt forgets and walks away after planning. The library compounds and the verifier keeps foresight live— that's the difference between a wrapper and an engine.
Architecture
Five components, one spine.
Refuses to just plan a feature. First interrogates what it touches, the non-obvious requirements, and the ordering that prevents rework — the forced foresight pass that can never be skipped.
Turns the interrogation into a sequenced plan with the dangerous, foundational pieces first — atomic hold before Stripe wiring, data-model shape before features built on it.
The unit of work is a feature with checkable completion criteria. Each gotcha becomes a concrete, verifiable checkpoint with a stable, namespaced id that is a permanent contract.
Reads the real repo and reconciles it against the checkpoints. A reasoning layer catches the fuzzy things; a deterministic assertion layer backstops what is mechanically checkable.
Every gotcha is saved as a transferable pattern, walled off from the never-leaves-the-project instance data. The pattern compounds across features and projects; the instance never travels.
Does the verifier tell the truth?
The whole tool rests on one number: how often the grader lets a bad thing through.
A labeled good/bad fixture corpus measures the reasoning verifier's precision, recall, and — the one that matters — its false-green rate. Real grading runs against a validated bar with an ANTHROPIC_API_KEY; without one it falls back to a deterministic keyword baseline that is honest about notbeing a grader to trust. “Is the verifier trustworthy?” becomes a number, not a hope.
You don't have to take that on faith. forespec demo runs a zero-setup, no-API-key walkthrough of a graded run in about 20 seconds — rendered through the same code path as a live verify, against a bundled vulnerable-checkout example, so the demo can never drift from real output. The full CLI installs in one command: npx forespec.
A composable standard
One shared checkpoint library. Every archetype composes it.
Checkpoints are authored once in the library and composed per archetype. A fix to a shared checkpoint lifts every archetype at once, and each new archetype reuses instead of copies. The portfolio archetype is the proof: a whole standard with nothing new to author.
Principles — true from commit #1
Build order — verifier first, shell last