peer-grill

name

peer-grill

description

Two (or more) agents — Claude sessions, other LLMs, or mixed — interrogate each other through a structured file-based protocol to converge on shared project state. Each agent independently dumps its model, the disagreements get grilled until convergence or surfaced as unresolved, and both sign off on a merged ground truth. Use when parallel sessions have diverged, when reconciling state across machines, or when the user mentions "have the agents grill each other", "peer-grill", "reconcile state", or "two agents agree on X".

Try agent-show-and-tell first. Most fleet-coordination needs are visibility, not consensus — show-and-tell is fire-and-forget, has no failure modes, and surfaces conflicts without trying to resolve them. Reach for peer-grill only when show-and-tell has already shown that two agents meaningfully disagree about a fact you actually need to settle.

This is a symmetric, file-based reconciliation protocol. There is no master and no relay. Each agent reads and writes only specific files in a shared directory. The protocol works whether the peer is another Claude session, a non-Claude LLM, or a human pretending to be one — as long as everyone follows the file conventions.

This skill is invoked by one of the peers. It assumes the other peer is independently running the same protocol (or a manual analog). If the other side never shows up, the protocol fails loud at the timeout step rather than silently merging one-sided state.

Working directory

All artifacts live in .peer-grill/<topic>/ relative to repo root, where <topic> is a short slug for what's being reconciled (e.g. pricing-decisions, infra-state, q2-plan). Default to default if the user doesn't specify.

File	Writers	Readers	Purpose
<agent>.claims.yaml	only that agent	everyone	self-reported model of the state
diff.md	last writer to compute it (append-only)	everyone	three-bucket diff: agreed / disagreed / only-one
grill-log.md	append-only, both	everyone	full Q&A transcript with timestamps and agent identity
state.merged.yaml	the merge writer (first alphabetically among peers) — once all claims identified in Phase 3 are ratified or escalated. Others read only.	everyone	the converged ground truth
unresolved.md	append-only, both	everyone	disputes that didn't converge; both positions recorded
signoff.md	append-only, both	everyone	identity + timestamp + sha256 of state.merged.yaml each agent attests to

Hard rules:

• An agent never edits another agent's claims.yaml.
• state.merged.yaml is written only by the merge writer — the peer whose name sorts first alphabetically — once all non-agreed claims are either ratified or escalated. The merge writer overwrites the file (it's a single-writer batch artifact; appending would produce malformed YAML).
• Append-only files (grill-log.md, signoff.md, unresolved.md) are append-only — never rewrite history.

Terminal events

The protocol has five terminal-event types. They share a log-line shape [<ISO>] <self> | <EVENT>: <detail> written to grill-log.md. Phase bodies below cite events by name; this table is the canonical definition.

Event	Trigger	Phase	Action
TIMEOUT: phase=<n>	Poll/wait exhausts poll_timeout_minutes	2, 5	append; surface to user; stop
PARSE-FAIL: <peer-file>	Peer's claims.yaml fails to parse as YAML on two reads 5 seconds apart	2	append; surface to user; stop
IDENTITY-COLLISION	Peer's agent field equals <self>	2	append; surface to user; stop
ESCALATE: <claim-id>	Round budget exhausted on a disputed claim	4	append; also write both positions to unresolved.md; continue protocol (only this event doesn't stop)
INTEGRITY-FAIL: <reason>	Sign-off cannot converge — reason=iter-loop (third sha256 mismatch in a row) or reason=stalled (5-minute no-activity stall)	6	append; surface to user; stop

Setup — ask the user before any writes

1. Topic — what state are we reconciling? Get a slug.
2. Identity — what name is this agent? (e.g., claude-laptop, claude-pr-bot, cursor-mac). Must be unique across peers.
3. Peer — what's the peer's identity, and how is it accessed (separate Claude session, another model, user-relayed)? If the peer is non-Claude, the user is responsible for getting that peer to follow the same protocol — offer to write a one-page system-prompt summary the user can paste into the peer.
4. Scope — what categories of claims belong to this reconciliation? (infra, code, decision, open-work, etc.) Anything outside these categories is filtered out before diffing.
5. Round budget — max grilling rounds per disputed claim before ESCALATE (default: 3).
6. poll_timeout_minutes — wall-clock budget for polls in Phase 2 and Phase 5 (default: 30). Single configurable parameter applied uniformly; not two independent budgets.

Protocol

1. Independent dump

Write <agent>.claims.yaml. Do not read the peer's file yet. Each claim is:

agent: <agent-name>
session_started: <ISO8601>
scope: [infra, code, decision, open-work]
claims:
  - id: <stable-slug>            # same id across agents = same subject
    statement: <one sentence>
    confidence: high | medium | low
    source: <how you know — file path, command, observation, prior decision>
    scope: <one of the declared scopes>
    last_verified: <ISO8601 or "unknown">

Confidence rules:

• high requires a checkable source (file path + line, command output, signed-off doc).
• medium is "I inferred this from X but X may be stale."
• low is "I think this is true but I don't have a source."

Stable slugs matter: db-version, not db-version-as-of-may-1. Same id from different agents = same subject; a different statement = a disagreement, not a collision.

2. Read & validate peer's claims

Three sequential checks: poll → parse → identity. Each check has one terminal event.

1. Poll for <peer>.claims.yaml every 60 seconds, up to poll_timeout_minutes. On timeout, emit TIMEOUT: phase=2.
2. Parse the file as YAML. On failure, wait 5 seconds and retry once (handles transient filesystem races where the peer is mid-write). If the second read also fails, emit PARSE-FAIL: <peer-file>.
3. Identity-check. If the peer's agent field equals <self>, emit IDENTITY-COLLISION. Catching this here — before grilling or merging — prevents both peers from later self-identifying as the alphabetically-first merge writer.

3. Diff

Compute three buckets:

• agreed: same id, same statement (modulo whitespace), compatible scopes. Merge directly into state.merged.yaml with sources = the union of both peers' source values for that id (deduplicate identical strings; preserve both peers' citations side-by-side otherwise). Agreed claims do not enter the grill loop and do not require RATIFY: lines.
• disagreed: same id, different statements.
• only-one-knows: id present in one agent's file, absent from the other's.

Append the diff to diff.md as a single block, prefixed with timestamp and which agent wrote it. If the peer also wrote a diff, compare them — diffs-of-diffs catch silent-drop bugs. Any divergence between the two computed diffs is itself a disagreement to resolve before grilling claims.

4. Grill loop

For each item in disagreed and only-one-knows, in grill-log.md:

[<ISO>] <asker> -> <answerer> | claim:<id> | round:1
Q: <question — must include the specific phrasing or source you doubt>
[<ISO>] <answerer> -> <asker> | claim:<id> | round:1
A: <answer — must cite a source the asker can in principle verify>

Rules:

• For disagreed claims, the agent with the lower confidence asks first. Ties broken alphabetically by agent name.
• For only-one-knows, the agent who doesn't know asks.
• An answer that doesn't cite a verifiable source is grounds for another round.
• After the round budget is exhausted without convergence, emit ESCALATE: <claim-id> per Terminal events. The rest of the protocol continues; only this claim is finalized as unresolved.
• On convergence, both agents must independently write RATIFY: <claim-id> | <agreed-statement> lines to grill-log.md. Both <agreed-statement> values must match exactly modulo leading/trailing whitespace. If they diverge, the claim is not ratified — return to the grill loop for that claim. The ratification attempt itself does not count as a round; the counter resumes from where it left off after the last actual Q&A round. If the budget was already exhausted when ratification was attempted, no further Q&A is possible and the claim immediately emits ESCALATE: <claim-id> per Terminal events.

5. Merge

The merge writer waits, up to poll_timeout_minutes, for every claim in the disagreed and only-one-knows buckets to be either ratified (matching RATIFY: lines from both peers) or escalated. Agreed-bucket claims skip the grill loop and don't need either; they're merged directly. On timeout, emit TIMEOUT: phase=5.

When all non-agreed claims are processed, the merge writer writes state.merged.yaml with all agreed claims plus all ratified claims. (Per Hard rules: only the merge writer writes; the file is overwritten, never appended.)

The non-writer peer polls for the file's appearance with the same poll_timeout_minutes and proceeds to Phase 6 once it's present. On timeout, emit TIMEOUT: phase=5.

Format mirrors the dump format minus per-agent fields:

topic: <topic>
ratified_at: <ISO8601>
peers: [<agent-a>, <agent-b>]
claims:
  - id: <id>
    statement: <agreed statement>
    sources: [<from agent-a>, <from agent-b>]   # both sources preserved
    scope: <scope>

6. Sign-off

Compute sha256 of state.merged.yaml after LF-normalizing the file content (strip any \r — cross-platform line endings are otherwise the most likely cause of stable-but-divergent hashes). Append to signoff.md:

agent: <name>
timestamp: <ISO8601>
merged_state_sha256: <hex>
attestation: "I attest the above merged state as the agreed truth as of this timestamp."

Mismatch handling. Iteration is normal — sha256 mismatches do not immediately escalate. Any agent that observes a mismatch with the peer's signoff re-reads state.merged.yaml (LF-normalized), recomputes their own sha256, and either confirms it still matches their last signoff (no further action) or appends a superseding signoff entry referencing their own prior signoff's timestamp:

agent: <name>
timestamp: <new ISO8601>
merged_state_sha256: <new hex>
supersedes: <prior timestamp from this agent>
attestation: "I attest the above merged state as the agreed truth as of this timestamp."

This is symmetric — the merge writer can have a stale hash too. Don't defer to a "later signer."

Emit INTEGRITY-FAIL: <reason> (per Terminal events) in exactly two cases:

• iter-loop: third sha256 mismatch in a row, i.e. two of your own supersedes without convergence. Indicates the merge writer is editing in a loop the other peer can't keep up with.
• stalled: mismatch persists 5 minutes with no new entry in signoff.md or grill-log.md and your hash is stable.

7. Report

To the user, summarize: converged claim count, unresolved count (with link to unresolved.md), peers, sha256 of final state, total rounds spent. Offer to commit .peer-grill/<topic>/ to git so the reconciliation is auditable.

Use case: teaching the skills framework via reconciliation

Peer-grill doubles as a teaching mechanism when one peer knows something the other doesn't. The asymmetry surfaces during step 3 as only-one-knows items, and step 4 forces the less-informed peer to grill the more-informed one until the claim is verified and ratified.

Concrete recipe — teaching the Claude skills framework to a non-Claude agent:

1. Set topic = skills-framework.
2. The Claude peer's claims.yaml enumerates what exists: each skill's id, location, purpose, and the rules of the framework itself (frontmatter format, trigger phrases, working-directory conventions).
3. The non-Claude peer's claims.yaml is mostly empty (or contains its current — possibly wrong — model of how skills work).
4. Steps 3–4 run normally. Every skill becomes an only-one-knows item; the non-Claude peer grills the Claude peer on each one until the source citations are convincing.
5. The merged state.merged.yaml becomes a verified, peer-attested description of the framework that the non-Claude agent now genuinely understands — not just was told.

This works for any framework, doc set, or shared mental model — not just skills. Pick topic to match what's being taught.

Multi-peer (3+) extension

For N-agent consensus or ratification of a single artifact, use the fleet-ratify skill instead. peer-grill is optimized for 1:1 reconciliation of broad state; fleet-ratify is the capstone for N agents signing a specific, frozen artifact.

Pairwise reconciliations in a chain (A↔B, then merged↔C) are still supported in peer-grill for broad state sync, but for formal decision-making by the whole fleet, fleet-ratify is the preferred path. Document the chain order in grill-log.md if using the chain method.

Consensus Governor (ConsensusManager)

The consensus_manager.py module provides the ConsensusManager class — the protocol governor that analyzes the immutable grill log to diagnose the current level of consensus, identify points of divergence, and suggest the next most valuable intellectual action.

Role

• Reads the grill log via ClaimsStateManager.get_history()
• Computes a divergence score from contradiction markers and log volume
• Classifies the session into one of three states: DEADLOCK, NEAR_CONSENSUS, or OPEN_DISPUTE
• Recommends next actions: continue grilling, trigger external skill calls (e.g. gitnexus-impact-analysis), or proceed to final ratification

States

State	Divergence Score	Meaning	Recommended Action
DEADLOCK	> 0.8	Claims are fundamentally irreducible via pure dialectic	Require external proof (system test, knowledge graph query)
NEAR_CONSENSUS	< 0.3 + sustained effort	Persistent agreement on core axioms	Trigger final_ratification()
OPEN_DISPUTE	0.3–0.8	Active, productive debate	Continue grilling on specific points of contention

The ConsensusManager is not a decision-maker — it is a diagnostic tool. It surfaces the state; the agents (and ultimately the human) decide.

Modular Dependency Graph

The peer-grill skill is implemented as a set of Python modules with clear dependencies:

core.py
├── state_manager.py   (ClaimsStateManager: append-only log ledger)
├── crypto_utils.py    (AttestationManager: SHA256 hashing, ratification)
├── dialectics.py      (DialecticProcessor: thesis/antithesis/synthesis structuring)
└── consensus_manager.py → state_manager.py  (ConsensusManager: divergence analysis)

Module responsibilities:

Module	Class	Responsibility
state_manager.py	ClaimsStateManager	Append-only log file management; claim dumping; history retrieval; log trimming
crypto_utils.py	AttestationManager	SHA256 hashing of claims and log state; re-attestation after each round; final ratification hash generation
dialectics.py	DialecticProcessor	Structural analysis of claims; classification into Thesis/Antithesis/Quaestio/Aporia; formal challenge formatting
consensus_manager.py	ConsensusManager	Divergence scoring; consensus state diagnosis; next-action recommendation
core.py	(entry point)	Session initialization; grilling cycle orchestration; ratification finalization; run_peer_grill() entry point

Scripts (in scripts/): peer_grill_init.sh, peer_grill_diff.py, peer_grill_check_convergence.py, peer_grill_signoff.py, peer_grill_grade.py, peer_grill_fingerprint.py — CLI wrappers for protocol phases.

Templates (in templates/): claims.yaml.template, system-prompt-for-non-claude-peer.md.

Schemas (in schemas/): claims.schema.json — JSON Schema for validating claims.yaml files.

Required Input Structure

Every peer-grill session requires these inputs before the protocol can begin (see Setup, Phase 1):

Session parameters (human-provided)

Parameter	Type	Required	Default	Description
topic	kebab-slug	Yes	—	What state is being reconciled (e.g. pricing-decisions, infra-state)
self (agent identity)	kebab-slug	Yes	—	This agent's unique name (e.g. claude-laptop, cursor-mac)
peer (peer identity)	kebab-slug	Yes	—	The other agent's unique name
scope	list of strings	Yes	—	Claim categories: infra, code, decision, open-work, etc.
round_budget	integer	No	3	Max grilling rounds per disputed claim before ESCALATE
poll_timeout_minutes	integer	No	30	Wall-clock budget for Phase 2 and Phase 5 polls

Claims file (<agent>.claims.yaml)

Each agent independently writes a claims file following this schema (validated by schemas/claims.schema.json):

agent: <agent-name>              # required, unique across peers
session_started: <ISO8601>       # required
scope: [<category>, ...]         # required, must match declared scopes
claims:                          # required, can be empty list
  - id: <stable-slug>            # required, same id across agents = same subject
    statement: <one sentence>    # required
    confidence: high|medium|low  # required
    source: <verifiable source>  # required for high confidence
    scope: <category>            # required, must be in declared scopes
    last_verified: <ISO8601>     # required, or "unknown"

Confidence rules:

• high requires a checkable source (file path + line, command output, signed-off doc)
• medium = inferred from possibly-stale signal
• low = guess with no source

Final Output Artifact

The terminal deliverable of a successful peer-grill session is state.merged.yaml — the converged ground truth, written by the merge writer in Phase 5 and attested by both peers in Phase 6.

Format

topic: <topic-slug>
ratified_at: <ISO8601>
peers: [<agent-a>, <agent-b>]
claims:
  - id: <stable-slug>
    statement: <agreed statement>
    sources: [<source from agent-a>, <source from agent-b>]
    scope: <category>

What it contains

• All claims from the agreed bucket (same id, same statement across peers) — merged directly, no grill loop required
• All claims from the disagreed and only-one-knows buckets that were ratified (both peers wrote matching RATIFY: lines in grill-log.md)
• Both peers' source citations preserved side-by-side (deduplicated when identical)

What it does NOT contain

• Claims that were escalated (round budget exhausted without convergence) — these go to unresolved.md instead
• Claims outside the declared scopes (filtered before diffing)
• Per-agent metadata (confidence, session_started) — the merged state is the agreed truth, not the process

Integrity

The state.merged.yaml file is attested by both peers via SHA256 in signoff.md. The hash is computed after LF-normalizing the file content. Mismatched hashes trigger the Phase 6 iteration protocol; three consecutive mismatches emit INTEGRITY-FAIL: iter-loop.

Companion artifacts

File	Content
unresolved.md	Disputes that didn't converge; both positions recorded
signoff.md	Identity + timestamp + sha256 attestations from both peers
grill-log.md	Full Q&A transcript with timestamps and agent identity
diff.md	Three-bucket diff: agreed / disagreed / only-one-knows

Guardrails

• Never silently accept a one-sided claim. only-one-knows items must be grilled at least once.
• Never rewrite append-only files; if a correction is needed, append a new entry that supersedes the old one and reference the old one's timestamp.
• Don't trust your own confidence levels uncritically — when a peer challenges a high claim, re-verify the source rather than restating the assertion.
• Don't invent claims to fill gaps. If a scope has no claims, the merged state has no claims in that scope, and that's correct.
• If running this skill and the peer is also Claude, suggest the user run each peer in a separate session/terminal so they don't share context — context-sharing defeats the point of independent dumps.