Documentation
The docs mirror the repository's own vocabulary and reading order — not a parallel rewrite. The canonical source is the checkout itself; these pages present it for humans.
Reading order, by role
The doc tree exists to keep every role's load short. Each role loads what its row names, in order, and nothing more.
| Role | Loads, in order | Bounded by |
|---|---|---|
| orchestrator, cold | router block, then the ownership map; vocabulary entries on demand | ~2 pages |
| orchestrator, lifecycle | the generated lifecycle table | one rendered table |
| decomposer | the root ticket, the stamped standard, the owners the spec names | the ticket |
| executor | its Goal and relevant Context | the ticket |
| evaluator | the lens, then the artifact — blind to the producer's prose | the lens |
| human | README, then whatever it links | nothing |
What lives where
The library is four tiers of dependency, plus the cross-cutting owners around them. Each entry names its tier and its job.
| Path | Tier | Owns |
|---|---|---|
contracts/ | T0 | The narrow waist — pure data shapes; the only interface between everything above them. |
skills/ | T1 | Callable packages: kernel/ primitives that call no skill, workflows/ domain-blind workflows. |
standards/ | T2 | Domain prose under the standard contract — never control flow. |
example-workflows/ | T3 | Named workflows, each a skill body calling callables. |
rules/ | — | Cross-cutting law: visibility, token economy, composition, delegation, verification, roles, topology, loops, improvement. |
docs/ | — | On-demand reference and the vocabulary. |
scripts/ | — | Repository automation; tickets.py is the public ticket facade. |
reader/ | — | The Observe browser — a read-only projection over the workflow graph. |
hosts/ | — | Host records, entry mechanisms, and role bindings. |
templates/ | — | Host-block source, installed at ~/.orchflows/host-block.md. |
benchmarks/ | — | Evidence corpora, not library machinery. |
Seven contracts are the entire interface surface:
bundle, dispatch, result, standard, verdict, work-item, and worklog. Anything that emits one plugs into anything that takes one.
Start with Installation, then Concepts for the vocabulary, then Architecture for where things live.