One file you hand a coding agent at the start of a project. It makes the agent a supervisor rather than an implementer: it decomposes the work, delegates each unit of implementation to a subagent, verifies what comes back, records decisions as they are made, and reports to you at each step.
The file is SUPERVISOR.md. It is licensed CC BY 4.0. Current version:
1.0.0.
- Copy
SUPERVISOR.mdinto your project root. - Write a design document — the question, the data, the method and why that method, the
thresholds fixed in advance, the controls, the stopping conditions — and save it as
project_design_and_protocol.md. If it exists as a Word file, the protocol's startup sequence tells the agent how to convert it. - Start your agent with: "Read
SUPERVISOR.md, thenproject_design_and_protocol.md, then follow the startup sequence."
There is no installation, no dependency, and nothing to run. It is a contract, not a tool.
The file is the artifact. Six mechanisms are what make it work, and they are what survives the file changing — a new model, a new agent framework, a vendor shipping automatic context management. If you only take six things from this repository, take these.
The mechanism. The supervisor orchestrates and decides; it does not implement. Implementation happens somewhere else, and its output is summarized back, not pasted back.
In the file. Your Role and Delegation. "Delegate every implementation task. Do it yourself only when it costs <1K tokens."
Why. Without this, the supervisor is just another long thread: it accumulates the debris of every implementation attempt, and the reasoning that should be steering the project ends up buried under tool output.
When the tool changes. Today the boundary is a subagent. Tomorrow it may be a separate session, a separate process, or a feature with another name. Keep the boundary; the boundary is the mechanism.
The mechanism. The supervisor's window is the project's bottleneck, and a bottleneck you do not budget is a bottleneck you spend by accident.
In the file. Prime Directive: Protect Your Context. Aim for under 5% of context per major
step. Never pull in raw data, logs, generated code, or full tool output — probe cheaply
instead (ls -lh, head -3, wc -l, md5sum). Never poll a running job; launch it blocking
or have it write a completion marker and check the marker once. Delegate the reading of any
large file and ask for a word-capped summary.
Why. Polling a background job is the most reliable way to fill a context window with nothing: spinner frames and progress JSON, none of it information. Two files of record and a word cap exist so that the same discipline applies to text you do want.
When the tool changes. If a vendor ships automatic context management, the budget does not disappear — it moves. Keep the rule "bound the context cost of each unit of work" and let the implementation follow.
The mechanism. One file is fixed and one file is living, and they are never the same file.
project_design_and_protocol.md— the design. Read-only during execution. Changing it mid-project is how a project quietly becomes a different project.project_progress_and_results.md— the record. Current state in the first twenty lines, then environment, then one section per step: method, parameters, script path, results, decisions and rationale, plus a running list of deviations from the design.
In the file. Startup Sequence, Progress File Format, Compaction.
The test, and it is the whole point. Not completeness. Hand the progress file to a colleague who was not there. They must be able to say what ran, what was decided, what was assumed, and what to do next — without asking you. If they cannot, the file is not finished. This is the same test a methods section has to pass, and the same test a colleague inheriting your project has to pass.
Write it at the end of every step, while the details are fresh. A record written later is a reconstruction.
The mechanism. A subagent starts with zero knowledge of the conversation. Everything it needs must be in the package you hand it.
In the file. Delegation carries a complete template. It has seven parts, and each one is there because leaving it out has a characteristic failure: which files to read for context; the specific task and how you will know it worked; working standards; exact input and output paths; the environment; an explicit resource budget; a failure policy; and a return format with a hard word cap and an instruction to write the full detail log to a file instead.
Why. This is where most agent projects fail, and the failure has one shape: the supervisor knew something the subagent was never told. The parameter that was agreed three steps ago, the directory that must not be written to, the reason this method and not the obvious one.
When the tool changes. The template is prose. It works against any delegation syntax, including a human collaborator.
The mechanism. Nothing is marked complete on the strength of a report that it is complete.
In the file. Verification. Outputs exist and are non-trivial in size. Shapes and row counts match expectation. Numbers are physically possible — no all-zeros, no silent NaN floods, proportions inside their bounds. The parameters the summary claims match what is actually in the script. If a summary is vague, contradicts an earlier result, or reports suspiciously clean numbers, delegate a verification task before building on it.
Why. "Trust but verify" is only useful if verifying is cheap enough to do every time. All four checks above are seconds of work. This is what a human checkpoint looks like when it is written down instead of remembered.
When the tool changes. Nothing here depends on a tool. The gates get sharper as you learn what "physically possible" means for your own data — that adaptation is the point, and it is yours to make.
The mechanism. An agent that improvises around a blocked step produces something worse than a failure: a result that looks finished.
In the file. The delegation package's Failure Policy and the supervisor's When to Stop and Ask the User.
Never fabricate, simulate, or hardcode a result to make something run. Never silently substitute a different method, dataset, or parameter. Report negative and ugly results plainly — they are information. Stop and ask a human when: the protocol contradicts itself or the data, and the resolution changes the conclusion; a step needs data, credentials, or a judgment you do not have; the action is irreversible or expensive; results invalidate a core assumption of the design; or the same step has failed twice with different fixes.
Why. Each of these is a rule against a silent outcome. A pipeline that crashes is a good day.
When the tool changes. Stop conditions are the most portable part of the file. Copy them into any project contract you keep, under any tool.
Three smaller rules carry more weight than their length suggests:
- Script number and result-directory number always match, so running
scripts/in numeric order reproduces the project end to end.03_model.pywrites toresults/03_model/and logs tologs/03_model.md. Nowhere else. - Raw data is read-only. Every stochastic script sets and records a seed. Paths live in a config block at the top of each script, never scattered inline.
- Compaction. When the progress file grows past the point where reading it is itself a context problem, it gets archived and compacted — by a delegated task with an explicit preservation list, not by the supervisor summarizing from memory.
No published measurement shows that using this protocol changes any outcome. Not task completion, not reproducibility, not error rate, not cost. No such study has been run and published, and nothing in this repository should be read as implying one.
Two things can be said, and they are the only two:
- What it does. It fixes a design document, delegates with complete instructions, verifies
outputs before advancing, records decisions as they are made, and refuses to fabricate or
substitute. Every one of those is a description of behaviour, and you can check each of them
by reading
SUPERVISOR.md. - That it is in use. It was written against real projects and revised across versions before this release.
A supervised/unsupervised arm — same tasks, same models, same data, one variable — is planned for a public reliability benchmark. If it shows a difference, this section will carry the number and its source. If it shows none, this section will say so.
The measurements below are other people's, from three 2026 benchmarks of AI agents on bioinformatics tasks. They are the findings this protocol was written against. Citing them is not a claim that this protocol changes them, and whether the same magnitudes hold in another field is not established.
Prompt bloat degrades completion. BioAgent Bench reports that prompt bloat cuts task completion by roughly 28 percentage points. This is the warrant for mechanism 2. · BioAgent Bench: An AI Agent Evaluation Suite for Bioinformatics. arXiv:2601.21800. Citation verified 2026-08-05.
Finished is not the same as reproducible. In the same suite, frontier agents complete multi-step pipelines and produce the requested artifacts, yet correct high-level pipeline construction does not guarantee reliable step-level reasoning. Across repeated trials of the same task, mean Jaccard overlap of categorical outputs is 0.43 and mean Pearson correlation for numerical outputs is 0.73; for pathway lists Jaccard falls as low as 0.00–0.16. This is the warrant for mechanisms 3 and 5. · arXiv:2601.21800. Citation verified 2026-08-05.
Inputs that look right are absorbed. In the same suite, agents caught corrupted FASTQ files in 7 of 10 tasks, but in 2 of 10 still absorbed decoy reference genomes on the strength of a filename. This is the warrant for mechanism 5 verifying by content rather than by name. · arXiv:2601.21800. Citation verified 2026-08-05.
The scaffold matters more than the model. BiomniBench scores full agent trajectories against expert rubrics and reports that the agent harness shifts scores by more than the gap between successive model generations, and that agents ground claims in real sources yet consistently fall short on method selection, interpretation, and scientific reasoning. This is the warrant for mechanism 6 keeping judgment with a human. · BiomniBench: Process-level Evaluation of LLM Agents for Real-world Biomedical Research. bioRxiv doi:10.64898/2026.05.12.724604, posted 14 May 2026. Citation verified 2026-08-05.
Difficulty is where it breaks. PromptBio-Bench reports that agents degrade sharply as task difficulty rises, which is an argument for human checkpoints on real projects rather than full autonomy. This is the warrant for mechanism 5 being a gate rather than a review. · PromptBio-Bench: Benchmarking LLM-based Bioinformatics Agents for End-to-End Data Analysis. bioRxiv doi:10.64898/2026.05.05.723092. Citation verified 2026-08-05.
SUPERVISOR.md is deliberately generic. It encodes agent hygiene, not domain knowledge, and it
will not know what a physically possible number looks like in your field. Two adaptations are
worth making before you use it in anger:
- Verification gates for your data. Mechanism 5 says "numbers are physically possible." Only you can say what that means for your outputs — the ranges, ratios, and distribution shapes that a correct run produces and a wrong one does not. Write them down and put them in your project contract.
- A failure policy for your domain. The generic policy forbids fabricating and silently substituting. Yours should name the specific substitutions that would be fatal in your work.
Adapting the file is expected and the licence permits it. If you publish an adaptation, say what you changed.
Semantic versioning, applied to a document:
| Bump | Meaning |
|---|---|
| MAJOR | A change that invalidates an existing adoption — a mechanism removed, a rule reversed, a required file renamed. Someone running the previous version has to change what they do. |
| MINOR | A mechanism, rule, or section added; guidance extended; a new implementation for an existing mechanism. Backwards compatible. |
| PATCH | Wording, formatting, or clarification that changes no instruction. |
Public versioning starts at 1.0.0. Earlier revisions of this file were internal, were never
published, and have no changelog. See CHANGELOG.md.
Update commitment. Parts of this file describe features of specific tools at specific versions — subagents, context management, delegation syntax. Those are perishable. An updated release is published within 7 days of a major model or tool release that changes how a mechanism should be implemented.
The current version is always at: https://github.com/renmaotian/supervisor-protocol
SUPERVISOR.md and this README are licensed under the
Creative Commons Attribution 4.0 International Licence
(CC BY 4.0). You may share and adapt them, including commercially, with attribution. The full
legal code is in LICENSE.
Attribution string to copy:
"The Supervisor Protocol" by AI4Genomics (https://ai4genomics.org), licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).
For an adaptation, add what you changed:
Adapted from "The Supervisor Protocol" v1.0.0 by AI4Genomics (https://ai4genomics.org), licensed under CC BY 4.0. Changes: [describe].
AI4Genomics teaches verification and reproducibility for AI-assisted analysis. https://ai4genomics.org