Notes for the Other Person's Agent

Two of us work on the same repo. Between us we run Claude Code, Cursor, Codex and Grok. Four agents writing code, none of them sharing a memory.

What breaks first is not code quality. It is that my agent re-opens a question yours closed yesterday, or quietly answers it the other way.

Transcripts do not fix that. Nobody reads someone else's transcript, and a bigger context window does not help when the context lives on another machine. So the repo carries the memory.

What happened

At the end of a session the agent writes a short dated file under docs/agents/sessions/: done, files, decisions, open questions, next, and Notes for teammate.

That last section is the point, and it is written for the other person's agent, not for the other person. One paragraph: what their agent should tell their human tomorrow morning.

Reading it back is the half that has to stay cheap.

Three rules keep it from rotting.

Read the index, never the sessions. INDEX.md is newest-first one-liners. Load only what is unread, the other author's first. Never all ninety-six.

Read state is local and gitignored. What I have read is not a fact about the team, and committing it means a merge conflict every session.

Old sessions leave the working tree. After a few days they are git rm'd and live in history. Restoring them so the index looks complete turns a briefing into an excavation.

What we agreed

The log says what happened. It does not say what we agreed before it happened, which is where the expensive mistakes are.

Any slice touching schema, a customer channel, money or tenant isolation opens a folder first: intent.md, design.md, tasks.md. Intent gets agreed, then design if the choice is irreversible, then code. The folder ships in the same PR. No folder, no merge.

The rule that does the work is the negative one: do not write the design as a recap at merge time. A design authored after the code is a description of what you did, and it can never tell you that you were wrong. Seventy-seven folders in, the sections I go back to are always Alternatives rejected.

Why not a tool

We looked at OpenSpec and put it down. The line in our own log is "same folders, fewer files". Side by side the overlap is almost total:

On the first three rows OpenSpec is plainly better. A command that scaffolds the folder and works across every assistant in the room beats a cp, and I would not argue otherwise. We kept ours because the structure already existed and the thing that kept failing was people not writing, which no tool fixes, and because a new vocabulary is a cost paid four times when four agents have to learn it.

Row four is the real disagreement rather than a preference. OpenSpec is deliberately fluid, no rigid phase gates, update any artifact anytime. We deliberately made four classes rigid, because those are the ones where being wrong is expensive and slow to find out about.

Row six is not a competition. Stores are genuinely a team feature, but they share the plan, and a plan is not a session. Nothing there tells my agent that yours spent last night discovering the accent lives in the wrong repo, which is the fact I actually needed at nine in the morning.

Who wins

Four places to write things down is three too many unless each one owns a question. Without that table they become four half-true copies, and the agent believes whichever it hit first.