The brief is the first deliverable

A non-engineer who built this site's theme and plugins with an AI coding agent reports that the written brief, not the agent, settled most of the outcome, and that a routine theme update from version 13.8.0 to 13.9.0 required 14 named test suites to stay green through every phase. The brief's four parts — already shipped work, this round's scope, an off-limits list naming files and settings one by one, and the tests that define done — close off directions the agent would otherwise take, with the off-limits list doing most of the work. Because the agent starts each session with no memory of the last, the briefs grow into an operating record of what done means and which failures have already happened once.

Contents The theme and plugin that run this site were built by an AI coding agent. I am not an engineer by trade. My part was the brief each change was built against, written before any session started, and the longer I work this way the more of the outcome I find was settled in that document. What a brief has to hold A working brief has four parts, and each one closes off a direction the agent would otherwise be free to take. A sample with its real exclusions is on the How I work with AI https://juanlentino.com/workflow/ page. The four parts of a brief 1. Already shipped. Finished work the agent leaves alone, including work it might be tempted to improve. 2. This round. The scope of the change, and nothing past it. 3. Off limits. Files, settings and habits the agent must not touch, named one by one. 4. The tests. The named suites that decide whether anything counts as done. The off-limits list does most of the work. An agent given open space fills it with reasonable choices, and a reasonable choice nobody asked for is the expensive kind, because nothing flags it. The brief for a routine theme update said, in plain sentences, not to touch the templates, not to add colors or font sizes, not to run a global find-and-replace and not to bump the version number inside the change. None of those would have been sabotage. Each would have looked sensible in the moment and cost an afternoon to find later. That update took the site's theme from version 13.8.0 to 13.9.0. Fourteen named test suites had to stay green through every phase of it. The test list is what makes done checkable in the domains where my own judgment runs out first https://juanlentino.com/notes/the-augmentation-happened-outside-the-studio/ . A suite of named tests that must stay green after every phase can be read by someone who could not have written the code, and a failure in any of them stops the work. Without it, the agent's own report of success would be the only evidence on the table. Decisions stay named Some choices in a brief are not technical at all. They are questions of taste or risk, and they belong to whoever owns the outcome. A brief that leaves one unmarked has handed it to the agent without saying so. Naming them is the remedy. One design element in that same update was ambiguous, so the question went into the document with three options attached, and the agent was told to present them and wait. The analytics work had the same shape: to tell my visits apart from readers', the brief had to settle one thing before any code existed. Readers would not get a cookie, and only my own browser would carry one. The simplest fix for that counting problem puts a cookie on everyone, and nothing about the task itself would have told an agent to avoid it. The brief outlives the session The agent begins every session with no memory of the last one, so whatever was learned has to be written down before the session closes. In practice the briefs grow. A mistake that happens twice becomes a test that fails the build the third time. Decisions already made get recorded so nobody reopens them by accident, and releasing a version stays separate from building the change, so nothing ships as a side effect. What builds up reads less like a set of instructions than an operating record: what done means for each kind of work, and which failures have already happened once. Writing that down for work someone else will carry out is the same job whether the someone else is software or a contractor. The agents change every few months. The record carries over to whichever one comes next.