A plan the next session can run

The story

Our agent sessions do not share memory, and one morning that cost us a near miss. A session was partway through a task when the engineering lead paused it to deal with something else. While it sat paused, a second session merged a branch into the same working tree. When the first session resumed, the files it had been editing were no longer the files it remembered.

What saved the work was not memory. Before the pause, the session had written a snapshot of its uncommitted edits into the plan's workspace and a line in the ledger saying where it was. On resume it compared the files on disk against the snapshot, found its edits intact under the merge, finished the task and sent it for review. The next task went to a third session that had never seen any of this, with the ledger, a one-page brief and the previous task's report. It picked up where the first had stopped.

We had written that plan for a reader with no context, and the morning proved why. A plan that lives in the author's head stops when the author does.

The pattern

A plan for a reader with no context has four properties, and each one closes a failure you will see.

Every step carries its code. Not a description of the code. The test, verbatim, that the step must make pass. The implementation, verbatim, or close enough that only names and imports need adjusting. The command that runs the test and the output it should print. When the step is "write the failing test, run it, watch it fail for this reason, then write this", the builder is transcribing and checking, not designing. Design happened earlier, with the person who owned the decisions.

Interfaces are stated where tasks meet. Each task names what it produces that a later task consumes: the function signatures, the field names, the file paths. The builder of task four never reads task three, so task four has to say what task three left behind. We write this as a short block at the top of each task. It is the part of the plan that most often catches a mistake while the plan is still a document.

Each task gets a brief, not the plan. The builder receives one task's text, extracted into its own file, plus the two or three decisions from earlier tasks that it cannot see. It does not receive the whole plan, and it does not receive the design conversation. A builder that reads the whole plan starts work on task six while finishing task two. A builder that reads only its brief finishes its brief.

The record lives in a file, not in anyone's head. We keep a ledger beside the plan. Every task appends a line when it starts and when it completes, with the commits it produced. Every decision the coordinator makes that the plan did not anticipate goes in as a ruling: what was decided, why, and what it costs if wrong. When a session stops partway through, the next one reads the ledger and the commit log and resumes at the first task without a completion line. That is what happened in the story: the next task went to a session that had never seen the plan, with the ledger, a one-page brief and the previous task's report, and nothing was built twice.

The rulings matter more than they look. A plan meets the code and finds that a name is taken, a test cannot reach the state it wants, a file is larger than expected. Someone has to decide, and waiting for a human to answer stalls the work until the human is free. So the coordinator decides, writes the ruling down, and keeps going. At the end, every ruling is listed for the human in one place. They read ten lines and rework the one they disagree with, instead of discovering the choice in a diff six weeks later.

There is a cost. A plan like this is long, and writing it takes longer than building from it would seem to need. We think that is the right ratio. The plan is where the thinking happens; the building is where the thinking gets checked.

Try it

Take the next task you would hand to an agent and rewrite it with the test first, verbatim, and the command that runs it. Add one line stating what the task produces for the task after it. Then start a plain text file next to the plan with the plan's name on the first line, and append one line per task as it completes. The first time a session dies halfway through, you will know whether the file was worth it.