One instruction file, five readers

I run several kinds of AI agent on the same projects. One orchestrates and judges. One builds. Others verify the work. A creative agent handles a different class of task, and another desk handles email and calendar work.

They all load the same instruction file at the start of every session. That is how the project’s rules stay in force when one session ends and another begins.

The file had grown a section titled “Orchestrate. Do not build.”

That section existed because I had told the orchestrator, twice and sharply, to stop writing implementation code itself. Its job was to direct the work, send implementation to a builder, and judge the result. The section said the main loop writes no implementation code and that everything which is typing goes to a subagent.

The instruction was clear. It was also correct for exactly one reader.

The builder loaded the same file. So did every verification agent. Taken literally, the builder had been told to refuse the task it was created to perform. A verifier could read the session-startup checklist as its own assignment and run a startup routine instead of the tests it had been asked to run.

Nothing had visibly broken.

The agents were reading instructions addressed to somebody else and usually deciding correctly which ones applied. The orchestrator delegated. The builder built. The verifiers ran their checks. The missing audience stayed hidden because the guesses mostly landed on the intended behavior.

That made the defect more expensive. A refusal would have pointed directly at the conflict. Mostly correct interpretation left no event to investigate. Every session simply depended on an unstated decision about who the text was talking to.

The fix was small. I did not split the project instructions into five files.

I put a reader table at the top of the shared file. It has five rows: the orchestrator, a verification subagent, the builder, the creative agent, and the desk that handles email and calendar. Each row says how that reader knows which role it has and which sections bind it.

The builder’s row says that building is its job. It also says the orchestrator’s rule does not apply to it. A verifier gets the same clarity about verification. The file still loads once for everyone, but it no longer asks each reader to infer its audience from the surrounding prose.

Two rules came out of that table.

First, a section intended for one kind of reader names that reader in its heading or first line. A section with no stated audience binds everyone. Silence about audience is therefore an explicit choice, not the residue of whoever wrote the section first.

Second, rules that truly bind every agent belong in the instruction file shared across every project and every role. That file opens by saying the role varies but the rules do not. A project file should not repeat those rules.

That second rule answered another complaint from the same day. The system also loads small memory files at the start of each session. Several repeated rules already present in the main instructions, using slightly different words.

Two copies appear harmless while they agree. Then one is corrected and the other keeps loading. The stale copy still looks deliberate. It has a title, an explanation, and the authority of being automatic. A reader now receives two versions of the rule and has to decide which one is current.

The problem was never that the original instruction lacked detail. It was specific and argued. It said what the orchestrator should do and why. The missing field was the reader.

An instruction is addressed to someone. In a file shared by several kinds of agent, every section names who it binds, and every rule has one source.