What I put in an agent's starting map

When I drop a new agent into a project, I want it to have a map before it starts exploring. Something that tells it what exists, how the important pieces fit together, and where to look next.

The hard part is deciding what belongs on that first map. Put too little on it and the agent won't know what it's missing. Put everything on it and you've filled its context window before it has done any work.

I call the target minimum viable competence. Enough understanding to start doing useful work, including knowing when it needs to go and find out more.

Here's what that looks like in OpenRig's public project context.

Workshop is a small team that works in a repository: a lead, a builder, a reviewer and a QA agent. Its startup instructions first have the agent find out who it is and where it is working. Then they make a useful distinction. If this is OpenRig's own repository, load the developing-openrig skill. If it's another project, start with that project's README, architecture, contribution guide or documentation index.

That distinction matters. Knowing how to use OpenRig doesn't mean an agent knows the project you've asked it to work on. The team needs a route into your project's knowledge.

Here's a short AGENTS.md you can copy and adapt:

# AGENTS.md

Before substantive work:

1. Run `rig whoami --json` to find out who you are and who your peers are.
2. Read `README.md` for what this project is, then `ARCHITECTURE.md` for how the pieces fit.
3. Read `PROGRESS.md` for where the work stands, so you don't redo what's done.
4. If the task touches an area with its own guide (`docs/`, a package `README.md`), read that before changing it.

## When the map runs out

- Search the code before inventing an answer.
- `rig roster find <topic>` lists who on the team knows the area.
- If a map is missing, say so, so the next agent gets a better one.

## Boundaries

- Never push or publish without explicit authorization.
- Keep credentials out of files, logs and screenshots.

That's it. It isn't rocket science. The file is a trailhead: it points the agent at a few things and says where to go when those run out. The detail lives in the files it points to.

OpenRig also puts its own instructions in these files. For Codex, it merges a marked block into the working folder's AGENTS.md, preserving the text outside it. For Claude Code, it uses CLAUDE.md unless the rig specifies another file; Workshop uses CLAUDE.local.md. Workshop's startup now spells out what that means: on a Codex seat, read the repository's own content in AGENTS.md as the project's map, not OpenRig's block. We added that line while researching this post.

That's also why the OpenRig repository doesn't currently track a root AGENTS.md. We keep that file local, so OpenRig's agent-specific blocks don't become changes waiting to be committed. The shared project map lives in the tracked developing-openrig skill, and the README points agents working on OpenRig to it. An agent opened directly in the clone can load it by name.

So the starting map can be spread across a few connected pieces. The important part is that the agent can find its way from the context it starts with to the knowledge the job needs.

The repo skill begins by separating two things agents can easily confuse: the installed OpenRig that's running their session, and the checkout they're changing. Restarting the installed daemon doesn't magically test the code in the checkout. The skill points them to the repository's test harnesses instead.

That's useful context to put near the entrance. It changes what the agent should do before it makes a mistake.

Then comes a table organized around questions. Here are some of its routes, condensed:

What the agent needs to figure out	Where the map sends it
Does this capability already exist?	The capability map and command help
Where does this behavior belong?	The architecture map, then the owning source files
What else could this change affect?	The “arteries” map: dependencies and past regressions
Which tests should I run?	The test-layer guide
How do I contribute the result?	The contribution guide

The actual table also has a column about how much to trust each source. One row reads:

| Whether a feature is already planned | ROADMAP.md | Check it before proposing a feature |

That row is quoted from .agents/skills/developing-openrig/SKILL.md in OpenRig v0.6.10, commit 3001cc436656c435e54425443e708e3e2d8c7d68. The question-and-route table above is a condensed explanation, not a verbatim copy.

Notice what the row does. It gives the agent a reason to open the file at a particular moment. A filename on its own would leave the agent to infer when the contents matter. Here, the route is attached to the decision it's about to make.

This is what I want the starting map to do throughout the project. If I ask an agent to add something, I want it to recognize that checking what already exists is part of the job. If it's about to change a shared mechanism, I want it to know there's a map of what depends on that mechanism.

It doesn't need all those answers in its starting context. It needs to know that those questions have places to go.

The detail stays behind those routes. The architecture document leads to packages, source files and examples of where to make different kinds of changes. The test guide describes what each test layer can establish. Deeper module documents carry the revision they were checked against, so the agent can judge whether they might have fallen behind the code.

And the agent still has to read the code. The map helps it choose where to look; it doesn't replace looking.

The edge of the map needs a route too. In this example, the skill tells the agent to search the code when the listed documents don't answer its question, and to report a missing map. Workshop's startup also points to a roster lookup when the team needs expertise it doesn't have. A roster is a short file that says who to involve for what, and why. There's more coming for rosters in 0.7.0. For now, think of it as context for the agent.

That's an important part of the design. Reaching the edge shouldn't make the agent conclude that nothing exists beyond it. It should know how to keep going.

The public OpenRig world pack adds the project's purpose, contribution workflow and engineering craft. Workshop's instructions tell the agent to load its fresh profile if the pack is available. The pack points into the repository for implementation detail, so the project maps can stay next to the code they describe.

Here an agent installs that pack and loads the orientation. The Workshop page has the setup, and the rig-bundles article explains how a team and its project knowledge can be shared. Workshop's published setup adds the OpenRig pack separately; it doesn't arrive knowing an unfamiliar repository.

For another project, I'd start with one real job I want the agent to do. What would it need to recognize before starting? Which prior work might it otherwise reinvent? Where should it go when the first document doesn't have the answer?

Those questions tell me what belongs on the starting map. Then I can watch where the agent actually gets lost and improve the route. Sometimes the information is missing. Sometimes it's already there, but nothing at the entrance gives the agent a reason to go looking for it.

I want the next agent to benefit from that repair. That's the useful part of maintaining a project world: every new arrival gets a better way to find what it needs.