Two People, Two AI Assistants, One Repo

How to run a shared project through two AI assistants: the file, the five sections, and the one line at the top that makes it work.

This spring I rebuilt a collaborator’s website with her, and for the first few weeks we coordinated it by sending each other files over WhatsApp. She was using an AI assistant on her machine and I was using one on mine, so every handover meant one of us explaining our half to the other in language they could follow. We fixed it by putting one shared file in the middle and letting each assistant do that explaining for its own person. Here’s the pattern, which works for any two people doing shared work apart from each other.

💡 The principle: when two people each have an assistant that knows how they work, you stop writing for each other and start writing for the machine in the middle — and it hands each of you back only the half you needed.

We’d started on WhatsApp. Each of us would get our assistant to do something, then send the other the output as a markdown attachment. Here’s what mine did to the nav. Here’s the updated about page. Then we’d each paste the other’s changes into our own copy by hand, working from a file that was already out of date by the time it arrived.

It sort of worked, with lag. I’d change the infrastructure and she wouldn’t know until I messaged her; she’d rewrite a page and I wouldn’t know until it arrived as an attachment. Two people with capable assistants, coordinating through a group chat.

The message I never had to read

I typed one line to my assistant: check the repo and see what she’s written. The repo — short for repository — is the shared copy of the project, along with a record of every change either of us has ever made to it. My assistant came back with the two things that affected me, in my terms, out of a page and a half she’d written in hers.

She hadn’t written any of it for me. She’d written it for the project, at whatever length suited her and in her own vocabulary. My assistant did the filtering on my side. When I replied, hers did the same in reverse. It took the technical half of what I’d sent and put it in the terms she works in, saving her the same tax it had just saved me.

It was almost like sending letters back and forth — except the letters carried the full chain of communication with them, so neither of us had to reconstruct the context before answering.

What an “instruction file” actually is

Assistants that run on your own computer — Claude Code, Codex, Cursor — each look for a particular file when they start, and treat whatever is in it as standing orders. There’s no settings screen. It’s a plain document, written in ordinary words, saying how you work and what you want done by default. Each tool has its own filename for it, so check which one yours reads.

This is the prerequisite for everything below, so it’s worth being blunt about it. An assistant in a browser tab won’t do this — it can’t see your files and it starts each conversation empty. Some have a “custom instructions” box that gets part of the way there. If that’s your setup, the shared file still works; you’ll just be pasting it in rather than having it read automatically.

When I say “make it standing” below, I mean write it into that file once so it happens every session afterwards without being asked.

Why a status update never works

Underneath the website rebuild sits a problem you’ll recognise from work that has nothing to do with code. Two people working apart, each holding something the other needs to know, and neither with the time to package it up for them.

It shows up as the weekly summary nobody reads, written for a reader who doesn’t exist. Or the handover document that manages to be both too vague to act on and too long to finish. Or the thread where you read all of it to find the third of it that concerned you.

The reason those never come right is that one document cannot be written for two different readers at the same time. So write it once, in full, for the machine, and let each side’s assistant produce the version its own person needs. Doing that translation by hand used to cost more than it was worth, which is why nobody kept it up.

That holds whether the shared thing is a website, a research project, a house move or a set of accounts.

How to run this yourself

1. Start with one shared document — nothing installed. A single file both of you write into, wherever you already keep things. Put instructions to each other at the top in plain language, and the messy detail underneath.

2. Write more than you would if a person had to read it. Put down what you did, why you did it, and what you were about to do next. The other side’s assistant will cut it to size, so the length costs them nothing and saves you the work of judging what they need.

3. Ask your assistant to read their entries, rather than reading the entries yourself. Tell it what you’re working on and ask which parts affect you. This is the step people skip, and it is the one that turns a shared file into a translation layer.

4. Move it next to the work. Once it’s earning its place, put the file wherever the work itself lives so the history sits underneath it. If that’s a code repository and the other person has never used one, write the setup instructions for their assistant to follow, not for them.

5. Make it standing. Five lines in each side’s instruction file, so neither of you has to remember any of this again.

The file itself

I’ve now run this on four separate projects, and the same five sections survived every time. Everything else I added to one or another turned out to be decoration. Copy this:

# COLLAB.md — [project name]

*Coordination file for [you] + [them].
Both humans and both assistants read this.*

**How to use it:** add to Flags when you need the other
person to do or decide something. Add to Log at the end
of every session. Clear a flag by moving it into the log
with what happened.

---

## Current focus

**[Your name]'s lane:**
- [ ] what you're on now

**[Their name]'s lane:**
- [ ] what they're on now

**Shared decisions needed:**
- [ ] the ones neither of you can make alone

---

## Flags

*Needing the other person. Clear by moving into the log.*

- **[YOU 2026-08-04]** the thing you need from them

---

## Log

*Newest first. One entry per session.*

### 2026-08-04 — [you]

What changed, why, and what you were about to do next.

Two details carry more than their weight. Flags are addressed to a person and dated, so neither assistant has to guess whether one is still live. And you clear a flag by moving it into the log with what happened, so the log writes itself out of the flags instead of being a second thing to remember.

If you keep one line, keep the one at the top: both humans and both assistants read this. Everyone who opens the file reads it first and writes for the right audience without being told again.

Sample prompts

Ask for the other side’s work, filtered for you:

Read [shared file] and tell me only the parts that affect
what I'm working on right now, which is [your current task].
Skip anything I don't need to act on.

Write your half so their assistant can use it:

Add an entry to [shared file] covering what I changed today,
why, and what I'm doing next. Keep the technical detail in —
their assistant needs it. Put anything [name] personally
needs to decide at the top, in plain language.

Make it standing, once:

Working in a shared file:
- Read it before touching anything.
- After a batch of work, add what changed and why, with the date.
- Anything the other person needs to know goes under Flags,
  addressed to them.
- If they've listed something as in progress, don't touch it.
  Flag it instead.
- Never rewrite their section. Add to yours.

The rung that will cost you time is the third one. Early on the translation comes back thin — technically accurate and useless — because your assistant doesn’t yet know enough about the person on the other side to know what matters to them. The cause is boring rather than hard: you told it about the project and not about the other human. Write two or three lines into your instruction file about who they are and what they care about. Do that once and the summaries stop being generic.

I’d assumed this needed software built for the purpose — something to pass messages between the two assistants, with rules about who says what. It didn’t. The record of changes already showed who did what and when, and a plain document is readable by people and machines alike.

Where to stop

Keep this to translation. It’s very good at telling you what the other person did and roughly what they meant. It is not where you agree scope, money or a deadline — those stayed in the one face-to-face session we had, and should have.

And prune the log. My oldest of these has reached forty-six thousand words, with the five sections that make it useful buried under a year of session entries. No assistant reads all of that carefully, so the file quietly stops being the thing both sides trust. The newest is three hundred words and works better. Once the log outgrows the rest of the file, archive the old entries and keep the last month.

The attachments stopped. She writes her half, I write mine, and each of us has something that has read the whole exchange and knows which part of it was ours.