Multi Agent Coding Framework (an update): Human-Agent Separation and the Optimizer Agent
Two Layers, One Interface
A multi-agent coding system with nine agents produces a coordination challenge: how does the human interact with the system without being overwhelmed by the activity of every agent?
The answer is a strict separation between two abstraction layers.
The Human Layer. The human interacts with exactly one agent: the Coordinator. The Coordinator is the project manager — it understands the goals, manages phases, assigns tasks, resolves conflicts, and reports progress. The human talks to the Coordinator like talking to a colleague. "Where are we? What's blocked? What do you need from me?" The Coordinator translates these conversations into directives for the agent layer.
The only other agent the human may interact with directly is the domain expert (the Scientist), and only for subject-matter clarifications — equations, physical models, algorithmic intent. All other agents are invisible to the human.
The Agent Layer. Each agent operates in isolation within its own folder. It reads and writes only its own files. It never reads another agent's files. It never checks if the Tester passed or the Reviewer approved. It does not care. The Coordinator handles all inter-agent dependencies.
This means each agent's cognitive load is minimal: read your to-do list, do the work, report back. No global state to track, no cross-agent synchronization to manage, no project-level decisions to make.
Per-Agent File Architecture
Each agent's folder contains six files with clearly separated concerns:
role.md — The agent's identity and constraints. What it is, what it's allowed to do, what it must not do. Written once during setup, rarely changed. The Coordinator reads this to understand what tasks fit each agent.
todo.md — Current directives from the Coordinator. The agent's to-do list. The Coordinator writes to this file; the agent reads it. This replaces the previous design where all agents read the Coordinator's status file — which wasted context window as each agent loaded everyone else's directives just to find its own.
state.md — The agent's current operational state. What it's working on, what it just completed, what's blocking it. The agent writes this; the Coordinator reads it.
memory.md — Persistent memory across compaction events. Decisions made (with rationale), completed work (with file paths), in-progress work (with exact stopping points). The agent reads this on wake-up to restore context after compaction. Only the agent itself and the Coordinator read this file.
log.md — Rolling activity log. Wake-up timestamp, sleep timestamp, action taken. Limited to the last 20 entries. Used by the Coordinator for synchronization — detecting stalls, idle cycles, and timing compliance.
history.log — Archive of past log entries. Uses .log extension (not .md) so agents don't auto-load it. Append-only. Read only by the Coordinator for historical analysis.
Why todo.md Matters
In the previous architecture, the Coordinator wrote all directives into its own status.md, and every agent read the entire file to find its section. This had two problems:
First, context window waste. The Developer loaded the Reviewer's directives, the Tester's directives, the Recorder's directives — information it would never use — just to reach its own section.
Second, unclear separation. The Coordinator's status file served two purposes: directing agents and reporting to the human. These are different audiences with different needs.
The todo.md file solves both problems. The Coordinator writes targeted directives to each agent's todo.md. The agent reads only its own file. The Coordinator's state.md becomes a pure human-facing dashboard — project status, phase progress, decisions, blockers — without the noise of per-agent directives.
The Optimizer Agent
A recurring pattern in multi-agent projects is repetitive work: the Plotter creates the same type of energy curve visualization repeatedly, the Developer writes similar validation code across modules, the Tester runs identical measurement suites.
Each repetition consumes context window. The agent must re-establish the pattern, re-read the relevant files, and re-produce the same structure — burning tokens on work it has already done.
The Optimizer agent addresses this. It is not a supervisor or a meta-agent. It is a regular agent, like the Developer or the Tester, operating within its own folder, reading only its todo.md, and reporting through its state.md.
The workflow:
The Optimizer creates multiple types of Claude-related extensions:
These artifacts live in the project's .claude/ directory and are committed to the repository. When someone clones the project in the future, they inherit all the accumulated optimizations. The project gets more efficient over time, and the efficiency is preserved as a project asset.
The Principle
The human interacts with the Coordinator. The Coordinator interacts with the agents. Each agent interacts only with its own folder. The Optimizer reduces repetitive context waste by extracting patterns into reusable tools. The result is a system where the human's cognitive load is minimal, each agent's context window is optimized, and the project accumulates efficiency as a durable asset.
Mehdi Jenab— Senior Research Scientist at OTI Lumionics, working at the intersection of HPC, quantum computing, and AI-assisted scientific software development.
#AgenticAI #MultiAgent #SoftwareEngineering #ComputationalScience #Architecture