Cross Review Project

---
name: cross-review-project
description: >
  Conduct a structured cross-project code review between two Claude Code
  instances via the cross-review-mcp broker. Each agent reads its own
  codebase, reviews the peer's code, and engages in evidence-backed
  dialogue — with QSG scaling laws enforcing review quality through
  minimum bandwidth constraints and phase-gated progression.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: mcp-integration
  complexity: advanced
  language: multi
  tags: mcp, cross-review, multi-agent, code-review, qsg, a2a
  locale: de
  source_locale: en
  source_commit: 11edabf5
  fence_basis_commit: 11edabf5
  translator: "Claude + human review"
  translation_date: "2026-05-03"
---

# Projekt-Cross-Review

Zwei Claude-Code-Instanzen pruefen die Projekte des jeweils anderen durch strukturierten Artefakt-Austausch via den `cross-review-mcp`-Broker. Der Broker erzwingt Quantized-Simplex-Gossip-(QSG)-Skalengesetze — Review-Buendel muessen mindestens 5 Befunde enthalten um im Selektionsregime zu bleiben (Γ_h ≈ 1,67), was verhindert dass oberflaechlicher Konsens als Uebereinstimmung durchgeht.

## Wann verwenden

- Zwei Projekte teilen architektonische Anliegen und koennten voneinander lernen
- Unabhaengiges Code-Review erwuenscht das ueber das hinausgeht was ein einzelner Reviewer sieht
- Cross-Pollination ist das Ziel: Muster in einem Projekt finden die im anderen fehlen
- Strukturiertes, evidenzbasiertes Review mit accept/reject/discuss-Verdicts noetig

## Eingaben

- **Erforderlich**: Zwei Projektpfade die zwei Claude-Code-Instanzen zugaenglich sind
- **Erforderlich**: `cross-review-mcp`-Broker laeuft und ist als MCP-Server in beiden Instanzen konfiguriert
- **Optional**: Fokusbereiche — spezifische Verzeichnisse, Muster oder Anliegen zu priorisieren
- **Optional**: Agent-IDs — Identifikatoren fuer jede Instanz (Standard: Projektverzeichnisname)

## Vorgehensweise

### Schritt 1: Voraussetzungen verifizieren

Bestaetigen dass der Broker laeuft und beide Instanzen ihn erreichen koennen.

1. Pruefen dass der Broker als MCP-Server konfiguriert ist:
   ```bash
   claude mcp list | grep cross-review
   ```
2. `get_status` aufrufen um zu verifizieren dass der Broker antwortet und keine veralteten Agents registriert sind
3. Die Protokoll-Resource bei `cross-review://protocol` lesen — dies ist ein Markdown-Dokument das die Review-Dimensionen und QSG-Beschraenkungen beschreibt

**Erwartet:** Der Broker antwortet auf `get_status` mit einer leeren Agent-Liste. Die Protokoll-Resource ist als Markdown lesbar.

**Bei Fehler:** Wenn der Broker nicht konfiguriert ist, hinzufuegen: `claude mcp add cross-review-mcp -- npx cross-review-mcp`. Wenn veraltete Agents aus einer vorigen Session existieren, fuer jeden `deregister` aufrufen bevor fortgefahren wird.

### Schritt 2: Registrieren

Diesen Agent beim Broker registrieren.

1. `register` aufrufen mit:
   - `agentId`: ein kurzer, einzigartiger Identifikator (z.B. Projektverzeichnisname)
   - `project`: der Projektname
   - `capabilities`: `["review", "suggest"]`
2. Registrierung verifizieren mit `get_status` — der Agent sollte mit Phase `"registered"` erscheinen
3. Auf Registrierung des Peer-Agents warten: `wait_for_phase` mit der Agent-ID des Peers und Phase `"registered"` aufrufen

**Erwartet:** Beide Agents beim Broker registriert. `get_status` zeigt 2 Agents in Phase `"registered"`.

**Bei Fehler:** Wenn `register` mit "already registered" scheitert, ist die Agent-ID aus einer vorigen Session belegt. Zuerst `deregister` aufrufen, dann erneut registrieren.

### Schritt 3: Briefing-Phase

Eigene Codebasis lesen und ein strukturiertes Briefing an den Peer senden.

1. Systematisch lesen:
   - Einstiegspunkte (Hauptdateien, Index, CLI-Befehle)
   - Abhaengigkeitsgraph (package.json, DESCRIPTION, go.mod)
   - Architektonische Muster (Verzeichnisstruktur, Modulgrenzen)
   - Bekannte Probleme (TODO-Kommentare, offene Issues, Tech Debt)
   - Test-Coverage (Test-Verzeichnisse, CI-Konfiguration)
2. Ein `Briefing`-Artefakt komponieren — eine strukturierte Zusammenfassung die der Peer nutzen kann um deine Codebasis effizient zu navigieren
3. `send_task` aufrufen mit:
   - `from`: deine Agent-ID
   - `to`: Peer-Agent-ID
   - `type`: `"briefing"`
   - `payload`: JSON-kodiertes Briefing
4. `signal_phase` mit Phase `"briefing"` aufrufen

**Erwartet:** Briefing gesendet und Phase signalisiert. Der Broker erzwingt dass ein Briefing gesendet werden muss bevor zu Review uebergegangen werden kann.

**Bei Fehler:** Wenn `send_task` das Briefing ablehnt, pruefen dass das `from`-Feld mit deiner registrierten Agent-ID uebereinstimmt. Self-Sends werden abgelehnt.

### Schritt 4: Review-Phase

Auf das Briefing des Peers warten, dann seinen Code pruefen und Befunde senden.

1. `wait_for_phase` mit der Peer-ID und Phase `"briefing"` aufrufen
2. `poll_tasks` aufrufen um das Briefing des Peers abzurufen
3. `ack_tasks` mit den empfangenen Task-IDs aufrufen — dies ist erforderlich (Peek-then-Ack-Muster)
4. Den tatsaechlichen Quellcode des Peers lesen, informiert durch sein Briefing
5. Befunde ueber 6 Kategorien produzieren:
   - `pattern_transfer` — ein Muster in deinem Projekt das der Peer uebernehmen koennte
   - `missing_practice` — eine Praxis die dem Peer fehlt (Testing, Validierung, Fehlerbehandlung)
   - `inconsistency` — interner Widerspruch innerhalb der Codebasis des Peers
   - `simplification` — unnoetige Komplexitaet die reduziert werden koennte
   - `bug_risk` — potenzieller Laufzeitfehler oder Grenzfall
   - `documentation_gap` — fehlende oder irrefuehrende Dokumentation
6. Jeder Befund muss enthalten:
   - `id`: einzigartiger Identifikator (z.B. `"F-001"`)
   - `category`: eine der 6 Kategorien oben
   - `targetFile`: Pfad im Projekt des Peers
   - `description`: was du gefunden hast
   - `evidence`: warum dies ein gueltiger Befund ist (Code-Referenzen, Muster)
   - `sourceAnalog` (empfohlen): das Aequivalent in deinem eigenen Projekt das das Muster demonstriert — dies ist der einzige Mechanismus fuer genuine Cross-Pollination
7. Mindestens **5 Befunde** buendeln (QSG-Beschraenkung: m ≥ 5 haelt Γ_h ≈ 1,67 im Selektionsregime)
8. `send_task` mit Type `"review_bundle"` und dem JSON-kodierten Findings-Array aufrufen
9. `signal_phase` mit Phase `"review"` aufrufen

**Erwartet:** Review-Bundle vom Broker akzeptiert. Weniger als 5 Befunde werden abgelehnt.

**Bei Fehler:** Wenn das Bundle wegen unzureichender Befunde abgelehnt wird, tiefer pruefen. Die Beschraenkung existiert um zu verhindern dass oberflaechliche Reviews dominieren. Wenn genuein keine 5 Probleme gefunden werden koennen, neu pruefen ob Cross-Review das richtige Werkzeug fuer dieses Projektpaar ist.

### Schritt 5: Dialog-Phase

Befunde ueber das eigene Projekt empfangen und mit evidenzbasierten Verdicts antworten.

1. `wait_for_phase` mit der Peer-ID und Phase `"review"` aufrufen
2. `poll_tasks` aufrufen um Befunde zum eigenen Projekt abzurufen
3. `ack_tasks` mit den empfangenen Task-IDs aufrufen
4. Fuer jeden Befund eine `FindingResponse` produzieren:
   - `findingId`: entspricht der Befund-ID
   - `verdict`: `"accept"` (gueltig, wird gehandelt), `"reject"` (ungueltig, mit Gegenevidenz) oder `"discuss"` (braucht Klaerung)
   - `evidence`: warum du akzeptierst oder ablehnst — muss nicht-leer sein
   - `counterEvidence` (optional): spezifische Code-Referenzen die dem Befund widersprechen
5. Alle Antworten via `send_task` mit Type `"response"` senden
6. `signal_phase` mit Phase `"dialogue"` aufrufen

Hinweis: das `"discuss"`-Verdict ist nicht durch das Protokoll gesperrt — als Flag fuer manuelle Nachverfolgung behandeln, nicht als automatisierten Sub-Austausch.

**Erwartet:** Auf alle Befunde wurde mit Verdicts geantwortet. Leere Antworten werden vom Broker abgelehnt.

**Bei Fehler:** Wenn keine Meinung zu einem Befund gebildet werden kann, auf `"discuss"` defaulten mit Evidenz die erklaert welcher zusaetzliche Kontext gebraucht wird.

### Schritt 6: Synthese-Phase

Ein Synthese-Artefakt produzieren das akzeptierte Befunde und geplante Aktionen zusammenfasst.

1. `wait_for_phase` mit der Peer-ID und Phase `"dialogue"` aufrufen
2. Verbleibende Tasks pollen und bestaetigen
3. Ein `Synthesis`-Artefakt zusammenstellen:
   - Akzeptierte Befunde mit geplanten Aktionen (was du aendern wirst und warum)
   - Abgelehnte Befunde mit Gruenden (bewahrt das Reasoning fuer zukuenftige Reviews)
4. `send_task` mit Type `"synthesis"` und der JSON-kodierten Synthese aufrufen
5. `signal_phase` mit Phase `"synthesis"` aufrufen
6. Optional GitHub-Issues fuer akzeptierte Befunde erstellen
7. `signal_phase` mit Phase `"complete"` aufrufen
8. `deregister` aufrufen zum Aufraeumen

**Erwartet:** Beide Agents erreichen `"complete"`. Der Broker verlangt mindestens 2 registrierte Agents um zu complete vorzurueacken.

**Bei Fehler:** Wenn der Peer bereits deregistriert hat, kann lokal trotzdem komplettiert werden. Die Synthese aus den empfangenen Befunden zusammenstellen.

## Validierung

- [ ] Beide Agents registriert und Phase `"complete"` erreicht
- [ ] Briefings ausgetauscht bevor Reviews begannen (Phasen-Erzwingung)
- [ ] Review-Bundles enthielten jeweils mindestens 5 Befunde
- [ ] Alle Befunde erhielten ein Verdict (accept/reject/discuss) mit Evidenz
- [ ] `ack_tasks` nach jedem `poll_tasks` aufgerufen
- [ ] Synthese produziert mit akzeptierten Befunden auf Aktionen abgebildet
- [ ] Agents nach Komplettierung deregistriert

## Haeufige Stolperfallen

- **Weniger als 5 Befunde**: Der Broker lehnt Bundles mit m < 5 ab. Dies ist nicht willkuerlich — mit N=2 Agents und 6 Kategorien setzt m < 5 Γ_h auf oder unter die kritische Grenze wo Konsens nicht von Rauschen unterscheidbar ist. Tiefer pruefen; wenn 5 Befunde genuein nicht gefunden werden koennen, profitieren die Projekte moeglicherweise nicht vom Cross-Review.
- **`ack_tasks` vergessen**: Der Broker nutzt Peek-then-Ack-Delivery. Tasks bleiben in der Queue bis sie bestaetigt sind. Vergessenes Ack verursacht doppelte Verarbeitung beim naechsten Poll.
- **Den `from`-Parameter vergessen**: `send_task` erfordert ein explizites `from`-Feld das mit der Agent-ID uebereinstimmt. Self-Sends werden abgelehnt.
- **Selbe-Modell epistemische Korrelation**: Zwei Claude-Instanzen teilen Training-Biases. Zeitliche Ordnung stellt sicher dass sie waehrend Review nicht die Ausgabe des anderen lesen, aber ihre Priors sind korreliert. Fuer genuine epistemische Unabhaengigkeit unterschiedliche Modellfamilien ueber Instanzen nutzen.
- **`sourceAnalog` ueberspringen**: Das `sourceAnalog`-Feld ist optional aber der einzige Mechanismus fuer genuine Cross-Pollination — es zeigt *deine* Implementation des Musters das du empfiehlst. Immer befuellen wenn ein Source-Analog existiert.
- **`discuss` als blockierend behandeln**: Nichts im Protokoll sperrt `complete` darauf dass anhaengende Diskussionen geloest werden. `discuss`-Verdicts als Flags fuer manuelle Nachverfolgung nach der Session behandeln.
- **Telemetrie nicht reviewen**: Der Broker loggt alle Events nach JSONL. Nach einer Session das Log pruefen um QSG-Annahmen zu validieren — α empirisch schaetzen (`α ≈ 1 - reject_rate`) und Per-Kategorie-Akzeptanzraten pruefen.

## Verwandte Skills

- `scaffold-mcp-server` — fuer Bauen oder Erweitern des Brokers selbst
- `implement-a2a-server` — A2A-Protokoll-Muster aus denen der Broker schoepft
- `review-codebase` — Single-Agent-Review (dieser Skill erweitert es zu Cross-Agent-strukturiertem Austausch)
- `build-consensus` — Schwarm-Konsens-Muster (QSG ist die theoretische Grundlage)
- `configure-mcp-server` — den Broker als MCP-Server in Claude Code konfigurieren
- `unleash-the-agents` — kann genutzt werden um den Broker selbst zu analysieren (battle-tested: 40 Agents, 10 Hypothesen-Familien)