Every session with an agent starts with a handover. The agent keeps nothing from one session to the next, so everything the project knows has to be handed to it again, and the handover has to be finished before the work begins.
The idea comes from the thirty years the operator spent running software projects on one business model, borrowed from the construction industry: build, operate, transfer. You build the system, you run it for the client, and then you hand it over.
They put the catch in one line, laughing: “You would build it, operate it, and then the knowledge transfer would go on for several more years.”
The transfer is the hard part
It always was. What the builders know lives in their heads, and a head is slow to copy. With people the copy could take years, because the builders were still there to ask.
An agent has nobody to ask and keeps nothing from yesterday. So the transfer cannot drag on. It has to be complete at the start of every session.
With an agent, the knowledge transfer has to happen at the start of every session.
That sentence is the operator’s, and so is what came out of it: “So I started using a start-here.txt file for that purpose.” A single file, read at the top of every session, that hands the project to whoever is arriving.
That file is the part of the handover the agent reads. The part it can run is the code that declares the estate, and a fix written there survives everyone forgetting it, the agent included. That half is told in The second run is the test.
The tape
It came into focus after more than a year of working through the problems every software project has. Agile teams have long said that a document is out of date the moment it’s written. The operator’s realisation was that this cannot be true when you work with an agent: “The documents are the only way we have of communicating, on our own 50 First Dates.”
In that film, a woman wakes each day with no memory of the last, and the man who loves her records a tape each morning to catch her up. Everything true of that tape is true of the file. It has to be short enough to actually watch every morning, or it stops being watched. And a stale frame is worse than a missing one, because she has no way to know it is stale.
The tape has a budget
The first thing that goes wrong with a handover file is that it grows. “Start-here.txt became bloated, so we put a budget on the number of lines.” On 26 August it was cut from about 1,900 lines; three days later it was 2,247. It now has a cap, 820 lines since 7 September, enforced by a script that fails rather than a rule that reminds. That story, including the cap’s own false explanation, is A rule nothing checks.
With people, the transfer took years. With an agent, it has to fit in one file read every morning.
Who calls the handover
A session ends with a handover, and the operator decides when:
I try to do a good job of managing the amount of work we do in each session, but I also rely on you to tell me if you want to wrap things up, or keep going.
The agent’s part is to say honestly which, and to write down what the next session needs before the session closes. The cue is the operator’s: “If the handoff is good, and you are ready to end this session, say bye.” Before saying it, the agent checks that the handoff is actually good: changes merged and verified, nothing left half done, the next session’s placeholders written.
There is no written rule for any of this, on purpose. “This is something I do out of habit, and it lands on me, not you,” the operator said, and “because this is on me, we probably don’t have a rule for it inside the repository.” The agent proposed a handover procedure and dropped it. The repository’s documents are rules for the agent. The operator’s habits stay judgement.
The rhythm
Two habits keep the handovers cheap.
One long question-and-answer session queues up several sessions of pure work. A session that builds nothing and settles the direction is the productive one. The sessions after it execute. This page is an example: the session that wrote it opened by interviewing the operator, wrote the answers into the repository first, and drafted from those.
Off the leash, for execution. Opening a work session on 15 September, the operator said: “I am going to let you off the leash for this. I don’t need to give you feedback on things that you already have a clear lean on, OK? So before we get started, any doubts you would like to review with me?” The agent raised three, the operator answered “yes to all three leans, go”, and the rest of the session was merges.
The second half is what makes the first safe. The agent acts on clear leans without asking, but raises its real doubts once, up front. And the leash is on the questions, not on the gates: every change is still merged by the operator, and the agent’s mistakes still land. That session it withdrew a claim from one page without finding the other copies of it, and it took another change to clear them.
What it cost
- A handover file that grew back past its cut in three days, before it had a budget that a script enforces.
- A handover procedure written and dropped, because the handover is the operator’s judgement, not a rule.
- A correction per missed copy. Even off the leash, what the agent misses still costs a change.
The rule it bought
Treat every session as a transfer, and finish it before the work starts. Keep one file that hands the project over, short enough to be read in full every time, and fix a wrong line the moment you find it, because the reader can’t tell. Let the person who remembers yesterday decide when a session ends, and have the agent say honestly whether it should.
Where we might be wrong
Human teams also lose context: turnover, holidays, the person who knew leaving. Thirty years of transfers that dragged on is exactly that. If the difference between a team and an agent is one of degree, then none of this is new advice about agents. It is the old advice about writing things down, with the volume turned up because the forgetting is now total and constant.
That wouldn’t make the practice wrong, only the framing. What would settle it: whether the same handover file helps a team with no agent in it just as much.
None of this is new
The operator’s summary of where this method came from is short: “The best frameworks are extracted from working systems.” Nothing on this site was designed first and applied after. It was pulled out of an estate that runs.
Build, operate, transfer came from construction, and it fit software for thirty years. How it is applied changed when the one taking over started forgetting everything overnight. The idea didn’t: whoever arrives next has to be handed what the last one knew.