{"slug": "agents-collab-md-a-live-handoff-protocol-for-multi-agent-projects", "title": "Agents-Collab.md – A live handoff protocol for multi-agent projects", "summary": "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.", "body_md": "**The live multi-agent collaboration layer for AI-assisted projects.**\n\nA companion to\n\n[AGENTS.md]— not a replacement.\n\n[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.\n\n**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?\n\nEach 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.\n\n**AGENTS-COLLAB.md is the live handoff layer between agents.**\n\nIt holds:\n\n- The\n**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\n**identity of each agent** and what it's responsible for - A\n**handoff block** that the departing agent writes for the arriving one\n\nIt is designed to be read in under 3 minutes, kept compact, and updated at the end of every relevant session.\n\n| AGENTS.md | AGENTS-COLLAB.md | |\n|---|---|---|\nPurpose |\nProject context for a single agent | Live handoff between multiple agents |\nUpdate frequency |\nRarely (stable conventions) | Every session (live state) |\nOwner |\nThe human developer | The current agent, on behalf of the team |\nContent |\nStack, test commands, PR rules | Active decisions, traps, current sprint, agent roles |\nLifespan of a fact |\nPermanent | Until promoted to AGENTS.md or a spec |\n\nBoth files coexist. The **reading order** is:\n\n`AGENTS-COLLAB.md`\n\n— live state and current decisions`AGENTS.md`\n\n— permanent technical history and rules- Relevant specs or docs\n- Real code, runtime, database — when in doubt\n\n```\ncp templates/AGENTS-COLLAB.template.md /your-project/AGENTS-COLLAB.md\n```\n\nOpen the file and fill in Blocks 1–3 (Human, Agents, Active Decisions). Be specific. Vague entries are noise.\n\n```\nAt the start of every session, read AGENTS-COLLAB.md before AGENTS.md.\nAt the end of every session where relevant changes were made, update AGENTS-COLLAB.md\nfollowing the Handoff Protocol in Block 6.\n```\n\nSee `integration/`\n\nfor platform-specific instructions (Claude Code, Codex, Cursor).\n\nThe departing agent writes a Handoff Block (see `templates/handoff-block.md`\n\n) and updates the Active Decisions list. Takes 2–5 minutes.\n\n```\nagents-collab.md/\n├── README.md                         — You are here\n├── AGENTS-COLLAB.md                  — The format specification (meta-example)\n├── AGENTS.md                         — agents.md file for this repo itself\n├── CHANGELOG.md                      — Version history\n├── LICENSE                           — MIT\n├── .gitignore\n│\n├── spec/\n│   ├── format.md                     — Block-by-block format reference\n│   └── lifecycle.md                  — Active Decision lifecycle + session protocol\n│\n├── templates/\n│   ├── AGENTS-COLLAB.template.md     — Blank template for your project\n│   ├── bootstrap-snippet.md          — Copy-paste for agent system prompts\n│   └── handoff-block.md              — Minimal handoff format\n│\n├── examples/\n│   ├── full-example.md               — Full real-world style example\n│   └── minimal-example.md            — Minimal 1-agent example\n│\n└── integration/\n    ├── claude-code.md                — Claude Code (hooks, memory, CLAUDE.md)\n    ├── codex.md                      — OpenAI Codex / ChatGPT\n    └── cursor.md                     — Cursor and other IDE agents\n```\n\n**1. Live, not historical.**\nAGENTS-COLLAB.md describes the *current* state. History belongs in git, AGENTS.md, or specs. If a fact no longer matters operationally, remove it.\n\n**2. Compact, not encyclopedic.**\nIf it takes more than 3 minutes to read, it has failed its purpose. Every sentence must earn its place.\n\n**3. Attributed, not anonymous.**\nEvery Active Decision records who made it (human, agent name, date). This allows future agents to trace the reasoning and challenge stale decisions.\n\n**4. Fail-closed handoffs.**\nWhen 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.\n\n**5. Promotes upward.**\nWhen an Active Decision stabilizes (implemented + tested + validated), it gets promoted to AGENTS.md or a spec. AGENTS-COLLAB.md should never accumulate permanent knowledge.\n\nAGENTS.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.\n\nBut 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.\n\nAGENTS-COLLAB.md is the protocol that keeps that context alive.\n\nThis 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.\n\nMIT — see [LICENSE](/Rlealbarili/Agents-Collab.md/blob/main/LICENSE).\n\n*Inspired by agents.md and the real-world pain of multi-agent project coordination.*", "url": "https://wpnews.pro/news/agents-collab-md-a-live-handoff-protocol-for-multi-agent-projects", "canonical_source": "https://github.com/Rlealbarili/Agents-Collab.md", "published_at": "2026-05-27 18:52:14+00:00", "updated_at": "2026-05-27 19:15:40.631706+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-products", "ai-infrastructure", "ai-research"], "entities": ["Claude Code", "Codex", "Gemini", "Cursor", "AGENTS.md", "AGENTS-COLLAB.md"], "alternates": {"html": "https://wpnews.pro/news/agents-collab-md-a-live-handoff-protocol-for-multi-agent-projects", "markdown": "https://wpnews.pro/news/agents-collab-md-a-live-handoff-protocol-for-multi-agent-projects.md", "text": "https://wpnews.pro/news/agents-collab-md-a-live-handoff-protocol-for-multi-agent-projects.txt", "jsonld": "https://wpnews.pro/news/agents-collab-md-a-live-handoff-protocol-for-multi-agent-projects.jsonld"}}