Spec-Driven Development with spec-kit

This section is written as a proposal you can adapt, not as a finished engagement. Placeholders in [BRACKETS] are yours to fill in, and the worked example in the middle is one project's answers — the method is what transfers.

Prepared for: [CLIENT NAME] Date: 3 August 2026 Status: Proposed approach — the pipeline used as the worked example is not yet built

How to read this guide

This page is the one-page summary in plain language. If you read nothing else, read this. The business view — what you get, what we need from you and when, what it costs, what could go wrong, and the eight decisions that are yours. No commands and no technology. If you are deciding whether to fund this rather than how to build it, read this page and that one, and stop. Why spec-driven — what goes wrong when you prompt for code ad-hoc, and the idea that fixes it. The seven commands — what each one reads, what it writes, and what it refuses to do. Setting it up — installing it, what lands on disk, and when the method is not worth the overhead. The worked example — one real automation through the first four phases: principles, specification, and the questions the specification leaves open. The plan and the task list — where the coding agent acts as architect, proposes an approach, and has to defend it in writing. Building it — why the agent's output can be trusted, what "done" means, and how to change it six months later. What this buys you — the argument for adopting it, for whoever signs off rather than whoever builds. Ends with a one-page command reference. Glossary — every term used here, in plain language.

Decisions that still need your input are listed in What we need from you to start, and set out in full — with the cost of deciding each one differently — in The decisions you own.

Assumptions in this draft — seven choices were made to keep the worked example concrete. Each is a single change if you disagree. Articles are filed as drafts for a person to approve, never published live automatically. Source sites appear as [SOURCE SITE 1..N] placeholders. WordPress is self-hosted, authenticated with an application password on a dedicated least-privilege account. The coding agent running spec-kit is Claude Code. The technical approach is not prescribed here — it is chosen by the coding agent at the plan phase, with its reasoning and the rejected alternatives written down. spec-kit is pinned at v0.15.1. The client name above is a placeholder.

---

Most teams using AI to write software do it by conversation: describe what you want, read the code that comes back, ask for a change, read it again. It works, and for a small change it is the fastest thing available. It stops working when the thing being built has to be correct, has to be handed over, or has to be changed six months later by somebody else.

Spec-Driven Development is the alternative. You write down what you are building and why, before anything is built. You turn that into a technical plan, and the plan into a numbered list of build steps. Only then does an AI coding agent write anything — and it writes against that structure rather than against a paragraph you typed five minutes ago.

spec-kit is GitHub's open-source toolkit for doing this. It is not a product you host or a service you subscribe to. It installs a set of commands into whichever AI coding agent you already use, and those commands write ordinary Markdown files into your own repository.

FIGURE 1 — The seven commands, and what each one leaves behind. Read each box top to bottom: the command you type, then the files the agent writes because you typed it.

What changes

That last row is the honest trade. Spec-driven development is slower to the first working version and faster to the tenth.

What it costs

An hour or two of structured thinking before the build, and a habit of amending the specification rather than the code. There is no licence fee: spec-kit is MIT-licensed and free. The AI coding agent you run it with may cost money; that cost is the same whether or not you use spec-kit.

The real cost is discipline. spec-kit does not enforce good specifications — it enforces having one, and it gives you three optional checks that catch the common failures. If a team writes vague specifications, spec-kit produces vague plans faster.

What it does not change

It does not remove engineering judgement, and it is not an attempt to. Somebody still decides what to build, what the technical approach should be, and whether the result is good. What disappears is the gap between the decision and the record of it.

What we need from you to start

Four things, each of which becomes a written decision in the worked example:

1. Which source sites to watch, and whether each publishes an RSS feed.
2. How often the pipeline should run.
3. Access to your WordPress site — a dedicated account we can create an application password for.
4. A sense of your house style, so the drafts sound like you rather than like a machine.

Those four are the first two lanes of FIGURE B2, and the first four rows of the decision register in FIGURE B6 — both in the business view, which also sets out what changes if you answer any of them differently.

---