@openrig/cli 0.1.12 → 0.3.0

package/daemon/specs/agents/conveyor/planner/startup/context.md

@@ -0,0 +1,12 @@
+# Startup Context
+
+Run `rig whoami --json` before making topology claims. Confirm that your
+session is `plan-planner@conveyor`.
+
+Default workflow role: `planner`.
+
+Receive packets from `intake-lead@conveyor`. Send executable plans to
+`build-builder@conveyor`.
+
+Keep planning outputs concise: objective, assumptions, steps, verification, and
+handoff notes.

package/daemon/specs/agents/conveyor/reviewer/agent.yaml

@@ -0,0 +1,35 @@
+name: conveyor-reviewer
+version: "1.0"
+description: Conveyor reviewer - checks build output, asks for rework, or clears the packet for close
+
+defaults:
+  runtime: codex
+
+imports:
+  - ref: local:../../shared
+
+profiles:
+  default:
+    uses:
+      skills: [openrig-user, review-team, plan-review, systematic-debugging, verification-before-completion]
+      guidance: []
+      subagents: []
+      hooks: []
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+
+resources:
+  guidance:
+    - id: role
+      path: guidance/role.md
+    - id: startup-context
+      path: startup/context.md
+
+startup:
+  files:
+    - path: guidance/role.md
+      delivery_hint: send_text
+      required: true
+    - path: startup/context.md
+      delivery_hint: send_text
+      required: true
+  actions: []

package/daemon/specs/agents/conveyor/reviewer/guidance/role.md

@@ -0,0 +1,29 @@
+# Role: Conveyor Reviewer
+
+You are the review station for the `conveyor` starter rig. Your job is to check
+the builder's output against the plan, surface concrete findings, and either
+send targeted rework back to build or clear the packet for close.
+
+## Skills Loaded
+
+- `openrig-user`
+- `review-team`
+- `plan-review`
+- `systematic-debugging`
+- `verification-before-completion`
+
+## Responsibilities
+
+- Review the plan, the claimed output, and the verification evidence.
+- Lead with blocking findings when behavior is wrong or proof is missing.
+- Keep non-blocking polish separate from correctness.
+- Send rework to `build-builder@conveyor` only when there is a concrete fix.
+- When the packet is ready, hand it to `intake-lead@conveyor` for close with a
+  compact evidence summary.
+
+## Principles
+
+- Review protects the user from false proof.
+- A finding needs a repro, file reference, command result, or observed behavior.
+- Do not nitpick style unless it changes correctness, safety, or maintainability.
+- The goal is clear motion: rework if needed, close when proven.

package/daemon/specs/agents/conveyor/reviewer/startup/context.md

@@ -0,0 +1,10 @@
+# Startup Context
+
+Run `rig whoami --json` before making topology claims. Confirm that your
+session is `review-reviewer@conveyor`.
+
+Default workflow role: `reviewer`.
+
+Receive proof-ready packets from `build-builder@conveyor`. Send targeted rework
+back to build when needed. Send clean packets to `intake-lead@conveyor` for
+closure.

package/daemon/specs/agents/design/product-designer/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       hooks: []
-      runtime_resources: []
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
   guidance:

package/daemon/specs/agents/development/implementer/agent.yaml

@@ -11,11 +11,11 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, development-team, test-driven-development, mental-model-ha, systematic-debugging, verification-before-completion, writing-plans, executing-plans]
+      skills: [using-superpowers, openrig-user, development-team, test-driven-development, systematic-debugging, verification-before-completion, writing-plans, executing-plans]
       guidance: []
       subagents: []
       hooks: []
-      runtime_resources: []
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
   guidance:

package/daemon/specs/agents/development/implementer/guidance/role.md

@@ -9,7 +9,6 @@ Load these packaged skills now before editing:
 - `openrig-user`
 - `development-team`
 - `test-driven-development`
-- `mental-model-ha`
 - `systematic-debugging`
 - `writing-plans`
 - `executing-plans`

package/daemon/specs/agents/development/qa/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       hooks: []
-      runtime_resources: []
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
   guidance:

package/daemon/specs/agents/orchestration/orchestrator/agent.yaml

@@ -11,11 +11,11 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, orchestration-team, mental-model-ha, systematic-debugging, verification-before-completion, writing-plans, executing-plans, brainstorming]
+      skills: [using-superpowers, openrig-user, orchestration-team, systematic-debugging, verification-before-completion, writing-plans, executing-plans, brainstorming]
       guidance: []
       subagents: []
       hooks: []
-      runtime_resources: []
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
   guidance:

package/daemon/specs/agents/orchestration/orchestrator/guidance/role.md

@@ -8,7 +8,6 @@ Load these packaged skills now before doing substantive work:
 - `using-superpowers`
 - `openrig-user`
 - `orchestration-team`
-- `mental-model-ha`
 - `systematic-debugging`
 - `brainstorming`
 - `writing-plans`
@@ -39,8 +38,8 @@ Then run:
 
 ## Communication
 
-- Send messages to agents via tmux or rigged send
-- Read agent output via rigged capture
+- Send messages to agents via tmux or `rig send`
+- Read agent output via `rig capture`
 - Use the chatroom for broadcast announcements
 - Keep the human informed of progress at natural milestones
 

package/daemon/specs/agents/product-management/pm/agent.yaml

@@ -23,6 +23,10 @@ profiles:
         - plan-review
         - exec-summary
         - backlog-capture
+      runtime_resources:
+        - shared:claude-default-settings
+        - shared:claude-default-mcp
+        - shared:codex-default-config
 
 resources:
   guidance:

package/daemon/specs/agents/research/analyst/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       hooks: []
-      runtime_resources: []
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
   guidance:

package/daemon/specs/agents/research/synthesizer/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       hooks: []
-      runtime_resources: []
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
   guidance:

package/daemon/specs/agents/review/independent-reviewer/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       hooks: []
-      runtime_resources: []
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
   guidance:

package/daemon/specs/agents/shared/agent.yaml

@@ -20,8 +20,10 @@ resources:
       path: skills/process/using-superpowers
     - id: openrig-user
       path: skills/core/openrig-user
-    - id: mental-model-ha
-      path: skills/mental-model-ha
+    - id: openrig-operator
+      path: skills/core/openrig-operator
+    - id: claude-compact-in-place
+      path: skills/claude-compact-in-place
     - id: systematic-debugging
       path: skills/process/systematic-debugging
     - id: test-driven-development
@@ -53,5 +55,18 @@ resources:
       path: skills/pm/exec-summary
     - id: backlog-capture
       path: skills/pm/backlog-capture
+  runtime_resources:
+    - id: claude-default-settings
+      path: runtime/claude-settings.fragment.json
+      runtime: claude-code
+      type: claude_settings_fragment
+    - id: claude-default-mcp
+      path: runtime/claude-mcp.fragment.json
+      runtime: claude-code
+      type: claude_mcp_fragment
+    - id: codex-default-config
+      path: runtime/codex-config.fragment.toml
+      runtime: codex
+      type: codex_config_fragment
 
 profiles: {}

package/daemon/specs/agents/shared/runtime/claude-mcp.fragment.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "exa": {
+      "type": "http",
+      "url": "https://mcp.exa.ai/mcp"
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}

package/daemon/specs/agents/shared/runtime/claude-settings.fragment.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "defaultMode": "acceptEdits",
+    "allow": [
+      "Bash(rig:*)"
+    ],
+    "ask": [
+      "Bash(rig up:*)",
+      "Bash(rig down:*)"
+    ]
+  },
+  "enabledMcpjsonServers": [
+    "exa",
+    "context7"
+  ]
+}

package/daemon/specs/agents/shared/runtime/codex-config.fragment.toml

@@ -0,0 +1,5 @@
+[mcp_servers.exa]
+url = "https://mcp.exa.ai/mcp"
+
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp"

package/daemon/specs/agents/shared/skills/claude-compact-in-place/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: claude-compact-in-place
+description: Use when a Claude Code seat in an OpenRig topology needs compact-in-place recovery or marshal verification after compaction.
+---
+
+# Claude Compact In Place
+
+## Purpose
+
+Use this skill when a Claude Code seat keeps the same OpenRig seat/session after `/compact` and must rebuild enough working context to continue safely. This is not succession, not seat handover, and not a generic memory note.
+
+Keep two layers separate:
+
+- **Restore mechanism:** seed from PreCompact output when present, Claude JSONL, touched-files inventory, active queue/session transcript or logs, root docs, and relevant source docs.
+- **Acceptance mechanism:** a marshal or peer audits the rebuilt mental model and gives explicit marshal acceptance before the seat resumes real work.
+
+Do not collapse these layers. A compacted Claude can sound coherent while important files were only injected, grepped, partially read, or not read.
+
+## Runtime Boundary
+
+This protocol is for Claude Code compact-in-place. It is not for Codex by default. Codex context management is different; do not intervene on Codex context percentage unless there are behavioral failure signals.
+
+## Policy Boundary
+
+The 400k token threshold is a policy target for considering preemptive Claude compaction on a 1M-context session. It is not an automatic action. Unattended compaction requires installed and dogfooded hooks, an audit path, and explicit policy or human authorization.
+
+Compact one Claude seat at a time unless a human or policy explicitly confirms spare marshal capacity. Do not compact multiple Claude seats at once as a convenience move.
+
+## Preflight
+
+Before restoring or auditing, recover canonical identity:
+
+```bash
+rig whoami --json
+rig whoami --session <target-seat> --json
+```
+
+The marshal verifies the target identity, seat name, runtime, active queue state, and transcript path before accepting any restore proof.
+
+## Required Evidence
+
+The target Claude should rebuild from concrete evidence, not just the compaction summary:
+
+- Claude JSONL transcript for the session.
+- Generated restore packet or PreCompact output, if present.
+- Touched-files inventory and recent git state.
+- Active queue file, queue packet body, session transcript, or session logs.
+- Rig bootstrap files such as `AGENTS.md`, `CLAUDE.md`, `CULTURE.md`, role guidance, and startup skills.
+- Relevant source docs, as-built docs, codemaps, and workstream trackers.
+
+If a required surface is absent, record it as `NOT-PRESENT`. If it exists but was skipped, record it as `NOT-READ`.
+
+## Required Proof
+
+The target must return an asked-vs-read-depth table before claiming readiness:
+
+| Surface | Source Of Ask | Read Depth | Evidence |
+|---|---|---|---|
+| `rig whoami --json` | marshal | FULL | canonical seat verified |
+| `<path>` | hook/marshal/touched-files | FULL / TARGETED / GREP / INJECTED / NOT-READ / NOT-PRESENT | lines, chunks, command, or reason |
+
+Allowed depth labels:
+
+- `FULL`: the whole surface was read after compaction.
+- `TARGETED`: selected ranges, head/tail, or named sections were read.
+- `GREP`: search excerpts were read.
+- `INJECTED`: content was present from hook, system, summary, or prior context, but not freshly read from disk.
+- `NOT-READ`: the surface exists but was not read.
+- `NOT-PRESENT`: the requested surface does not exist.
+
+The proof must also include canonical identity, JSONL or restore packet path, active queue items, selected touched files, skipped files with rationale, blockers, and exact next action.
+
+## Acceptance Rule
+
+The target may say `awaiting marshal acceptance` or `blocked`. It must not claim `RESTORED`, resume implementation, review, release, architecture, or orchestration work until marshal acceptance is explicit.
+
+Reject any proof that hides read depth, treats injection as a fresh read, omits queue reconciliation, or says "all docs read" without evidence.
+
+Accept only when:
+
+- The seat identity matches the target.
+- JSONL or restore artifacts were used, or their absence is explicitly explained.
+- Important recent-work files are either `FULL` or explicitly waived.
+- `INJECTED`, `TARGETED`, `GREP`, `NOT-READ`, and `NOT-PRESENT` surfaces are named honestly.
+- Active queue/session state is reconciled from durable evidence.
+- The target did not resume real work before marshal acceptance.
+
+## Marshal Follow-Up
+
+Ask these before accepting a clean-sounding proof:
+
+1. Which files were explicitly assigned, and which did you read in full after compaction?
+2. Which files were only injected by hook, summary, system context, or prior context?
+3. Which files were partial reads? Give line ranges or chunks.
+4. Which touched-files entries were important, and which were skipped?
+5. Did any read fail due to size? If yes, did you retry by chunk until complete?
+6. Which queue items changed between checkpoint and now?
+7. What would be unsafe for you to do before additional reads?
+
+If a mandatory surface is partial or injected only, ask for a corrected audit before acceptance.

package/daemon/specs/agents/shared/skills/core/openrig-operator/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openrig-operator
+description: Use when operating or debugging host-side OpenRig runtime issues including daemon reachability, partial identity, unified-exec warnings, stale helper-process cleanup, or when distinguishing harness/process issues from live topology health.
+---
+
+# OpenRig Operator
+
+## Overview
+
+This skill covers host/runtime/operator triage around OpenRig itself.
+Use it when the problem may be the daemon, the shell/runtime surface, or stale helper processes rather than the product workflow you are trying to run.
+
+## When to Use
+
+Use this skill when you see:
+- `rig whoami --json` returning partial identity
+- `rig ps --nodes --json` failing while some other `rig` commands still work
+- `Sent to ...` plus `Verified: no`
+- repeated unified-exec-process warnings
+- suspicion that stale helper processes are accumulating
+
+Do not use this skill for normal product workflow routing, queue handling, or ordinary peer communication. Use `openrig-user` for that.
+
+## First Checks
+
+Start with the minimum truthful operator read:
+
+```bash
+rig whoami --json
+rig daemon status
+rig ps --nodes --json
+```
+
+Interpret them together, not in isolation:
+- partial `whoami` can mean identity is inferable while daemon-backed surfaces are degraded
+- `daemon status` tells you whether the host daemon is up, not whether every seat can reach it cleanly
+- `ps --nodes --json` is the best machine-readable topology check when it works
+
+## Verification Drift Vs Send Failure
+
+For `rig send`:
+- `Sent to ...` + `Verified: yes` = strong positive delivery evidence
+- `Sent to ...` + `Verified: no` = ambiguous delivery, not automatic failure
+- no `Sent to ...` line or a hard error = send failure
+
+When verification is ambiguous, check:
+- direct reply
+- `rig capture <session>`
+- transcript evidence
+- queue/outbox state if the message asked for a durable handoff
+
+Do not blindly retry until you have checked one of those.
+
+## Unified Exec Warning
+
+If you see:
+
+- `Warning: The maximum number of unified exec processes you can keep open is 60 ...`
+
+treat it first as a host/tooling-layer warning, not as automatic proof that the OpenRig topology is unhealthy.
+
+This warning can coexist with a healthy live topology.
+
+## Safe Process Triage
+
+Inspect the process surface first:
+
+```bash
+ps -axo pid,ppid,command | rg 'tmux send-keys|rig queue create|tmux attach|codex|claude'
+```
+
+Think in layers:
+- host/tooling layer: stale one-shot wrappers, session bookkeeping, helper shells
+- topology layer: live `tmux attach` seats, live `codex` / `claude` runtimes, daemon health
+
+Do not diagnose topology failure from tooling-layer warnings alone.
+
+## Safe Cleanup Boundary
+
+Usually safe to reap when clearly orphaned / one-shot:
+- `tmux send-keys ...`
+- short-lived shell wrappers created only to enqueue or send one message
+
+Do not mass-kill:
+- `tmux attach ...`
+- `codex ...`
+- `claude ...`
+- other long-lived daemon/runtime processes
+
+The point is to remove garbage, not workers.
+
+## Common Mistakes
+
+- treating `Verified: no` as if it proves the message did not land
+- treating the unified-exec warning as if it proves the rig is overloaded
+- killing live seats when only stale helper wrappers needed cleanup
+- concluding "daemon down" from one seat's failure without checking host-level daemon status
+
+## Practical Rule
+
+Clean the smallest safe surface that matches the evidence.
+
+If the warning or failure remains after stale-wrapper cleanup, re-check:
+
+```bash
+rig daemon status
+rig ps --nodes --json
+```
+
+If those remain healthy, the residual issue may still be in the host/tool/session layer rather than in OpenRig topology state.

package/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md

@@ -8,6 +8,31 @@ description: Use when operating OpenRig with the `rig` CLI and you need the ship
 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.
+
+## Runtime-Gated Coordination Primitives
+
+OpenRig v0.2.0 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`.
+
+Do not confuse package/source truth with active daemon truth. These commands are shipped product
+surfaces in v0.2.0+, but they need a v0.2.0+ daemon and matching SQLite schema at runtime.
+
+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 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.
+- 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.
+
 ## Core Loop
 
 Most work in OpenRig reduces to this loop:
@@ -123,6 +148,17 @@ rig send <session> "message" --json
 
 Use `--verify` when you want delivery evidence. Use `--force` only when you intentionally want to bypass activity-risk checks.
 
+Observed operator nuance for `--verify`:
+- `Sent to ...` + `Verified: yes` = strong positive delivery evidence.
+- `Sent to ...` + `Verified: no` = ambiguous delivery, not automatic failure. The message may still land; treat this as verification drift until disproven.
+- no `Sent to ...` line or a hard error = send failure.
+
+When you get `Verified: no`, do not immediately retry blindly. First check one of:
+- a direct reply from the target
+- `rig capture <session>`
+- transcript evidence
+- queue/outbox state if the message asked for a durable handoff
+
 ### Capture terminal output
 
 ```bash
@@ -217,6 +253,7 @@ Current behavior notes:
 - `rig up --cwd` is shipped. `rig up --cwd <path>` sends a per-run cwd override for all members in that launch.
 - `local:` `agent_ref` values resolve relative to the rig spec directory, not your shell cwd.
 - if you copy a built-in spec elsewhere, keep its `agents/` tree beside the YAML or rewrite those refs to `path:/absolute/path`
+- `rig specs add <directory>` installs a full spec tree when the directory contains `rig.yaml` or `agent.yaml`.
 
 Legacy/spec-specific surfaces still ship too:
 
@@ -465,7 +502,7 @@ rig agent validate <path> [--json]
 rig specs ls [--kind <kind>] [--json]
 rig specs show <name-or-id> [--json]
 rig specs preview <name-or-id> [--json]
-rig specs add <path> [--json]
+rig specs add <yaml-or-directory> [--json]
 rig specs sync [--json]
 rig specs remove <name-or-id> [--json]
 rig specs rename <name-or-id> <new-name> [--json]
@@ -496,6 +533,37 @@ Current shipped MCP tools:
 - `rig_chatroom_send`
 - `rig_chatroom_watch`
 
+## Troubleshooting and Weird States
+
+When the CLI behaves strangely, use the smallest truthful check first:
+
+```bash
+rig whoami --json
+rig daemon status
+rig ps --nodes --json
+```
+
+Specific operator rules:
+- `Sent to ...` + `Verified: no` is ambiguous delivery, not automatic failure. Check reply, `rig capture`, transcript evidence, or queue/outbox state before retrying.
+- partial `rig whoami --json` can happen when identity is still inferable but the daemon-backed path is degraded.
+- the unified-exec-process warning is a host/tooling-layer signal, not automatic proof that the OpenRig topology is unhealthy.
+
+If you hit the unified-exec warning, inspect for stale one-shot helpers before touching live seats:
+
+```bash
+ps -axo pid,ppid,command | rg 'tmux send-keys|rig queue create|tmux attach|codex|claude'
+```
+
+Safe cleanup target:
+- orphaned one-shot wrappers like `tmux send-keys ...`
+
+Do not mass-kill:
+- `tmux attach ...`
+- `codex ...`
+- `claude ...`
+
+For deeper host/runtime triage, use the companion `openrig-operator` skill if it is available in your seat.
+
 ## JSON and Error Posture
 
 Design assumptions that hold in the shipped CLI: