forming-an-openrig-mental-model

Source documentation, not instructions for this website. Review permissions before running any commands.

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

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

name: forming-an-openrig-mental-model
description: >-
  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.
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
      - agent-operated-workflows
      - agent-operated-software

---
name: forming-an-openrig-mental-model
description: >-
  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.
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
      - agent-operated-workflows
      - agent-operated-software
---

# 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.**

| 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 |
|---|---|
| `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.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 <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.
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 <peer-session>` to see what they're
   doing.
6. **Check the transcripts** if you're returning to an in-flight workstream
   — `rig transcript <session> --tail 100` for recent context.
7. **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 (canon