Plan, then build, then QA
One written spec is the contract. The work is cut into packages that are built in a fixed order, and each package has to pass its checks before it is committed.
Use it When the work is too big for one session and the parts depend on each other.
The problem
A large build does not fit in one agent session. If I split it over several sessions without a plan, each one makes its own assumptions and the parts do not fit. The later sessions also cannot ask the earlier ones what they meant.
How it works
- Plan. One spec says what gets built, in which order, and what each part promises to the others: names, routes, file ownership, limits.
- Build. The work is cut into packages. One engineer builds one package. It knows only the spec and the code that is already committed.
- QA. Each package has to pass before it is committed: unit tests, a script that runs against the deployed preview, and a real browser at a desktop width and a phone width.
- Commit. The next package starts from what is now in the branch.
Two rules hold the loop together. If the spec turns out to be wrong, the engineer changes the spec in the same commit as the code and adds a note, so the next engineer sees it. And every package leaves the branch in a state that could ship.
What it costs
The spec. The one for the workbench is about 1,900 lines, and it was written and reviewed before any code. It also costs strictness: an engineer may not quietly do something smarter than the contract says.
Where it fails
When the plan is wrong in a way nobody sees until late. In the eighth package the spec asked for one prompt that mixed text I had reviewed with text I had not, and another section of the same spec forbids exactly that. The engineer split it into two calls and wrote the change into the spec.
It also fails quietly when the checks are weak. A package that passes its own tests can still break an earlier one, so each package also runs the earlier smoke scripts again.
And one engineer per package is the rule, not what always happened. Twice an engineer was cut off in the middle of a package. The next one read every file of the unfinished commit again before building on it.
Where I used it
For the AI lab: nine packages, built in order, from the private vault first to this pattern library last.
Used inAI lab