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.

This is not the config-layer or builder guide. Use the substrate control-plane guidance for rigx and experimental overlays. Use the OpenRig builder guidance when changing OpenRig behavior, doctrine, or release posture.

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 "" — 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:

rig send velocity-guard@openrig-velocity "Heads up — filing per-commit handoff on slice-22 Bug 1 BONUS at tip 6b8673b6." --verify

rig queue create --source --destination --tags --body "" — 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.

Body discipline: substantive bodies go through a temp-file pattern, not inline --body with raw backticks — rig queue create body parsing breaks on unescaped backticks and rejects flag-like tokens.

Example:

rig queue create \
  --source redo-driver-2@openrig-velocity \
  --destination redo-guard-2@openrig-velocity \
  --tags "mission:release-0.3.2,slice:22-rig-up-paper-cut-fix-round,gate:guard,handoff:per-commit,checkpoint:bug-1-bonus" \
  --body "$(cat /tmp/per-commit-body.txt)"

rig queue handoff --to ... — 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 phase boundary forward (e.g. gate:guard → gate:qa).

Example:

rig queue handoff qitem-20260601012431-d78aa805 \
  --to velocity-qa@openrig-velocity \
  --tags "mission:release-0.3.2,slice:22-rig-up-paper-cut-fix-round,gate:qa,handoff:adversarial-dogfood"

§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 process does not include. If the work was authorized, the per-commit guard + adversarial QA + orch heavy-verify are the guardrails — not an operator pre-commit gate. Do the authorized work and pass the ball.

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.

• Hand-coding rigx queue for new work → rig queue is the daemon-backed

canonical surface since the 2026-05-11 host-CLI fix. rigx queue is a recovery-only fallback; qitems written via rigx queue are invisible to daemon-backed reads and break fleet-wide routing discipline.

• Inlining a multi-line / backtick-heavy body into rig queue create --body

→ write the body to /tmp/.txt first, then --body "$(cat /tmp/.txt)". 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.

• CANONICAL SURFACE NOTE (2026-05-11): rig queue (daemon-backed SQLite) became

the canonical queue-routing surface when the 2026-05-11 host-CLI fix landed. The coordination model is now load-bearing at the top of this skill — see "Coordination primitives — when to use which" above for the send / queue / queue-handoff usage model and the §1b doctrine. Auxiliary queue verbs: rig queue update / show / list complement rig queue create / handoff for in-flight inspection and state mutation.

• Use temporary substrate overlays such as rigx queue, rigx stream, rigx project, and

rigx view-proto only where the current OpenRig workstream explicitly says that legacy/control layer is still in use. For queue specifically, rigx queue is recovery-only fallback; qitems written via rigx queue are invisible to daemon-backed reads and break fleet-wide routing discipline.

• 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.

rig workspace validate --json
rig workspace validate  --kind  --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. Idempotent on existing dirs without --force.

rig config init-workspace
rig config init-workspace --root 
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
• artifacts/ — work artifacts produced inside the workspace
• evidence/ — non-dogfood evidence (release evidence, proof packets, etc.)
• progress/ — progress index + per-mission rails
• field-notes/ — operator + agent observations
• specs/ — spec library (rig + agent + workflow YAML lives here)
• dogfood-evidence/ — dogfood proof packets + run artifacts

The scaffold seeds one example mission (getting-started) with multiple slices, and drops a workspace README.md + STEERING.md so a fresh install has browsable Project content. --root targets a non-default root for this call; --dry-run reports what would be created without writing. --force overwrites existing FILES but never deletes directories — operator content is safe.

Redirect the workspace root

Operator-gated when persistent. Agent-actionable when one-shot via env-var.

For a single command:

OPENRIG_WORKSPACE_ROOT= rig  ...

For a persistent host-level redirect, the operator changes the config file or runs the setter:

rig config set workspace.root 

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 /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.

rig config init-workspace --root /path/to/new/workspace

The command creates the root dir if missing (idempotent: existing root + populated subdirs 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:

/specs/workflows/.yaml

` 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 /dist/builtins/workflow-specs/` and adapt. Once written:

rig workflow validate /specs/workflows/.yaml --json

rig workflow instantiate /specs/workflows/.yaml \
  --root-objective "" \
  --created-by @ \
  --json

Both --root-objective and --created-by are REQUIRED on instantiate — omitting either yields a Commander required-option error before the daemon is contacted. --entry-owner 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:

rig workflow specs --json   # list registered specs (built-in + operator-authored)
rig workflow list --json    # list active workflow instances
rig workflow show  --json

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

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:

rig plugin list
rig plugin show 
rig plugin used-by 
rig plugin validate 

There is no rig plugin install verb in v0.3.1. Plugin installation remains explicit operator copy/symlink to $OPENRIG_HOME/plugins//.

Claude auto-compaction policy is opt-in default-off. The v0.3.1 package and this host's active daemon ship policies.claude_compaction.* ConfigStore keys, but no behavior changes unless the operator enables the policy.

Known v0.3.0/v0.3.1 caveats:

• rig down now accepts a rig name or id (symmetric with rig up): the earlier

name-to-404 caveat (the D1 path) is resolved in v0.3.3. An ambiguous name matching more than one active rig is refused with the matching ids; re-run with rig down .

• rig queue / rig view JSON and limit compatibility drift is an open

follow-up from host-adoption proof; treat it as a compatibility caveat, not a daemon-health failure.

• Queue/view JSON/limit drift is now refined as a wrapper-layer routing issue,

not a daemon-layer issue; use human-readable output for affected wrapper commands until v0.3.2.

• First v0.3.1 daemon start hit a plugin-vendor fallback health-probe timeout;

controlled retry succeeded. Manual retry is the current workaround.

• Topology mobile drawer restoration and plugin source-label taxonomy are

v0.3.2 carry-forwards.

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; it composes existing primitives (daemon start + kernel verify + per-rig restore) into one call.

rig start                    # interactive: daemon + kernel + pick-and-restore
rig start --last             # headless: restore all rigs that were last running
rig start --all              # headless: restore all rigs with restore-usable snapshots
rig start --rigs  [...]   # headless: restore only the named rigs
rig start --json             # JSON output for agents

Framing: rig start is the RECOVERY entry point, not the getting-started hero. The fresh-user boot hero remains rig up (typically rig up product-team). Reach for rig start after a host reboot, daemon restart, or any "bring my rigs back" moment.

rig reconcile-session — no-launch adopt of a hand-resumed session

When an operator has externally resumed an agent session (e.g. attached a shell, restarted a runtime by hand) and you want OpenRig to reconcile its lifecycle state without re-launching or sending input, use:

rig reconcile-session 
rig reconcile-session  --rig  --node 
rig reconcile-session  --no-launch
rig reconcile-session  --json

This is a no-launch, no-input adopt. --rig/--node disambiguate when the canonical session name does not uniquely resolve. --no-launch is accepted for explicitness (it is the only mode this command has).

Five-term restore status vocabulary

The shipped restore vocabulary is intentionally honest. It surfaces in rig up / rig restore / rig ps. Use the term that fits — do not collapse to a generic "ok/failed":

• resumed — seat resumed from its original session/snapshot and is live.
• fresh-primed — seat opted into --fresh and was freshly started.
• awaiting-decision — zero-session honest state. There is no resumable

session AND no --fresh opt-in was given; the seat is waiting for an operator decision. Previously fudged as failed; that was wrong — nothing is broken, the system is asking for input.

• attention_required — seat is in a state needing operator attention; not

a transport failure. Clear via rig seat clear-attention once the attention has been resolved.

• failed — the send transport or launch genuinely failed.

This replaces the prior collapsed model (the v0.3.3 four-term vocabulary, in which rebuilt was a term, is retired).

rig seat clear-attention —

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mvschwarz
• Source: mvschwarz/openrig
• License: Apache-2.0
• Homepage: https://openrig.dev

Install and usage instructions live in the source repository linked above.