Agents-Collab.md – A live handoff protocol for multi-agent projects

A new open-source protocol called AGENTS-COLLAB.md provides a live handoff layer for projects where multiple AI agents work on the same codebase across different sessions. The specification solves the problem of agents arriving "cold" without knowledge of recent decisions, active architectural bets, or known traps, by maintaining a compact file that holds current project state, active decisions, agent identities, and handoff blocks. The protocol is designed to be read in under three minutes and updated at the end of every relevant session, complementing the existing AGENTS.md standard rather than replacing it.

The live multi-agent collaboration layer for AI-assisted projects. A companion to AGENTS.md — not a replacement. AGENTS.md https://agents.md gives a single AI agent the context it needs to work on your project: stack, conventions, test commands, PR rules. AGENTS-COLLAB.md solves a different problem: what happens when multiple AI agents — Claude Code, Codex, Gemini, Cursor — work on the same project across different sessions, sometimes in parallel? Each agent arrives cold. It doesn't know what the previous agent decided five minutes ago, which architectural bets are still in-flight, or which corners of the codebase just burned someone. It has to re-derive everything from scratch, and it often gets it wrong. AGENTS-COLLAB.md is the live handoff layer between agents. It holds: - The current state of the project not the history — the now Active Decisions DAs that are still in-flight, with who made them and why Traps and nuances discovered in production that agents must not repeat- The identity of each agent and what it's responsible for - A handoff block that the departing agent writes for the arriving one It is designed to be read in under 3 minutes, kept compact, and updated at the end of every relevant session. | AGENTS.md | AGENTS-COLLAB.md | | |---|---|---| Purpose | Project context for a single agent | Live handoff between multiple agents | Update frequency | Rarely stable conventions | Every session live state | Owner | The human developer | The current agent, on behalf of the team | Content | Stack, test commands, PR rules | Active decisions, traps, current sprint, agent roles | Lifespan of a fact | Permanent | Until promoted to AGENTS.md or a spec | Both files coexist. The reading order is: AGENTS-COLLAB.md — live state and current decisions AGENTS.md — permanent technical history and rules- Relevant specs or docs - Real code, runtime, database — when in doubt cp templates/AGENTS-COLLAB.template.md /your-project/AGENTS-COLLAB.md Open the file and fill in Blocks 1–3 Human, Agents, Active Decisions . Be specific. Vague entries are noise. At the start of every session, read AGENTS-COLLAB.md before AGENTS.md. At the end of every session where relevant changes were made, update AGENTS-COLLAB.md following the Handoff Protocol in Block 6. See integration/ for platform-specific instructions Claude Code, Codex, Cursor . The departing agent writes a Handoff Block see templates/handoff-block.md and updates the Active Decisions list. Takes 2–5 minutes. agents-collab.md/ ├── README.md — You are here ├── AGENTS-COLLAB.md — The format specification meta-example ├── AGENTS.md — agents.md file for this repo itself ├── CHANGELOG.md — Version history ├── LICENSE — MIT ├── .gitignore │ ├── spec/ │ ├── format.md — Block-by-block format reference │ └── lifecycle.md — Active Decision lifecycle + session protocol │ ├── templates/ │ ├── AGENTS-COLLAB.template.md — Blank template for your project │ ├── bootstrap-snippet.md — Copy-paste for agent system prompts │ └── handoff-block.md — Minimal handoff format │ ├── examples/ │ ├── full-example.md — Full real-world style example │ └── minimal-example.md — Minimal 1-agent example │ └── integration/ ├── claude-code.md — Claude Code hooks, memory, CLAUDE.md ├── codex.md — OpenAI Codex / ChatGPT └── cursor.md — Cursor and other IDE agents 1. Live, not historical. AGENTS-COLLAB.md describes the current state. History belongs in git, AGENTS.md, or specs. If a fact no longer matters operationally, remove it. 2. Compact, not encyclopedic. If it takes more than 3 minutes to read, it has failed its purpose. Every sentence must earn its place. 3. Attributed, not anonymous. Every Active Decision records who made it human, agent name, date . This allows future agents to trace the reasoning and challenge stale decisions. 4. Fail-closed handoffs. When an agent writes a handoff, it must state: what changed, what was tested, what is blocked, and what the next agent should do first. No vague summaries. 5. Promotes upward. When an Active Decision stabilizes implemented + tested + validated , it gets promoted to AGENTS.md or a spec. AGENTS-COLLAB.md should never accumulate permanent knowledge. AGENTS.md is a static document. It describes conventions that rarely change. It's excellent for onboarding a new agent to a project's permanent rules. But a live multi-agent project has a different problem: the context that matters right now is not in any permanent document. It's in the heads of the people and agents who were just working on it. That context evaporates between sessions. AGENTS-COLLAB.md is the protocol that keeps that context alive. This format is early. If you use it on your project, open an issue or PR with what worked, what didn't, and what you changed. The goal is a format simple enough to be adopted without tooling, but precise enough to actually improve multi-agent coordination. MIT — see LICENSE /Rlealbarili/Agents-Collab.md/blob/main/LICENSE . Inspired by agents.md and the real-world pain of multi-agent project coordination.