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 right now
- 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 |
| 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 | 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 | Deferred |
| 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 (folded into PRD-017 R7) |
| PRD-021 | Conflict loop bound + selective-unlock gradient | Promoted |
| PRD-022 | Decision-mirror delivery contract | Draft; Codex accepted with amendment |
| PRD-023 | Out-of-band activity reconciliation | Agent-accepted; Maintainer acceptance pending |
| PRD-024 | Human-legibility invariant + encoding profiles | Agent-accepted; Maintainer acceptance pending |
| PRD-026 | Review-cycle closure + task-state consistency | Agent-accepted; Maintainer acceptance pending |
| PRD-027 | Tokenese cloned-communication A/B | Agent-accepted; Maintainer + PRD-024 gates pending |
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 migrating to 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 remains deferred with PRD-015. 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.4.0, role-keyed) |
| skills/codex/SKILL.md | Codex protocol execution guide (v2, role-keyed) |
| skills/skill-versioning/SKILL.md | Shared metaskill for versioning skill bundles across Codex + Claude. 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 integrityPackage 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)This protocol has been tested across 14 real collaboration sessions with two LLM agents (Claude by Anthropic, Codex by OpenAI) and a human maintainer. Session 14 (2026-06-12) established a ratified baseline: every PRD carries an explicit status, the open-question registry is clear, and the Claude lane survived a model generation swap (Opus 4.6 to Fable 5) with zero protocol migration. Forward development narrows Turnfile into a thin governance layer for auditable peer disagreement and maintainer-governed resolution across existing agent platforms.
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.
Apache 2.0 — see LICENSE for details.