Explainer 0 · Architecture
How our AI system fits together
The short version. One person sets the direction. A single AI session, the hub, makes the judgment calls and hands work out. Separate agents each cover one area of work and stay inside it. Cheaper AI models do most of the actual work, and the pricey one only decides.
Around all of that sit three things that keep it sane: rules that block bad moves, a memory of what we learned, and a task list so nothing lives only in a chat.
Think of a small office. The owner decides, a manager routes the work, specialists each have their own desk, and everyone writes things down.
Going deeper
This is the version for people building something similar. The shape is the same, with the moving parts named.
One person, one hub
A human sets goals and keeps the calls that need judgment, money or taste. The hub is a long-lived AI session that reads the ranked work list, decides what matters next, and routes it. It does not do bulk work itself. Its job is deciding, summarizing what comes back, and talking to the human in short messages.
Lane agents with their own boundary
Each area of work gets its own agent definition: one for each business, one for the tooling that runs all of this, a few for narrow jobs like placing windows or driving a browser. Every one reads the same short contract first, then its own lane file, and nothing else. A lane file says what it handles, what it never handles, and which credentials it may read.
We are straight about what that is. The boundaries are written rules plus hooks that catch the common crossings. They are not a sandbox, and every agent still runs as the same machine user. That is why the sensitive paths also have hooks that fail closed.
The expensive seat judges, cheaper models work
Model choice is a routing decision, not a default. The top-tier model sits in the seat that talks to the human and makes judgment calls. Everything else is dispatched to a model picked for that job, and the dispatch says which model and why:
- Lookups, greps, status checks, formatting: the smallest, cheapest tier.
- Drafting, code in a known area, structured reads: the middle tier.
- A subtask that itself needs hard reasoning (an architecture review, a nasty diagnosis): the top tier, as a subagent.
The reason is quota and cost, not taste. A long conversation re-sends its whole history every turn, so doing bulk reads in the expensive seat burns the budget fast. A subagent returns a short summary and its own context disappears. Parts of this are enforced by a hook that refuses the common wrong shapes, like running a plain lookup on the top tier. Parts are only a rule we follow.
Gates and hooks
Rules that only live in a prompt get ignored under pressure, so the important ones are code. Examples: tests must pass before a commit goes through, a hook blocks reads of secrets and of areas an agent has no business in, background jobs may never touch a metered paid API, and anything addressed to a person outside the system needs the human's approval of the exact text first. A hook that fires is cheap. A rule an agent forgets is not.
Memory and the vault
Two layers hold what we learned. Memory is a folder of small notes the agent loads at the start of a session, covering preferences and corrections. The vault is a git repository of plain markdown: decisions, references, records of what happened. The split is simple. If it is a fact or a decision, it goes in the vault. If it does something, it is code. If it is a way of looking at what the code already knows, it is a view. One record, one engine, and any number of views over them. Explainer 1 covers memory in detail.
Everything is a task
Work starts from a ticket. A session opens by naming the ticket it is on, questions go up to the hub one at a time, and the result is recorded against the ticket. That way nothing important lives only in a chat window that will be gone tomorrow.
What this costs you to copy
You do not need all of it. The smallest useful version is three parts: a hub that decides and delegates, one lane file per area with explicit "never handles" lines, and two or three hooks that block the mistakes you have already made once.