An agent language has an unusual property: the spec is not documentation, it is the runtime dependency. The model reads it in context before writing a line, every session, so every token of spec is a tax on every program ever written in the language. Two data points from my own patch:
- Mog, another syntactic-camp language, bounds its spec at 3,200 tokens by policy
- ilo’s
SPEC.mdhas grown past 40,000 tokens
How ilo got here
ilo’s whole premise is token cost. Programs are a fraction of the Python equivalent, and the early spec was small enough to inline into any agent’s context. Then the language grew, clusters of builtins, worked examples, edge-case rulings, and each addition was individually justified. The spec that resulted is thorough and an order of magnitude past what “read this, then write code” comfortably supports.
The failure mode is quiet. An agent given a 40k-token spec does not complain; it skims, and skimming a spec produces plausible-but-wrong programs, which is the exact failure the language exists to prevent. Meanwhile ai.txt, the deliberately token-minimal companion file, drifts toward being the real spec while SPEC.md becomes the reference nobody inlines.
The bounded-spec discipline
Mog’s 3,200-token cap reads as an engineering constraint rather than a style preference, and I think that framing is right. A hard budget forces the same decisions a binary size budget forces: every addition evicts something, so the spec keeps only what changes model behaviour. Rulings that matter once a year move to lookup-on-demand. Examples earn their place by fixing observed generation errors, not by completeness.
The counterargument is real: a small spec undersells a large language, and Mog’s language is far smaller than ilo. But the counterargument concedes the point. If the language has outgrown a readable spec, the answer is layering, a bounded core spec that is always in context plus reference material fetched when a specific cluster is used, not a monolith nobody reads end to end.
What I would set the budget at
For ilo: a core spec within 4,000 tokens, back near the size it was when the language’s headline generation-accuracy numbers were recorded, with per-cluster reference files behind it. The measure of success already exists, the spec-only generation accuracy runs I use for release checks. If a 4k layered spec matches the 40k monolith on those runs, the other 36k tokens were never load-bearing.