Spec-Driven Agentic Development

August 9, 2026

Context

Most of what makes AI-assisted development work or fail happens before a model writes a line of code, and after it stops. The interesting engineering is in the specification, the constraints, the verification and the review — not in the prompt. This is the workflow I use, and the evidence from one run of it. It is deliberately generalised: no client detail, no source code, no repository internals. The honest disclosure is that this portfolio is itself an output of the process described here. The repositioning of this site — its case studies, its messaging, the removal of a superseded section and its entire authentication surface — was carried out as a single goal-driven run under the workflow below.

The workflow

Two things carry most of the weight. The definition of done is written first, and it is a file. Acceptance criteria live in the repository as a checklist, alongside separate documents recording approved messaging, factual boundaries and what may and may not be published. An agent may only tick a criterion once it has genuinely been verified. Because the criteria are committed, they outlive the session that produced them and can be checked by anyone afterwards. Checking is a step in the workflow, not an afterthought. A failed check returns the work to an earlier step rather than being reported as a caveat. There are two human gates: one before any file is touched, and one before anything is called done.

Real run evidence

8 August 2026 run date50 minutes continuous358 agent turns230 tool calls0 human prompts during execution

Written definition of doneAcceptance criteria and the factual boundaries the work had to stay inside were committed to the repository before implementation began.
No human implementation prompts during executionFifty minutes from goal to final report. The input log, which records typed input only, holds no human keystrokes in between.
Parallel research agentsRead-only agents mapped the stack, the routes and the component conventions concurrently, each returning findings rather than raw files.
Independent review agentA separate agent — read-only, without the implementing agent's context — checked the output against the source documents. The agent that wrote the content was not the agent that approved it.
Automated validationLint, production build, route status and computed colour contrast inside the run; Playwright end-to-end and visual-regression suites across desktop and mobile over the same body of work.
Blockers preserved rather than bypassedThree criteria that needed unavailable access were left unchecked and documented, not ticked and not worked around.
Reviewer findings fed back before completionTwelve findings, two of them blockers, were applied before the run reported done — including a claim it had written itself that contradicted its own source material.

Process and outcomes only. No client identities, no source code, no transcript internals.

What the process caught

The reviewer's most useful finding was against the run's own output. Two shared pages had come to describe a client site as being in commercial production, while the case study they linked to correctly recorded that the public domain had not yet cut over. The implementing agent had written both and did not notice the contradiction; a reviewer reading the source documents first, without that context, found it in minutes. A second finding was a delivery constraint asserted in a case study that no source document supported. It was plausible, well-written and untrue. That is the characteristic failure mode of a language model writing narrative content, and it is the reason the review step reads the evidence before it reads the output. Separately, the run found and fixed five defects that predated it and sat outside the brief — among them a misconfigured base URL that was corrupting every canonical link, social image and sitemap entry on the site, and a lint script that had silently not been running.

Limits

This is a workflow for work that has a checkable definition of done. It suits implementation against a specification, migrations, removals and consistency passes across many files. It does not replace deciding what to build, and it is weakest exactly where the specification is thin — an agent will fill a gap in the brief with something plausible rather than stopping, which is what the review gate exists to catch. Three criteria in that run were left unchecked because they needed access that was unavailable at the time. Leaving them visibly unfinished was the correct outcome. When the tooling was authenticated later, the check they were blocking on found a real deployment regression that would otherwise have shipped.