Openrig Operating Model

The OpenRig Operating Model

Canonical term: the Operating Model. How an OpenRig topology organizes every kind of context so that any agent — cold, fresh, or five generations in — can find what it needs and knows where to write what it learns. Authored context stays in addressed Markdown and manifests. Supported writers record semantic judgments; their read models remain rebuildable from those artifacts.

This skill owns the structure: trees, chains, tracing, and placement of authored knowledge. Resolve installed context through its current library addresses and the project's selected loadout; a private corpus is not a required public dependency.

Companion implementation assets in this skill's folder:

• templates/ and scripts/ — starters and working tools, described in §8.

1. The model in one breath

Everything lives on one of two trees, and every kind of context is a chain: the same filename at every level of a tree. To know anything, you trace from where you are toward the root, reading that one filename at each level — nearer levels refine or override farther ones. The trace (§5) is the act of doing that ascent deliberately, with your own file reads.

• Topology tree — how work is done: fleet → instance → rig → pod → seat.
• Work tree — how the product gets built: project → mission → slice → proof item.

An instance is one OpenRig daemon and the rigs it manages; a fleet is all instances. Where a daemon runs is a deployment fact, not an altitude — say the instance's name when you mean a particular one.

The one-parent law: the trace follows the directory path and NOTHING else — no pointer fields, no link-following, no branching, ever. The trace is the instrument confused agents reach for, so it must be simpler than anything it corrects: path-only ascent fails only in obvious ways. A child that relates to a second parent gets an also-serves: ANNOTATION (read by humans and agents, walked by nothing) — and a genuine two-parent tie usually means the item belongs one level up, under the common ancestor, with mentions pointing down. The operational many-to-many lives in the queue's tags, which are maintained by use. Legacy serves: lines are transition bridges for the flat layout only: never required, never walked, deleted as work nests properly.

The filename law: one name per chain, identical at every level. The folder tells you whose it is; the filename tells you what kind it is. A seat named pm-lead in two different rigs has two different LEARNED.md files — the path is the identity. Never invent per-level names (no SEAT.md, no RIG.md): that breaks the trace, the self-description, and every tool at once.

2. THE GRID — what exists at each level, and who keeps it true

This table is the model. If you internalize one thing, internalize this.

Topology tree

The chains carry what is true of a position. How a kind of thing works — the operating model — ships in the mode-neutral openrig-core plugin; an operating-mode plugin (openrig-lab, openrig-factory, or openrig-hq) may refine it.

Chain files sit on nodes, not on the shelves that hold them. rigs/, pods/, seats/, missions/ and slices/ are shelves — the trace passes through them and expects nothing there.

Work tree

ONE authored node file: SPEC.md. Intent lives in its FRONTMATTER; the specification lives in its body. Alongside it sit three files with different jobs and different writers:

A scaffold may create NOTES.md and its starter instructions; its lived entries are never generated or projected. It is the work tree's lived file, the way LEARNED.md is the topology tree's — the field-notes rung, where raw observation goes before anything has earned a place in the node itself. Keeping lived files out of the render path is what makes them safe to write freely in.

Legacy name: older workspaces may use MISSION_NOTES.md. Keep legacy content addressable; use NOTES.md for the chain because its name works at every altitude.

Current acceptance: Scope relationships and policy are authored in manifests; an item judgment is recorded once against its promise, evidence and policy revision. Slice, mission and project readiness derive upward. A distinct outcome or publication decision remains its own authority. Queue ownership and generic done are custody facts, not proof acceptance. Historical checkbox marks stay readable without acquiring current item authority.

Use rig proof --help for the supported write/read path. The project owner selects proofPolicy.judges in project.yaml, mission.yaml or slice.yaml (nearest wins), using exact actor addresses. There is no implicit fixed-role review conveyor. rig proof judge mission/slices/slice#1 --verdict accept --reason 'Observed the outcome' --evidence proof/result.md resolves the item identity, revision, evidence digests and retry identity. Evidence may be an existing legacy artifact or a non-code outcome. A patch-equivalent subject also names its actual comparison/adoption receipt with --comparison; the agent owns that judgment. rig proof show returns the current basis and retained receipt; it does not publish anything.

Correct with reject, or withdraw when prior acceptance no longer stands. History stays in the addressed proof home. A repeated request returns its original receipt and current readiness; --replace deliberately reaffirms an old identical judgment after a correction. Changed promises, policy or evidence require a current judgment. Explicit optional <!-- proof-item: stable-id --> markers preserve identity across wording edits; the product otherwise derives identity from the full promise and reports ambiguity.

Intent composes; the body does not. The trace reads the intent: FIELD at every altitude, so four levels unfurl as four sentences rather than four documents. The body is read only when you are standing on that node.

compose.py up <node> --name SPEC.md --field intent --root <project>

A level whose file exists but lacks intent: is reported as a gap — a mission with no intent is real information, never silently skipped.

Legacy README.md nodes stay valid indefinitely — the resolver prefers SPEC.md and falls back, so nothing is forced to migrate and dormant missions need no attention.

PROGRESS stays separate. Narrative and legacy marks are retained testimony. For a project with selected proof policy, current readiness comes from rig proof show and the shared existing views, not hand-maintained parent checkboxes or copied status prose. scripts/compose.py progress remains a legacy checklist renderer; it does not certify attributed acceptance. Intent composes downward; proof readiness aggregates upward.

The axis behind the columns: every context kind has a template half (what ships — SOP, the default culture) and a learned half (what living in it taught — LEARNED, culture amendments). Only the pace of change differs: values change rarely and deliberately, like a constitution; practice changes constantly and cheaply, like working notes; intent changes at real pivots. Keep each file's pace; don't constitutionalize your notes or scribble on the constitution.

3. Why this exists (the failure it fixes)

Seat knowledge needs a durable home that successors and other runtimes can read. A private runtime memory or an urgent handover packet alone can omit standing duties and the reasons behind a practice. Keep general operating craft in the shared skill and position-specific knowledge in the seat's LEARNED.md chain. At a handover, read the current chain alongside the packet and record any missing job context before claiming readiness. Each occupant maintains what the seat has learned; the handover packet carries the current transition.

4. LEARNED.md — the living file (all altitudes; seat shown)

Sections, in order — see templates/LEARNED.md:

1. Header — coords · which SOP it refines · updated date (from the clock command, never from memory).
2. MY JOB HERE — this instance's actual function, in plain operational terms.
3. STANDING DUTIES — every recurring duty, each with its rhythm and where it happens. Duties listed anywhere else die at the next handover; this section is why they survive.
4. HOW I WORK — practices learned on the job, each with its reason. A practice with its why can be re-judged when the world changes; a bare rule outlives its reason and gets misapplied.
5. GATES & AUTHORITIES — what this instance may decide alone, what it must never assume. Authority exists in writing or not at all.
6. KEY RELATIONSHIPS — who it hands to, who reviews it, who it reports to.
7. TRIGGER POINTERS — "when X happens, read Y." Attach pointers to the moments that need them; lists of boot-time reading decay.
8. LESSONS — dated, newest first. Periodically distill old entries into HOW I WORK or drop them.

Size: soft guidance, not a rule. Keep it as small as honestly covers the job — attention is the budget, and every reader pays it. Some seats genuinely need more; write what the job needs. The failure mode to watch for is the rulebook that only ever grows. Distill lessons into practices with reasons at deposit boundaries (before clear or handover); use that habit, not a line count.

5. The trace — deliberate reorientation

A trace is walking your chains with your own file reads and writing down where you stand: what am I doing (queue/NOTES) → under what contract (SPEC) → toward what intent (SPEC.md intent field, leaf to root) → by what practice (LEARNED + SOP) → within what values (CULTURE). A few written lines at the end. scripts/compose.py up assembles any chain for you.

Two rules give the trace its value:

• Your reads are the trace. A trace written from memory is a recitation — if you didn't open the files, you didn't trace, and you will confidently re-derive whatever drift you already have.
• Report broken links; never obey them. A missing file, a stale date, an intent that contradicts observable reality — say so to the level that owns it. That is how the chains stay true: they are audited by being used. And the chains inform decisions; they never enforce anything by themselves — a stale map must never be able to block true work.

When to trace — one principle: trace when enough has changed that your picture of where you stand may be stale — after a large stretch of work, at a boundary (boot, handover, new mission, confusion), or when someone asks you to reorient. Why not simply "every N hours": identical scheduled prompts fade from an agent's attention with repetition, and idle seats accumulate ritual traces that crowd out real context. Where a schedule fits your context anyway, use one — but prefer gating the action on evidence of change: scripts/trace-due.sh decides "has enough happened since my last trace?" deterministically and stays silent when the answer is no, so a scheduler can fire it as often as it likes.

5b. Trace and rig walk — one idea, two ends

These get confused because they share a word. They are not in conflict; they are the same thing seen from either end, and the relationship is worth holding.

A chain is an ordered sequence of context meant to be absorbed one piece at a time. Two kinds exist and both are chains in that sense:

• Altitude chain — the same filename at every level of a tree, read by ascending (LEARNED.md; SPEC.md with intent:). The sequence is position: leaf → root.
• Boot chain — a seat's startup reading sequence. The sequence is order of onboarding.

A chain can be traversed two ways, and that is the only real difference:

Pacing is the mechanism in both directions, and it is the load-bearing part. Absorption between pieces is what makes a chain land; a concatenated dump of the same bytes is a failed delivery regardless of content. That is why rig walk elapses --pace between pieces, and why a composed render is meant to be read as a sequence rather than skimmed as a wall.

Use distinct names for the two directions:

• TRACE — the pull ascent. compose.py up renders a node's chain to the root.
• rig walk — the push verb for paced delivery into a seat's pane.

Use refocusing for the current trace workflow. A delivery receipt and an agent's read-depth report answer different questions; pacing alone does not establish understanding.