Cross-Review Project

Two Claude Code instances review each other's projects through structured artifact exchange via cross-review-mcp broker. Broker enforces Quantized Simplex Gossip (QSG) scaling laws — review bundles must have at least 5 findings to stay in selection regime (Γ_h ≈ 1.67). Stops shallow consensus from passing as agreement.

When Use

• Two projects share architectural concerns, could learn from each other
• Want independent code review going beyond what single reviewer sees
• Cross-pollination is goal: finding patterns in one project missing in other
• Need structured, evidence-backed review with accept/reject/discuss verdicts

Inputs

• Required: Two project paths accessible to two Claude Code instances
• Required: cross-review-mcp broker running and configured as MCP server in both instances
• Optional: Focus areas — specific directories, patterns, or concerns to prioritize
• Optional: Agent IDs — identifiers for each instance (default: project directory name)

Steps

Step 1: Verify Prerequisites

Confirm broker running. Both instances can reach it.

1. Check broker configured as MCP server:

   claude mcp list | grep cross-review
   

2. Call get_status to verify broker responsive. No stale agents registered.
3. Read protocol resource at cross-review://protocol — markdown document describing review dimensions and QSG constraints

Got: Broker responds to get_status with empty agent list. Protocol resource readable as markdown.

If fail: Broker not configured? Add it: claude mcp add cross-review-mcp -- npx cross-review-mcp. Stale agents from prior session? Call deregister for each before proceeding.

Step 2: Register

Register this agent with broker.

1. Call register with:
   • agentId: short, unique identifier (e.g., project directory name)
   • project: project name
   • capabilities: ["review", "suggest"]
2. Verify registration by calling get_status — your agent should show with phase "registered"
3. Wait for peer agent to register: call wait_for_phase with peer's agent ID and phase "registered"

Got: Both agents registered with broker. get_status shows 2 agents at phase "registered".

If fail: register fails with "already registered"? Agent ID taken from prior session. Call deregister first, then re-register.

Step 3: Briefing Phase

Read own codebase. Send structured briefing to peer.

1. Read systematically:
   • Entry points (main files, index, CLI commands)
   • Dependency graph (package.json, DESCRIPTION, go.mod)
   • Architectural patterns (directory structure, module boundaries)
   • Known issues (TODO comments, open issues, tech debt)
   • Test coverage (test directories, CI configuration)
2. Compose Briefing artifact — structured summary peer can use to navigate your codebase
3. Call send_task with:
   • from: your agent ID
   • to: peer agent ID
   • type: "briefing"
   • payload: JSON-encoded briefing
4. Call signal_phase with phase "briefing"

Got: Briefing sent and phase signaled. Broker enforces you must send briefing before advancing to review.

If fail: send_task rejects briefing? Check from field matches your registered agent ID. Self-sends rejected.

Step 4: Review Phase

Wait for peer's briefing. Review their code. Send findings.

1. Call wait_for_phase with peer's ID and phase "briefing"
2. Call poll_tasks to retrieve peer's briefing
3. Call ack_tasks with received task IDs — required (peek-then-ack pattern)
4. Read peer's actual source code, informed by their briefing
5. Produce findings across 6 categories:
   • pattern_transfer — pattern in your project peer could adopt
   • missing_practice — practice peer lacks (testing, validation, error handling)
   • inconsistency — internal contradiction within peer's codebase
   • simplification — unnecessary complexity that could be reduced
   • bug_risk — potential runtime failure or edge case
   • documentation_gap — missing or misleading documentation
6. Each finding must include:
   • id: unique identifier (e.g., "F-001")
   • category: one of 6 categories above
   • targetFile: path in peer's project
   • description: what you found
   • evidence: why this is valid finding (code references, patterns)
   • sourceAnalog (recommended): equivalent in your own project showing pattern — single mechanism for genuine cross-pollination
7. Bundle at least 5 findings (QSG constraint: m ≥ 5 keeps Γ_h ≈ 1.67 in selection regime)
8. Call send_task with type "review_bundle" and JSON-encoded findings array
9. Call signal_phase with phase "review"

Got: Review bundle accepted by broker. Fewer than 5 findings rejected.

If fail: Bundle rejected for insufficient findings? Review more deeply. Constraint exists to stop shallow reviews from dominating. Cannot find 5 issues? Reconsider whether cross-review is right tool for this project pair.

Step 5: Dialogue Phase

Receive findings about own project. Respond with evidence-backed verdicts.

1. Call wait_for_phase with peer's ID and phase "review"
2. Call poll_tasks to retrieve findings about your project
3. Call ack_tasks with received task IDs
4. For each finding, produce FindingResponse:
   • findingId: matches finding's ID
   • verdict: "accept" (valid, will act on it), "reject" (invalid, with counter-evidence), or "discuss" (needs clarification)
   • evidence: why you accept or reject — must be non-empty
   • counterEvidence (optional): specific code references that contradict finding
5. Send all responses via send_task with type "response"
6. Call signal_phase with phase "dialogue"

Note: "discuss" verdict not gated by protocol — treat as flag for manual follow-up, not automated sub-exchange.

Got: All findings responded to with verdicts. Empty responses rejected by broker.

If fail: Cannot form opinion on finding? Default to "discuss" with evidence explaining what extra context you need.

Step 6: Synthesis Phase

Produce synthesis artifact summarizing accepted findings and planned actions.

1. Call wait_for_phase with peer's ID and phase "dialogue"
2. Poll any remaining tasks and ack them
3. Compile Synthesis artifact:
   • Accepted findings with planned actions (what you will change and why)
   • Rejected findings with reasons (preserves reasoning for future review)
4. Call send_task with type "synthesis" and JSON-encoded synthesis
5. Call signal_phase with phase "synthesis"
6. Optionally create GitHub issues for accepted findings
7. Call signal_phase with phase "complete"
8. Call deregister to clean up

Got: Both agents reach "complete". Broker requires at least 2 registered agents to advance to complete.

If fail: Peer already deregistered? Can still complete locally. Compile synthesis from findings received.

Checks

• Both agents registered and reached "complete" phase
• Briefings exchanged before reviews began (phase enforcement)
• Review bundles had at least 5 findings each
• All findings received verdict (accept/reject/discuss) with evidence
• ack_tasks called after every poll_tasks
• Synthesis produced with accepted findings mapped to actions
• Agents deregistered after completion

Pitfalls

• Fewer than 5 findings: Broker rejects bundles with m < 5. Not arbitrary — with N=2 agents and 6 categories, m < 5 puts Γ_h at or below critical boundary where consensus indistinguishable from noise. Review more deeply. 5 findings genuinely cannot be found? Projects may not benefit from cross-review.
• Forgetting ack_tasks: Broker uses peek-then-ack delivery. Tasks stay in queue until acknowledged. Forgetting to ack → duplicate processing on next poll.
• Forgetting the from parameter: send_task requires explicit from field matching your agent ID. Self-sends rejected.
• Same-model epistemic correlation: Two Claude instances share training biases. Temporal ordering ensures they don't read each other's output during review, but priors correlated. For genuine epistemic independence, use different model families across instances.
• Skipping sourceAnalog: sourceAnalog field optional but single mechanism for genuine cross-pollination — shows your implementation of pattern you're recommending. Always populate it when source analog exists.
• Treating discuss as blocking: Nothing in protocol gates complete on pending discussions being resolved. Treat discuss verdicts as flags for manual follow-up after session.
• Not reviewing telemetry: Broker logs all events to JSONL. After session, review log to validate QSG assumptions — estimate α empirically (α ≈ 1 - reject_rate) and check per-category accept rates.

See Also

• scaffold-mcp-server — for building or extending broker itself
• implement-a2a-server — A2A protocol patterns broker draws from
• review-codebase — single-agent review (this skill extends it to cross-agent structured exchange)
• build-consensus — swarm consensus patterns (QSG is theoretical foundation)
• configure-mcp-server — configuring broker as MCP server in Claude Code
• unleash-the-agents — can analyze broker itself (battle-tested: 40 agents, 10 hypothesis families)