Notes for the Other Person's Agent

Two of us work in the same repo, using Claude Code, Cursor, Codex and Grok. That's four agents, and they don't share memory.

I thought the code would be the first problem, but my agent was asking again about something the other agent had already settled yesterday. Sometimes it decided the opposite and didn't even say so.

We weren't going to read each other's transcripts, and a bigger context window wouldn't help because the context we needed was on another machine. So we started leaving a file in the repo for each session, with a date and rules for reading it.

Session notes

At the end of a session, the agent writes a short file under docs/agents/sessions/, recording what's done, files, decisions, open questions, and what's next. Then there's Notes for teammate.

That section is a paragraph for the other person's agent to read, telling it what to bring up with its human tomorrow morning. Here's a shortened example:

There are 171 session files now, and reading all of them every morning would be too much, even for an agent.

My agent starts with INDEX.md, which has one line per session, newest first. From there it loads only the sessions it hasn't read, starting with the other author's, rather than loading all 171.

The read state stays local and gitignored, because committing which notes my agent has read would give us a merge conflict every session.

After a few days, old sessions leave the working tree (git rm keeps them in history). Don't bring them back just to fill out the index, or we'd have all those files to read again.

Agreeing on a change

Session notes tell us what happened, but we also need what we'd agreed on before starting, especially if getting it wrong would cost money or affect a customer.

For changes to schema, a customer channel, money, or tenant isolation, we open a folder with intent.md, design.md, tasks.md. We agree on intent first, then design if we can't undo the choice, and then write code. The folder goes in the same PR, and we don't merge without it.

Don't leave the design until merge time, because then you're just describing code you've already written. We have 91 folders now, and I keep going back to Alternatives rejected to see why we picked something.

Why we kept the files

We looked at OpenSpec. Our log says "same folders, fewer files". Here's the comparison:

OpenSpec does the first three rows better, and I'd rather have a command that creates the folder across assistants than use cp. We kept ours because it was already there: people weren't writing the notes, and I don't think another tool would fix that, while four agents would have to learn the new vocabulary too.

Row four is how we wanted it. OpenSpec lets you change any artifact whenever you want, without rigid phase gates, but we need those checks for our four kinds of change where getting them wrong is expensive and you might not notice for a while.

Stores, in row six, share the plan with the team, but we still need to know what happened in the session. At nine in the morning I needed to know the other agent had spent last night finding the accent bug in another repo, and my agent wouldn't get that from the plan.

Where to look

With four places to write things, where should an agent look? We assigned a question to each one:

Without this, we end up with four incomplete copies, and the agent uses whichever it reads first, even if another file has the decision we actually agreed on.