All docs

Start

Methodology

The nine principles and three red lines used to judge a design.

Designs and changes to aiL are judged by these principles. Each one ends with a test question.

Nine principles

1. Human attention is the bottleneck

You propose, decide and accept. Sessions, Clients and worktrees are implementation details: one Desk shows everything you have to handle, and you never need to remember which session on which machine holds what. You are interrupted only when you must act or can use a result.

Test: does this design make the user remember one more thing, look in one more place, or perform one more action?

2. Two layers: the Router judges, Workers execute

The Router takes all your requests and makes only light judgments: pick the intent, pick the repository, dispatch. Execution happens in Workers with isolated context. How Workers go back and forth is invisible to the Router.

Test: does the Router need to read repository files or understand the inside of the task? If so, give it to a Worker.

3. Fast and slow paths: what is certain goes to code

Hand-offs (who is next, which review round, when it ends, who is notified), merging, archiving, committing and the Journal are executed by the engine; models produce only judgment and content. Exchanges whose owner is already known go direct: your answer to a Worker enters its queue without passing the Router.

Test: is the output of this step uniquely determined by its input? If so, write it into the engine.

4. No polymorphism: one abstraction, one set of interactions

An abstraction defines a class of entities and all their interactions. Instances may take different parameters, but every instance reads the parameters the same way.

Test: does this change need "except for X" or "only when it is Y"? If so, change the abstraction first.

5. Context: isolated, linked, on demand

A Worker starts in the repository responsible for the work, and one context does one thing. Repositories are linked only through the main repository's registrations and stable ids. Resident context (role descriptions, the Router contract) holds only what every turn needs; everything else is a path or a command, fetched when needed.

Test: is this text useful to every agent that will read it? Is it needed every turn, or is a path enough?

6. One source of truth; state apart from history

A fact is maintained in one place. Plugin content lives in files in Git; tasks and maps live in task records in the repository; sessions, runs and reports live in the Desk database. Programs hand over fields; they never parse state out of text written for people.

Test: in how many places is this fact written now? How many must change with it?

7. Runtime apart from context

Context lives in Git and can be rebuilt on any machine. The runtime (binary, harnesses and subscriptions, sessions, database) can be replaced wholesale. The dependency on harnesses is confined to the narrow interface of the Worker contract, which uses only public ACP methods and events.

Test: to move the runtime to another machine, what must move besides installing and logging in? If a harness is upgraded by one version, what breaks?

8. Asynchronous, with few turns

Dispatch returns at once and results arrive as new messages; nothing waits or polls. What can be handled silently does not trigger a turn; notifications that can be merged are delivered together. Nothing interrupts a running turn: messages to a busy session are queued. A Worker's own waits follow the same rule: it says when to be woken, and the engine wakes it.

Test: how many turns does this change add to a typical run?

9. Improve from data

Everything that happens in a run is written to the run log, and problems are found in statistics and samples. Verification is judged at the end point: what the model actually received and what the user actually saw.

Test: which runs does this change cite as evidence?

Three red lines

  1. One consistent abstraction, zero work-arounds. Every harness session the orchestration layer sees is the same Worker. No branching on a harness or instance name, no special cases, patch flags or temporary detours. A difference between harnesses has two places to go: data in the harness definition, or outside the contract. When a capability does not fit the abstraction, change the abstraction first.
  2. Spec-driven. When a convention must change, change the spec first and the implementation with it, in the same change.
  3. Prototype first. Key external dependencies get a minimal prototype, and the formal design waits for the measured result.