Copy This Brief: A Coordinator Agent Plus Cross-Vendor Review
In Green Tests, Broken App, I changed how fixes get built: one AI coordinator plans the work, builders write the code, and LLMs from other vendors review every piece. In The Bug Was in the Instruction, Not the Code, those reviewers caught the coordinator's own instructions being wrong. Those posts are the stories. This one is the part you can copy: the brief, the builder instruction, and the review checklist.
The templates are a starting point. I have not measured them, and you do not need my exact setup to use them.
Who Does What
Think of a home remodel.
- The coordinator is the general contractor. It is one AI session that plans the work, writes an instruction for each builder, checks review findings, and puts the pieces together. It writes almost no code.
- A lane is one room: one slice of the change with its own files, so two crews are never tearing out the same wall.
- A builder is the crew in that room. It writes the fix.
- A reviewer is the building inspector. It comes from a different vendor than the builder, which is the cross-vendor part. It did not swing the hammer and has no reason to go easy on the work. Inspectors can misread the plans too, so their findings get checked.
- I am the homeowner. I walk through the finished room before anything goes live.
In my own setup, the coordinator is one Claude Opus 5.5 session, and the builders are Claude, Codex running GPT-6.1 Sol, and Grok 4.7. Every lane is reviewed by the two vendors that did not build it. Two vendors is enough to start. The idea goes back to Executor Model, Reviewer Model in August, and to my training app in Seven Releases With Grok, where LLMs from two vendors wrote code for the same update for the first time.
Try It on Something Small
Here is the whole loop on a made-up change, small enough to try in a few minutes.
Suppose you run the website for a small cafe. The footer says "Open weekdays 9 to 5." You want to add "Open Saturday 10 to 2."
The brief. Three lines are enough:
Goal: add "Open Saturday 10 to 2" to the footer.
Must stay true: the weekday line "Open weekdays 9 to 5" is unchanged, the page URL is unchanged, and the new line is readable on a phone.
Done means: a phone screenshot of the live page showing both lines.
A weak instruction. This one sounds reasonable:
Add the Saturday line, then check the footer against the text we just wrote.
A good reviewer flags it: "This check compares the change with itself, so it can't fail. Compare against the published page instead." A check that cannot fail is not a check. I learned that the hard way on a real backup check, a story I told in The Bug Was in the Instruction.
A better instruction. Same goal, with a proof that can fail:
Add the Saturday line below the weekday line. Do not change anything else in the footer. Proof: a phone-width screenshot showing both lines, plus the weekday line copied word for word from the live page before the change.
A slip the reviewer catches. Now suppose the builder "tidies" the footer into one line: "Open weekdays and Saturday." It looks cleaner, and the hours are gone. Nothing in the new text looks broken on its own. The reviewer catches it by holding the result up against the brief's "must stay true" line.
The last step is yours. Load the real page on a phone. If both lines are there and the hours are right, you publish.
The Brief
Now the full versions. Copy this one and fill in the brackets. Keep it short enough that a builder can hold the whole thing in view. Details for one lane go in that lane's instruction.
# Release brief
## Goal
[One or two sentences. What should be true when we are done?]
## Out of scope
[What we will not touch, even if it looks related.]
## Already shipped, do not loosen
[Rules or checks that already exist. A new version may add to them.
It may not catch less than what is already shipped.]
## Lanes
### Lane A - [name]
- Files: [only these]
- Builder: [one vendor, named before work starts]
- Reviewers: [1 or 2; none from the builder's vendor]
- Done looks like: [a result a person can see or do]
## Acceptance criteria
- [ ] [A specific check a person can perform]
- [ ] [What must still work, not only what is new]
## Proof
Proof is the real app or page, with real actions, not only passing tests.
How I will check: [phone, browser, or a check I will run myself].
## Stop and publish
The coordinator does not publish. I do.
If a finding is still in dispute after I have checked it, and after at most
one more reviewer pass, stop and ask me.
The stop rule at the end is there so a disagreement comes to me instead of going another round.
The Builder Instruction
The brief sets the destination. The instruction is the turn-by-turn for one lane. Write it after the brief, and read it once yourself before you send it.
# Lane instruction: [name]
Use the release brief. Do not widen the scope.
Files you may change: [only these]
Do not change: [neighboring files or behavior]
Build this:
[What to add or fix, in plain language]
Done means:
[The same acceptance criteria as the brief, applied to this lane]
Already shipped:
[Any existing check or behavior this lane must not loosen]
Proof I expect:
[How this lane will be checked on the real app or page]
When you are done, list what you changed and how you checked it.
Do not add extra features, commands, or shortcuts that the brief did not ask
for.
The last line is there because a wrong premise in a brief can make a lane "fix" a problem that was not there, or add a way to approve everything at once that nobody asked for.
The Review Checklist
Hand this to the reviewer with the brief, the lane instruction, and the change.
# Review checklist
1. Read the instruction, not only the change.
Does the instruction match the brief and the acceptance criteria?
Does it loosen something that is already shipped?
Does it remove a check the brief still requires?
2. Read the change against that instruction.
Did the builder do what was asked, and only what was asked?
3. Look for a check that cannot fail.
If the new check compares a result with the same source that produced it,
say so.
4. Say how you would prove the finding.
Point to the file, the behavior, or a check a person can run.
A finding is a claim, not an order.
5. After a fix, do at most one more reviewer pass, and only if asked.
Check the new instruction as well as the new code.
If you still disagree, say what would settle it. Do not keep stacking
rounds on your own.
The Two Habits Behind the Checklist
Review the instruction, not only the code. In The Bug Was in the Instruction, the reviewers caught wrong instructions three times in one release. I did not set the method up for that, but it is now the first item on the checklist.
A review finding is a claim to check, not an order. In that same post, a reviewer said some new test helpers were broken. The coordinator did not argue, and it did not send the builder back on reflex. It ran the tests that use those helpers, they passed, and that settled it. The reviewers check the coordinator, and the coordinator checks the reviewers.
When a finding does hold, the coordinator writes a new instruction for the fix, and that instruction gets the same reading as the first one. I usually ask for one more reviewer pass on the fix.
Putting the Lanes Together
When the lanes come back, the coordinator puts the pieces together and looks for collisions: two lanes touching the same file, one lane breaking another lane's acceptance criteria, or a fix that passes its own check and fails on the real page.
Then I do the proof myself. In Green Tests, Broken App I put it as "proof means the app, not the tests," and it still holds.
What It Costs
I did not measure a price or a speed, and a handful of releases judged by one person is not a benchmark. What the earlier posts did show is the shape of the cost:
- Lanes often take more than one fix round.
- More of the coordinator's time goes to checking than to building, and that includes checking its own instructions.
- A vendor can hit a usage limit mid-round while the others keep working.
- I am still in the loop. I sign in to a tool when it asks, and I do the final check myself.
What I got for it: reviewers from other vendors caught problems the builder missed, and they caught wrong instructions, not only wrong code. I would not rank the models from that.
Where I Would Start
Do not start with a large release. Pick one small change, write the brief, use one builder and one reviewer from another vendor, and keep the publish decision for yourself. Once that feels natural, split the next change into two lanes.
Work With Me
Running more than one AI agent on the same codebase? I help engineering teams set up coordinator and cross-vendor review workflows that catch what green tests miss, through MERA Consulting.
Comments