version: "1.0.2" name: forming-an-openrig-mental-model description: | Use when an agent is newly oriented to OpenRig and needs to form an accurate mental model of the system fast — what rigs are, how skills load, what the topology shapes mean, what the product loop is. For agents booting into a new seat or returning to OpenRig work after time away. NOT for compaction recovery (use claude-compaction-restore for that) or for specific operational procedures. metadata: cli_surfaces_referenced:

• ask
• capture
• down
• ps
• send
• transcript
• up
• whoami

openrig: stage: factory-approved sibling_skills:

• openrig-user
• openrig-operator
• openrig-builder
• openrig-architect
• openrig-upgrade
• ai-dev-workflows
• software-for-agents

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 the topology pillar. The other two are filled by Corpus (future) and transcripts (now). Most of your work probably touches multiple pillars; knowing which one you're operating in helps you reach for the right artifacts.

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 harness only sees the first two. Other locations are authoring, shipping, and source-of-truth — they reach the harness via projection or NPM install, not directly.

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 tear down
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.

Cultural posture (how to behave)

OpenRig has a few load-bearing cultural principles. Internalize these:

• Honesty over convenience. If resume fails, say so loudly. Don't

silently launch fresh.

• The agent is the power user. The CLI is designed for a 10x staff

engineer at the terminal. You're that user.

• CLI is context engineering. Every error message and help text gives

you information to act on. Read errors carefully.

• Convention over invention. Follow docker/git/kubectl patterns. Agent

muscle memory is real.

• Semi-deterministic is OK. Core contracts are solid; edge cases are

agent-handled.

• Pets, not cattle (today). OpenRig is currently optimized for long-lived

agents that develop instincts over sessions. Cattle support is on the roadmap.

What you should do in your first 10 minutes

If you're booting into a new seat in an OpenRig rig:

1. `rig whoami --json` — recover identity. Know your rig, pod, member,

peers.

1. Read your role guidance — typically delivered via startup files.

guidance/role.md for your specific seat.

1. Read the rig's `CULTURE.md` if it has one — the team operating

manual.

1. Check what skills you have — list .claude/skills/ or

.agents/skills/ in your cwd. Each skill has a frontmatter description that tells you when to reach for it.

1. Check your peers — rig capture <peer-session> to see what they're

doing.

1. Check the transcripts if you're returning to an in-flight workstream

— rig transcript <session> --tail 100 for recent context.

1. Ask `rig ask <rig> "<question>"` if you need cross-cutting evidence

from the rig's transcripts and chat.

You're now oriented enough to start doing useful work.

Permission policy (at setup): OpenRig sets only a minimal usability floor on your harness permissions, then offers recommended policies you opt into (Locked / Standard / Open — or YOLO to bypass). If you're creating or bringing up a rig, that's a choice you make, not something OpenRig decides for you — see openrig-user's "Permission policy — pick one at setup" and the applying-a-permission-policy skill.

Going deeper (canonical references)

For real depth, these are the load-bearing canonical docs:

If you're going to be authoring rigs, read HOST-TOPOLOGY.md §7 (the authoring SOP) before touching YAML.

If you're going to be doing skill work, read the factory-design reference and the operating-the-skill-library skill that lives in substrate/shared-docs/rigs/skill-library/agents/shared/skills/.

What this skill is NOT for

• Compaction recovery. That's claude-compaction-restore. Different

skill, different scenario.

• Operating a specific rig. Specific rigs have their own DESIGN.md and

CULTURE.md. Read those.

• Authoring a new rig. Use the openrig-architect skill for that.
• Day-to-day OpenRig operation. Use openrig-user for that.
• Administering an OpenRig install. Use openrig-operator.

This skill exists to form your initial mental model of OpenRig as a system. Once oriented, reach for the role-specific or task-specific skills that fit your actual work.

Common misorientations to avoid

Disaster-recovery test for this skill

If you read only this skill, can you:

1. State what kind of system OpenRig is, in one sentence?
2. Name the four layers and where you live?
3. Run rig whoami --json and interpret the output?
4. Find your role guidance and your peers?
5. Identify what kind of rig you're in (kernel / project / ephemeral / etc.)?
6. Know where to look for a skill body (which folder)?
7. Know what to read next for depth (the canonical references)?

If yes — you're oriented. If no — tell your peer or the human; missing context is fixable, but only if surfaced.