Build + review: refactor with a reviewer on watch

When should you use a build + review squad?

Use it when a change is risky enough that you want a second agent to read it before you do. The builder writes, the reviewer pushes back, and the loop runs without you until there is something worth your time.

• Refactors and migrations: auth, data layers, framework upgrades.
• Security-sensitive changes: tokens, permissions, input handling.
• Anything you would never merge without a review from a teammate.
• Not for exploring several approaches. That's best of three.

How do you set up the squad?

Open Squads → New squad and pick Build + review. The template prefills a builder ("Does the work described in the objective") and a reviewer ("Reviews the result and lists what must change before it is approved"). Keep the builder as is. Make the reviewer specific: tell it what to look for.

What objective should you paste?

Describe the end state, the constraints and what the reviewer must check. The clearer the review bar, the fewer rounds you burn.

Migrate auth from server sessions to signed JWTs.

Scope
- Issue and verify tokens in src/auth. Replace the session middleware.
- Update every call site that reads req.session.user.

Constraints
- Signing keys come from the existing secrets loader. Never commit keys.
- Logout must invalidate the token server-side.
- All auth tests pass; add tests for expiry and logout.

Review bar
- The reviewer approves only when token expiry, key rotation and
  logout invalidation are covered by tests.

The prefilled Leader instructions already describe the loop: send to the builder, ask the reviewer, send changes back, repeat until approval. Keep them.

What limits should you set?

Keep 5 rounds and set members at once to 2. Every build → review pass uses a round, so five leaves room for two or three rounds of feedback plus a spare.

Put a reviewer on your next refactor. Build it in Tallos in a few minutes.

Get Tallos →

How does the run go?

An example run, step by step. Call-site counts and findings are illustrative, not measurements.

1. 1

   The leader sends the objective to the builder

   The builder starts in its own worktree, separate from your checkout.

2. 2

   The builder delivers

   In the example: JWT issue and verify, new middleware, 42 call sites updated.

3. 3

   The reviewer pushes back

   Three required changes: rotate signing keys, shorten the access-token lifetime, revoke tokens on logout.

4. 4

   Round 2

   The leader sends the three changes back to the builder, who applies them and adds tests.

5. 5

   A question for you

   The leader asks whether existing sessions should stay valid during a 24-hour migration window. You answer yes, 24h.

6. 6

   Round 3: approved

   The reviewer approves. The leader files the report with tallos squad report and the run shows Ready for your review.

What will the leader ask you?

Build + review questions are usually rollout and policy calls that the reviewer can flag but not decide. You pick an option or write your own answer.

• "Keep old sessions valid for a 24h migration window, or force everyone to log in again?"
• "The reviewer wants a revocation list. Store it in Redis or in the database?"
• "Two call sites live in a deprecated module. Update them or delete the module?"

What do you get at the end?

• Final report: what changed, the reviewer's verdict, open risks and what to verify. In the example: key rotation with short-lived access tokens, a revocation list on logout, a 24h window for existing sessions.
• Results by worktree: the builder's worktree marked Recommended, with View changes.
• Accept or Discard: Accept turns the recommended row into Open to create PR. Discard keeps the worktrees unless you choose to delete the members' worktrees.

The reviewer's approval is not yours. Read the diff in diff review with the checklist in how to review AI-generated code.

What variations work well?

• Two reviewers. Add a performance reviewer next to the security one and raise members at once to 3.
• Reviewer that runs the tests. Write "Runs the full test suite and pastes the output. Approves only on green." into the reviewer's function.
• Put it on a schedule. Save the squad and run it every weekday, like the scheduled maintenance squad.
• Build on a bigger split. For a change with several independent parts, use ship a feature and add a reviewer member.

What are the common mistakes?

• A reviewer with no bar. "Review the code" invites endless nitpicks that eat rounds. Say what blocks approval.
• Too few rounds. At the limit the leader reports what it has, even without approval. Check the report for open findings.
• Scope creep in review. If the reviewer asks for unrelated cleanups, answer the leader: out of scope.
• Treating approval as a merge. Nothing merges until you accept and open the PR yourself.

New here? Start with your first squad or the squads overview.