# Context engineering as world building

2026-10-16 · Mike

How I organize context so agents can find what they need, and I can still understand and repair the system as it grows.

![A glowing Claude mascot in a forest clearing, connected by a blue dotted route to a cabin with a terminal symbol. Text reads “Agents find their way.”](/blog-assets/how-my-agent-teams-find-their-way/forest-hero-1280.jpg)

I kept asking capable coding agents to work on my open-source project, OpenRig, and getting a new implementation of something we already had.

One time, we'd nearly finished connecting OpenRig's messaging system to Slack. I set the work aside for about a month, then asked an agent to get it running before a vacation. It searched for Slack, found something it could work with, and built a working integration.

Except it had also built a completely separate messaging system to connect Slack to.

The documentation was there. The earlier work was there. I'd tried graph databases and AI memory tools, and I was still running into this same problem. Eventually I sat back and realized that the agent didn't know what it didn't know. It had no reason to look for the system I assumed it would find.

Writing another note saying we already had a Slack integration might prevent that exact mistake. But I couldn't anticipate every version of this problem and write a rule for it. I needed something that generalized.

That sent me into months of rethinking context from first principles. One question kept coming back. Why do good examples help agents so much? What does an example supply that a pile of facts and rules doesn't?

Think about a connect-the-dots puzzle. The dots can all be present while the picture is still missing. Connecting them reveals an arrangement. When you ask someone to connect the dots for you, you're often saying you have the information but can't see how it fits together.

![Numbered dots connected into an owl, under the words ‘Arrangement creates meaning.’](/blog-assets/how-my-agent-teams-find-their-way/connect-the-dots-1280.jpg)

An agent arrives with an enormous amount of inherited knowledge. It understands programming, organizations, tools and all kinds of relationships between them. What it lacks is your particular arrangement. Some connections are missing between things it already knows. Some things are entirely new.

I think of that difference as the diff, like in a pull request. Context engineering supplies the missing concepts and connections so the agent can make sense of this project. The diff might span thousands of pages, but the agent doesn't need all of them in its context window at once.

![A network labeled ‘This project’: white dots represent familiar concepts, while blue dots and links add new concepts and connections.](/blog-assets/how-my-agent-teams-find-their-way/project-diff-1280.jpg)

Familiar concepts can do a surprising amount of that work. If I say castle, you already know the difference between a throne room and a dungeon. I can tell you something specific about this castle without first explaining every kind of room and how it relates to the others. You bring an existing model, and I add the differences.

That's a form of compression. The recipient reconstructs part of the explanation using what it already understands.

I wanted the human side of this system to benefit from the same idea. Years ago, I read Joshua Foer's *Moonwalking with Einstein*. The memory-palace technique stuck with me. You place things you want to remember along a route through a familiar place, then mentally walk that route to recall them. It makes use of our ability to remember places and where things belong. [Foer's account](https://penguinrandomhousehighereducation.com/book/?isbn=9781101475973) got me thinking about information I could navigate in my own mind.

World building already does something like this for people entering a game or a complicated fictional world. You give them a setting, recognizable relationships, ways to navigate and ways to get help. They discover more as they need it. That's progressive disclosure. The whole world can be much larger than what the newcomer understands on arrival.

This is the overlap I'm interested in. Humans and language models work very differently, but models learn from language shaped by human experience. Familiar concepts give us a place to meet. I want to build systems around the cognitive capabilities of their participants, including the person responsible for the system.

Markdown is a useful example of a shared medium. An agent can read it, edit it and write programs against its structure. I can open the same file and understand it. For context and coordination, I think world building could occupy a similar middle ground. We can reason about the same places, relationships and routes. You could call that cognitive interoperability.

This matters when something goes wrong. If the context system is too opaque for me to understand, I become dependent on tools to tell me what my own agents are doing. I want a picture I can work with quickly, especially under pressure.

So how do you turn project context into something like a navigable world?

I start by thinking about the things in it. A system, a decision, an agent, a convention. Ontology gives us a way to describe what those things are and the relationships they can have. A decision might explain why a system works a certain way. That connection changes what you understand about the system.

As these connections accumulate, you get an arrangement. Topology gives me a way to think about its shape and connectivity. Following a link from one Wikipedia article to another is a familiar version of navigating a structure like this. Each stop gives you something to understand and routes into related knowledge.

But the Slack agent's problem happened before it knew which route to follow. The entire messaging system was missing from its view of the project. So the first thing I wanted to give it was a wider map. An inch deep, a thousand miles wide.

Knowing something exists takes far less context than knowing everything about it. Show the important systems with enough detail that an agent can recognize when one might matter. Then give it a route to find out more. That's width before depth.

The right amount of detail depends on the work. A reviewer and an architect may need different starting maps. More complex or consequential work can justify a larger context budget, but you still have to leave room for the agent to do the job. I'm aiming for minimum viable competence. Enough orientation to locate itself, begin working, and recognize when it needs to go deeper or look wider.

And the edge of the map matters. If an agent reaches that edge, it needs to know the world continues beyond it. There may be another map, with a route into a part of the project it hasn't explored. As the project grows, those maps can lead to other maps. The starting context stays useful without pretending to contain the entire world.

![A hand-drawn map connects a trailhead, bridge, library, castle and workshops with dashed paths. One path continues off the right edge.](/blog-assets/how-my-agent-teams-find-their-way/wide-map-1280.jpg)

The next question is how the agent gets its map. Handing it the right document in every conversation puts me back in the middle of every task. I want the route to begin where the agent already starts.

In my system, `AGENTS.md` is a trailhead into the context library. A router skill helps agents recognize which area they need and where to go next. The title and description of that skill matter because they're what the agent sees before deciding to open it. I think of it as useful clickbait. The description should make an agent recognize its current problem, and the skill should reward opening it with a useful path forward.

Addressability makes those routes practical. A file has a path. A section inside a Markdown file can have a reference based on its heading. With OpenRig's context tools, the agent can retrieve that section rather than loading an enormous document, then follow links for more detail. Those references also let me compose a useful view from pieces that live in different files.

*Demonstration: Read one heading with rig context get. Asked how Slack connects to OpenRig messaging, the agent runs rig context get 'demo/slack.md#messaging'. It returns only that section: Slack connects through OpenRig messaging, the adapter handles Slack-specific work, and two links lead onward, to messaging.md#routing and team.md#slack.*

So a route might begin at the startup instructions, lead into a router skill, then to a heading in the context library, and from there to a decision or the relevant code. I want to be able to trace that path all the way through. The bootstrap supplies the first directions; the world supplies the rest.

I don't try to draw every possible road. As the architect of the context, I establish the main highways. Agents also discover connections as they work and can add routes of their own. The job is to make the important paths usable and decide which ones should be trusted.

Trust adds another dimension. A team of agents produces a lot of what I call Markdown exhaust. Logs, observations, notes, conclusions. Something can be worth keeping without being ready to guide the entire project.

I picture this as elevation. Raw observations sit near the bottom. A useful observation might become a field note, then a shared insight. At the top is canon, the knowledge the project treats as established. The connections downward should let you find the evidence supporting it.

That's epistemic maturity. Age alone doesn't establish it. A new discovery might be strong enough to rely on immediately, while an old note might only apply to one situation. Finding a piece of information and deciding what authority to give it are separate parts of the work. This is the epistemology part of the world, how we decide what we know and why we trust it.

Now the dots and connections have become terrain. Things have places, routes between them, and different levels of support. This is a thinking tool that helps me ask which knowledge is missing, how an agent can reach it, and why it should rely on what it finds.

![Dots form a hilly knowledge landscape, labeled from raw data at the bottom through observation, field note and insight to canon at a peak.](/blog-assets/how-my-agent-teams-find-their-way/epistemic-relief-1280.jpg)

Then time gives us another useful dimension. Systems change, decisions get made, relationships move. Take a sequence of those arrangements and you have the material for a story. Choose the moments that let someone understand what happened and why it mattered, and you have the beginnings of a good example.

That brings us back to the question that started this whole exploration.

In the previous video, I used a story I call Doghouse Moonbase. An agent is asked to build a doghouse. One reasonable addition leads to another until the result is a moonbase and the original request has been lost. The point is that each decision can make sense locally while the whole project drifts away from what anyone wanted.

![Four panels turn a doghouse request into a moonbase: add a light, then power and fuel, until a dog in a space helmet is still waiting for its shelter.](/blog-assets/how-my-agent-teams-find-their-way/doghouse-moonbase-1280.jpg)

I keep stories and lessons like this in a `lore` folder. In OpenRig, a seat is a persistent position on a team, and the next agent to occupy it can inherit what the earlier agents learned. I use these stories during onboarding and after compaction, when a long session's context has been summarized. Once an agent knows the story, saying moonbase can bring back the whole pattern. It can recognize the same failure in work that has nothing to do with doghouses.

A good example gives the recipient enough of the arrangement to connect more of the dots itself. The circumstances, choices and consequences arrive together, so you don't have to spell out every relationship independently. In that sense, you're automating some of the work of connecting the dots. The example can travel into a new situation and act like a principle.

At this point, though, it's worth stepping out of the abstraction. The map is not the territory.

The world is a tool for thinking about the system. In practical terms, I'm working with files on disk, headings, text, links, code and OpenRig commands. I still have to open those files, inspect the implementation and check what the agents are actually doing. A coherent picture in my head is useful because it helps me do that work.

The routes can also lead to people and agents. At work, you often know who understands a particular part of a project and ask them a question. You don't reconstruct their entire experience from documents before you can use it.

OpenRig gives agents addresses so they can reach one another. In the film, I show `rig send` reaching an online agent that worked on Slack. For a dormant agent, `rig ask` can look through its saved session history; explicitly waking it is a separate way to get an answer from the live agent. That history depends on keeping the session files. I don't have to keep every agent running all the time to retain a route to what it knew.

*Demonstration: Ask an online agent with rig send. The agent who worked on Slack is online, so the builder runs rig send slack-original@demo "Why use OpenRig messaging?". The reply arrives in the builder's terminal: messaging handles agent addresses and delivery, and the adapter handles Slack-specific work.*

*Demonstration: Ask an earlier session with rig ask. The agent who built the Slack work is offline. rig ask demo "What did you search for?" --seat slack@demo searches that seat's saved history and returns excerpts: it searched for Slack, found leftover pieces and concluded the integration had barely started. Then rig ask with --wake slack@demo@2 explicitly resumes the earlier session to answer: it treated what it found as all that existed and missed the existing messaging system. The resumed session answers once and exits.*

Each specialist can know its own context domain in depth, with enough of the wider map to recognize when to ask someone else. Those specialists can know about each other too. I'm part of that network as well. An agent can route a question to me through Slack when it needs something I know.

That's distributed context engineering. You're organizing what a population knows, where that knowledge lives, and how it can be reached. The familiar human practice of asking a colleague becomes part of a system agents can navigate.

So what changes for the agent that rebuilt the Slack integration?

The first improvement is that its project orientation should make the existing messaging system visible. It has something to recognize and a path to follow. That path could lead to the integration we'd already worked on, the explanation of how it connects, or an agent who can answer a question about it. It still needs to investigate. It now has a better starting point for that investigation.

When OpenRig hit GitHub trending and outside contributions started arriving, this onboarding work had already been underway for months. OpenRig organizes coding agents into persistent teams I call rigs. I could add rigs for different kinds of work across my Mac Minis and VPSs, while continuing to talk to a lead agent that coordinated with the other leads.

The important part was being able to add agents that could find the project context and reach existing experts. That made the extra compute useful without requiring me to personally orient each new arrival. One real example in the film is an outside contributor adding buttons for answering agent questions in Slack. The teams handled the review and merge.

The stress test also exposed broken routes. Some agents missed context during onboarding. Others lost the path after compaction. Because I could understand the world they were using, I could ask whether the knowledge was missing or the road was broken, then work with the agents to trace and repair it while the system was running.

That's where the shared human-readable model paid off. I could scale my capability by adding compute because I'd made competence reproducible. And I could still understand enough of the system to maintain it.

Sharing that arrangement is the next experiment. A rig bundle can package a team and the context it needs, which is the idea behind a shippable unit of competence. I've written separately about [using that approach to help open-source projects](https://openrig.dev/blog/rig-bundles-for-open-source). That's where I get into Workshop and what someone else could try.

The broader lesson is the one I keep coming back to. Give an agent enough of the world to recognize what it might need, and reliable routes to find the rest. You haven't solved the infinite problem of not knowing what you don't know. You've made a particular project easier to navigate.

The [video](https://youtu.be/CYRJDTcTKhQ) develops this through diagrams, maps and an inhabited world. The explanation itself uses the same technique. Castles, roads, stories and colleagues are things you already understand. I've added unfamiliar concepts and connected them to those familiar ones so you can build the picture yourself. To me, that's where context engineering is going next.

Source video: https://youtu.be/CYRJDTcTKhQ