Build-review loop

One session builds; another, independent session checks. An agent that grades its own work misses what a second agent catches. In the project this comes from, the reviewer sent work back 7 times with 12 blocking problems, among them a "fix" whose new test also passed on the old, broken code. The loop is a contract between the two roles, so both read this file, and each then reads its own role file.

The roles

Use a different model for the reviewer than for the builder where you can; a different model misses different things. This drifts: when one model's usage runs out, the reviewer gets moved to the builder's model. Put it back when the usage resets. Every role works restart-ready (see the restart-ready skill): its state lives in files, and it ends each unit of work by saying whether it's a good moment to restart it.

Setup

1. Look before asking. Read the project's notes, README and plan, and find how to run the tests and the build. Don't ask the owner what the repo already says.
2. Ask the owner once, as numbered questions in the chat. Give each a recommended answer, worded so "yes" accepts it:
   1. Session names and models. Default: builder on the strongest model, reviewer on a different one. Names must be unique among running sessions.
   2. What goes through a pull request. Default: steps that touch stored data, security or money; everything else goes on the main branch.
   3. Who merges a pull request. Default: the reviewer, after its own PASS, as a plain merge.
   4. What blocks a review. Default: the list under "What blocks", plus anything special to this project ("imported files must give the same totals as the old app").
   5. Private folders, which no session may read (real records, personal files). Default: none.
   6. A tester for risky parts (sync, payments, imports). Default: only when a step is risky.
3. Write docs/workflow.md from templates/workflow.md, filled in. If the project has no plan, add PLAN.md from templates/plan.md. The builder's first step is then drafting the plan for the owner to approve.
4. Hand over. Give the owner each session's exact name, model and prompt, from the workflow file, each folded in a <details> block. In a git repo, ask before committing. Commit only these files.

The loop

1. The builder finishes a step: the code with tests, its state file updated, any new decision recorded, plain commits. It puts a step on a branch with a pull request if the workflow says that kind of step goes through one.
2. The builder messages the reviewer (by name, with SendMessage) with the step, the commit range and the evidence: the commands it ran and their results, plus screenshot paths. Then it ends its turn and waits.
3. The reviewer checks it (see roles/reviewer.md). It writes docs/reviews/<date>-<step>.md, commits only that file on the branch under review without pushing, and messages the builder one verdict:
   • PASS. The builder pushes. For a pull request, the reviewer merges after its PASS if the workflow allows it; the builder waits until it's merged, updates its branch, and goes on.
   • FIX, with a numbered list of blocking findings. The builder fixes only those and sends the step back.
   • STOP. Something needs the owner, or the same problem came back twice. The builder stops and writes the owner a summary.
4. If they disagree twice about the same finding, the builder stops and leaves it for the owner. Neither side argues a third round.
5. If the reviewer's model refuses to review something, the reviewer replies REFUSED, with the step and what it couldn't review, and waits. The builder (or a chief of staff) switches the reviewer's model for that one review (set_session_model, loaded with ToolSearch), asks for the review again, and switches back afterwards. If the switch isn't possible, ask the owner to change the model in the reviewer's model menu.

What blocks

Only these send work back:

• Data safety: records could be lost, overwritten or corrupted, or a safety rule has no test that fails when the rule is taken out.
• A fix without its kind: the fix's test covers only the reported case, with no second case where the same rule applies.
• Privacy: something leaves the device or the system without the owner's OK, or outside code was added without it.
• Wrong results under the project's rules.
• A broken build or failing tests.
• Contradicting a recorded decision or the design.
• Scope creep beyond the step.
• Records not updated: the state file, or the decisions file for a new decision. A design rule written only in a code comment counts.
• Anything the owner added in setup.

Style isn't a finding. Don't invent problems to have something to report. A reviewer that always finds something trains everyone to ignore it.

The owner

Decisions are the owner's; facts are the sessions'. Ask decisions as numbered questions, each with a recommended answer, worded so "yes" accepts it. Look facts up yourself. Nothing is installed, bought, published or deleted without the owner's word in chat.

• With the chief-of-staff skill, everything for the owner goes to the chief of staff instead, which relays the owner's answers word for word.
• With the owner-desk skill, the owner may answer on the desk.