# Forming An Openrig Mental Model > Use when the system around you does not make sense yet: you just booted into a seat and do not know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do not know how skills reach you or where context comes from; or you are about to act on a guess about how OpenRig works. Gives the runtime mental model fast, so you stop guessing. - Skill: `mvschwarz/forming-an-openrig-mental-model` (Agent Skill) - Install (CLI): `npx skillmds@latest add mvschwarz/forming-an-openrig-mental-model` - Raw SKILL.md: https://api.skillmd.com/api/skills/mvschwarz/forming-an-openrig-mental-model/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: mvschwarz (https://skillmd.com/u/mvschwarz) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mvschwarz/forming-an-openrig-mental-model --- # 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 (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.** | Layer | Name | Analogy | What it is | |---|---|---|---| | L0 | Model | CPU | Foundation model — Claude, GPT, Gemini. Stateless tokens-in/tokens-out. | | L1 | Agent Core | Process loop | The reason-and-act cycle: observe, plan, choose, act, repeat. | | L2 | Harness | Container / OS | Tools, memory, lifecycle around the model. Examples: Claude Code, Codex CLI. | | L3 | Rig | Docker Compose / Terraform | Multi-agent topology — what agents exist, how they relate. **OpenRig.** | 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: | Pillar | What it is | Where it lives | |---|---|---| | **Ontology** | What exists. Curated knowledge — facts, code maps, as-built docs. | Shipped public context packs plus project-authored docs; discover with `rig context list`. | | **Epistemology** | Why an agent believes what it believes — reasoning, instincts, decisions. | Transcripts (auto-captured). Session logs. ADRs. | | **Topology** | How agents are connected — pods, edges, communication paths. | OpenRig itself. RigSpec YAML. | 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. --- ## The core vocabulary (read these terms literally) | Term | What it means | |---|---| | **Rig** | A topology of agents working together as a single system. Defined in YAML (RigSpec). The top-level object. | | **Pod** | A bounded context group within a rig. Members of a pod share a context domain and continuity responsibility. Think Kubernetes pod for knowledge. | | **Member / Node** | A single agent (or terminal-node service) within a pod. | | **Edge** | A relationship between members or pods. Kinds: `delegates_to`, `spawned_by`, `can_observe`, `collaborates_with`, `escalates_to`. | | **Topology** | The shape of the rig — how agents are grouped into pods, how edges connect them, how the whole thing fits together. | | **AgentSpec** | A reusable agent blueprint. Defines skills, guidance, hooks, profiles, startup. File: `agent.yaml`. | | **RigSpec** | The topology YAML. Defines pods, members, edges, culture. File: `rig.yaml`. | | **RigBundle** | A portable archive of a RigSpec + vendored AgentSpecs. Move topologies across machines. | | **Agent Starter** | A named, reusable starting context bundle. RigSpec member can declare `starter_ref`. | | **Skill** | A markdown file with frontmatter that an agent loads at boot or on activation. Cross-runtime standard at `agentskills.io`. | | **Profile** | A named configuration within an AgentSpec. The rig spec's member field selects which profile to use. | | **Culture** | Rig-wide constitution — how the team communicates, what "done" means, escalation rules. File: `CULTURE.md`. | | **Snapshot** | Point-in-time capture of a rig — sessions, conversations, state. Restorable. | | **Session name** | `{pod}-{member}@{rig}`. The canonical address for tmux sessions and agent-to-agent messaging. | 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. | Class | Purpose | Lifecycle | |---|---|---| | **kernel** | Host-level supervision, intake, authoring. One per host. | Always on; never auto-hibernated. | | **project** | Long-lived team bound to a codebase. | Stays hot when active; hibernates on explicit request. | | **ephemeral** | Short-lived mission (research, build, migration, spike). | Spawn → work → retire. | | **infra-build** | Subclass of ephemeral whose output becomes permanent infrastructure. | Retired only after output verified in place. | | **managed-app** | Services-backed rig with specialist agents (e.g., a vault specialist, a skill librarian). | Long-lived; accessed by other rigs. | 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) | Home | Purpose | |---|---| | `/.claude/skills/`, `/.agents/skills/` | Where the harness actually loads from. Populated by `rig up`. | | `~/.claude/skills/`, `~/.agents/skills/` | User-level harness skill directories. Inspect the current projection and harness configuration to determine which skills are installed and where they came from. | | `openrig/packages/daemon/{specs/agents/shared/skills,assets/plugins/*/skills}/` | Product skills that ship with OpenRig — the spec pool + the bundled plugin assets (openrig-user, openrig-operator, openrig-architect, forming-an-openrig-mental-model, queue-handoff, claude-compaction-restore, …). | | the skills authoring workspace | Skill authoring source (not runtime-loaded). | 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 # boot or restore the topology rig ps --nodes # see what's running rig whoami --json # know who you are rig send "msg" # talk to a peer rig capture # see a peer's terminal rig transcript # read a peer's history rig down # snapshot and tear down rig up # 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. 2. **Read your role guidance** — typically delivered via startup files. `guidance/role.md` for your specific seat. 3. **Read the rig's `CULTURE.md`** if it has one — the team operating manual. 4. **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. 5. **Check your peers** — `rig capture ` to see what they're doing. 6. **Check the transcripts** if you're returning to an in-flight workstream — `rig transcript --tail 100` for recent context. 7. **Ask `rig ask ""`** 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: | Reference | What it covers | |---|---| | `openrig/docs/as-built/README.md` | As-built map of territory — daemon architecture, system overview, package boundaries; routes to the 13 `architecture/` + 4 `ui/` modules via `codemap.md` | | `openrig/docs/as-built/cli-reference.md` | The full `rig` CLI surface with all subcommands and flags | | `openrig/docs/reference/rig-spec.md` | The RigSpec YAML format — pods, members, edges, all fields | | `openrig/docs/reference/agent-spec.md` | The AgentSpec YAML format — resources, profiles, imports | | `openrig/docs/reference/agent-startup-guide.md` | The 7-layer startup layering model; delivery hints | | the product taxonomy | Canonical vocabulary (read literally) | | `openrig-operating-model` skill | Placement and operating-model guidance — topology and work trees, context altitude | | `openrig-architect` skill | Rig and topology authoring | | `https://agentskills.io/specification` | The cross-runtime skill standard | If you're going to be authoring rigs, use the `openrig-architect` skill before touching YAML. --- ## 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 | Misorientation | Reality | |---|---| | "OpenRig is a chat interface or assistant" | No. OpenRig is a control plane that *manages* your harness sessions. The chat happens inside the harness; OpenRig is around it. | | "Pods are workflow groups" | No. Pods are **context domains** — agents that share working context. If two agents communicate every turn, they should be in one pod; if they communicate rarely, they shouldn't be. | | "Edges represent reporting hierarchy" | No. Edges describe *coordination shape* — who delegates to whom, who observes whom. Avoid hierarchy interpretations; they distort behavior. | | "I should manage Codex's compaction the way I manage Claude's" | No. Codex auto-compacts cleanly; Claude doesn't. Different runtimes, different lifecycles. | | "MEMORY.md auto-loads, so I don't need to read it" | Maybe. Sometimes MEMORY.md auto-loads via system reminders; sometimes not. Don't assume. If your work touches the topics it covers, read it explicitly. | | "Skills inherit from a parent or compose like classes" | No. Skills are flat artifacts; composition happens via AgentSpec `profile.uses.skills` (structural) or soft cross-references in skill bodies (advisory). Not via OO-style inheritance. | | "The substrate `shared-docs/skills/` folder is the canonical runtime path" | No. The harness doesn't read there. It's an authoring workspace. Runtime loads from `.claude/skills/`, `.agents/skills/`, and product built-in. | --- ## 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.