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.
mvschwarz · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mvschwarz/openrig --skill forming-an-openrig-mental-model技能说明
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 wh |