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

> Source: <https://github.com/Rlealbarili/Agents-Collab.md>
> Published: 2026-05-27 18:52:14+00:00

**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.*