working-with-an-openrig-team · git:20261115.861710b · 2026-11-15 · sha256 8105f89e597f9488

working-with-an-openrig-team git:20261115.861710bA

Immutable. This exact content never changes and is served at /api/v1/blob/8105f89e597f9488.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_mar52qqh6xglfljr/8105f89e597f94883c9de351fb2ccbeb7b5934c9d9945d6c9e3a7d64a6de6c78.json

Then /plugin install working-with-an-openrig-team@markdownregistry-mar52qqh6xglfljr in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: working-with-an-openrig-team
description: >-
  Use when the person runs an OpenRig team of agents on this machine and wants it to do some work, wants to know how
  that work is going, has a question from the team to answer, or wants to read what the team returned. Works through
  the `rig` command in your shell; no MCP server is needed.
---

# Working with an OpenRig team from Claude Code

The person runs a team of agents with OpenRig: each agent has its own terminal, and they keep working after this chat
ends. You aren't one of those terminals. You're the person's front door to the team: you hand it work, follow that
work, bring the team's questions to the person, and bring back what it produced. You do all of it with the `rig`
command in your shell.

## Your address on the team

Every command that writes to the team runs as one address, such as `claude-app@my-team`. Items you create are recorded
as coming from it, and the team's questions about your work come back to it. It's an address the queue takes items for;
nothing is launched for it.

- If the person hasn't chosen one, run `rig ps` to list their teams (rigs), and suggest `claude-app@<rig>`. Use the
  address they agree to.
- Prefix every `rig queue` command with it: `OPENRIG_SESSION_NAME=<address> rig queue ...`. That's how OpenRig knows
  who is acting. Without it, claiming and recording answers are refused.
- `rig` must be on the PATH (`rig --version`). If it fails, `rig` isn't on this shell's PATH: OpenRig may not be
  installed, or may be installed where this shell doesn't look. Ask the person. If it isn't installed, point them to
  https://openrig.dev, and stop until `rig --version` works.

## Find who takes the work

- `rig ps --nodes --rig <rig>` lists the team's seats. Work goes to the lead (a seat named `lead`, `orch` or
  `orchestrator`, or the rig's only seat) unless the person names one. If you can't tell, ask the person which seat.
- Use the seat's full session name from that list, such as `lead.agent@my-team`, as the destination.

## Hand the team work

Write the body for a capable colleague: the goal, why it matters, what done looks like, and where to look. End it with
the reply route, because your address has no terminal and `rig send` can't reach it:

> To ask me anything, create a queue item to `<address>` (`rig queue create --destination <address> ...`), then block
> this item on that new item's id (`rig queue block <this id> --on <question id>`), so my answer wakes you. I check it
> whenever the person talks to me. Don't ask in your own terminal: the person isn't there. A seat's permission prompt
> in this work is their question too: send me its own text and choices, the seat, what it was doing and any
> escalation's id, unless a question about that prompt is already open at my address. Whoever sent the question
> passes on the answer, and no one else does. Capture that seat again first (a changed prompt needs a new answer),
> then `rig send <seat> "<key>" --dangerously-interact --reason 'task <question id>: <their answer>'` with the key the
> prompt shows for their choice (for Escape, `$'\e'` in place of `"<key>"`, never the word). Keep the reason in single
> quotes so the shell runs nothing in their words, and write each `'` in them as `'\''`. A no stays a no. If they gave
> no answer, or their words don't clearly pick one choice
> (a condition the action doesn't plainly meet, say), ask me again before sending anything, and never pick a "don't
> ask again" choice they didn't pick. Check the effect, and never send again while it's unknown. If you hand this item
> on or give this work to another seat, copy this paragraph into the new item. When you finish, put the outcome in
> this item's resolution, with what the latest review found, and any file in its evidence ref.

Write the body to a file first, so quotes and newlines survive the shell.

```sh
OPENRIG_SESSION_NAME=<address> rig queue create --destination <lead session> \
  --summary "<one line>" --body-file <file>
```

- Tell the person the `qitemId` it prints. It's how both of you find this work again.
- If the command times out, check `rig queue show <qitemId>` before trying again. To retry, pass the same id with
  `--id <qitemId>`. Never retry without it: that creates the work twice.

## Follow it

- `rig queue show <qitemId> --full` gives its state, its current owner and how it closed. Its history, including the
  notes the team recorded, is `rig queue transitions <qitemId> --full`.
- When a seat hands the work on, `handedOffTo` names the seat it went to, not the next item, so never pass it to
  `rig queue show`. The next item is the one whose `handedOffFrom` is this item's id. On OpenRig 0.7.12 or later,
  `rig queue show <qitemId> --json` lists it under `successors`. On 0.7.11, find it in
  `rig queue list --destination <that seat> -a -o json`. Follow the chain to the newest item before you report.
- Report what the record says. A claimed item isn't finished work, and a quiet one isn't stuck: say what you saw and
  when it last changed.
- Before you say the work is done, find the newest review of it on the chain and tell the person its outcome. Work a
  review sent back with something to fix isn't done, even if a commit exists: say what the review asked for.
- Nothing wakes this chat when the team asks or finishes. While its work is open, check each time the person talks to
  you, and when they come back.

## The team's questions

- Questions about your work come to your address:
  `OPENRIG_SESSION_NAME=<address> rig queue list --owned --state pending,in-progress`.
- Read each one in full (`rig queue show <qitemId> --full`). Show the person the question, in the team's words where
  the item gives them. Then ask for their answer.
- Record only what the person actually tells you. Claim the item, then close it with exactly what they typed, nothing
  else: no label such as "The person's answer:", no quotation marks, and no notes of your own.

  ```sh
  OPENRIG_SESSION_NAME=<address> rig queue claim <qitemId>
  OPENRIG_SESSION_NAME=<address> rig queue update <qitemId> --state done \
    --closure-reason no-follow-on --resolution "<the person's words>"
  ```

- Then check the work item the question was about. If it's still `blocked` on a gate such as `external:...` rather
  than on the question's id, your answer won't wake its seat. Release it with the person's words:
  `OPENRIG_SESSION_NAME=<address> rig queue resolve <work qitemId> --decision "Answered in <question qitemId>: <the person's words>"`.
- If the person isn't there to answer, leave the item open and tell them it's waiting. Never choose an answer for them.
- If a work item is blocked waiting on the person but no question reached your address, its transitions
  (`rig queue transitions <qitemId> --full`) usually say what it needs. Show the person, and send their answer as a new
  item to the same seat that names the blocked `qitemId`.
- A question can be a seat's permission prompt that the operator or a team seat sent you: show it with the seat, the
  exact action and the choices it offers, and record the person's words the same way. The agent that sent it passes
  their answer to the seat, so don't send that prompt's answer yourself as well.
- Some questions go to a registered person directly, not to your address. Those wait where they already answer the
  team, such as the OpenRig TUI or Slack. You can mention them; answering them isn't yours.

## Read the result

- When the item is `done`, its `resolution` is the answer, and its transitions
  (`rig queue transitions <qitemId> --full`) hold the notes the team recorded.
- If it names an `evidenceRef`, that's the file the team produced. Read it with your file tools, or give the person
  the path.
- To ask for changes, create a new item that names the earlier `qitemId` in its body, so the revision is easy to trace.

## Come back later

- `OPENRIG_SESSION_NAME=<address> rig queue list --mine` lists open items this address sent or owns. Finished ones,
  including questions the person already answered, need `--state done`:
  `rig queue list --destination <address> --state done`. Items outlive conversations, so a new chat with the same
  address reaches the same work.

## The full plugin

This skill uses the shell. OpenRig also has a full plugin for Claude Code, from OpenRig's own marketplace, that adds
OpenRig's MCP server: typed tools instead of shell commands, and your address set once in the plugin's settings. If the
person wants it:

```sh
claude plugin marketplace add mvschwarz/openrig
claude plugin install openrig@openrig-app
```

Then they set the plugin's OpenRig seat (`/plugin`, then configure) and start a new session.

## What this doesn't do

- It adds no panel, and nothing wakes this chat when the team finishes.
- It reaches a team on this machine.
- Anyone using Claude Code on this machine with the same address acts as that address.