The agent briefing

An AI coding agent working inside a workbench needs to know how this particular one is set up: which services are running and how to reach them, which ports are exposed and at what URLs, and how to start a server so it keeps running. Monoceros writes all of that down for the agent, so it starts already knowing the workbench instead of guessing at it. The same files are yours to extend with project notes of your own.

What Monoceros writes

On monoceros apply, Monoceros writes the briefing at the root of the workspace, plus the chapters it imports:

AGENTS.md is the briefing itself, the cross-tool file most agents read. It opens with the rules of this workbench, one line each, and then lists what is actually in it: the languages, features, and services (with the exact connection environment variables your code reads, the same ones listed on each service page), and the exposed ports with their .localhost URLs.
CLAUDE.md is Claude Code’s own file. It imports AGENTS.md so Claude Code reads the same briefing, and it leaves room for your Claude-specific notes.
.monoceros/conventions.md and .monoceros/servers.md are the two long chapters, imported by AGENTS.md: where to build and what the workspace root is, and the full contract for long-running servers (the launch config, monoceros-ctl, binding 0.0.0.0, and asking you to open a port from the host).
.monoceros/commands.md is a reference for every monoceros subcommand, also imported.
.monoceros/deploy.md appears when a service in the workbench carries a pipeline shape, and hands the agent that service’s compose block for the project’s own pipeline.

Everything except your own notes is Monoceros-owned and rewritten in full each time, and all of it is derived from the workbench yml and the component catalog, so the briefing always matches what the workbench actually contains.

The order is deliberate. An agent sometimes reads only the first screen of a file, and if that screen is background it has read nothing that changes what it does. So the rules come first, the explanations last, and the header states how many lines the file has and which files it imports: an agent that stopped early has a contradiction in front of it.

When it is written and kept current

The full briefing is regenerated on every monoceros apply. A few commands that take effect immediately also refresh it on the spot, so it never lags behind a live change: add-port and remove-port (the route is live at once) and add-repo (it clones straight away). The commands whose change only lands on the next apply, add-feature, add-language, add-service, and add-apt-packages, deliberately leave the briefing alone until then. Their change is not materialized yet, so refreshing early would make the briefing claim something that is not true yet. The update arrives with the next apply.

When the agent reads it

An agent reads the briefing when it starts a new session. Claude Code loads CLAUDE.md on startup, which pulls in AGENTS.md and, through it, the chapters under .monoceros/. Other agents that follow the AGENTS.md convention read that file directly. Either way the agent has the briefing in context from its first message, with nothing for you to paste in.

Add your own instructions

The briefing is not only Monoceros’s. Both AGENTS.md and CLAUDE.md keep the generated content inside a marker pair:

<!-- monoceros:begin -->

... Monoceros writes and owns this part ...

<!-- monoceros:end -->

Anything you write outside those markers is yours, and apply leaves it untouched. That is where project-specific guidance belongs: coding conventions, where things live, what the agent should not touch. It survives every rebuild.

Two rules keep it working. Put your notes above or below the marker block, never inside it, because the content between the markers is overwritten on the next apply. And do not delete the markers: a file without them is treated as Monoceros’s own and rewritten in full, which would drop your notes. Leave the files under .monoceros/ alone as well, since they are regenerated whole every time.

If you change the workbench mid-session

If you apply a change while an agent session is already running, say you add a service, expose a port, or clone a repo, the briefing files are rewritten, but the agent that is already running still has the old version in its context. It does not pick up the change on its own. Tell it to re-read AGENTS.md (or CLAUDE.md), or start a fresh session, so it sees the new services, ports, or URLs before it acts on them.