Building It, and What "Done" Means

Everything up to here was written down and agreed. This is where an agent finally writes code — and where the question every client asks properly gets answered.

2.8 /speckit.implement — and why the output can be trusted

This is the phase where the honest answer matters most, because "an AI agent builds it" is the part clients are right to be sceptical about.

The scepticism is warranted, and the reason is specific. An agent asked to build something from memory will produce confident, plausible, wrong output — an interface that does not exist in that shape, a parameter that was renamed two releases ago, a call that reads correctly and returns nothing. It will not hedge while doing it. This is not a flaw that a sterner prompt fixes.

What fixes it is being made to satisfy something that cannot be argued with. By the time /speckit.implement runs, four such things already exist, and none of them were written by the agent:

• The contract. contracts/article.schema.json is a machine-checkable statement of what the writer must return. An article with an empty sources array does not reach an editor to be judged — it fails to parse.
• The tests. A task is not complete because the agent says so. It is complete when the thing it wrote does what the acceptance scenario in spec.md said it would.
• The type check. Cheap, total, and it catches the specific failure mode above — a call that was hallucinated in the wrong shape.
• A real call to a real system. The last check is not a simulation. It creates an actual draft on an actual site, and somebody reads it.

A failing test is a harder gate than a lookup in a reference manual. The agent cannot talk its way past any of the four, and it does not get to decide when they have been met.

FIGURE 10 — What the last command actually does. The tasks on the left are what you agreed. The gates on the right are what the result has to survive.

So the division of labour is:

Before writing anything, /speckit.implement checks the checklists in specs/001-content-pipeline/checklists/ and produces a PASS/FAIL table. An incomplete checklist stops the run and asks whether to proceed.

Avoid: pointing any of this at the live site on the first run. Work against a staging site or a throwaway account, confirm what gets created, then move it. AI output is not always predictable, and your production site is not where you want to discover that.

And note which phase this is. Everything the agent decided about how — the approach, the libraries, the file layout — was decided in section 2.5 and written down before this command ran. /speckit.implement is not where the architecture happens. It is where an architecture somebody already reviewed gets built.

2.9 What "done" looks like

"It works" is a matter of opinion unless it was defined beforehand. It was.

FIGURE 11 — What "done" means — five checks, all of them green. Agreed in writing before the build starts.

1. The checks pass. Tests and type check report no errors, with the output shown before and after fixing. A silent "fixed it" is not reviewable.
2. Deployed, schedule not enabled. It exists on your host and does not run. This is the first moment anything touches your systems.
3. One manual run. Executed once by hand, end to end, with the log read — which sources returned how many items, what the writer produced, what it logged as a warning.
4. A real draft. A person opened the resulting article in WordPress and would have published it.
5. Every task [X], and /speckit.analyze reports full requirement coverage.

Only then is the schedule switched on.

Check 1 is necessary and not sufficient. The tests prove the thing does what the acceptance scenarios said it would. They say nothing about whether the articles are any good. That is what check 4, and the first fortnight of review, are for — and no amount of engineering rigour substitutes for it.

Evidence of all five belongs here once the pipeline exists — the specification open in an editor, the task list part-completed, the repository with its tests passing, and the drafts list on the website. None of it is mocked up, deliberately.

Before any screenshot of a real run leaves the building. No API keys, tokens or application passwords, including partially visible ones. No internal hostnames or IP addresses. No real customer data in any draft shown. The author shown is the pipeline's service account, not a person. No unrelated browser tabs, bookmarks or notifications.

2.10 Day two — changing it later

Six months in, you want to add a source site. There are two ways to do that and only one of them is the method.

The wrong way is to open the code and add the source by hand. It works, it takes ten minutes, and it makes spec.md a lie. Do it three more times and the specification is fiction, at which point every argument in Why spec-driven stops applying to you.

The way that holds is to amend the specification — add the source to the entity list, adjust the assumption about how many there are — and let the downstream artifacts follow. Then:

/speckit.converge

/speckit.converge compares the codebase against the spec, plan and tasks, and appends whatever is missing to tasks.md as new tasks. It is append-only. If the implementation already satisfies everything, it leaves tasks.md byte-for-byte unchanged and says so.

The same applies to changing the target article length, the run cadence, or the de-duplication key. Each is a specification amendment with a task list falling out of it, not an edit made directly to a running system.

Assumption — this assumes whoever operates the pipeline has a coding agent configured against the repository. If day-two changes will instead come back to the original build team as requests, that is equally workable, and this section becomes background rather than instruction.