pjt222/cross-review-project

Cross-Review Project

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

When to Use

• Two projects share architectural concerns and could learn from each other
• You want independent code review that goes beyond what a single reviewer sees
• Cross-pollination is the goal: finding patterns in one project that are missing in the other
• You 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 an 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)

Procedure

Step 1: Verify Prerequisites

Confirm the broker is running and both instances can reach it.

1. Check the broker is configured as an MCP server:

   claude mcp list | grep cross-review
   

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

Expected: The broker responds to get_status with an empty agent list. The protocol resource is readable as markdown.

On failure: If the broker is not configured, add it: claude mcp add cross-review-mcp -- npx cross-review-mcp. If stale agents exist from a previous session, call deregister for each before proceeding.

Step 2: Register

Register this agent with the broker.

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

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

On failure: If register fails with "already registered", the agent ID is taken from a previous session. Call deregister first, then re-register.

Step 3: Briefing Phase

Read your own codebase and send a structured briefing to the 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 a Briefing artifact — a structured summary the peer can use to navigate your codebase efficiently
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"

Expected: Briefing sent and phase signaled. The broker enforces that you must send a briefing before advancing to review.

On failure: If send_task rejects the briefing, check that the from field matches your registered agent ID. Self-sends are rejected.

Step 4: Review Phase

Wait for the peer's briefing, then review their code and send findings.

1. Call wait_for_phase with the peer's ID and phase "briefing"
2. Call poll_tasks to retrieve the peer's briefing
3. Call ack_tasks with the received task IDs — this is required (peek-then-ack pattern)
4. Read the peer's actual source code, informed by their briefing
5. Produce findings across 6 categories:
   • pattern_transfer — a pattern in your project that the peer could adopt
   • missing_practice — a practice the peer lacks (testing, validation, error handling)
   • inconsistency — internal contradiction within the 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 the 6 categories above
   • targetFile: path in the peer's project
   • description: what you found
   • evidence: why this is a valid finding (code references, patterns)
   • sourceAnalog (recommended): the equivalent in your own project that demonstrates the pattern — this is the 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 the JSON-encoded findings array
9. Call signal_phase with phase "review"

Expected: Review bundle accepted by the broker. Fewer than 5 findings will be rejected.

On failure: If the bundle is rejected for insufficient findings, review more deeply. The constraint exists to prevent shallow reviews from dominating. If you genuinely cannot find 5 issues, reconsider whether cross-review is the right tool for this project pair.

Step 5: Dialogue Phase

Receive findings about your own project and respond with evidence-backed verdicts.

1. Call wait_for_phase with the peer's ID and phase "review"
2. Call poll_tasks to retrieve findings about your project
3. Call ack_tasks with the received task IDs
4. For each finding, produce a FindingResponse:
   • findingId: matches the 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 the finding
5. Send all responses via send_task with type "response"
6. Call signal_phase with phase "dialogue"

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

Expected: All findings responded to with verdicts. Empty responses are rejected by the broker.

On failure: If you cannot form an opinion on a finding, default to "discuss" with evidence explaining what additional context you need.

Step 6: Synthesis Phase

Produce a synthesis artifact summarizing accepted findings and planned actions.

1. Call wait_for_phase with the peer's ID and phase "dialogue"
2. Poll any remaining tasks and acknowledge them
3. Compile a Synthesis artifact:
   • Accepted findings with planned actions (what you will change and why)
   • Rejected findings with reasons (preserves the reasoning for future review)
4. Call send_task with type "synthesis" and the 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

Expected: Both agents reach "complete". The broker requires at least 2 registered agents to advance to complete.

On failure: If the peer has already deregistered, you can still complete locally. Compile your synthesis from the findings you received.

Validation

• [ ] Both agents registered and reached "complete" phase
• [ ] Briefings exchanged before reviews began (phase enforcement)
• [ ] Review bundles contained at least 5 findings each
• [ ] All findings received a 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

Common Pitfalls

• Fewer than 5 findings: The broker rejects bundles with m < 5. This is not arbitrary — with N=2 agents and 6 categories, m < 5 puts Γ_h at or below the critical boundary where consensus is indistinguishable from noise. Review more deeply; if 5 findings genuinely cannot be found, the projects may not benefit from cross-review.
• Forgetting ack_tasks: The broker uses peek-then-ack delivery. Tasks remain in queue until acknowledged. Forgetting to ack causes duplicate processing on the next poll.
• Forgetting the from parameter: send_task requires an explicit from field matching your agent ID. Self-sends are 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 their priors are correlated. For genuine epistemic independence, use different model families across instances.
• Skipping sourceAnalog: The sourceAnalog field is optional but is the single mechanism for genuine cross-pollination — it shows your implementation of the pattern you're recommending. Always populate it when a source analog exists.
• Treating discuss as blocking: Nothing in the protocol gates complete on pending discussions being resolved. Treat discuss verdicts as flags for manual follow-up after the session.
• Not reviewing telemetry: The broker logs all events to JSONL. After a session, review the log to validate QSG assumptions — estimate α empirically (α ≈ 1 - reject_rate) and check per-category accept rates.

Related Skills

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