openrig-user

# OpenRig User This is an as-built guide to the shipped `rig` CLI. Use current code and `rig ... --help` as ground truth if anything here ever conflicts with older planning docs. Use the OpenRig builder guidance when changing OpenRig behavior, doctrine, or release posture. ## Coordination trust boundary Coordinate as openly as the trust boundary you actually control allows. Within a set of machines you own that already trust each other — they can reach each other's daemon URLs and the daemon itself requires no authentication — direct `rig send`, `rig capture`, and `rig queue` should just work. Don't invent bearer placeholders, allowlists, trust handshakes, or guest-reach restrictions the environment doesn't require. Do not add or defend a restriction without naming the protected asset, the actual adversary, the blocked attack path, and the concrete consequence. Missing capability is not protection — repair the route, registration, runtime posture, or product defect directly. Arbitrary boundaries create constraint-induced circumvention: under goal pressure, agents build shadow transports, alternate credentials, and weaker proof instead of the direct authorized path. Keep only explicitly stated external or irreversible boundaries — public push / PR / publish, and destruction of canonical data. ## Coordination primitives — when to use which Three coordination surfaces, used together for forward-momentum work. Internalize this on first read — it shapes every turn you take in a rig. ### `rig send <seat> "<text>"` — intra-pod direct messaging / nudges Use when you need to ask a quick question or give a teammate context that does not carry handoff semantics. **NOT for durable work.** NOT for state that must survive across turns. The message lands in the target's pane; there is no durable queue record. The CLI prints `Sent to ...` (and `Verified: yes/no` with `--verify`); read the receipt and move on. Example: ```bash rig send dev-reviewer@example-project "The import report is ready; the durable handoff names its evidence." --verify ``` ### `rig queue create --destination <Y> --tags <...> --body-file <path>` — durable work item Use for any substantive work that must not fall through chat — slice handoffs, guard verdicts, QA results, full-tip reviews, multi-item batches. Survives agent restarts. Tracked in the daemon SQLite schema. Surfaces in Project / queue views + in the destination seat's inbox. Tag with mission / slice / gate / checkpoint so future-you (and any peer) can find it. Give the row a `--summary` (its subject, wherever the row is listed) and the `project:`, `mission:` and `slice:` tags when it is project work. Body discipline: substantive bodies go through **`--body-file <path>`** (or `-` for stdin) — the purpose-built, corruption-safe surface (it kills the backtick-shell-corruption class for multi-line bodies). Do NOT inline a backtick-heavy or multi-line body via `--body`: `rig queue create` body parsing breaks on unescaped backticks and rejects flag-like tokens. Example: ```bash rig queue create \ --destination dev-reviewer@example-project \ --summary "Review the import report: it changes how rows are deduplicated" \ --tags "project:example-project,mission:data-import,slice:import-report" \ --body-file /tmp/import-report-handoff.md ``` ### `rig queue handoff <qitem-id> --to <next> ...` — hot-potato handoff Use when you have completed your turn on a qitem and the work moves to the next owner. **This is forward momentum.** The ball passes to the destination seat; chain-of-record (the prior qitem id) is preserved so the verdict trail is intact; tags carry the selected work context forward. Gate tags describe checks actually selected for that work; they do not require a fixed sequence of roles. Example: ```bash rig queue handoff <qitem-id> \ --to dev-reviewer@example-project \ --summary "Review the import report: it changes how rows are deduplicated" \ --tags "project:example-project,mission:data-import,slice:import-report" \ --body-file /tmp/import-report-handoff.md ``` ### After a queue write — use the response; read back only when it doesn't show what you need A queue write (`create`, `claim`, `update`, `handoff`, `handoff-and-complete`) answers with the row it wrote; a handoff answers with the closed row and its successor. When that answer shows what you need to establish, use it. `create` also prints `Queue create request ID: <id> (not proof of persistence)` on stderr *before* it sends the write, so an interrupted create can be reconciled. That ID names a request, not a row. The row is the `qitemId` on stdout when the command exits 0. A non-zero exit means no row was confirmed, even when stdout carries a `qitemId`: an indeterminate answer repeats the request ID so you can reconcile by it. Don't merge stderr into stdout and keep the first `qitem-…` you find there; a refused create prints its request ID first, too. Read back (`rig queue show <id> --full --json`, or `rig queue transitions <id>`) when the answer doesn't show what you need, for example: - the outcome was INDETERMINATE (a transport failure, or a 502 `remote_queue_write_failed` that may have reached the other host), or the write warned `qitem_body_not_saved` (an existing row came back). Reconcile by the original ID before any retry. A 502 whose `failureClass` is `unknown-host`, `unsupported-transport` or `registry` isn't indeterminate: the daemon refused before contacting any host and wrote nothing (`create` says "No row was created"). `unsupported-transport` means that host entry is SSH-declared. Use the http entry for the same machine from `rig host list`; if there isn't one, add it with that machine's daemon URL (`rig host add --id <id> --transport http --url <daemon-url>`), asking whoever runs that host for the URL; - the output was compact or truncated and the field you need isn't in it (the compact receipt shows `bodyBytes`, not the body, and its footer names what it left out); - you need a transition note, a closure or blocker detail, or a successor that the output you saw omits; - you need evidence from downstream of the write: the recipient's wake (`create --verify` waits for it), or its pickup or claim (a later read); - your team's custody rule asks for a separate read-back. Don't read back only to see again a field the response already showed you. ### §1b doctrine — turn ends by passing the ball **A turn ends by passing the ball, never by going idle holding the slice waiting on a confirmation the selected process does not include.** Follow the current `mission-slice-sop`: proportional owner checks are the default; independent review runs when selected, at the authored work boundary. Role names do not add per-commit guard, QA, or orchestration gates. Do the authorized work, run its selected checks, and return the outcome through durable custody. Valid pauses are only: - A genuine blocker — file a blocked-state qitem against the blocking peer or surface explicitly to orch. - A scope-or-architecture question that requires owner input and changes the plan — surface to orch with the specific decision needed. Implementing already-authorized work is neither of these. Proceed without phantom-gating on an imagined "next prompt" or "operator confirmation" that the process does not require. ### Anti-patterns - Using `rig send` for durable work → use `rig queue create` instead. Sends do not survive restarts and do not show up in queue/project views. - Idle-holding a slice for an imagined "next prompt" or "operator confirmation" that the process does not require → pass the ball via `rig queue handoff` and proceed to the next slice or stand by for the inbound verdict. See the §1b doctrine above. - Inlining a multi-line / backtick-heavy body into `rig queue create --body` → use `--body-file /tmp/<descriptive-name>.txt` (or `-` for stdin), the corruption-safe surface. The body parser does not tolerate raw backticks or flag-like tokens inline. ## Runtime-Gated Coordination Primitives OpenRig v0.3.1 is published publicly as `@openrig/cli@0.3.1` and GitHub Release `v0.3.1`. It includes the bundled PL-004 Coordination Primitive System: Phase A `rig stream` / `rig queue`, Phase B `rig project` / `rig view`, Phase C `rig watchdog`, and Phase D `rig workflow` / `workflow-keepalive`. These are shipped product surfaces in v0.3.x, but they require a compatible v0.3.x daemon and matching SQLite schema at runtime — the installed package version is not automatically the version of the daemon serving you. If a coordination command behaves unexpectedly, confirm the running daemon with `rig whoami --json` and daemon status before assuming a product bug. Default posture: - Treat daemon `rig queue`, `rig stream`, `rig project`, `rig view`, `rig watchdog`, and `rig workflow` as the product coordination surfaces when the active daemon is v0.2.0 or newer. - Use daemon-backed `rig queue` for durable routing. `update / show / list` complement `create / handoff` for inspection and state changes; records in an unrelated store are not evidence that this daemon owns the work. - If a daemon-backed coordination command fails, debug the command/runtime/schema edge directly; do not assume the right workaround is to drop back to a config-layer primitive. - Do not perform daemon stop/start, production DB copy/mutation, release, publish, or other consequence-boundary actions unless the operator/workstream has granted that specific gate. ## First-user workspace setup When booting into a rig on a host where the workspace is unset, gap-ridden, or points at a stale layout, address that before substantive project work. The shipped surface is small + bounded — reach for the canonical commands rather than improvising. ### Detect workspace state at boot Agent-actionable when the daemon is reachable. ```bash rig workspace validate --json rig workspace validate <path> --kind <user|project|knowledge|lab|delivery> --json ``` `rig workspace validate` walks the workspace root and emits a structured frontmatter-gap report against the v0 contract. Exit code is non-zero when gaps exist (operators chain into hygiene fix loops). Default root is the current directory; pass a positional path to validate elsewhere. `--kind` scopes the contract to a specific workspace kind; omit for a kind-agnostic structural check. If `rig workspace validate` reports a non-zero `gapCount` OR the workspace root is unset / unwritable, the workspace needs instantiation — see the next section. ### Instantiate the canonical workspace scaffold Agent-actionable. The operation is additive and preserves existing files. ```bash rig config init-workspace rig config init-workspace --root <path> rig config init-workspace --dry-run --json ``` `rig config init-workspace` scaffolds the canonical workspace layout at the configured `workspace.root` (default `~/.openrig/workspace`): - `missions/` — release missions + slices - `exhaust/` — project-local coordination exhaust - `SPEC.md` — project intent - `project.yaml` — project catalog selections and mission root - `workspace.yaml` — project registration - `.gitignore` — local OpenRig state and exhaust exclusions `--root <path>` targets a non-default root for this call; `--dry-run` reports what would be created without writing. `--force` is deprecated compatibility and still preserves existing files. ### Redirect the workspace root Operator-gated when persistent. Agent-actionable when one-shot via env-var. For a single command: ```bash OPENRIG_WORKSPACE_ROOT=<path> rig <command> ... ``` For a persistent host-level redirect, the operator changes the config file or runs the setter: ```bash rig config set workspace.root <path> ``` ConfigStore precedence: `OPENRIG_WORKSPACE_ROOT` env > config-file `workspace.root` > built-in default `~/.openrig/workspace`. The same precedence governs `OPENRIG_WORKSPACE_SPECS_ROOT` → `workspace.specs_root` (default `<workspace_root>/specs`). Prefer the env-var form for one-shot redirects (transparent to operators); reserve `rig config set` for changes the operator owns. ### Build a workspace from scratch Agent-actionable. Same surface as the canonical scaffold above; the `workspace.root` cascade handles non-existent host paths. ```bash rig config init-workspace --root /path/to/new/workspace ``` The command additively creates any missing canonical entries and preserves every existing one; only a complete six-entry scaffold is a no-op. Run `rig workspace validate /path/to/new/workspace --json` after to confirm the contract holds. ### Create a workflow inside an existing workspace Authoring is operator-or-agent; validation + instantiation are agent-actionable. Workflow spec files live at: ``` <workspace_root>/specs/workflows/<name>.yaml ``` `<workspace_root>` resolves via the ConfigStore precedence named above. There is no `rig workflow create` verb in v0.3.x — the spec YAML is authored directly. Template by hand from the documented schema, or copy a built-in starter from `<openrig install>/dist/builtins/workflow-specs/` and adapt. Once written: ```bash rig workflow validate <workspace_root>/specs/workflows/<name>.yaml --json rig workflow instantiate <workspace_root>/specs/workflows/<name>.yaml \ --root-objective "<one-line objective for the run>" \ --created-by <your-session>@<your-rig> \ --json ``` Both `--root-objective <text>` and `--created-by <session>` are REQUIRED on `instantiate` — omitting either yields a Commander required-option error before the daemon is contacted. `--entry-owner <session>` is an optional override for the entry-step owner; default routing is per the workflow spec. `validate` returns a structured ok/error report; `instantiate` creates a workflow instance + entry-step qitem. Inspect existing surface state with: ```bash rig workflow specs --json # list registered specs (built-in + operator-authored) rig workflow list --json # list active workflow instances rig workflow show <instanceId> --json # inspect one instance rig workflow project <instanceId> # ADVANCE an instance — projects the next-step packet rig workflow continue <instanceId> # read-only inspector of an instance (does NOT advance it) ``` *(Surface note — the current `rig workflow` command group registers **13** subcommands: `validate`, `instantiate`, `project`, `list`, `specs`, `show`, `trace`, `continue`, `run`, `watch`, `route`, `resume`, `status`. There is still no `create` verb — the spec YAML is authored on disk. `project` is the advancing verb (it projects the next-step packet); `continue` is a read-only inspector, NOT an advance — do not conflate them. The 13-verb set and the project-vs-continue semantics are verified against current product main `d37a08ad` (`packages/cli/src/commands/workflow.ts`, 13 registered `.command(...)` entries; the earlier "6-verb surface / continue-advances" claim here was stale). Verify individual subcommand flags with `rig workflow --help`.)* ## Permission policy — pick one at setup (onboarding) OpenRig sets only a **minimal usability floor** on your harness permissions and otherwise stays out of the way — then it ships **recommended policies you opt into**. It never bakes a permission policy for you. On install / onboarding this is a required choice, presented as a top-level pick: - **POLICY MODE** — pick a built-in policy and have it applied: - **Locked** — deny-by-default whitelist; untrusted rigs/work. - **Standard** ⭐ (recommended) — routine development including push is allowed; PR creation, publication, merge/release, force-push and destructive actions ask. - **Open** — allow-by-default; everything except explicitly-destructive, which ask. The built-in definitions ship as read-only policy spec files (Locked / Standard / Open); applying your pick is the job of the **`applying-a-permission-policy`** skill — it translates the chosen spec into your live harness config (Claude `settings.json` / Codex `config.toml`), interactively, showing the diff before it writes. - **YOLO MODE** — done with permissions, just want it to work: OpenRig boots every seat with the harness full-bypass launch flag. No config policy is applied (the bypass overrides it). This is a deterministic OpenRig setting, not a skill. - **No choice = the floor** — the minimal usability baseline (Claude `acceptEdits` / Codex workspace-only / Pi `--no-approve`), one consistent minimum, nothing more. The floor and YOLO are **launch flags** OpenRig sets deterministically; the Locked / Standard / Open policies are **config-file** policies the skill applies (agent-driven, because harness config formats drift). A rig **carries** its chosen policy on its spec and boots with it — see Lifecycle → Bring a rig up. To (re)apply or change a policy, open **`applying-a-permission-policy`**. ## v0.3.x Starter, Workspace, And Plugin Surfaces OpenRig v0.3.0 adds `rig agent-image`, `rig context-pack`, `rig workspace`, and `rig config init-workspace`. *(0.5.0: the `rig context-pack` alias is retired — the store + compose library is the single `rig context` noun; see "Context packs and paced delivery (0.5.0)".)* It also shifts fresh-user starter guidance toward `product-team` for human-directed work and `conveyor` for workflow-oriented work. Treat `demo` as legacy/test content unless a task specifically asks for the old demo spec. *(0.6.6: the built-in teams are `starter` and `factory`, plus the specialist teams `code-review`, `research` and `pm`. `product-team`, `conveyor` and `demo` are gone, and `first-project` is starter's old name. `workshop` is a rig bundle.)* OpenRig v0.3.1 adds public package/source surfaces for Plugin Primitive v0, Claude Auto-Compaction Policy, migration `040_workflow_specs_diagnostic`, Library Explorer finishing, Settings Destination Explorer, Dashboard/For You vellum refresh, storytelling adapter, and action outcome + inline error UX. `rig plugin` is read-only at v0: ```bash rig plugin list rig plugin show <id> rig plugin used-by <id> rig plugin validate <path> ``` There is no `rig plugin install` verb in v0.3.1. Plugin installation remains explicit operator copy/symlink to `$OPENRIG_HOME/plugins/<plugin-id>/`. The v0.3.1 package introduced opt-in Claude auto-compaction policy through `policies.claude_compaction.*` ConfigStore keys. A package version alone says nothing about a running daemon's configuration; inspect the selected instance before relying on a policy or its default. Compatibility checks: - `rig down` accepts a rig name or id. An ambiguous name matching more than one active rig is refused with matching ids; use the intended id. It ends every agent's session and any work in progress, so check `rig ps --nodes --rig <rig>` and that the person asked; `rig up <rig> --existing` restores it. - For queue/view JSON or limit differences, compare the installed command's help, the running daemon version and the actual response. A wrapper mismatch is not by itself a daemon-health failure, and historical workarounds are not current behavior guarantees. - After a startup timeout, inspect status and logs before retrying; a timeout does not establish whether the underlying operation completed. ## Recovery and Resilience (v0.3.4+) v0.3.4's theme is Recovery + Resilience. The surfaces below compose into a single boot-to-running-rig path that survives crashes, hand-resumed sessions, profile-load drift, and partial workspace state without silently fudging status. ### `rig start` — recovery entrypoint `rig start` is the top-level recovery sequencer. It does not invent recovery;