Internal complexity may grow; perceived complexity must fall

The rule, and the failure it prevents

Goal-first outside, rigorous inside. The user states a business goal; the rails are selected by the workflow rather than hand-orchestrated by the user. Every rail may be rigorous, deterministic and opinionated inside — that is what makes the result trustworthy — but none of that rigour may leak outward as a step the user has to perform, sequence or remember.

The named failure is specific: a user who has to know that app inspect comes before solution check, which comes before package scaffold, has been handed our implementation as their workflow. Every primitive is judged against that outcome rather than against its own merits.

The budget itself is deliberately asymmetric. New internal complexity is allowed to grow, and it has grown — a package contract, a conformance kit, a characterization harness. Each was justified by something that became simpler or provable on the outside. None was justified by being interesting.

The eight questions

Every new agent-facing command, tool, contract or namespace must answer all eight in the PR that introduces it. One: which concrete agent failure mode does it prevent — the failure, not the capability. Two: why are existing primitives insufficient, with the attempt shown, because if an existing command almost does it then extending it usually beats adding one. Three: does it overlap semantically with an existing tool, since two commands that answer nearly the same question are worse than one that answers it completely — the agent now has to choose, and will choose wrong. Four: can it remain deferred or on-demand, which most things can.

Five: does it preserve Claude, Codex and Gemini portability — if the behaviour lives anywhere but a CLI, a JSON contract, the Package Contract, canonical Skill semantics or the Quality Gates, the answer is no. Six: what machine-readable evidence proves its value — an exit code, a contract-versioned document, a fingerprint, a measured number; 'it feels better' is not evidence. Seven: does horizontal impact update the compatibility backfill, because a capability every domain could use, recorded for one domain only, is a fork. Eight: does the end-user goal flow become simpler rather than more manual — if the answer is 'the agent now has one more thing to run', the primitive has failed question one.

A primitive that cannot answer these is not blocked forever. It is blocked until somebody can name the failure it prevents. AGENTS.md carries the same gate as a standing review item, so the rule is cited in review rather than remembered.

The budget, with today's numbers

A principle stated in a strategy document erodes one reasonable addition at a time, so it is also a number with a ceiling, a reason and an exit code. Running node scripts/surface-check.js prints the surface an agent has to understand before it can start: goal entry points 1 / 1, skills 12 / 12, always-on tools 9 / 10, commands in skills 11 / 11, and then the line 'Internal complexity may grow. Perceived complexity has not.'

Three of the four measures are at or on their ceiling, which is what a budget looks like when it is doing something. The commands ceiling was raised from 10 to 11 on 2026-08-09, and the argument is written into scripts/surface-check.js beside the number: project doctor, package scaffold and package test shipped three genuinely new answers and took nothing out. The same comment then closes the door — eleven is where it stops, the package namespace already holds four verbs, package test already proves what package validate checks, and the next command that wants a place in a skill pays for it by folding validate into test rather than by moving the number again. A ceiling raised twice is not a ceiling.

The check is not only counting. It fails a skill whose description never says what it is not for, because the description is the routing table a harness matches against and a skill that does not exclude competes with every skill it overlaps. It fails a second skill that describes itself as answering a bare business goal, because two front doors means the user picks, and the user should not have to know there is a choice. And the ceilings are themselves exercised: tests/surface-budget.test.js builds a fixture that breaks each one, on the grounds that a budget nobody has watched fail is a budget nobody should trust.

What it deliberately does not measure

Not capability. The framework may grow a hundred capabilities; it may not grow a hundred things an agent has to read first. Those are different numbers, and conflating them is how a good architecture becomes an unusable one.

Not quality. The budget can tell you another command appeared. It cannot tell you whether the command was well designed, and no count on this page implies anything about the code behind it.

Not agent success. Question six asks for a measured number, and the one number that would settle whether coding agents can actually build with this does not exist yet — the benchmark protocol is published and has not been run (L-03). The evidence that does exist is narrower and checkable: 701 tests run on every push (C-20), one command that reads an application's real composition from checked-in source and returns a machine-readable list of what it cannot see (C-14), and MCP tools where anything that generates code or destroys state is dry-run unless an explicit apply flag is passed (C-18).

What the document is not

Not a roadmap — other documents sequence work; this one decides whether work should exist. Not permission to build the rails it lists as future: of the thirteen rails in the table, six are marked future, including skill mirror reconciliation, project verify, the scenario runner, the context pack, implementation evidence and MCP parity. Every entry is either implemented and verifiable by a command, or future and marked as such, with nothing in between.

Not marketing either. Positioning claims live elsewhere and are bounded by evidence and by an explicit list of things not to claim. The reason this page exists on a public site is narrower than a manifesto: the rule is only binding if a reviewer can cite it, and a rule with an exit code can be cited by someone who does not work here.