@openrig/cli 0.5.10 → 0.5.12

package/daemon/specs/agents/design/product-designer/guidance/role.md

@@ -2,16 +2,18 @@
 
 You are the design side of the product team. Your job is to turn rough product intent into clear user flows, interface structure, and design-system decisions that implementation and QA can execute without guesswork.
 
-## Startup checklist
-
-Load these packaged skills now before giving product direction:
-- `openrig-user`
-- `mission-slice-sop`
-- `development-team`
-- `frontend-design`
-- `verification-before-completion`
-
-Then run `rig whoami --json` and look for the first ambiguity the development pod should not have to guess through.
+## Task-triggered capabilities
+
+Run `rig whoami --json`, resolve the assigned outcome and selected procedure,
+and look for the first ambiguity the development pod should not have to guess through.
+Load skills when the work calls for them:
+- `openrig-user` for command syntax.
+- `mission-slice-sop` for mission/slice operations.
+- `development-team` for coordination under the selected development path.
+- `frontend-design` for interface design.
+- `verification-before-completion` before claiming a verified result.
+
+This list adds no blanket preload or gates beyond the selected task.
 
 ## Responsibilities
 

package/daemon/specs/agents/product-management/pm/guidance/role.md

@@ -3,36 +3,38 @@
 ## Role
 Senior Product Manager. Own the "what" and "why" — never architecture, estimates, or implementation details.
 
-## Skills Loaded
-
-Load these packaged skills now before shaping product work:
-- `openrig-user`
-- `mission-slice-sop`
-- `office-hours`
-- `context-builder`
-- `requirements-writer`
-- `ui-mockup`
-- `plan-review`
-- `exec-summary`
-- `backlog-capture`
+## Task-triggered capabilities
+
+Resolve the assigned outcome and selected procedure. Load `openrig-user` for
+command syntax and `mission-slice-sop` for mission/slice operations. When the
+8-step feature flow below is selected, load each step's named skill as that
+step begins: `backlog-capture`, `office-hours`, `context-builder`,
+`requirements-writer`, `ui-mockup`, `plan-review`, and `exec-summary`.
+Keep that selected flow and its SPEC contract; this list adds no blanket
+preload or feature-flow gate to other assignments.
 
 ## 8-Step Feature Flow
 
 1. **Capture** — run `backlog-capture` and record the idea in `idea_backlog.md`.
 2. **Validate** — run `office-hours` and produce `validation.md` with a `GO`, `REFINE`, or `PAUSE` verdict.
 3. **Context** — run `context-builder` and produce `background.md` using `validation.md` as the starting point.
-4. **Require** — run `requirements-writer` and produce `requirements.md` using `validation.md` and `background.md`.
+4. **Require** — run `requirements-writer` and produce `SPEC.md` using `validation.md` and `background.md`.
 5. **Mockup** — run `ui-mockup` and produce `supporting/mockup-ascii.md` plus one or more `mockup-*.html` artifacts.
 6. **Review** — run `plan-review` and record issues or revisions before handoff.
 7. **Summarize** — run `exec-summary` and produce `executive-summary.md` from the full artifact set.
 8. **Handoff** — prepare the branch/ticket handoff only after the earlier artifacts are coherent.
 
-Each step's output feeds the next. `validation.md` is the foundation for the rest of the feature packet.
+Each step's output feeds the next. The feature folder below is the selected
+slice directory; `SPEC.md` is its single requirements authority.
+`validation.md`, `background.md`, mockups and the executive summary are supporting
+artifacts. For legacy `requirements.md`, preserve it as input/history and
+reconcile its requirements into `SPEC.md` before continuing this flow; do not
+maintain two competing contracts.
 
 ## Working Norms
 
 1. **Research before you build** — every feature needs context (competitive, regulatory, customer) before requirements are finalized.
-2. **Requirements are literal** — AI agents treat requirements.md as instructions. Be precise. No aspirational content.
+2. **Requirements are literal** — AI agents treat SPEC.md as instructions. Be precise. No aspirational content.
 3. **Stay in your lane** — PM writes requirements, researcher gathers context, coder builds prototypes. Escalate when you hit a boundary.
 4. **Write things down** — every step should leave artifacts in the feature folder. Nothing important lives only in conversation.
 
@@ -42,7 +44,7 @@ Each step's output feeds the next. `validation.md` is the foundation for the res
 {feature}/
 ├── validation.md
 ├── background.md
-├── requirements.md
+├── SPEC.md
 ├── executive-summary.md
 └── supporting/
     ├── mockup-ascii.md
@@ -52,5 +54,5 @@ Each step's output feeds the next. `validation.md` is the foundation for the res
 ## Key Outputs
 - validation.md — GO/REFINE/PAUSE verdict on feature ideas
 - background.md — synthesized context for a feature
-- requirements.md — structured acceptance criteria and business rules
+- SPEC.md — structured acceptance criteria and business rules
 - executive-summary.md — single document orienting sales, leadership, and engineering

package/daemon/specs/agents/shared/skills/core/agent-starters/SKILL.md

@@ -23,9 +23,9 @@ A named, reusable per-seat starting point. Composes an agent role, startup
 context, optional native session source, and provenance into something a
 user or rig can choose when creating, refreshing, or packaging a seat.
 
-"Agent image" is the analogy. **Agent Starter is the cleaner product
-noun.** This is NOT a VM image — it is a managed starting point for an
-agent seat, with provenance you can inspect.
+This registry-backed startup context is distinct from the `rig agent-image`
+surface and from a VM image. See the current behavior below before treating
+optional session provenance as an executable native session source.
 
 ## Use this when
 
@@ -49,7 +49,7 @@ Capture the seat as it naturally is at a functional, proven point. Don't pad it
 
 Never compact, summarize, or shrink a seat in order to make or "lean" a starter. There is nothing valuable in "smaller," and compaction is lossy — you would trade away the exact capability the starter exists to preserve. (Compaction is a separate last-resort step for a seat genuinely near its context limit, with its own before/after plan — never part of capturing a starter.)
 
-## State model — 6 states
+## Authoring lifecycle — 6 conceptual states
 
 1. **Captured** — a useful seat/session/context pattern is identified.
 2. **Named** — it becomes an Agent Starter with stable id and owner.
@@ -66,30 +66,32 @@ Never compact, summarize, or shrink a seat in order to make or "lean" a starter.
 4. **Secret leakage** — starter packages or displays provider auth material. **Refuse.** Refer to session sources and context, never copy credentials.
 5. **Runtime mismatch** — starter used with unsupported runtime. **Refuse with a clear error.**
 
-## Manifest shape (v0+v1 shipped)
+## Registry entry and current behavior
+
+Save one entry as `<registry-root>/reviewer-v1.yaml`. The resolver selects an
+explicit root or `OPENRIG_AGENT_STARTER_ROOT`; absent those, it checks the home
+registry `~/.openrig/agent-starters` and a configured fallback.
 
 ```yaml
-agent_starters:
-  - id: velocity-reviewer-v1
-    runtime: claude-code
-    agent_ref: local:reviewer
-    context_refs:
-      - doctrine:advisor-orchestrator-mode-judgment
-      - convention:workstream-continuity
-    session_source:
-      mode: fork
-      ref:
-        kind: native_id
-        value: "<prior-native-session-id>"
+starter_id: reviewer-v1
+role: Review the assigned change against its stated outcome.
+context: Read the current task and the source needed to judge it.
 ```
 
+The current resolver checks the entry shape and credential boundary, then
+delivers this YAML itself as one required `guidance_merge` startup file on a
+fresh start. It does not interpret arbitrary context refs, load a native
+conversation from this example, or seal an image. A RigSpec member combining
+`starter_ref` with `session_source.mode: fork` is currently rejected; use a
+separate supported session-source path when native continuity is the outcome.
+
 Member usage:
 
 ```yaml
 members:
   - id: reviewer
     starter_ref:
-      name: velocity-reviewer-v1
+      name: reviewer-v1
 ```
 
 When a starter points at a primed session produced from a Composable
@@ -113,7 +115,7 @@ Priming Pack, record:
 
 ## Dependencies on other primitives
 
-- **Firm**: `session-source-fork` — native conversation-source continuity for fork-based starters
+- **Separate path**: `session-source-fork` — native conversation-source continuity; currently not composable with `starter_ref`
 - **Firm**: `specification-system` — declarative starter and member references
 - **Soft**: `rig-bundles-and-shareable-artifacts` — shareable starter packaging
 - **Soft**: `context-engineering-and-retrieval` — richer declarative context assembly

package/daemon/specs/agents/shared/skills/core/agent-startup-and-context-ingestion/SKILL.md

@@ -24,8 +24,7 @@ metadata:
 
 How an agent becomes useful after launch: **AGENTS.md overlays, role
 files, skills, rig specs, workflow specs, startup checklists, refocus
-messages**, and any future "rig context" command or skill-librarian
-surface.
+messages**, and the current `rig context` retrieval and profile surface.
 
 It is the current concrete startup path inside the broader
 context-engineering-and-retrieval primitive. Startup gets a seat into
@@ -91,14 +90,16 @@ reentry case, distinct from reusable Agent Starters / priming packs):
 
 ## Memory surfaces consumed at startup
 
-Per the externalized-memory-surfaces convention's 13-row inventory:
+Inventory the selected startup inputs: AGENTS/role/CULTURE overlays, replay
+context, and any declared restore packet or starter. Record where each comes
+from, whether it is current, and why this task needs it. An available skill or
+old packet does not select the work.
 
-- **Row 7** — AGENTS/role/CULTURE/startup overlays (primary)
-- **Row 3** — startup replay context (primary)
-- **Row 12** — restore/reentry packets and Agent Starters (cross-runtime startup path)
-
-The umbrella's authority-rank + permission-posture columns govern which
-surfaces a startup ingestion path can write vs only read.
+Use the task-scoped startup path above to resolve current authority. Permission
+to read an input is not permission to rewrite its source; writes follow the
+active project/rig policy and assignment. Load
+`skills/openrig-operating-model/SKILL.md` with `rig context get` when deciding
+where durable context belongs.
 
 ## Startup files vs skills (the distinction)
 
@@ -123,5 +124,5 @@ culture / pod / member / operator) handles the layering.
 - `session-compaction-and-restore` skill — restore-time startup ingestion
 - `agent-starters` skill — reusable starter manifests that compose startup context
 - `composable-priming-packs` skill — manifests that produce primed sessions
-- `externalized-memory-surfaces` skill — umbrella convention for memory surfaces this primitive consumes
+- `openrig-operating-model` skill — placement and authority of durable context
 - `openrig/docs/reference/agent-startup-guide.md` (product reference doc; not a skill) — the 7-layer additive startup model + delivery hints

package/daemon/specs/agents/shared/skills/core/cross-host-rig-commands/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: cross-host-rig-commands
-description: Use when issuing `rig` commands against a remote host via `--host <id>` flag (single-hop SSH to a host declared in `~/.openrig/hosts.yaml`). Covers the 4 structured failure modes (ssh-unreachable / permission-gate / remote-daemon-unreachable / remote-command-failed), the `--verify` honest pass-through (SSH success is NOT verify success), and the host-registry shape. v0 supports `rig send / capture / ps / whoami --host <id>`.
+description: Use when addressing a registered remote OpenRig host, choosing its transport, or interpreting a cross-host result.
 metadata:
   cli_surfaces_referenced:
     - capture
     - daemon start
     - host list
-    - host show
+    - host add
+    - host doctor
     - ps
     - send
     - whoami
@@ -22,167 +23,102 @@ metadata:
       - extension-and-user-workspace
 ---
 
-# Cross-Host Rig Commands
+# Cross-host rig commands
 
-A first-class OpenRig surface for issuing `rig` commands against a
-remote host via single-hop SSH. v0 productizes the existing SSH-envelope
-operator pattern (`ssh <host> rig <cmd>`) with declared host identity,
-explicit cross-host invocation path, preserved `--verify` semantics, and
-4 named failure modes.
+Use a registered host address and the entry's declared transport. SSH entries
+run a remote CLI through a single-hop shell; HTTP entries use the remote daemon.
+These paths have different prerequisites and command coverage. Check the exact
+command's help and the target installation before a consequential operation.
 
-The live host registry may contain SSH or HTTP read-through/tunnel entries.
-Use each registry entry as ground truth for transport shape. HTTP entries
-require `url` plus exactly one of `bearer_file` or `bearer_env`.
+## Choose and inspect the destination
 
-**v0 is CLI-side shell-out only — `packages/daemon/` is NOT touched.**
-The remote host has its own managed `rig` available on `$PATH`.
-
-## Use this when
-
-- Driving a Tart VM from the host (the immediate cross-host consumer)
-- Operating Mac host A against Mac host B
-- Reading remote state via `rig ps --host` / `rig whoami --host`
-- Sending or capturing on a remote rig session (`rig send/capture --host <id>`)
-- Authoring a `~/.openrig/hosts.yaml` registry entry
-
-## Don't use this when
-
-- The target is local. Don't pass `--host` for local commands.
-- You need multi-hop SSH (host A → host B → host C). v0 is single-hop only.
-- You want reverse direction (remote initiates back to local). v0 is originator-pull only.
-- Cross-host **seat handover** (moving a durable owned seat across hosts) — deferred to higher-level primitives. (Cross-host **queue writes**, by contrast, now ship — see "Cross-host queue writes" below.)
-- The transport isn't SSH. v0 supports `transport: ssh` only.
-
-## Cross-host queue writes (updated 2026-07-21 vs main d37a08ad)
-
-Cross-host **queue writes** are no longer deferred — they ship — but the rule
-differs from the interactive verbs (`send`/`capture`/`ps`/`whoami`):
-
-- **Queue writes are EXPLICIT-only.** Address the target host explicitly with
-  `--host <id>` or the `member@rig@<host>` form. A queue write **never** follows a
-  persisted host selection.
-- **`host select` stickiness does NOT apply to queue.** `host select` affects the
-  `resolveEffectiveHost` verbs (`send`/`capture`/`ps`/`whoami`) — those follow the
-  selected host — but a queue write ignores it and requires explicit addressing.
-- **Host address parsing differs** between the interactive verbs and the queue
-  verbs; do not assume the interactive form carries over. When unsure, address the
-  host explicitly.
-
-## Host registry shape (`~/.openrig/hosts.yaml`)
-
-Host ids must be non-empty and unique. Choose stable, operator-meaningful ids
-that describe the destination without depending on transient network details.
+`rig host list` shows registered hosts. `rig host add --help` describes registry
+writes; `rig host doctor --help` describes reachability checks. Inspect the
+configured OpenRig home rather than assuming the default `~/.openrig/hosts.yaml`.
+Registry changes affect later routing, so make them within the requested scope.
 
 ```yaml
 hosts:
-  - id: a-test-vm
-    transport: ssh                       # v0 supports "ssh" only
-    target: a-test-vm.local         # DNS name, SSH config alias, or IP
-    user: example-user                   # optional
-    notes: "Tart VM"                     # optional
-  - id: laptop-b
+  - id: test-vm
     transport: ssh
-    target: laptop-b.tail-scale-net
+    target: test-vm.local
     user: example-user
+  - id: remote-dev
+    transport: http
+    url: http://remote-dev.example:7433
+    bearer_env: REMOTE_RIG_TOKEN
 ```
 
-Validation rules:
+The registry requires a hosts array, unique non-empty ids and a supported
+transport. SSH needs a non-empty target; user and notes are optional. HTTP needs
+a URL and accepts at most one of bearer_env or bearer_file. Omitting both is
+valid for a tokenless target. A configured but unavailable bearer is a permission
+failure, not anonymous fallback. Host ids also have reserved-name validation;
+use the actual validator's error rather than inventing an alias that collides.
 
-- `hosts` required, non-null array
-- Each entry: `id` required (non-empty, unique), `transport` required (`ssh` only), `target` required
-- `user` and `notes` optional
-- Operator-managed file; v0 does NOT include any sub-command to add/remove/list hosts (operators edit YAML directly)
-- Missing or invalid file returns a clear error pointing at the canonical path
-
-## CLI surface (v0 shipped)
+## Address the intended operation
 
 ```bash
-rig send <session> "msg" --host <id> --verify
-rig capture <session> --host <id>
-rig ps --host <id> [--nodes] [...]
-rig whoami --host <id>
+rig send dev-worker@example-rig "check the assigned result" --host remote-dev --verify
+rig capture dev-worker@example-rig --host remote-dev
+rig ps --host remote-dev --nodes --json
+rig whoami --host remote-dev
 ```
 
-Forwards every shaping flag (`--nodes`, `--full`, `--limit`, `--fields`,
-`--summary`, `--filter`, `--json`) to the remote `rig` invocation. The
-remote rig's output is verbatim passthrough on success.
-
-## The 4 structured failure modes (load-bearing API contract)
-
-The CLI distinguishes 4 failure modes; operators get an actionable error
-per mode; JSON output preserves the `failedStep` enum:
-
-| Mode | Cause | Action |
-|---|---|---|
-| `ssh-unreachable` | SSH itself failed (connection refused, host key mismatch, DNS failure, timeout) | Verify SSH access and the registry entry |
-| `permission-gate` | SSH hit auth/permission gate (Permission denied, Keychain) | Error includes hint to keychain-over-SSH field note (L4-3 D6) |
-| `remote-daemon-unreachable` | SSH succeeded but remote `rig` reported the remote daemon was not reachable | `ssh <target> rig daemon start` |
-| `remote-command-failed` | SSH succeeded but remote `rig` exited non-zero for some other reason; remote stderr is surfaced | Read remote stderr; debug remote command |
-
-Each is distinct and routable. Don't conflate them.
-
-## `--verify` honest pass-through (load-bearing)
-
-`--verify` against a remote target must:
-
-- **Propagate** the verification request to the remote daemon (or remote `rig` invocation that talks to it)
-- **Bring back a structured verification result** (true/false + reason if false), NOT just SSH exit code 0
-- **Distinguish "SSH succeeded but verify returned false" from "SSH itself failed"** — these are different operator actions
-
-**SSH success is NOT verify success.** The remote rig is authoritative
-on `--verify`; its `Verified: yes/no` line is surfaced verbatim. Verified
-at 3 layers (executor unit, command integration, source impl).
-
-## Hard boundaries (do-not list)
-
-- **Do NOT collapse `--verify` honest result into SSH exit code.** Operators and agents rely on the distinction.
-- **Do NOT silently retry SSH failures inside the primitive.** Surface them; let the caller decide.
-- **Do NOT introduce non-SSH transports in v0.** Goal is productizing the existing shipped pattern, not replacing it.
-- **Do NOT touch host-side daemon code as part of v0.** Cross-host shape is on the originator side.
-
-## Cross-host annotation
-
-Every cross-host invocation is observable as cross-host:
-
-- **Operator output**: `[via host=<id> (<target>)]` annotation
-- **JSON output**: `cross_host: { host, target }` field
-
-Annotation is PRESENT when `--host` is set and ABSENT otherwise
-(compat regression).
-
-## Currently shipped (v0) vs deferred
-
-Shipped at openrig `cdce3a6` (2026-04-30):
-- `--host <id>` flag on `rig send / capture / ps / whoami` (initial 2 commands; promoted to 4 at `6b7043a` same day)
-- Read-only host registry validation
-- Single-hop SSH executor with 4-mode `failedStep` enum
-- `--verify` honest pass-through
-- Cross-host annotation (operator + JSON)
-- Daemon untouched
-
-Deferred:
-- Tier 2 real-runtime cross-host proof (disposable Tart VM cycle)
-- `rig host list / show` read-only sub-namespace (only if host count grows past comfortable manual editing)
-- Non-SSH transports
-- Multi-hop SSH
-- Reverse direction (remote initiates)
-- Connection pooling/caching
+These coordination commands select SSH or HTTP from the registry entry. They
+do not silently try another transport when one fails. A host-qualified target
+can be convenient, but confirm its parsing and any persisted host selection
+with the particular command. Explicit --host is preferable for consequential
+cross-host work.
+
+Queue destinations use explicit --host or a supported host-qualified destination;
+queue writes do not follow persisted host selection. The CLI separates the host
+from the canonical seat in the routing envelope. Different queue subcommands
+have different flags: check their help instead of copying a flag from send.
+A local success message alone does not establish remote persistence or pickup.
+
+## Read failures at the layer that failed
+
+| Signal | What to inspect |
+|---|---|
+| registry-load-failed / unknown-host | Registry path, entry and exact destination |
+| ssh-unreachable | SSH connection, target and transport diagnostics |
+| permission-gate | The configured SSH or HTTP credentials and target policy |
+| remote-daemon-unreachable | Target listener and actual running daemon identity |
+| remote-command-not-found | Remote CLI installation and executable lookup |
+| remote-command-failed | The remote operation's own status and error |
+
+The exact result taxonomy depends on the path. HTTP failures expose the remote
+status/error; SSH distinguishes the shell transport from the remote command.
+Do not start or replace a remote daemon merely because a diagnostic suggests it;
+first establish the target's state and the authority for that lifecycle action.
+A timed-out write may have reached its destination. Reconcile its durable effect
+before retrying.
+
+## Verification and attribution
+
+Transport success is not delivery verification or agent consumption. SSH forwards
+--verify and returns the remote CLI result. HTTP preserves the remote transport
+verdict and explicitly reports that the local pane-effect check did not run
+cross-host. Inspect that result and the destination effect required by the task;
+never replace it with “SSH exited zero” or “HTTP returned successfully.”
+
+Cross-host output names the host/target; JSON envelopes carry cross_host metadata.
+The precise envelope differs by command and transport. Preserve the underlying
+remote result when passing evidence onward.
+
+A target's host suffix selects a destination; a sender's origin identifies where
+a reply belongs. Use the rendered reply address and verify its host mapping.
+Current send derives the sender from the executing seat context, not a caller's
+--from assertion. It adds origin-host identity at cross-host forwarding; do not
+assume local sends have the same suffix. Unknown identity remains unknown.
+
+This guide describes the implemented command paths, not proof of a live remote
+journey on your installation. Forks, handovers and other lifecycle compositions
+need their own supported command and scoped authority; reading remote state
+does not authorize them.
 
 ## See also
 
-- `seat-continuity-and-handover` skill — host-aware seat-binding semantics for cross-host handover (deferred to v1 on top of this v0 baseline)
-- `openrig-user` skill — the local CLI surface that cross-host commands wrap
-
-## Sender identity carries the ORIGIN host (51-09, 2026-08-06)
-
-The `@host` sugar on a TARGET is **addressing** (`member@rig@<host>` routes to that host).
-The **From:** sender now ALWAYS carries the **origin** host: a cross-host (and local) message's
-signature is **`member@rig@<originHost>`** — the sender reflects the host it was sent from, so a
-received signature names the ORIGIN, and the `↩ Reply:` hint round-trips **verbatim** back to that
-origin (never a same-named local lookalike). This is the always-suffix rule — deterministic and
-collision-proof: a signature means one thing to every receiver. (This SUPERSEDES the pre-51-09
-asymmetry — "the sender carries no `@host` suffix" — that pm@your-rig flagged as a core gap on
-2026-07-25; 51-09 closed it.) Per BR-1 the host is NEVER folded into the session string on the
-wire: the CLI edge renders/strips it, the daemon refuses an in-band 3-part destination with a
-teaching hint, and a stale 2-part same-name destination is closed by `--host` + that teaching —
-not by any in-string magic.
+- openrig-user — exact command reference
+- seat-continuity-and-handover — stable seat and occupant outcomes

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

@@ -21,8 +21,7 @@ metadata:
       - openrig-upgrade
       - forming-an-openrig-mental-model
       - ai-dev-workflows
-    notes: |
-      Description was already correct (starts with "Use when..."; lists specific authoring triggers including the diagnose-bad-rig case). Final sentence ("Covers the full authoring lifecycle from user intent to validated, launchable rig.") is workflow-summary-adjacent; on next iteration, consider trimming. For factory-adoption cycle, kept as-is to match product source-of-truth.
+
 ---
 
 # OpenRig Architect
@@ -33,43 +32,33 @@ Your job is to take a user's intent — "I need a team that does X" — and prod
 
 You also diagnose problems when a rig launches but agents aren't behaving as intended.
 
-## Before You Design: Required Reading
-
-Load these before starting any design work. The quality of your output depends on the depth of knowledge you bring.
-
-**Required (read all of these):**
-
-1. **`openrig-user` skill** — full OpenRig CLI surface. You must know the operator primitives. If your runtime supports skills, load it by name. Otherwise, look for it at `~/.openrig/skills/openrig-user/SKILL.md` (the runtime install dogfood mirror — packaged skills land here) or inside the OpenRig installation under `packages/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md`. The `~/.openrig/reference/` directory holds reference docs (rig-spec.md, agent-spec.md, etc.), NOT skills.
-
-2. **OpenRig reference docs** — these are installed at `~/.openrig/reference/` when the daemon starts. Read all of them:
-   - `~/.openrig/reference/rig-spec.md` — canonical RigSpec YAML reference. Every field, validation rule, default.
-   - `~/.openrig/reference/agent-spec.md` — canonical AgentSpec YAML reference. Same depth.
-   - `~/.openrig/reference/agent-startup-guide.md` — how to think about what goes into agent startup. Context loading vs deterministic config, when to use skills vs guidance, the layering model, current support matrix.
-   - `~/.openrig/reference/edge-types.md` — what edges do today vs what they're intended to do.
-
-   If `~/.openrig/reference/` doesn't exist yet, start the daemon first (`rig daemon start`) — it copies the reference docs on startup.
-
-**Read as worked examples:**
-
-3. **Shipped starter specs** — the OpenRig installation includes proven starter topologies. Find them by running `rig specs ls`. Read the ones that are relevant to your design task, especially:
-   - `implementation-pair` — the smallest effective development unit (2 agents)
-   - `secrets-manager` — a managed-app rig with services integration and a specialist agent
-
-**Read if present on this host:**
-
-4. **Host-level doctrine** in your host's topology doc, if it keeps one. If this file exists, it supersedes the baseline process below for complex or high-stakes rigs. Specifically:
-   - §3 defines the canonical rig classes (kernel, project, ephemeral, infra-build, managed-app). Classify before designing.
-   - §4 defines context-sharing patterns (pods as context domains, pair pattern, HA via mental-model-ha skill + substrate session logs, terminal nodes as common-room, chatroom/substrate/transcripts/Corpus).
-   - **§7 is the canonical 12-step rig-spec authoring SOP for high-stakes rigs — use it instead of the baseline "Design Process" below when the rig is ≥4 members, uses HA, is a managed-app, or will be shared/copied.** The baseline below still applies to small/focused rigs.
-   - §10 contains the host's bootstrap sequence so you know where your new rig fits.
-   - §12 has the naming canon and vocabulary mapping to shipped terms.
-5. **`building-agent-software` skill** if available in your skill catalog. Design principles for agent-facing tools and surfaces. Relevant when your rig ships a new CLI, service, or managed app.
-
-**Load as needed:**
-- Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
-- If the design session is long and you're running inside a managed rig, use `rig whoami --json` to recover your identity after compaction
-
-Do not skip the required reading. A rig architect who doesn't know the spec format will produce specs that don't validate. An architect who doesn't know the startup layering model will produce agents that boot without knowing their role. An architect who doesn't check for host-level doctrine will reinvent conventions the host has already established.
+## Before you design: select the relevant sources
+
+Start with the user's outcome, the current project authority, and the part of
+the format you will author. Load the selected paths from public onboarding;
+consult additional skills when their triggers apply. A design task does not
+require reading the whole command library.
+
+- Read the relevant sections of `rig-spec.md` and `agent-spec.md` before writing
+  those declarations. Consult `agent-startup-guide.md` for startup/loadout work
+  and `edge-types.md` when selecting relationships. Resolve the installed
+  reference root from the actual OpenRig installation; `~/.openrig/reference/`
+  is a default, not a fixed location. If it is absent, use the matching source
+  repository docs or report the missing reference. Reading does not require
+  starting or changing a daemon.
+- Use current `rig <command> --help` for command shape. Load `openrig-user` for
+  the specific CLI surface needed, through the installed skill/context catalog.
+- Inspect relevant starter specs with `rig specs ls`. Treat them as examples to
+  validate against the current environment, not proof that your new rig works.
+- If the environment declares host or project doctrine, read the actual
+  applicable authority and reconcile it with the task. Do not assume a filename,
+  section number, rig classification or fixed authoring SOP. Missing authority
+  is a question to resolve when it changes the design.
+- Load domain-specific guidance for specialist roles. When authoring an
+  agent-facing tool, consult `building-agent-software` if available.
+
+Keep the spec, startup layering, role responsibilities and selected proof
+standard explicit. Scale the reading and checks to what the design changes.
 
 ## The Design Process
 
@@ -152,14 +141,17 @@ To verify the current builtin set on this host, run `rig specs ls` and look for
 
 Each member needs a `runtime` and optionally a `model`.
 
-**Runtime selection:**
-- `claude-code` — Claude Code. Best for: complex reasoning, architecture, code review, orchestration. Supports `/loop` for recurring tasks, rich hooks system, MCP servers.
-- `codex` — Codex. Best for: parallel work, implementation, testing. Different approval model. Less reliable for recurring tasks.
-- `terminal` — Infrastructure nodes. Servers, log tails, build watchers. Not an agent — a process.
-
-**Runtime diversity is valuable.** Using both Claude Code and Codex in the same rig gives you different reasoning perspectives. The `product-team` starter uses Claude Code for the lead/impl/design/r1 roles and Codex for peer/qa/r2 roles. This is deliberate — model diversity catches different classes of issues.
+Choose from the installed, authenticated runtimes and the project's current
+execution policy. `claude-code` and `codex` are agent runtimes; `terminal` is an
+infrastructure process. Their model availability, hooks, approval behavior and
+continuation support differ. Check the relevant installed interfaces rather
+than ranking vendors permanently in a reusable role skill.
 
-**Model selection** is optional. The runtime's default model is usually fine. Override only when you have a specific reason (e.g., a complex architecture agent might benefit from a specific model).
+Pin a model when the work or environment requires it, and verify the active
+runtime reports that model before relying on its result. Select reviewers and
+support roles by consequence, competence and the declared policy. Runtime
+diversity can provide different methods; it does not by itself prove independence
+or make any model suitable for a task.
 
 ### Step 5: Design Edge Topology
 
@@ -181,7 +173,8 @@ This is where most rigs succeed or fail. The topology is mechanical; the startup
 **Minimum for every rig:**
 1. Each agent has a `guidance/role.md` — who they are, what they do
 2. The rig has a `CULTURE.md` — how the team works together
-3. Each agent gets `openrig-user` skill — so they know how to use the rig primitives
+3. Each agent gets the selected onboarding path and can discover the relevant
+   command/skill references when needed
 
 **For serious rigs, also include:**
 4. `startup/context.md` per agent — boot-time grounding (project info, environment details)