Design rationale
The library has one significant reader and writer: a language model operating through a file-tool harness. Every structural choice traces to an operating constraint of that reader. Human legibility is welcome; it is never the design driver.
The reader's constraints
| Constraint | What it means |
|---|---|
| Amnesia | Every context starts empty and dies without heirs. Nothing persists except files; a convention that lives only in a prior context is already lost. |
| Metered, parallel-shallow reading | Reading costs per file; breadth parallelizes, depth serializes. Deep indirection is the most expensive shape a repository can take. |
| Search is memory | The reader finds things by exact-match search, not recollection. One name per concept, one concept per name. |
| Cheap generation, scarce verification | Plausible artifacts are produced far faster than anything can check them. The binding resource of any run is trustworthy verdicts, not output. |
| Diluted attention | Instruction-following degrades with every word that is not load-bearing. |
| Shared blind spots | Executor, reviewer, and judge are the same weights. Independence must be manufactured structurally — fresh contexts, blind lanes, external oracles — never assumed. |
Structure → constraint
- A narrow waist (
contracts/) - N workflows, M standards, and H hosts meet in eight data shapes — N+M+H mutual understandings instead of N×M×H.
- Skills wear function anatomy
- Require / procedure / Never / Return gives a contract the reader can pattern-match instead of prose it must infer. Body budgets with overflow to
references/keep the always-paid cost small. - Kernel skills call no skill
- Call depth is the serial cost; a frozen floor of primitives bounds every chain statically. A child can load one file and have its whole world.
- Standards are data, never control flow
- The domain fork must not live in workflow bodies, or there are M diverging copies of every workflow. One generic body reading domain facts means a domain is added by writing data, not by editing control flow.
- Tickets and worklogs are markdown on disk
- Files are the only memory every context shares, and the only store the reader can search with native tools.
Advantages over Dynamic Workflows
Measured against Anthropic's shipped runtime as documented 2026-08-15.
Dynamic Workflows
orchflows
One harness.
Cross-harness — one library drives Claude Code, Codex, and Grok Build.
Adversarial review is house advice.
Verification is contractual, not merely available — Goal, executor evidence, and an independent path stand between a claim and "done".
Runs leave nothing to mine.
Self-improving — friction and traces feed the improvement workflow, including on itself.
Exit mid-run, start over.
Survives session death — every ticket is a file in a per-user state sink, resumable from any checkout.