Three layers, nearest wins.
A global file carries what is true everywhere: authority, how to choose the size of a workflow, what counts as evidence, when to stop and ask. A workspace file describes the shape of the disk. A project file describes the stack, the entry points and the state files of one repository.
The rule that binds them is one sentence: read the nearest manual before changing a project. Precedence runs from the message you are given, down through global policy, to the project file that sits closest to the code.
- 35 project directories carry their own manual today.
- Two runtimes read the same layering, under two filenames, so the policy does not fork when the tool changes.
- A rule about a repository lives in that repository, not in someone's memory of it.
Live code beats old notes.
The most load-bearing line in the global manual is about precedence between sources of truth: live code and configuration establish what is true; stale status documents do not set priorities.
Without that line an agent reads a six-week-old plan describing work that shipped, and helpfully re-does it. With it, the plan is context and the repository is the authority.
The manual says what may be done without asking.
Most of the value is not in style rules; it is in a written boundary around consequence. Routine reversible decisions are made from context and never escalated. Money, deploys, anything public, anything destructive stops and asks, every time, no matter how obvious it looks from inside the task.
That boundary is what makes autonomy safe to grant. An agent that cannot tell a rename from a production migration has to be supervised on both.
- Reversible and in scope: proceed, report afterwards.
- Irreversible, outward-facing or consequential: prepare the reviewable result, then stop.
- Risk is classified by consequence, never by how many lines the change touches.
Match the machinery to the job.
The manual also governs its own overhead. Clear, bounded work proceeds directly with the verification that fits it. Heavier structure — durable plans, independent review, parallel workers — is reserved for work whose failure is expensive.
Written down, this stops the most common waste in agent work: ceremony applied to a task that needed one edit.
What it costs to keep true.
A manual that drifts is worse than none, because it is trusted. These files are edited when a rule is learned the hard way, and the entries that survive are the ones written immediately after something went wrong.
The honest failure mode is length. Each added paragraph competes for attention with every other, and a manual nobody finishes is a manual nobody follows.