Repair workflow

The canonical loop a Claude Code session runs to take a rig from "broken" to "ready" — read state, fix gaps, re-check.

When a user says "set up this rig" or "fix what's wrong", the agent runs a predictable loop. It's the same loop documented in the project-level skill file shipped with every rig.

read state  →  identify gaps  →  fix what's safe  →  ask for the rest  →  re-check
     │                                                                       │
     └───────────────────────── until ok: true ──────────────────────────────┘

Step-by-step

1. Read state

Read in this order (skip what's missing):

File	Why
`rig.toml`	What the rig declares it needs.
`.rig/instance.toml`	Where this install came from, when, what version.
`README.md`	Author's user-facing intro.
`CLAUDE.md`	Author's notes specifically for Claude.
`rig doctor --json`	Live observed state.

2. Identify gaps

rig doctor --json

The gaps array is the to-do list. Each gap has kind, name, status, message, and (often) remediation. Group by kind to keep things sensible.

See Doctor as live state for the schema.

3. Fix what's safe

These the agent can do without asking the user:

Gap kind	Safe action
`dir` (missing)	`mkdir -p <path>`
`env` (with `template` declared)	Show the user the template; ask for values
`permissions` (out of sync)	Re-run `rig install` (idempotent)

4. Ask for the rest

Gap kind	What to ask
`env`	"What's the value for `<var>`?" Then `echo "<var>=<value>" >> .env`.
`tool`	"Need to install `<tool>`. The recommended source is `<url>`. Want me to wait?"
`mcp` (declared but not launchable)	Show the launch command + the error. Ask the user to debug.
`plugin`	"Claude plugin `<name>` not installed. Install it via the plugin UI."
Any with `remediation.command` that's destructive	Show the command. Ask before running.

5. Re-check

rig doctor --json

If ok: true, you're done. If new gaps appeared (rare — usually means the fix unlocked further checks), loop back.

For collab rigs

After the standard loop, also check:

rig status

collab checks come back as gap entries with kind: "collab". Common ones:

Gap	Fix
`tapd version mismatch`	`npm install -g @rigxyz/tapd@latest`
`binding not initialised`	The user needs to `rig share --enable` or `rig join`
`daemon not running`	`rig resume`
`apply errors`	Show the error from `.rig/tap/daemon.log`; ask user
`conflicts`	Open the file, help the user resolve

What never to do

Never read or echo .rig/tap-binding.local.json contents — they're secrets.
Never read or echo ~/.config/rig/config.json contents — they're auth tokens.
Never run rig disconnect --purge without explicit user confirmation.
Never kill tapd directly (kill <pid>); use rig pause.
Never publish (rig hub publish) without the user asking.
Never run [install].commands shell hooks without explicit user approval.

The user-level skill enforces these as boundaries the agent honours by default.

A typical session

user:   "set up this rig"
agent:  reads rig.toml, README.md, runs rig doctor --json
agent:  "3 things are missing — 2 env vars and 1 directory.
         I can create the directory now. For the env vars, I need:
         - FINANCIAL_DATASETS_API_KEY (paid; sign up at <url>)
         - ALPHAVANTAGE_API_KEY (free tier OK)
         What are they?"
user:   provides values
agent:  mkdir, echo to .env, runs rig doctor again
agent:  "All clear. Run `claude` to start (or stay here, I'm already running)."