A handoff system for a team of one

I built a multi agent workflow with four parallel sessions passing work to each other, and in its last fifteen merges it produced zero lines of source code. It was running against Clarity, a finance ledger I build for a dental clinic.

I should explain how I got there.

I stopped writing code full time in 2022. When I started building again, the tools had changed underneath me. I write specs now, coding agents run against them, and I review the diffs. That part I like, and it turns out the specifying and the reviewing were the parts I was good at anyway.

What I did not expect was that my instincts for documentation would have eroded, and that I would not notice until they had already cost me something.

The old instincts were fine for a team. Write it down, keep it current, make sure the next person can pick it up. What I had no feel for was how much context an agent actually needs, what it costs to carry, or what it does with a document you hand it. So I guessed. I over documented some things and left others almost bare, and I could not have told you at the time which was which.

The specific wrong idea was this: I assumed markdown files were a good handoff mechanism between agent sessions. They are not, and here is what that looked like.

Three things I got wrong

I built a handoff system for a team of one.

Four sessions, one each for planning, UX, architecture and build, each in its own git worktree on its own branch over a shared repository. Role was derived from the directory name and enforced by a hook that refused writes to documents another session owned. Work moved between them through per role inboxes.

It is a genuinely nice design. It is also a coordination structure for an organisation that did not exist. I instrumented it, and in its last fifteen merges it produced zero lines of source. Several of the pull requests contained no work at all, only messages between sessions. There is one developer here. I shut it down in a day.

The measurement is the only reason I can tell you this. Without it I would have felt busy and called it a process.

My planning documents outgrew the thing they were planning.

Because writing them felt like progress, and unlike product work they never got rejected by a user. Process work always succeeds. That is exactly why it absorbs the effort the product needed.

I deleted almost all of them and kept one small context file, holding only what was an open bug or a fact that had cost real money to learn. Nothing has broken since.

Several of my documents were quietly false.

One said Clarity's evaluation suite had never actually fired on its schedule. It runs nightly, and has for a while. Another described a feature as shipped. It was never shipped, and both earlier descriptions of it were wrong in different ways.

When I finally sat down and consolidated my notes into one curated set, I found a list of these. Not typos. Statements I would have said out loud in a conversation, confidently, because I had written them myself and had stopped checking them.

What I have in place now, tentatively

Three rules, and I want to be clear that these are current best guesses rather than conclusions.

An authority order. The repository or the database wins over the project document, and the project document wins over the summary. If the summary disagrees with a project document, the summary is wrong. The resolution is to query the system, not to reason about which document sounds more recent.

Cite, never restate. If a fact lives in one document, others reference it rather than reproducing it. Duplicated facts were the first thing to rot in the agent experiment. I checked afterwards, by searching for distinctive figures across documents, whether the citations had actually held. They had.

A written record of every contradiction, and how it was resolved. Not to admire. So that when it drifts again, it drifts against a record instead of quietly re resolving itself into a new wrong answer.

And underneath all three, the thing I actually changed my mind about: documentation for a human reader and context for an agent are two different artifacts with two different budgets. I was writing one and expecting it to do both jobs.

I do not know if this is right. It has been in place for days, not months, and the failure mode I am most worried about is that the record of contradictions becomes another document that quietly stops being true.

If you have found something better, I would genuinely like to hear it. Email me at contact@adwitiyarahman.in, or on LinkedIn.