A Practical Agentic SDLC

Most demos of coding agents show a single prompt producing a working app. That is a genuinely useful trick and a bad model for shipping real software. The projects this studio delivers are small, but they carry the same obligations as large ones: correctness, a maintainable shape, and a record of why decisions were made. The process below is what makes agent-assisted delivery repeatable rather than lucky. This site was built with it.

Four documents, in order

The loop runs through four artefacts, each the input to the next.

intent.md states what we are changing and why, in the owner’s words. It is short, it avoids implementation detail, and it is the thing we check the finished work against.

spec.md turns intent into a design and requirements specification: architecture, data schemas, page-by-page behaviour, non-functional targets. This is where the human does the most thinking. An agent can draft it, but every claim in it is something you are willing to be held to later, so you read every line.

plan.md breaks the spec into ordered phases, each ending in a verifiable checkpoint. Phase n does not start until phase n − 1 is green. This is mostly an agent’s job — decomposition is something they are good at — with the human pruning scope and fixing the sequence.

STATE.md is the running checklist. Every task has a box, a number, and a description, and it is updated as work lands. When a session ends mid-task, a HANDOFF.md captures enough state for the next session to resume cold.

Why the governance files matter more than the prompts

The instinct is to spend effort on prompt wording. In practice the leverage is in the structure around the prompt.

A phased plan with checkpoints means each unit of agent work is small enough to review properly and has an objective pass condition. You are never asked to bless a thousand-line diff on vibes. Schema validation on content and typed interfaces on code turn a class of agent mistakes into build failures instead of production bugs — the agent can be wrong, loudly, and cheaply. Tests written against frozen fixtures before the implementation let you accept agent-written parser changes because the fixture still passes, not because you trust the diff.

The STATE.md and HANDOFF.md habit matters because agent sessions are lossy. Context windows fill, sessions restart, and a different model may pick up the work. Externalising progress into a checklist that lives in the repo means the process survives the discontinuity.

The loop in practice

A phase looks like this: read the spec section and the plan checkpoint; let the agent propose an approach for that checkpoint only; implement; run the checkpoint’s verification (make lint, make build, a targeted test); update STATE.md; commit. Then the next phase.

The human interventions cluster in predictable places. Naming and interface shape — agents will invent three names for one concept if you let them. Anything involving judgement about people or public claims. And the moment where an agent has technically satisfied the checkpoint but missed the point, which you only catch by having written the spec yourself.

What it costs

This is more overhead than prompting an agent and hoping. Writing a real spec for a small site takes an afternoon. The return is that the implementation phase is fast and mostly hands-off, the result matches what was asked for, and six months later the repo still explains itself. For work you intend to maintain, that trade is heavily positive. For a throwaway prototype it is not, and you should skip straight to the single prompt.