Ask the Fleet, Don't Grep It
Every new Claude Code session starts blind. It opens CLAUDE.md, then a command file, then two or three agent files, and somewhere around the fourth file it has spent a good part of its context window just finding out what exists. Ten agent systems, twenty-five subagents, fifteen guardrails, four verification shapes: the facts are all in the repository, but they are spread over dozens of markdown files, and the only way to get at them is to read them all.
That is the problem I set out to fix this week, and the fix came from my day job. In enterprise architecture we do not ask people to read every project file to find out which system talks to which. We keep a model and query it. So I gave the agent fleet a model.
What an ontology is, in this context
The word sounds heavier than the thing. An ontology here is three lists and a set of links.
The first list says what kinds of things exist: an agent system, a subagent, a tool, a guardrail, an artifact, a usage scenario, a human decision, a blog post. Twenty-one kinds in total.
The second list says how they relate. A system dispatches subagents, in a given wave, in parallel or not. A subagent is granted tools. A subagent reads and writes artifacts. A system is guarded by guardrails and verified by a verification shape. Twenty relations, each with a name a person can read.
The third list is the actual things: email-triage is a subagent, granted three Gmail tools, one of them draft, none of them send. There are 312 of those entries, and most of them are not typed by hand. A small script reads the agent, command, blog and prompt files and generates them, the same way a surveyor reads a building. The handful of judgement calls the files cannot express (which access class a subagent falls into, what the human decides at the end of a run) live in one overrides file.
The model is written in the .nai language of nai-onto, my own ontology tool, and loaded into it. From there it is queryable over an MCP endpoint, which means a Claude Code session can ask it questions directly.
What changes for a session
The benefit is not that the documentation is prettier. It is that questions which used to cost a file walk now cost one call.
Orientation. "List the agent systems with their cadence, verification shape and human decision" is one query. The answer is the same every time, because it comes from the same generated inventory, not from whichever files the session happened to open.
Tool grants before dispatch. "Which tools may email-triage use?" returns the grant, the access class and the sentences that begin with never. A session about to dispatch that subagent gets the boundary without parsing YAML frontmatter.
Impact analysis. "Who reads the payroll JSON?" and "which systems dispatch the cockpit writer?" are inbound-link lookups. Before I move an output folder or rename an agent, the graph tells me what breaks.
Drift as a gate. The generator has a check mode. If an agent file changes and the inventory was not regenerated, the check fails. It runs before a pull request; it could run as a pre-push hook.
Rules the files cannot state. Three consistency rules run every time the instances load. A subagent that claims no web access but is granted WebSearch is caught. A system that claims a verifier shape but dispatches no verifier is caught. A system that claims a cockpit but never calls the cockpit writer is caught. These are the cross-file contradictions a reader misses and a linter cannot see, because no single file contains both halves.
A run ledger. Each agent-system run appends one small entry: system, period, outcome. "When did the last quarter close", "which option studies ran this month", "how many payroll runs were flagged" stop being folder listings and become queries. The step is last in every command and never blocks the run; if the endpoint is not configured, it says so and exits clean.
Documentation with a second source. My architecture pages are already surveyed from the agent files. Now the checker that verifies each page's claims has a second place to look, and the survey can cite an instance key instead of a line number.
Views for humans. The same graph draws the dispatch tree, the artifact flows and the guardrail coverage in the nai-onto UI, in four viewpoints: features, systems, architecture, usage. A German sidecar translates every label, so the model is presentable to a German-speaking client without a second copy.
What it does not do
The agent files stay the source of truth. No agent reads its own boundary from the graph; the boundary is enforced by the tools: grant in the file the runtime executes, and the ontology merely reports it. This matters. A model that agents consult at run time becomes a second place a mistake can hide. A model that is generated from the agents can only be wrong in ways the drift check catches.
The ontology also does not record why. It knows that the option study loops at most three rounds and the review pack runs one pass with no loop. It does not know that the second was a deliberate contrast to the first, written to show what bounded loop engineering costs. That reasoning still gets written once, by a person, in a design spec, and the spec is linked from the graph. The link is the point: the model tells you where the reasoning is, so nobody has to remember.
Where it goes next
The near-term additions are small. The morning briefing can read the run ledger and open with a status strip: last tax close, last newsletter, studies still open. A weekly query for elements with no guardrail link is a coverage report I never had. The fifteen usage scenarios, with their steps and decision points, can regenerate the user guide.
The bigger step is the one that made me build it. This fleet is one ontology. The other products get their own, cross-linked. And the same twenty-one kinds, applied to a client's agent landscape, give an enterprise-architecture view of it: what runs, what it may touch, who decides. The nai-os instance is the worked example.
In model-based engineering we say: one model, many views, and never let a view become the master. This is that principle turned on the tooling itself. The agents are the model. The ontology is a queryable view of the agents. Regenerate it, check it, ask it. Do not grep it.