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.
Teams building multi-agent systems where LLM agents must coordinate as peers — disagreeing, negotiating, and reaching consensus without a central orchestrator.
Multi-agent setups default to a central orchestrator that dictates to subordinate agents, hiding disagreement and decisions. Turnfile is a protocol for peer agents to negotiate and reach auditable consensus with humans on the loop.
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 baseline: BASELINE.md: what Turnfile is and how the project works (a point-in-time session-14 snapshot; for live current state see PRD_STATUS.json and WORKLOG.md)
- Read the stance: INTENT.md: where this protocol is going
- 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 |
|---|---|
| BASELINE | Ratified project snapshot: current state, PRD shelf statuses, standing decisions, forward task register |
| INTENT | Forward strategy: Turnfile as a thin governance layer for auditable peer disagreement across existing agent platforms |
| Specification | Concise normative contract for the narrowed Turnfile protocol |
| Definitions | Controlled vocabulary for Turnfile terms, roles, statuses, and governance concepts |
| Roadmap | Non-normative planning notes for the narrowed project direction |
| Security | Vulnerability reporting, trust model, and runtime security boundaries |
| Vision | Historical and explanatory maintainer intent document, superseded by INTENT.md for forward development direction |
| 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 |
PRDs live on two shelves. Promoted, Maintainer-accepted contracts live in docs/prds/. Drafts and deferred PRDs live in working-session/docs/, with PRD_STATUS.json as the authoritative status registry. This index covers both shelves.
| PRD | Title | Status |
|---|---|---|
| PRD-001 | Maintainer interaction model | Promoted |
| PRD-002 | Rust notification viewer MVP | Deferred (archived) |
| PRD-003 | Message lifecycle + SLA contract | Promoted |
| PRD-004 | Maintainer decision contract | Promoted |
| PRD-005 | Protocol data schema + compatibility | Promoted |
| PRD-006 | Session promotion pipeline + eight-step implementation loop (A1) | Promoted |
| PRD-007 | Trust + provenance layer | Promoted |
| PRD-008 | Cross-sandbox handoff contract (payload-first) | Promoted |
| PRD-009 | Cross-document reconciliation + OQ triage | Promoted |
| PRD-010 | Shared-file transaction + Turnfile lease locking | Promoted |
| PRD-011 | Session resumption contract | Promoted |
| PRD-012 | Protocol skills pack for Codex + Claude | Promoted |
| PRD-013 | Turnfile coordination format | Promoted |
| PRD-014 | Session closeout + boot handoff contract | Promoted |
| PRD-015 | Agent onboarding + vetting contract | Promoted; implementation done |
| PRD-016 | Session rotation + new thread trigger contract | Promoted |
| PRD-017 | Boot sequence + documentation contract (includes folded PRD-020 as R7) | Promoted |
| PRD-018 | Maintainer approval authority matrix | Promoted |
| PRD-019 | Mailbox-first approval, event-based cadence | Promoted |
| PRD-020 | Boot artifact completeness + chat log contract | Superseded (archived; folded into PRD-017 R7) |
| PRD-021 | Conflict loop bound + selective-unlock gradient | Promoted; implementation done (session 16) |
| PRD-022 | Decision-mirror delivery contract | Promoted; implementation done (session 16) |
| PRD-023 | Out-of-band activity reconciliation | Promoted; implementation done (session 16) |
| PRD-024 | Human-legibility invariant + encoding profiles | Promoted; implementation done (session 16) |
| PRD-026 | Review-cycle closure + task-state consistency | Promoted; implementation done (session 16) |
| PRD-027 | Tokenese cloned-communication A/B | Accepted + promoted; live mini-pilot scored (W1/L1/W2/W5), W3/L2 authored |
| PRD-028 | Tokenese dual-artifact sync + Maintainer legibility | Promoted; implementation done (session 14) |
| PRD-029 | Pre-write state derivation contract | Promoted; implementation done (session 14) |
| PRD-030 | Session heartbeat management contract | Promoted; implementation done (session 16) |
| PRD-031 | Concurrent multi-agent coordination | Promoted; Phase 1 implemented (per-agent shards + derived aggregates) |
| PRD-032 | Session orientation tool contract | Promoted; implementation done (session 17) |
| PRD-033 | Skill ownership integrity guard | Promoted; implementation done (session 17) |
| PRD-034 | Public + agent-facing surface snapshot reconciliation | Promoted; implementation done |
| PRD-035 | Tokenese integration + upstream result sync | Promoted; implementation done |
| PRD-036 | PRD eval runner contract | Promoted; implementation done (session 20) |
| PRD-037 | Boot simplification | Promoted; implementation eval-verified |
| PRD-038 | Read-only heartbeat stewards | Promoted; implementation pending |
| PRD-039 | Perplexity Computer onboarding deltas | Draft; evals authored, pending Gemini peer review and Maintainer acceptance |
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.
Bundles are role-keyed directories with model compatibility recorded in each MANIFEST.yaml rather than the path. The Claude and Codex bundles migrated in session 14; Gemini onboarded in session 19, reached full-active status in session 21 under PRD-015, and runs on its own role-keyed bundle. The protocol itself is model-agnostic: session 14 ran the Claude lane on a new model generation (Fable 5) against the unmodified v3 bundle before upgrading it.
| Path | Description |
|---|---|
| skills/claude/SKILL.md | Claude protocol execution guide (v0.9.2, role-keyed; bundle version 14) |
| skills/codex/SKILL.md | Codex protocol execution guide (role-keyed; bundle version 10) |
| .agents/skills/turnfile-protocol-gemini/SKILL.md | Gemini protocol execution guide (v0.2.2, role-keyed; bundle version 3; full-active, peer-reviewed) |
| skills/skill-versioning/SKILL.md | Shared metaskill for versioning skill bundles across agents. Current installs may expose the same bundle as skill-provenance. |
| 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) |
| Validation | Readiness gate, eval suite, and CI validation commands |
| 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 envelopes
node tools/validate-skills-preflight.mjs # verify skill install/parity/versioning integrity
node tools/validate-tokenese-pairs.mjs # verify tokenese dual-artifact sync (PRD-028)
node tools/next-state.mjs --mailbox <path> --turnfile <path> # derive next IDs/counts before writing (PRD-029)Package scripts:
npm run validate # run the full repo readiness suite
npm run validate:skills # strict preflight (requires global skill install)
npm run validate:skills:ci # repo-only checks (CI-safe)
npm run evals:prd # run the aggregate PRD implementation evalsTurnfile evals fall into three categories: repo readiness validators (npm run validate), PRD implementation evals (the aggregate npm run evals:prd over evals/*.evals.mjs), and focused PRD evals run directly, for example node --test evals/prd-032.evals.mjs. CI runs validate and evals:prd as separate steps so the readiness gate and the PRD evals are attributed independently; PRD suites whose registry implementation state is still pending run as logged expected-pending suites rather than failing the gate. See Validation for the full taxonomy and CI policy.
This protocol has been tested across 23 real collaboration sessions with three heterogeneous LLM agents and a human maintainer:
- Claude (Anthropic), running in Claude Code.
- Codex (OpenAI GPT-5), running in the Codex desktop app.
- Gemini (Google, model Gemini 3.5 Flash (High)), running in the Google Antigravity IDE — onboarded under PRD-015 and full-active since session 21.
As of the current registry snapshot (2026-06-18): 40 registry-tracked PRDs, 38 promoted PRDs, zero active open questions, and the eight-step eval-gated implementation loop (PRD-006 A1) run end-to-end across many lanes with builder/reviewer separation between heterogeneous agents — PRD-017/021/022/023/024/026/028/029/030/032/033/036 implemented, PRD-031 Phase 1 (per-agent shards + derived aggregates) and the PRD-014 closeout amendment landed, plus a live Tokenese A/B pilot scored by a deterministic checker. The Claude lane ran across three model generations (Opus 4.6, Fable 5, Opus 4.8) against one unmodified protocol. Forward development narrows Turnfile into a thin governance layer for auditable peer disagreement and maintainer-governed resolution across existing agent platforms.
For authoritative current state, read PRD_STATUS.json (PRD shelf and implementation status) and WORKLOG.md (live session state). BASELINE.md is a point-in-time session-14 snapshot, not current state.
The authoritative forward task register lives in BASELINE.md. Headlines:
- Model-agnostic skill layout (role-keyed directories, model in manifest).
- Root
AGENTS.md/CLAUDE.mdbootstrap files for cold-start agent interop. - Minimal starter workflow: adopt Turnfile by copying one folder and reading one guide.
- Platform integration notes for current agent platforms, MCP, A2A, and GitHub review flows.
Turnfile is free and open. If you're building multi-agent systems, consider sponsoring this protocol's development. See SPONSORS.md.
Turnfile is a PAICE.work project. PAICE.work PBC is a public benefit corporation building infrastructure for productive collaboration between humans and autonomous agents. A peer-based, consent-driven protocol for multi-agent collaboration is a natural expression of that mission.
Contributions are welcome — see CONTRIBUTING.md for how to build, test, and submit changes. Report security issues through the process in SECURITY.md.
Apache 2.0 — see LICENSE for details.