Spec-Driven Development with OpenSpec

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: 5 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 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 OpenSpec — what goes wrong when you prompt for code ad-hoc, why rigid phase gates fail differently, and how OpenSpec compares with the alternatives. The anatomy — two folders, one round trip, and the four artifacts inside a change. The whole mental model. The command line — every terminal command, grouped by the job it does. The artifacts — what lands on disk, who owns each half, and the exact grammar of a specification. Skills and slash commands — how the workflow reaches whichever AI assistant each person already uses. Adopting it on an existing codebase — the brownfield case, which is the one OpenSpec was built for. Starting a new project with it — the greenfield case, where there is no code to catch a wrong guess. Closing the gap — moving a brownfield codebase toward spec coverage, and an honest account of what that can and cannot mean. The worked example — one real automation, from a fuzzy idea to a change folder on disk. Specs, deltas and validation — the capabilities contract, one requirement traced end to end, and what the validator refuses. Applying and archiving — building it, the five checks before anything runs on a schedule, 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 — eight 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 OpenSpec is Claude Code, one of thirty-six supported. The technical approach is not prescribed here — it is chosen at the design stage, with its reasoning and the rejected alternatives written down. Specifications live in openspec/ inside the project repository, committed to git. OpenSpec is pinned at v1.7.0. 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 approach, and the approach 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.

OpenSpec is an 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 assistant you already use, and those commands write ordinary Markdown files into your own repository. It is published as @fission-ai/openspec, is MIT-licensed and free, and needs Node.js 20.19 or later.

FIGURE 1 — Four commands, and what each one leaves behind. Read each box top to bottom: the command you type, then the files that exist 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.

The row above it is the one that separates OpenSpec from most of its alternatives, and it is the row nobody notices until the second year of a system's life. A specification written once is accurate on the day it is written. A specification that every completed change merges back into is accurate on the day you read it.

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: OpenSpec is MIT-licensed and free. The AI coding assistant you run it with may cost money; that cost is the same whether or not you use OpenSpec.

The real cost is discipline. OpenSpec does not enforce good specifications — it enforces having one, and it gives you a validator that catches the common failures. If a team writes vague specifications, OpenSpec 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.

It also does not make anything run itself. The pipeline described in the worked example runs on a schedule you control, on a host you own, filing drafts that a person reads. Nothing in this proposal publishes anything to the public without a named human deciding to.

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 column of FIGURE 2 and the first four rows of the decision register in FIGURE 5 — both in the business view, which also sets out what changes if you answer any of them differently.

---