Spec-driven development solves a real problem: an AI assistant with no spec will happily build the wrong thing, fast. Give it a spec and it builds the right thing. Simple.
Except that's not where most SDD setups stop. The actual flow looks like this by hand:
write spec → review spec → plan tasks → implement → review code → run QA → push Seven steps. Seven moments where a human has to remember to run the next thing, check the output of the last thing, and decide whether to continue. In practice, that's where SDD quietly falls apart — not because the spec was wrong, but because nobody re-ran the drift check before the fourth commit, or the "review" step got skipped because the diff "looked fine."
SDD doesn't fail on the spec. It fails on the handoffs between steps. The fix isn't a better spec format — it's removing the handoffs.
What "driven" actually means here
I built a driver skill on top of my ai-project-boilerplate template. It doesn't replace the individual skills (spec-driven-development, tdd-loop, e2e) — it coordinates them, so a human never has to be the glue between steps.
One command: /ship-feature.
It maps the feature onto 5 layers, each one a single clean commit:
| # | Layer | Does | Commit prefix |
|---|---|---|---|
| 1 | spec | Actors, use cases, tasks, graphify context, mockup if the UI needs one — then a hard human checkpoint before anything else runs | spec(feature): |
| 2 | api | Backend-contract tasks (Rails/Python), TDD red→green | feat(feature): api — |
| 3 | app | UI/consumer tasks, TDD red→green | feat(feature): app — |
| 4 | qa | E2E coverage via a planner → generator → healer pipeline | test(feature): e2e — |
| 5 | stats | Metrics report, brain update, PR | chore(feature): stats — |
The part that actually matters is between the layers, not inside them: a gate.
scripts/metric-logger.sh report Before the driver moves from api to app, from app to qa, and once more before stats, it runs this and stops if the report's alerts contains:
-
ai_blob_score too high— a heuristic over the diff for 40+ line functions with no tests. Instead of "I'll clean this up in review," the driver runs/ponytail-reviewright there as a refactor pass and re-checks until it's clear. -
spec_drift: check manually— files changed that the spec's task list doesn't account for. The driver actually reads the spec's task breakdown and checks every touched file against it, instead of letting an unrelated change ride along into the commit because nobody looked.
Same two thresholds that were already written down in CLAUDE.md as rules. The difference is the driver enforces them mid-flight, between layers, instead of hoping a human remembers to check them at review time — which is the same gap that makes "review step" fail silently in the hand-chained version.
The one human checkpoint that's non-negotiable is at the end of layer 1: the driver presents the spec and stops. Not a prompt it can talk itself past — it ends its turn and waits. Everything after that approval runs end-to-end.
How it starts
Review, adjust and apply !
What this looks like end to end
The evidence, not the pitch
Talk is cheap, so here's an actual feature shipped through this exact flow: App Scaffold — ai-starter#3. Five tasks, two stacks (Rails 8.1 API + React 19.2), fully dockerized, signup/login/logout wired end to end and verified with Playwright.
The PR body isn't hand-written — it's generated by the stats layer from the session's own metrics:
| Metric | Value |
|---|---|
| Session time | 5.7 min |
| Session tool calls | 72 |
| Tasks completed | 5 / 5 |
| AI blob score | 3 / 20 max |
| Session cost (real, from transcript) | $48.37 |
Test evidence, same PR:
| Suite | Result |
|---|---|
| rspec | 15 examples, 0 failures, 2 pending |
| vitest | 18 passed |
| playwright | 5 passed (3.3s) |
The brain vault's own comparison note for this feature puts the human estimate at 17 hours across the 5 tasks against this session. I'm deliberately not printing the resulting multiplier here — the note itself flags that the session timer it's computed from is a narrow internal clock, not reliable wall-clock time, so the number is directional at best. What I'll stand behind instead: 5/5 tasks shipped, a 3/20 blob score (nothing needed a refactor pass), zero failing tests, and a PR whose body nobody hand-wrote — because the driver generated it from the same report it gated layers on.
Where this breaks
- It's not magic process compliance. The gates catch measurable drift (files touched outside the spec's tasks, functions past a line-count heuristic). They don't catch a subtly wrong business decision baked correctly into clean code — that's still the human checkpoint's job at layer 1.
- A feature with no backend contract or no UI skips that layer — the driver isn't forcing five commits onto a two-task feature.
- The
ai_blob_scoreheuristic is a line-count proxy, not real complexity analysis. It's cheap and it's caught real cases, but it's not a static analyzer.
Try it
The skill, the gate script, and the whole boilerplate (skills, agents, hooks, Obsidian brain vault) are open: aleguro/ai-project-boilerplate. /ship-feature is the entrypoint; every layer's skill still works standalone if you only need one piece.
