Negotiation, not transaction. Collaboration, not control.
A protocol for LLM agents that disagree, negotiate, and build consensus (without an orchestrator telling them what to do). Agents work as peers. Disagreement is signal, not error. Humans arbitrate, not micromanage. Every decision is auditable in plain markdown.
This is a Structured Negotiation of Autonomous Peers (SNAP). It's consent-based, peer multi-LLM collaboration with human-on-the-loop governance and public auditability.
A reusable protocol for collaborative sessions where multiple LLM agents work in parallel on a shared codebase, coordinated through markdown files and a human maintainer. No shared runtime, no direct agent-to-agent communication, no single model "in charge" of another.
This project is a protocol standard, not a centralized orchestration runtime.
Most multi-agent frameworks assume a boss. One model plans, others execute. Failure cascades before anyone catches it.
Turnfile inverts that:
- Peer agents, no hierarchy — agents propose within owned lanes, not commanded by an orchestrator
- Adversarial by design — counter-recommendations are first-class; disagreement surfaces before action
- Human as arbiter — maintainer holds intent and veto, not copy-paste relay duty
- Consensus under ambiguity — this is negotiation, not transaction; collaboration, not control
- Auditable in plain text — every decision in markdown, recoverable without tooling
The protocol emerged from real collaboration: 11 sessions, two LLM agents, one human maintainer, zero file collisions.
The inception archive contains the unedited record of two LLM agents (Claude 4.6 + Codex 5.3) building this protocol together across 11 sessions. No human wrote their messages. No orchestrator commanded them.
Start here:
- WORKLOG.md — session-by-session narrative of what happened
- MAILBOX.md — actual agent-to-agent messages with proposals, reviews, and counter-recommendations
- Session 10 Turnfile — coordination state mid-flight
Want a single example? MSG-20260208-027 shows Claude proposing a PRD change, Codex pushing back, and the agents converging without maintainer intervention.
- Read the stance: VISION.md — what this protocol believes
- See it work: examples/inception/WORKLOG.md — real session record
- Run your own: Copy templates/working-session/ and follow LLM Onboarding
Deeper dive: Protocol Core defines the invariant rules. PRDs in docs/prds/ define the contracts.
These principles emerged from real collaboration sessions and are encoded throughout the protocol:
- File-level lane ownership prevents merge conflicts — if two agents might edit the same file, redesign the split
- Contract-first enables parallel work — the shared interface ships with tests before implementation begins
- Disagreement is signal — counter-recommendations are documented and produce better outcomes than silent compliance
- The WORKLOG is the message bus — append-only, human-readable, eventually-consistent
- Retrospectives drive protocol evolution — every rule in this protocol was earned through real-world experience
- Turnfile as coordination state — a single YAML artifact replaces scattered lock files and status blocks for runtime coordination
This repository is intentionally scoped to maximize interoperability and auditability:
- Protocol-first: defines governance + communication contracts, not a control-plane implementation
- Runtime-agnostic: works across providers and tools without requiring a shared orchestrator
- Public-by-default artifacts: decisions, handoffs, and objections are readable without specialized tooling
- Human intent authority: maintainer sets direction and resolves disputes through logged decisions
- Explicit non-goal: not an autonomous agent-command system
| Document | Purpose |
|---|---|
| Protocol Core | Invariant rules, handoff formats, WORKLOG structure, session checklist |
| Communications Protocol | Event model, delivery semantics, mailbox extension |
| Notification Protocol | Mailbox format, 5-status lifecycle, SLA tiers, payload-first review envelopes |
| Session Charter | Reference for session-level governance (lanes, contracts, approval gates) |
| Conflict Resolution | Escalation ladder, counter-recommendation template, rollback policy |
| Human Governance | Maintainer role, approval bands, audit requirements |
| LLM Onboarding | Adding new agents: checklist, progression path, shadow review |
| Open Questions | Cross-PRD question registry with resolution tracking |
| Legal Summary | High-level patent landscape summary for counsel handoff |
Promoted PRDs define the detailed contracts that govern agent coordination. See docs/prds/ for the full (actioned) set. More are pending.
| PRD | Title |
|---|---|
| PRD-003 | Message lifecycle + SLA contract |
| PRD-004 | Maintainer decision contract |
| PRD-005 | Protocol data schema + compatibility |
| PRD-006 | Session promotion pipeline |
| PRD-007 | Trust + provenance layer |
| PRD-008 | Cross-sandbox handoff contract (payload-first) |
| PRD-009 | Cross-document reconciliation + OQ triage |
| PRD-010 | Shared-file transaction + Turnfile lease locking |
| PRD-011 | Session resumption contract |
| PRD-012 | Protocol skills pack for Codex + Claude |
| PRD-013 | Turnfile coordination format |
| PRD-014 | Session closeout + boot handoff contract |
Each agent maintains a self-contained skill file encoding the full protocol workflow (PRD-012). Skill files are reconciled by shared policy tests, not by sharing code.
| Path | Description |
|---|---|
| skills/claude-opus_4.6/SKILL.md | Claude protocol execution guide (v0.2.0) |
| skills/codex_5.3/SKILL.md | Codex protocol execution guide |
| templates/SKILL.md | Skill template for onboarding new agents |
| Artifact | Purpose |
|---|---|
| VISION.md | Maintainer intent and alignment reference |
| schemas/turnfile/ | JSON Schema for TURNFILE.yaml validation |
| tools/ | Validators and helpers (turnfile-lint, mailbox invariants, PRD promotion, payload envelopes) |
| Template | When to use |
|---|---|
| Session Charter | Starting a new collaborative session (includes handshake) |
| PRD | Drafting a new product requirement document |
| Skill File | Onboarding a new agent with protocol execution guide |
| Handoff | Transferring task ownership between agents |
| Proposal | Proposing a design decision or scope change |
| Decision Record | Recording a finalized decision |
| Counter-Recommendation | Disagreeing with another agent's recommendation |
| Retrospective | Closing a milestone with a structured review |
| Working-Session Files | Canonical file templates for the active workspace (TURNFILE, MAILBOX, WORKLOG, etc.) |
| Directory | What it contains |
|---|---|
| examples/ai-feature-tracker/ | Artifacts from the first real multi-agent session — protocol versions v1-v5, WORKLOG, retrospectives, onboarding guide |
| examples/inception/ | Full archive of the 11-session inception pilot — two LLM agents (Claude + Codex) collaborating on protocol development, including mailbox exchanges, TURNFILE.yaml, skill files, and policy test evidence |
Want to see what this looks like in practice? Start with the inception WORKLOG — it's the unedited session-by-session record of two LLM agents building this protocol together.
npm install # installs validator dependencies (ajv, js-yaml)Tools are in tools/ and can be run directly:
node tools/turnfile-lint.mjs # validate TURNFILE.yaml
node tools/validate-mailbox-invariants.mjs # check mailbox consistency
node tools/validate-prd-promotion.mjs # verify PRD promotion gates
node tools/export-mailbox-json.mjs # export mailbox to JSON
node tools/new-payload-envelope.mjs # generate payload envelopesThis protocol has been tested across 11+ real collaboration sessions with two LLM agents (Claude by Anthropic, Codex by OpenAI) and a human maintainer. The core rules are stable. Twelve PRDs have been promoted to canonical status. The protocol is being extended for 3+ agent support.
- Third agent onboarding (Gemini) — validates the onboarding guide and skill template with a non-incumbent agent
- GitHub repository polish: issue templates, PR templates, CI workflows (
.github/directory)
Apache 2.0 — see LICENSE for details.