@openrig/cli 0.2.0 → 0.3.1

package/daemon/assets/plugins/openrig-core/skills/forming-an-openrig-mental-model/SKILL.md

@@ -0,0 +1,305 @@
+---
+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 HA-pair compaction recovery (that's the pair-of-seats coordination pattern; orientation is a solo task) or for specific operational procedures.
+metadata:
+  openrig:
+    stage: factory-approved
+    last_verified: "2026-05-04"
+    distribution_scope: product-bound
+    source_evidence: |
+      Authored 2026-05-02 in response to founder-observed pattern: agents
+      Distinct from HA-pair mental-model preservation (which is a
+      pair-of-seats coordination pattern). This skill serves the legitimate
+      need to form an initial mental model of OpenRig as a system.
+    sibling_skills:
+      - openrig-user
+      - openrig-operator
+      - openrig-architect
+    transfer_test: pending
+---
+
+# 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. | Corpus (planned future system). Today: substrate prose docs. |
+| **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 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)
+
+| 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/` | Your personal/global skills + the OpenRig bootstrap set (openrig-user, openrig-operator, openrig-architect, forming-an-openrig-mental-model, plus the rest of the openrig-core plugin skills). |
+| openrig-core plugin skills | Product built-in skills that ship with OpenRig (installed via the openrig-core plugin). |
+| `~/.openrig/skills/` | Runtime install home for OpenRig-shipped skills. |
+
+The harness only sees the first two. Other locations are 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.
+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.
+
+---
+
+## Going deeper (canonical references)
+
+For real depth, these are the load-bearing canonical docs:
+
+| Reference | What it covers |
+|---|---|
+| `openrig/docs/as-built/architecture.md` | Daemon architecture; system overview; package boundaries |
+| `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 |
+| `https://agentskills.io/specification` | The cross-runtime skill standard |
+
+If your team maintains a host-level topology doc (rig classes, context
+patterns, authoring SOPs), read its rig-authoring section before
+touching YAML for high-stakes rigs.
+
+---
+
+## What this skill is NOT for
+
+- **HA pair compaction recovery.** Forming an initial mental model is a
+  solo orientation task — different from the pair-of-seats coordination
+  pattern that preserves a shared mental model across compactions.
+- **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. |
+| "Any folder I keep skill files in is the canonical runtime path" | No. The harness only loads from `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.agents/skills/`, and the runtime-installed plugin skills. Other folders are authoring or source-of-truth. |
+
+---
+
+## 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.

package/daemon/{specs/agents/shared/skills/rig-architect → assets/plugins/openrig-core/skills/openrig-architect}/SKILL.md

@@ -1,11 +1,23 @@
 ---
-name: rig-architect
-description: Use when designing multi-agent topologies, authoring rig specs and agent specs, creating agent startup content (guidance, skills, culture), or diagnosing why a launched rig's agents aren't behaving as intended. Covers the full authoring lifecycle from user intent to validated, launchable rig.
+name: openrig-architect
+description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (work in the openrig product repo); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
+metadata:
+  openrig:
+    stage: factory-approved
+    last_verified: "2026-05-04"
+    distribution_scope: product-bound
+    source_evidence: |
+      Bootstrap skill — NPM install lands this in personal homes (~/.claude/skills/, ~/.agents/skills/) for users authoring their own rigs.
+    sibling_skills:
+      - openrig-user
+      - openrig-operator
+      - forming-an-openrig-mental-model
+    transfer_test: pending
 ---
 
-# Rig Architect
+# OpenRig Architect
 
-You are now a rig architect. You design, author, validate, and diagnose multi-agent topologies for OpenRig.
+You are now an OpenRig architect. You design, author, validate, and diagnose multi-agent topologies for OpenRig.
 
 Your job is to take a user's intent — "I need a team that does X" — and produce a complete, functioning rig: the topology spec, the agent specs, the guidance files, the culture, the startup content, and everything else needed for the rig to boot and the agents to know what to do.
 
@@ -17,14 +29,14 @@ Load these before starting any design work. The quality of your output depends o
 
 **Required (read all of these):**
 
-1. **`openrig-user` skill** — full OpenRig CLI surface. You must know the operator primitives. If your runtime supports skills, load it by name. Otherwise, look for it at `~/.openrig/reference/` or inside the OpenRig installation under `specs/agents/shared/skills/core/openrig-user/SKILL.md`.
+1. **`openrig-user` skill** — full OpenRig CLI surface. You must know the operator primitives. If your runtime supports skills, load it by name. Otherwise, look for it at `~/.openrig/skills/openrig-user/SKILL.md` (the runtime install dogfood mirror — packaged skills land here) or inside the OpenRig installation under `packages/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md`. The `~/.openrig/reference/` directory holds reference docs (rig-spec.md, agent-spec.md, etc.), NOT skills.
 
 2. **OpenRig reference docs** — these are installed at `~/.openrig/reference/` when the daemon starts. Read all of them:
    - `~/.openrig/reference/rig-spec.md` — canonical RigSpec YAML reference. Every field, validation rule, default.
    - `~/.openrig/reference/agent-spec.md` — canonical AgentSpec YAML reference. Same depth.
    - `~/.openrig/reference/agent-startup-guide.md` — how to think about what goes into agent startup. Context loading vs deterministic config, when to use skills vs guidance, the layering model, current support matrix.
    - `~/.openrig/reference/edge-types.md` — what edges do today vs what they're intended to do.
-   
+
    If `~/.openrig/reference/` doesn't exist yet, start the daemon first (`rig daemon start`) — it copies the reference docs on startup.
 
 **Read as worked examples:**
@@ -35,13 +47,8 @@ Load these before starting any design work. The quality of your output depends o
 
 **Read if present on this host:**
 
-4. **Host-level doctrine** at `~/code/substrate/shared-docs/HOST-TOPOLOGY.md` (or wherever substrate lives on this host). If this file exists, it supersedes the baseline process below for complex or high-stakes rigs. Specifically:
-   - §3 defines the canonical rig classes (kernel, project, ephemeral, infra-build, managed-app). Classify before designing.
-   - §4 defines context-sharing patterns (pods as context domains, pair pattern, HA via mental-model-ha skill + substrate session logs, terminal nodes as common-room, chatroom/substrate/transcripts/Corpus).
-   - **§7 is the canonical 12-step rig-spec authoring SOP for high-stakes rigs — use it instead of the baseline "Design Process" below when the rig is ≥4 members, uses HA, is a managed-app, or will be shared/copied.** The baseline below still applies to small/focused rigs.
-   - §10 contains the host's bootstrap sequence so you know where your new rig fits.
-   - §12 has the naming canon and vocabulary mapping to shipped terms.
-5. **Building-agent-software skill** at `~/code/substrate/shared-docs/skills/building-agent-software/` if present. Design principles for agent-facing tools and surfaces. Relevant when your rig ships a new CLI, service, or managed app.
+4. **Host-level doctrine file** (if your team maintains one — e.g., a HOST-TOPOLOGY doc that defines canonical rig classes, context-sharing patterns, and authoring SOPs for high-stakes rigs). If present, it supersedes the baseline process below for complex or high-stakes rigs (≥4 members, HA, managed-app, or shared/copied). Solo operators and small/focused rigs use the baseline below directly.
+5. **Agent-facing software design principles** if your rig ships a new CLI, service, or managed app that agents will operate. Treat the operating surface as a context-engineering problem: every error message and help text gives the agent information to act on.
 
 **Load as needed:**
 - Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
@@ -104,10 +111,15 @@ Each pod member needs a clear role. The role determines:
 | orchestrator | `local:agents/orchestration/orchestrator` | Rig orchestration lead |
 | implementer | `local:agents/development/implementer` | TDD implementation agent |
 | qa | `local:agents/development/qa` | Quality assurance agent |
-| reviewer | `local:agents/review/reviewer` | Independent code reviewer |
-| design | `local:agents/design` | Product designer |
+| independent-reviewer | `local:agents/review/independent-reviewer` | Independent code reviewer |
+| product-designer | `local:agents/design/product-designer` | Product designer |
+| pm | `local:agents/product-management/pm` | Product manager |
+| analyst | `local:agents/research/analyst` | Research analyst |
+| synthesizer | `local:agents/research/synthesizer` | Research synthesizer |
 | vault-specialist | `local:agents/apps/vault-specialist` | Vault domain specialist |
 
+To verify the current builtin set on this host, run `rig specs ls` and look for entries with type `agent` and source `builtin`.
+
 **Path resolution:** The `local:` prefix means relative to the rig spec file's directory. In shipped starters, these paths resolve against the builtin specs directory inside the OpenRig installation. When authoring a custom rig spec outside the installation, you have two options:
 - **Reference your own agent specs** with `local:` paths relative to your rig spec file
 - **Use `path:` with an absolute path** to reference builtins inside the OpenRig installation (look under the `specs/agents/` directory near where `rig` is installed)
@@ -206,8 +218,9 @@ For rigs that reuse builtin agents, the agents directory is often unnecessary
 4. **Write role guidance** for each custom agent — who they are, what they do
 5. **Write startup context** for agents that need environment grounding
 6. **Validate:** `rig spec validate rig.yaml` and `rig agent validate agents/*/agent.yaml`
-7. **Launch:** `rig up rig.yaml --cwd /path/to/project`
-8. **Verify:** `rig ps --nodes` — all agents ready? Check `rig capture` on each agent.
+7. **Confirm the runtime cwd** — do not assume agents should work from the directory where the rig spec is stored. The spec root controls file resolution; the runtime cwd controls trust, project guidance, permissions, and repo context.
+8. **Launch:** `rig up rig.yaml --cwd /path/to/project`
+9. **Verify:** `rig ps --nodes` — all agents ready? Check `rig capture` on each agent.
 
 ### Validation Is Non-Negotiable
 
@@ -232,7 +245,7 @@ If validation fails, fix the errors. Do not try to launch an invalid spec — it
 
 **Symptom:** Agent tries raw tmux commands instead of `rig send`, doesn't know peer session names.
 **Root cause:** Agent didn't receive `openrig-user` skill or `openrig-start` overlay.
-**Fix:** Ensure the agent's profile `uses.skills` includes `openrig-user`. Verify via `rig ps --nodes` that the agent shows the correct skills count.
+**Fix:** Ensure the agent's profile `uses.skills` includes `openrig-user`. Verify via `rig ps --nodes` that the agent shows expected startup status; check installed skills via direct startup/capture/transcript evidence or the UI node detail (the `rig ps --nodes` projection does not expose installed-resource counts).
 
 ### Agent hits approval prompts on rig commands
 
@@ -252,11 +265,17 @@ If validation fails, fix the errors. Do not try to launch an invalid spec — it
 **Root cause:** Docker Compose issue, health check failure, or port conflict.
 **Fix:** Check `docker compose up` manually with the compose file. Verify health check URLs are correct. Check for port conflicts.
 
+### Agent boots from the wrong project context
+
+**Symptom:** Agent misses expected guidance, trust settings, permissions, or repo context even though the spec validates.
+**Root cause:** The rig spec directory was treated as the agent's runtime cwd by assumption.
+**Fix:** Confirm the intended cwd before launch. The spec can live in a rig/spec shelf while the agent works from the project or hub directory that carries the relevant `AGENTS.md`, `CLAUDE.md`, trust, and permissions. Use member `cwd` or `rig up --cwd` deliberately.
+
 ### Startup content not delivered
 
 **Symptom:** Agent is missing expected guidance/skills.
 **Root cause:** File paths in the spec don't resolve, or `delivery_hint` is wrong.
-**Fix:** Verify file paths are relative to the agent spec directory. Check `delivery_hint` — use `guidance_merge` for pre-boot content, `send_text` for post-boot instructions.
+**Fix:** Verify file paths resolve relative to their owning artifact — AgentSpec resource paths are relative to the agent spec directory; RigSpec startup, culture, compose, cwd, and `local:` agent-ref paths are relative to the rig root. Check `delivery_hint` — use `guidance_merge` for pre-boot content, `send_text` for post-boot instructions.
 
 ### Agent startup delivered but agent doesn't use skills
 

package/daemon/assets/plugins/openrig-core/skills/openrig-operator/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: openrig-operator
+description: |
+  Use when debugging host-side OpenRig runtime issues: daemon reachability, Codex permission or writable-root failures, command approval friction, rate limits/account switches, helper cleanup, or topology health confusion. NOT for ordinary CLI operation (use openrig-user) or for changing OpenRig itself (work in the openrig product repo).
+metadata:
+  openrig:
+    stage: factory-approved
+    last_verified: "2026-05-04"
+    distribution_scope: product-bound
+    source_evidence: |
+      Bootstrap skill — NPM install lands this in personal homes (~/.claude/skills/, ~/.agents/skills/).
+      Companion to openrig-user (daily CLI surface) — this skill is host-side troubleshooting.
+    transfer_test: pending
+    sibling_skills:
+      - openrig-user
+      - openrig-architect
+      - forming-an-openrig-mental-model
+---
+
+# OpenRig Operator
+
+## Overview
+
+This skill covers host/runtime/operator triage around OpenRig itself.
+Use it when the problem may be the daemon, the shell/runtime surface, or stale helper processes rather than the product workflow you are trying to run.
+
+> **CANONICAL SURFACE NOTE (2026-05-11)** — for durable queue routing while doing
+> operator triage, use `rig queue` (daemon-backed SQLite). `rigx queue` is
+> recovery-only fallback; qitems written there are invisible to daemon-backed
+> reads and should not be used for new substantive work.
+
+## When to Use
+
+Use this skill when you see:
+- `rig whoami --json` returning partial identity
+- `rig ps --nodes --json` failing while some other `rig` commands still work
+- `Sent to ...` plus `Verified: no`
+- repeated unified-exec-process warnings
+- suspicion that stale helper processes are accumulating
+- Codex seats hit `Operation not permitted`, command approval friction, or stale writable roots
+- Codex seats report usage-limit/rate-limit or need a ChatGPT account switch
+
+Do not use this skill for normal product workflow routing, queue handling, or ordinary peer communication. Use `openrig-user` for that.
+
+Do not use this skill to decide how to change OpenRig behavior. Changes
+to the OpenRig product (CLI, daemon, UI, specs) happen in the openrig
+product repo — operate that as a normal software project, not via
+this troubleshooting skill.
+
+## First Checks
+
+Start with the minimum truthful operator read:
+
+```bash
+rig whoami --json
+rig daemon status
+rig ps --nodes --json
+```
+
+Interpret them together, not in isolation:
+- partial `whoami` can mean identity is inferable while daemon-backed surfaces are degraded
+- `daemon status` tells you whether the host daemon is up, not whether every seat can reach it cleanly
+- `ps --nodes --json` is the best machine-readable topology check when it works
+
+## Verification Drift Vs Send Failure
+
+For `rig send`:
+- `Sent to ...` + `Verified: yes` = strong positive delivery evidence
+- `Sent to ...` + `Verified: no` = ambiguous delivery, not automatic failure
+- no `Sent to ...` line or a hard error = send failure
+
+When verification is ambiguous, check:
+- direct reply
+- `rig capture <session>`
+- transcript evidence
+- queue/outbox state if the message asked for a durable handoff
+
+Do not blindly retry until you have checked one of those.
+
+## Unified Exec Warning
+
+If you see:
+
+- `Warning: The maximum number of unified exec processes you can keep open is 60 ...`
+
+treat it first as a host/tooling-layer warning, not as automatic proof that the OpenRig topology is unhealthy.
+
+This warning can coexist with a healthy live topology.
+
+## Safe Process Triage
+
+Inspect the process surface first:
+
+```bash
+ps -axo pid,ppid,command | rg 'tmux send-keys|rig queue create|tmux attach|codex|claude'
+```
+
+Think in layers:
+- host/tooling layer: stale one-shot wrappers, session bookkeeping, helper shells
+- topology layer: live `tmux attach` seats, live `codex` / `claude` runtimes, daemon health
+
+Do not diagnose topology failure from tooling-layer warnings alone.
+
+## Safe Cleanup Boundary
+
+Usually safe to reap when clearly orphaned / one-shot:
+- `tmux send-keys ...`
+- short-lived shell wrappers created only to enqueue or send one message
+
+Do not mass-kill:
+- `tmux attach ...`
+- `codex ...`
+- `claude ...`
+- other long-lived daemon/runtime processes
+
+The point is to remove garbage, not workers.
+
+## Terminal Node Escalation
+
+Use a terminal node when evidence shows a seat-level sandbox/profile cannot perform required host work, but another approved operator surface can. This is an explicit operator lane, not a silent permission bypass.
+
+Good fits:
+- Codex/Claude seat cannot access Tart, SSH, tmux, queue directories, or host files needed for a proof
+- a VM/test-proof or current-host-operator task needs real host capability
+- another seat or terminal/sysadmin node has approved access and can return command evidence
+
+Do not use this lane to bypass repo safety, dirty-worktree boundaries, review gates, or destructive-action approval. If the command would stop live rigs, delete data, reset git state, or mutate VM state beyond the accepted plan, require explicit authorization and record it.
+
+Protocol:
+1. Classify the original failure as seat/profile-specific if possible, not product failure.
+2. Write or cite a packet with objective, lane, exact commands, cwd, expected outputs, stop conditions, and artifact path.
+3. Route to an existing sysadmin/infrastructure/terminal node when available; otherwise provision a named terminal node through the topology/config layer instead of using a hidden ad hoc shell.
+4. Terminal node runs only the packeted commands and returns command log, exit codes, cwd/env notes, and artifacts.
+5. Original agent keeps task ownership and proof classification; terminal node supplies host capability.
+
+Field lesson: if tester sees `Operation not permitted` for Tart/SSH while driver or another approved seat can reach the VM, treat it as permission/profile variance and route a terminal-node/operator remediation before changing product code.
+
+## Codex Permission Policy
+
+Use the `security-and-consequence-boundary-policy` skill for the security model.
+OpenRig gates consequence boundaries, not ordinary work inside the intended boundary.
+
+Treat Codex permissions as two independent layers:
+- command approval rules decide which shell commands can run outside the sandbox
+- filesystem writable roots decide which paths a `workspace-write` seat can mutate
+
+Codex `auto_review`, `--full-auto`, and approval-bypass modes are not normal fleet defaults. They
+can burn quota catastrophically and do not widen filesystem roots for an already-running seat. Full
+access scope with `approvals_reviewer = "user"` is the intended Codex default here.
+
+Claude Code auto permissions are different and are the preferred Claude default on this host when
+the consequence-boundary rules still apply.
+
+Current host policy:
+- default profile is `fleet`
+- `fleet` uses `sandbox_mode = "danger-full-access"`, `approval_policy = "on-request"`, `approvals_reviewer = "user"`
+- top-level `[sandbox_workspace_write].writable_roots` intentionally includes `~/code` and tool dotdirs: `.codex`, `.claude`, `.openrig`, `.agents`, `.config`, `.cache`, `.local`, `.docker`, `.npm`, `.nvm`, `.pnpm-store`
+- `permissions.fleet.filesystem` mirrors those writes and denies `.ssh`, `.gnupg`, and project env files
+- `default.rules` broadly allows `rig` and `rigx`; `rigx` is fully permitted for now because it is the fast-moving config-layer overlay
+- `default.rules` still prompts for destructive/publishing surfaces such as `rm`, `mv`, `chmod`, `git push`, PR mutation, `sudo`, process kills, daemon lifecycle, and destructive Docker/Brew/rig commands
+
+## Codex Account / Usage-Limit Refresh
+
+When Codex seats hit usage limits or need a ChatGPT/OpenAI account rotation, use the focused
+`codex-seat-auth-refresh` skill instead of improvising.
+
+Key reminder: host auth can switch while already-running Codex TUIs keep the old account. Refresh
+only the scoped seats, preserve stable seat names, and record auth-seat registry rows sequentially.
+
+Known failure modes this policy prevents:
+- Codex seats assuming a task is impossible when the real issue is stale launch roots
+- agents creating workaround slices/features for what is actually a sandbox/config problem
+- writing load-bearing canon into `state/`, `/tmp`, or a nearby writable folder because the intended durable path was blocked
+- trusting labels like `full access`; verify actual roots and command policy instead
+- changing `config.toml` and expecting already-running seats to pick it up without restart
+
+When `Operation not permitted` appears:
+1. Identify whether it is command approval, filesystem root, macOS privacy, or stale session.
+2. Check effective roots with `codex -p fleet debug prompt-input <probe-name>`.
+3. Verify with a tiny direct write probe in an allowed target and a negative probe in a protected target such as `.ssh`.
+4. If `config.toml` changed, restart one seat and re-run the probes before fleet rollout.
+5. If the target should be durable and is not writable, stop and escalate; do not invent fallback storage.
+
+Field note: as of Codex CLI `0.125.0`, top-level `[sandbox_workspace_write]` was the shape reflected by `debug prompt-input`; profile-scoped writable roots did not show in the effective prompt. Re-test this if Codex changes.
+
+
+## Durable Write Escalation
+
+If the task requires writing load-bearing knowledge or behavior and the intended target is not writable, stop and escalate. Do not silently write to `state/`, `/tmp`, or a nearby writable folder.
+
+Use the intended durable home for the kind of content:
+- `skills/` (e.g. `~/.claude/skills/`, `~/.agents/skills/`, or your team's
+  shared skill folder) for operating rules and refocus behavior
+- Your team's workstream notebook (field notes, lab experiments, mission
+  packets, etc.) for durable observations and PM canon
+- The product repo for shipped OpenRig daemon/CLI/config/spec/test behavior
+
+A runtime mirror under a rig `state/` path may be used only as a temporary live patch, must be labeled as non-canonical, and must have a canonical sync follow-up.
+
+## Common Mistakes
+
+- treating `Verified: no` as if it proves the message did not land
+- treating the unified-exec warning as if it proves the rig is overloaded
+- killing live seats when only stale helper wrappers needed cleanup
+- concluding "daemon down" from one seat's failure without checking host-level daemon status
+- assuming Codex config changes apply to already-running seats without a restart/probe
+- confusing command approval with filesystem write permission
+- calling a VM or product path broken before comparing another approved seat or terminal-node probe
+- assuming a label like `full access` proves effective write/network capability; verify command approval and filesystem writable-root coverage separately
+
+## Practical Rule
+
+Clean the smallest safe surface that matches the evidence.
+
+If the warning or failure remains after stale-wrapper cleanup, re-check:
+
+```bash
+rig daemon status
+rig ps --nodes --json
+```
+
+If those remain healthy, the residual issue may still be in the host/tool/session layer rather than in OpenRig topology state.