# Openrig User

> Use when operating OpenRig with the `rig` CLI and you need the shipped command surface for identity, inventory, communication, lifecycle, specs, recovery, or agent-facing JSON output.

- **Type:** Skill
- **Install:** `agentstack add skill-mvschwarz-openrig-openrig-user`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mvschwarz](https://agentstack.voostack.com/s/mvschwarz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mvschwarz](https://github.com/mvschwarz)
- **Source:** https://github.com/mvschwarz/openrig/tree/main/skills/_canonical/core/openrig-user
- **Website:** https://openrig.dev

## Install

```sh
agentstack add skill-mvschwarz-openrig-openrig-user
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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:

```bash
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:

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

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

```bash
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:

```bash
OPENRIG_WORKSPACE_ROOT= rig  ...
```

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

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

```bash
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:

```bash
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:

```bash
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:

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

```bash
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:

```bash
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](https://github.com/mvschwarz)
- **Source:** [mvschwarz/openrig](https://github.com/mvschwarz/openrig)
- **License:** Apache-2.0
- **Homepage:** https://openrig.dev

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mvschwarz-openrig-openrig-user
- Seller: https://agentstack.voostack.com/s/mvschwarz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.