Glossary of AI-era software delivery

Building software where the specification is the durable artefact and the code is downstream of it. The document is precise enough that a competent engineer — or agent — could implement from it and land somewhere you would recognise.

Not a return to waterfall: the loop is short and the specs are small. What changed is that generating code got cheap, so agreeing what to build became the expensive part.

One unit of work, carrying two documents: requirements (what and why) and implementation (how). Everything else — tasks, approvals, code refs, pull requests — hangs off it.

The what-and-why half. Problem, who has it, what changes when it ships, what you are deliberately not building, and the hard rules.

Length is a feature. A reviewer who has to read 1,400 words to find the decision will skim, and skimming is how bad specs get approved.

The how half: approach, data model, API surface, failure modes, test strategy, slices, rollout. Written after reading the actual code, not from imagination.

A point a spec cannot pass until a named human approves it. The approval is bound to the document version they read — edit the document and the approval dies.

Without the binding, an approval is a timestamp on a document that has since changed, which is worse than no approval because it looks like one.

A piece of implementation small enough to be wrong cheaply — two days or less, one reviewable pull request. Agents will happily generate a week of work in one pass, which nobody reviews properly.

The stage after Released: did the thing you shipped do what the spec claimed? Most teams never close this loop, which is why the same mistake gets specified twice.

The append-only record of who moved a spec, who approved which version, and when. The thing that answers “who decided this?” six months later, when nobody remembers the meeting.

A GitHub permalink attached to a spec — repo, path, line range, commit — with a note saying why those lines matter. Rendered as source inline beside the document.

Linking code at a commit SHA rather than a branch, so the link keeps showing the code the decision was made against instead of whatever the branch drifted into.

Code a change could break but does not touch. Marking it explicitly tells a reviewer where to look for second-order damage without reading the whole diff.

A pull request opened to explore rather than to merge: stubs, a shape, enough to discover the constraint nobody remembered. It informs the plan and should never be treated as evidence the work is done.

The pattern where a request goes to an agent and comes back as a pull request. Fast, and it skips the two questions that matter: was this the right thing to build, and did anyone agree to it?

An open protocol that lets an AI agent read and write real systems — files, APIs, trackers — instead of being told the state of the world in every prompt.

Practically: the difference between an assistant you brief from scratch each time and one that can look things up and write back.

A service exposing tools an agent may call. A well-designed one is defined as much by what it omits — RelayWork has no approve tool at all, so no misconfiguration can let a machine sign off its own work.

Whether a token may read or also write, and which tools it can reach. Scoped, revocable tokens are what make agent access auditable rather than a shared password.

Recording an automated write as the token that made it rather than as a person. Without it, an agent’s edit silently borrows a human’s authority.

A model given tools and a goal, running a loop rather than answering once. The useful distinction from a chatbot is not intelligence — it is that an agent changes state in systems you care about.

Building by describing what you want and accepting what comes back without reading it closely. Genuinely fine for a prototype. The failure mode is shipping it, then discovering nobody — human or model — knows why the code does what it does.

Deciding what an agent should be able to see. Increasingly the real skill: a model with the approved spec, the review notes and the relevant code will beat a better model working from a paragraph.

The fixed shape documents must follow in a workspace, enforced on submission. It is what stops agent output from being 1,400 words of fluent, unreviewable prose.