Workflow Wiring Appendix A Code Reviewer

The Problem This Solves

Adding a reviewer to team.md gives them an identity. It does NOT:

• Tell the coordinator to route PRs to them
• Prevent PRs from being merged without their approval
• Prevent issues from being closed before review happens

What goes wrong without enforcement: A reviewer can be on the roster as “Reviewer” from day one. Their charter says they review PRs. The routing table says “PR code review → {ReviewerName}.” But PRs get merged and issues get closed without them ever being spawned. Why?

Because the routing table says WHO handles what — it’s for incoming requests (“review PR #42”). It does NOT say “after every agent completes work, route their output to {ReviewerName}.” The coordinator routes work TO agents, but nothing tells it to route COMPLETED work to a reviewer. The “After Agent Work” flow in squad.agent.md says: collect results → present → spawn Scribe. No review step.

The fix has three layers:

Most squads get layers 1 and 2 right. Layer 3 — enforcement — is what’s usually missing.

Step-by-Step Walkthrough

Step 1: Create the reviewer’s identity

Create .squad/agents/{name}/charter.md:

Create .squad/agents/{name}/history.md seeded with project context.

Step 2: Add to team.md roster

Step 3: Add routing table entry

In routing.md → routing table:

⚠️ This is necessary but NOT sufficient. This only handles explicit review requests. It does NOT enforce automatic review of every PR.

Step 4: Add enforcement rule (THIS IS THE CRITICAL STEP)

In routing.md → ## Rules section, add a numbered rule:

Why this works when the routing table alone didn’t: The routing table is for matching incoming work to agents. Rules are behavioral constraints the coordinator must follow AFTER work completes. The rule says “after a PR exists, you MUST do X before proceeding.” The routing table says “if someone asks for a review, route to X.”

Step 5: Wire into issue-lifecycle.md

In .squad/templates/issue-lifecycle.md, the “Coordinator Post-Work Steps” section should reference your reviewer by name:

This is the operational detail — the step-by-step instructions the coordinator follows after an agent completes issue work. The routing rule (Step 4) is the mandate; the lifecycle template is the procedure.

Step 6: Add to casting registry

Update .squad/casting/registry.json with the new entry.

Step 7: Verify

Ask yourself these questions:

• Not done: If a clean session coordinator reads routing.md Rules, will it know to route PRs to this reviewer? → Check rule N exists.
• Not done: If an agent completes work and pushes a PR, does the coordinator’s post-work flow include a review step? → Check issue-lifecycle.md step 4.
• Not done: Can the coordinator merge a PR without the reviewer’s approval? → The rule should say “No PR merges without {Name}’s approval.”
• Not done: Can the coordinator close an issue without a merged PR? → Check the issue closure rule exists.

If any answer is wrong, you have a gap.

What Each File Controls (Summary)

Remove any one of these and the gate has a hole. The most commonly missed piece is the Rules section entry (Step 4).