OpenRig Mental Model Primer

Forming an OpenRig Mental Model

You're new to OpenRig — or returning after time away — and you need to quickly understand what kind of system this is, what your seat is, and what the moves are. This skill is the fast on-ramp.

For depth, read the canonical reference docs the skill points to. This skill's job is to get you oriented — accurate enough to operate, fast enough to be useful — not to replace the canonical docs.

The 60-second mental model

OpenRig is a local control plane for multi-agent coding topologies. You declare a topology of agents in YAML, boot it with one command, and OpenRig manages tmux sessions, harness lifecycles, transcripts, snapshots, and restoration. When the system goes down, OpenRig snapshots; when it comes back, agents resume their conversations.

The product loop:

down (auto-snapshot) → up <rig-name> (auto-restore) → work → repeat

The unit of work is the rig — a topology of agents working together as a single system.

The four-layer model (where you live)

Everything in agent engineering happens at one of four layers. OpenRig operates at Layer 3.

You are an agent at L1 inside an L2 harness, configured by L3 OpenRig. OpenRig manages your harness; the harness wraps the model; the model generates your tokens.

Three pillars of context

OpenRig is built on three context-engineering pillars. When you're oriented, you should know which pillar you're operating in:

OpenRig manages topology and exposes public context through rig context. Project-authored sources supply project-specific knowledge; transcripts retain recorded work. These sources already coexist. Discover the configured library and selected task context rather than assuming a particular private corpus: rig context list shows the configured packs, and rig context work-install lists what the current project declares (intent, context files, skills), so you read only the pieces a task needs.

The core vocabulary (read these terms literally)

The session-name format {pod}-{member}@{rig} is your address. When you run rig whoami --json, you get back your full topology context: rig name, pod, member, peers, edges, transcript path.

Rig classes (what kind of rig am I in?)

OpenRig has five rig classes. The class determines authoring discipline, supervision, and lifecycle policy.

You're probably in a project rig or managed-app rig if you're doing substantive work. Knowing your class helps you understand the supervisory expectations on your seat.

How skills load (the most important thing to get right)

Skills are an established cross-runtime standard at https://agentskills.io/specification. Both Claude Code and Codex build on it.

The shape

A skill is a directory containing SKILL.md (uppercase). The SKILL.md has YAML frontmatter (name, description) and a Markdown body. Optional sibling directories: references/, scripts/, assets/.

Progressive disclosure (why skills scale)

The harness reads frontmatter cheaply at boot — names + descriptions of all available skills. Body content loads only when a skill activates. This is ambient awareness — you know all the skills exist; you only pay token cost when you reach for one.

Where skills come from in OpenRig

• Per-agent loadout: your AgentSpec's profile.uses.skills: [...] determines what skills get projected into your runtime skill folder (.claude/skills/ or .agents/skills/) before your harness boots. This is the structural composition layer.
• Cross-pod sharing: AgentSpecs can imports: [shared] to access a shared skill pool. Built-in agents commonly do this.
• Belt-and-suspenders: the spec projects skill files; startup guidance also tells you to load specific skills. Both paths matter — if the projection silently fails, the guidance still tells you what to read.

Where skills live (sources of truth)

The product already discovers its installed shared skill pool and serves packaged context through rig context list/get. Discovery and retrieval do not prove that every skill was projected into every harness. Inspect the selected profile and actual runtime directories; do not assume a universal home/bootstrap installation from this table.

The product loop (your day-to-day)

rig up <rig-name>         # boot or restore the topology
rig ps --nodes            # see what's running
rig whoami --json         # know who you are
rig send <session> "msg"  # talk to a peer
rig capture <session>     # see a peer's terminal
rig transcript <session>  # read a peer's history
rig down <rigId>          # snapshot and stop every agent; check rig ps first, only when asked
rig up <rig-name>         # restore from snapshot

The first command in any new seat is rig whoami --json. It tells you your rig, pod, member, peers, edges, and transcript path. Treat it as ground truth — your CLAUDE.md or AGENTS.md startup overlay can be wrong; whoami is authoritative.