Architecture

Four tiers of dependency, one narrow waist, and a set of cross-cutting owners. Terms are the vocabulary's.

Four tiers

T3 example-workflows/ Named workflows, each a skill body calling callables; their authoring standard is custom-workflow-authoring.
T2 standards/ Domain prose under the standard contract, never control flow. A root states one domain; narrows: optionally names one tightening base.
T1 skills/ Callable packages. kernel/ owns the two profile-neutral callables; workflows/ the reusable domain-blind workflows. Control flow is the caller's prose.
T0 contracts/ The narrow waist — each contract owns one pure data shape, rendered from contracts/shapes.json.

Dependencies point one way: a lower layer may link the law or contract binding it, but no lower-layer skill depends on a workflow, and generic skills never name a standard or domain.

The seven contracts

Seven data shapes are the only interfaces. Anything that emits one plugs into anything that takes one.

  • bundle — one ring's tree of skill/standard/workflow items.
  • dispatch — the v1 grammar; one launch, one return.
  • result — the dispatch-outcome envelope every return crosses.
  • standard — consumed frontmatter, word ceiling, lens compatibility, tree digest.
  • verdict — PASS / FAIL / UNVERIFIED with evidence.
  • work-item — the ticket: Goal, Context, Details, lifecycle, graph position.
  • worklog — the run view rendered from the ticket directory.

Cross-cutting owners

OwnerScope
rules/Cross-cutting law — scope, dependency, canonical-fact ownership, token economy, verification, delegation, roles, topology, loops, improvement.
docs/On-demand reference; vocabulary.md owns library terms, documentation.md the reading order.
scripts/Repository automation. tickets.py owns the public ticket facade; sibling modules own syntax, admission, generation, dispatch, join.
templates/Host-block source, installed at ~/.orchflows/host-block.md.
install.py / installer/The installation facade and the private runtime at ~/.orchflows/runtime.
reader/The Observe browser and its closed /api/v1 state-sink seam.
hosts/Host records, entry mechanisms, and role bindings.
benchmarks/Evidence corpora, not library machinery.

State boundary

The state sink is the one user-scope root every run's durable state resolves to — outside every repository. scripts/state_root.py alone derives its path and branch; nothing else computes either. Research evidence lives in the sink's research/ tree; run state in runs/ and tickets/; friction in friction/.

Dependency direction

Arrows point from reader or binder to dependency:

AGENTS.md → rules/ → contracts/ → skills/ → package scripts/

Standards depend on contracts and may name callable skills. Generic skills never name a standard or domain. A workflow's prose calls skills, other workflows, and scripts; no lower-layer skill depends on a workflow. Shared packages never name project packages; project packages may name visible ones.