@openrig/cli 0.4.6 → 0.4.8

package/daemon/docs/reference/rig-spec.md

@@ -174,12 +174,31 @@ edges:
 | `name` | string | yes | — | Rig name. Used in session naming (`{pod}-{member}@{name}`), snapshot identification, and spec library lookup. |
 | `summary` | string | no | — | Human-readable description. Shown in spec library, review surfaces, and `rig specs show`. |
 | `culture_file` | string | no | — | Relative path to a rig-wide culture/constitution file. Must be a safe relative path (no `..`, no absolute). |
+| `permission_policy` | string | no | — | Permission policy attached to the rig. Either a built-in (`builtin:locked`, `builtin:standard`, `builtin:open`, `builtin:operator`) or a safe relative path to a custom policy file (resolved from this spec's directory; no `..`, no absolute). Absent leaves the default floor. A member may set its own `permission_policy`, which takes precedence over the rig-level one. See "Attaching a permission policy" below. |
 | `docs` | Doc[] | no | — | Documentation files that should travel with the rig. Included in rig bundles. Each entry has a `path` field (safe relative path). The engine does not consume these — they are for humans and agents setting up the environment before launch. |
 | `startup` | StartupBlock | no | — | Rig-level startup files and actions. Applied to all members via the startup layering model. |
 | `services` | ServicesBlock | no | — | Optional managed services (Docker Compose). When present, services boot before any agent launches. |
 | `pods` | Pod[] | yes | — | At least one pod required. Each pod is a bounded context containing members and pod-local edges. |
 | `edges` | CrossPodEdge[] | no | `[]` | Cross-pod edges connecting members in different pods. Must use fully-qualified `pod.member` IDs. |
 
+### Attaching a permission policy
+
+Attach a policy to a rig with `permission_policy`, either at the rig level or on a member:
+
+```yaml
+# a built-in, by name:
+permission_policy: builtin:standard
+
+# or a custom policy file, by relative path (resolved from this spec's directory):
+permission_policy: policies/my-cautious-dev.policy.md
+```
+
+Built-in policies (`locked` / `standard` / `open` / `operator`) are read-only and are
+referenced as `builtin:<name>`. A custom policy lives in your own project and is
+referenced by a safe relative path (no `..`, no absolute). A shipped example of the
+custom shape is `packages/daemon/policies/examples/my-cautious-dev.policy.md` — copy it
+into your project and edit it to taste.
+
 ---
 
 ## Pod

package/daemon/policies/builtin/locked.policy.md

@@ -0,0 +1,24 @@
+---
+source: builtin
+name: locked
+surface: config
+policy_schema_version: 1
+description: Whitelist posture for untrusted or sensitive work — implicit deny-all plus a minimal explicit allow. Tight, but far more usable than raw harness-default.
+default_posture: deny
+allow: [run_toolchain, rig_up, rig_down]
+ask: []
+deny: []
+destructive_class: [delete_everything, drop_persistent_store, reset_or_discard_vcs, delete_files, force_push]
+---
+
+# Locked (built-in policy)
+
+The tightest built-in. Everything is denied unless explicitly allowed. Use for untrusted rigs, sensitive repos, or work where the blast radius must be minimal.
+
+- **default_posture: deny** — any semantic action not in `allow` is denied.
+- **allow** — only the dev toolchain (`run_toolchain`: npm/node/tsc/test/lint) and rig lifecycle (`rig_up`/`rig_down`). No push, no PR, no publish, no arbitrary shell, no network egress beyond what the toolchain needs, no secret reads.
+- **destructive_class** — listed for completeness; moot here (default-deny already blocks them).
+
+**The usability FLOOR is separate and always on** (flag surface, not a config knob): Claude `acceptEdits` + Codex `workspace-write` (the edit/sandbox floor); Pi `--no-approve` is a resource-TRUST posture, not a permission floor (Pi has no permission surface). So a Locked seat can still edit files — it just can't reach beyond the minimal allow-set without an explicit grant.
+
+**Translation is the skill's job.** This spec is harness-neutral semantic intent; the `applying-a-permission-policy` skill translates it to each harness (Claude prefix rules / Codex posture / Pi bit) with the version-stamped caveats. Grounded in schema `a8dba0d9`.

package/daemon/policies/builtin/open.policy.md

@@ -0,0 +1,24 @@
+---
+source: builtin
+name: open
+surface: config
+policy_schema_version: 1
+description: High-trust denylist posture — everything allowed except the explicitly-destructive class, which asks. Just below YOLO.
+default_posture: allow
+allow: []
+ask: []
+deny: []
+destructive_class: [delete_everything, drop_persistent_store, reset_or_discard_vcs]
+---
+
+# Open (built-in policy)
+
+High-trust posture: everything runs without a prompt except the catastrophic-destructive class. Use for trusted autonomous fleets that still want a backstop on disk-destroy-class acts. One step below YOLO.
+
+- **default_posture: allow** — everything, including push, PR, publish, merge/release, force_push, arbitrary shell, network, secrets, topology.
+- **destructive_class → ask** — `delete_everything`, `drop_persistent_store`, `reset_or_discard_vcs` ASK, never silent-block (best-effort-safe). This is the only carve-out.
+- Difference from Standard: Standard ASKs the release-class (PR/publish/merge/force_push); Open ALLOWs them and asks only the destructive class.
+
+**Autonomous note:** the destructive-class `ask` will freeze a fully-autonomous seat if such an action is attempted — which is the intended backstop. An autonomous fleet that must never pause even on a disk-destroy-class act uses YOLO (flag-surface full-bypass), not Open.
+
+**FLOOR (always on, flag surface):** Claude `acceptEdits` + Codex `workspace-write` (the edit/sandbox floor); Pi `--no-approve` is a resource-TRUST posture, not a permission floor (Pi has no permission surface). **Translation is the skill's job.** Grounded in schema `a8dba0d9`.

package/daemon/policies/builtin/standard.policy.md

@@ -0,0 +1,25 @@
+---
+source: builtin
+name: standard
+surface: config
+policy_schema_version: 1
+description: The recommended default — the 80% software-factory interactive-dev posture. Routine dev including push; the outward/release/history-rewriting acts ask the human.
+default_posture: allow
+allow: [push_to_remote]
+ask: [create_pr, publish_package, merge_or_release, force_push]
+deny: []
+destructive_class: [delete_everything, drop_persistent_store, reset_or_discard_vcs]
+---
+
+# Standard ⭐ (built-in policy — recommended default)
+
+The everyday software-factory posture for INTERACTIVE dev. Routine work runs without prompts; the consequential outward and history-rewriting acts defer to the human.
+
+- **default_posture: allow** — routine dev (toolchain, arbitrary shell, install deps, scoped file deletion, network, topology) runs without a prompt.
+- **allow: [push_to_remote]** — routine `git push` is allowed (pinned explicitly; the founder rejected gating push as a default).
+- **ask: [create_pr, publish_package, merge_or_release, force_push]** — outward/release/history-rewriting acts ASK the human. **ASK ≠ deny**: OpenRig bakes no block; ASK = defer to the human, the founder's explicit beyond-floor default. `force_push` is additionally best-effort on Claude (prefix rules can't reliably split `git push --force`), so ASK is the honest disposition, not a can't-enforce deny.
+- **destructive_class → ask** — `delete_everything`, `drop_persistent_store`, `reset_or_discard_vcs` default to ASK, never a silent block (best-effort-safe).
+
+**INTERACTIVE-dev posture:** an `ask` freezes an autonomous seat by design — autonomous fleets use Open or YOLO, not Standard.
+
+**FLOOR (always on, flag surface):** Claude `acceptEdits` + Codex `workspace-write` (the edit/sandbox floor); Pi `--no-approve` is a resource-TRUST posture, not a permission floor (Pi has no permission surface). **Translation is the skill's job** (harness-neutral intent → per-harness format, caveated). Grounded in schema `a8dba0d9`; the ask-set is pinned per cold-transfer `627abbb6`.

package/daemon/policies/builtin/yolo.policy.md

@@ -0,0 +1,20 @@
+---
+source: builtin
+name: yolo
+surface: flag
+launch_posture: full_bypass
+policy_schema_version: 1
+description: Full-bypass posture — the flag-surface YOLO opt-in. Everything runs, nothing prompts. Guardrailed by skills and starter markdown, not by permission-blocking.
+---
+
+# YOLO (built-in policy — flag surface)
+
+The maximum-permissive built-in. The seat runs the harness with its full-bypass launch flag: Claude `--dangerously-skip-permissions`, Codex full-bypass, Pi `--approve`. Nothing prompts; nothing is denied. Use only for fully-trusted autonomous work where any pause is unacceptable.
+
+**APPLICATION is deterministic, NOT skill-translated.** YOLO is a `surface: flag` policy: it resolves to a stable launch flag, so it is applied by the deterministic flag-surface opt-in — the rip-out slice's YOLO setting (OPR.0.4.8.2). The `applying-a-permission-policy` skill does **NOT** translate this policy; it simply points at that setting. This is the two-surface distinction: the flag surface is stable enough for deterministic code, so it does not pay the skill-indirection tax.
+
+**Config policies are MOOT when YOLO is on.** The full-bypass launch flag overrides any Claude prefix rules / Codex posture, so an attached config-surface policy (Locked/Standard/Open) has no effect while YOLO is active. Pick YOLO OR a config policy, not both.
+
+**Guardrails come from skills + starter markdown, not permission-blocking** — a YOLO seat is bounded by what its skills and operating context tell it to do, since the permission layer imposes nothing.
+
+**Naming lineage:** the founder's FINAL DESIGN named the fourth built-in **Operator**. The two-surface refinement (2026-08-03) subsumed Operator into this flag-surface full-bypass built-in and renamed it **YOLO** to name the posture plainly; the picker presents all four named postures (Locked / Standard / Open / YOLO) uniformly. Grounded in schema `a8dba0d9`.

package/daemon/policies/examples/my-cautious-dev.policy.md

@@ -0,0 +1,40 @@
+---
+source: custom
+name: my-cautious-dev
+surface: config
+policy_schema_version: 1
+description: An example personal policy — everyday development runs freely, but anything that leaves this machine (push, publish, network) checks with you first.
+default_posture: allow
+allow: []
+ask: [push_to_remote, create_pr, publish_package, merge_or_release, force_push, network_egress]
+deny: []
+destructive_class: [delete_everything, drop_persistent_store, reset_or_discard_vcs]
+---
+
+# my-cautious-dev (example custom policy)
+
+A starting point you can copy and adjust. It shows the shape of a personal policy you
+keep in your own project and attach by path — it is **not** one of the built-ins.
+
+- **default_posture: allow** — everyday development (editing, building, running the
+  toolchain, scoped file changes) runs without a prompt.
+- **ask** — anything that leaves this machine checks with you first: pushing to a remote,
+  opening a pull request, publishing a package, merging or releasing, force-pushing, and
+  network access. "Ask" means *check with me*, not *blocked*.
+- **destructive_class → ask** — wide-blast-radius actions (wiping a workspace, dropping a
+  data store, discarding version-control state) ask before they run.
+
+## Using it
+
+Keep a policy like this in your own project, then point a rig at it by **relative path**
+— resolved from the directory of the rig spec that references it:
+
+```yaml
+# rig.yaml
+permission_policy: policies/my-cautious-dev.policy.md
+```
+
+Copy it, rename it, and edit the lists to taste — it's yours to change. The built-in
+policies (locked / standard / open / operator) stay read-only and are referenced as
+`builtin:<name>`; a custom policy like this one lives in your project and is referenced
+by path.

package/daemon/specs/agents/apps/vault-specialist/agent.yaml

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, systematic-debugging, verification-before-completion, vault-user]
+      skills: [using-superpowers, systematic-debugging, verification-before-completion, vault-user]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [openrig-user, mission-slice-sop, development-team, test-driven-development, systematic-debugging, executing-plans, verification-before-completion]
+      skills: [development-team, test-driven-development, systematic-debugging, executing-plans, verification-before-completion]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [openrig-user, mission-slice-sop, orchestration-team, backlog-capture, writing-plans, executing-plans, verification-before-completion, brainstorming]
+      skills: [orchestration-team, backlog-capture, writing-plans, executing-plans, verification-before-completion, brainstorming]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [openrig-user, mission-slice-sop, requirements-writer, context-builder, writing-plans, verification-before-completion]
+      skills: [requirements-writer, context-builder, writing-plans, verification-before-completion]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [openrig-user, mission-slice-sop, review-team, plan-review, systematic-debugging, verification-before-completion]
+      skills: [review-team, plan-review, systematic-debugging, verification-before-completion]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, mission-slice-sop, development-team, frontend-design, verification-before-completion, writing-plans, brainstorming]
+      skills: [using-superpowers, development-team, frontend-design, verification-before-completion, writing-plans, brainstorming]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
@@ -26,4 +27,13 @@ startup:
     - path: guidance/role.md
       delivery_hint: send_text
       required: true
-  actions: []
+  actions:
+    - type: send_text
+      value: >-
+        A task is coming. BEFORE you do anything else, load and invoke your process skills NOW
+        using your runtime's supported skill mechanism: using-superpowers, frontend-design,
+        verification-before-completion, writing-plans, brainstorming. Load them first, then begin
+        the work.
+      phase: after_ready
+      applies_on: [fresh_start, restore]
+      idempotent: true

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, mission-slice-sop, development-team, test-driven-development, systematic-debugging, verification-before-completion, writing-plans, executing-plans]
+      skills: [using-superpowers, development-team, test-driven-development, systematic-debugging, verification-before-completion, writing-plans, executing-plans]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
@@ -26,4 +27,13 @@ startup:
     - path: guidance/role.md
       delivery_hint: send_text
       required: true
-  actions: []
+  actions:
+    - type: send_text
+      value: >-
+        A task is coming. BEFORE you do anything else, load and invoke your process skills NOW
+        using your runtime's supported skill mechanism: using-superpowers, test-driven-development,
+        systematic-debugging, verification-before-completion, writing-plans, executing-plans. Load
+        them first, then begin the work.
+      phase: after_ready
+      applies_on: [fresh_start, restore]
+      idempotent: true

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, mission-slice-sop, development-team, systematic-debugging, verification-before-completion, agent-browser, dogfood, writing-plans, executing-plans]
+      skills: [using-superpowers, test-driven-development, development-team, systematic-debugging, verification-before-completion, agent-browser, dogfood, writing-plans, executing-plans]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
@@ -26,4 +27,13 @@ startup:
     - path: guidance/role.md
       delivery_hint: send_text
       required: true
-  actions: []
+  actions:
+    - type: send_text
+      value: >-
+        A task is coming. BEFORE you do anything else, load and invoke your process skills NOW
+        using your runtime's supported skill mechanism: using-superpowers, test-driven-development,
+        systematic-debugging, verification-before-completion, agent-browser, dogfood, writing-plans,
+        executing-plans. Load them first, then begin the work.
+      phase: after_ready
+      applies_on: [fresh_start, restore]
+      idempotent: true

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

@@ -6,6 +6,7 @@ You are the quality assurance side of a dev pair. You gate every edit the implem
 
 Load these packaged skills now before reviewing work or dogfooding:
 - `using-superpowers`
+- `test-driven-development`
 - `openrig-user`
 - `mission-slice-sop`
 - `development-team`

package/daemon/specs/agents/factory-rsi/dogfood/agent.yaml

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, mission-slice-sop, dogfood, systematic-debugging, verification-before-completion]
+      skills: [using-superpowers, dogfood, systematic-debugging, verification-before-completion]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

package/daemon/specs/agents/factory-rsi/release-manager/agent.yaml

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, mission-slice-sop, verification-before-completion]
+      skills: [using-superpowers, verification-before-completion]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, mission-slice-sop, orchestration-team, systematic-debugging, verification-before-completion, writing-plans, executing-plans, brainstorming]
+      skills: [using-superpowers, orchestration-team, systematic-debugging, verification-before-completion, writing-plans, executing-plans, brainstorming]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
@@ -26,4 +27,13 @@ startup:
     - path: guidance/role.md
       delivery_hint: send_text
       required: true
-  actions: []
+  actions:
+    - type: send_text
+      value: >-
+        A task is coming. BEFORE you do anything else, load and invoke your process skills NOW
+        using your runtime's supported skill mechanism: using-superpowers, systematic-debugging,
+        verification-before-completion, writing-plans, executing-plans, brainstorming. Load them
+        first, then begin the work.
+      phase: after_ready
+      applies_on: [fresh_start, restore]
+      idempotent: true

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

@@ -15,8 +15,6 @@ profiles:
   default:
     uses:
       skills:
-        - openrig-user
-        - mission-slice-sop
         - office-hours
         - context-builder
         - requirements-writer
@@ -24,6 +22,7 @@ profiles:
         - plan-review
         - exec-summary
         - backlog-capture
+      plugins: [shared:openrig-core]
       runtime_resources:
         - shared:claude-default-settings
         - shared:claude-default-mcp

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [openrig-user]
+      skills: []
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [openrig-user]
+      skills: []
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:

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

@@ -11,9 +11,10 @@ imports:
 profiles:
   default:
     uses:
-      skills: [using-superpowers, openrig-user, mission-slice-sop, review-team, systematic-debugging, verification-before-completion, writing-plans, brainstorming]
+      skills: [using-superpowers, review-team, systematic-debugging, verification-before-completion, writing-plans, brainstorming]
       guidance: []
       subagents: []
+      plugins: [shared:openrig-core]
       runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
 
 resources:
@@ -26,4 +27,13 @@ startup:
     - path: guidance/role.md
       delivery_hint: send_text
       required: true
-  actions: []
+  actions:
+    - type: send_text
+      value: >-
+        A task is coming. BEFORE you do anything else, load and invoke your process skills NOW
+        using your runtime's supported skill mechanism: using-superpowers, systematic-debugging,
+        verification-before-completion, writing-plans, brainstorming. Load them first, then begin
+        the work.
+      phase: after_ready
+      applies_on: [fresh_start, restore]
+      idempotent: true

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

@@ -16,18 +16,10 @@ resources:
       path: skills/process/frontend-design
     - id: using-superpowers
       path: skills/process/using-superpowers
-    - id: openrig-user
-      path: skills/core/openrig-user
-    - id: openrig-operator
-      path: skills/core/openrig-operator
-    - id: openrig-installer
-      path: skills/core/openrig-installer
     - id: openrig-architect
       path: skills/core/openrig-architect
     - id: rig-lifecycle
       path: skills/core/rig-lifecycle
-    - id: mission-slice-sop
-      path: skills/core/mission-slice-sop
     - id: systematic-debugging
       path: skills/process/systematic-debugging
     - id: test-driven-development
@@ -57,6 +49,11 @@ resources:
       path: skills/pm/exec-summary
     - id: backlog-capture
       path: skills/pm/backlog-capture
+  plugins:
+    - id: openrig-core
+      source:
+        kind: local
+        path: ~/.openrig/plugins/openrig-core
   runtime_resources:
     - id: claude-default-settings
       path: runtime/claude-settings.fragment.json

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

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

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

@@ -0,0 +1,132 @@
+---
+name: agent-starters
+description: Use when creating, refreshing, packaging, inspecting, promoting, or deprecating a named per-seat starting point — Agent Starter manifest authoring, the 6-state lifecycle (captured → named → inspectable → used → promoted → deprecated), provenance honesty, and refusal rules. NOT a VM image; a managed starting point composed from agent role + startup context + optional native session source + provenance.
+metadata:
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - claude-compaction-restore
+      - mental-model-ha
+      - scope-recovery
+      - session-compaction-and-restore
+      - agent-startup-and-context-ingestion
+      - composable-priming-packs
+      - session-source-fork
+      - seat-continuity-and-handover
+      - claude-compact-in-place
+      - pre-maintenance-agent-preservation
+---
+
+# Agent Starters
+
+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.
+
+## Use this when
+
+- Creating a new seat from a known-good starting context.
+- Refreshing a seat with `rig expand` and `starter_ref`.
+- Authoring a new starter (registry entry).
+- Inspecting an existing starter's provenance, freshness, or recommended status.
+- Promoting / deprecating starters in the registry.
+- Composing a starter with a Composable Priming Pack (record manifest id/version, runtime, source session id or transcript path, ready-check evidence, freshness state).
+
+## Don't use this when
+
+- You want VM-style deterministic state capture. Starters don't capture VM state.
+- You want to copy provider auth material into a starter. **Starters refer to session sources and context; they do NOT copy credentials.**
+
+## What makes a starter valuable
+
+A starter is valuable when it is **functional** — it carries the context the seat needs to do its task well. Functional is the *only* measure of a good starter. Size is not: a smaller starter is not a better one, and a bigger one is not worse. Whatever it took for the seat to become genuinely capable at its job is the right starter — 80K tokens or 800K.
+
+Capture the seat as it naturally is at a functional, proven point. Don't pad it with context the seat doesn't use, and — just as important — don't strip context out to make it smaller. Size is an *outcome* of what the seat needed, never a target.
+
+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
+
+1. **Captured** — a useful seat/session/context pattern is identified.
+2. **Named** — it becomes an Agent Starter with stable id and owner.
+3. **Inspectable** — runtime, context inputs, session source, and provenance are visible.
+4. **Used** — a rig member or `rig expand` operation starts from it.
+5. **Promoted** — evidence shows it is recommended for a role or bundle.
+6. **Deprecated** — replaced, stale, unsafe, or incompatible.
+
+## Failure modes (5)
+
+1. **Overclaiming image semantics** — UI/docs imply deterministic VM-style state capture. Say "starter," name what's included, show provenance.
+2. **Hidden provenance** — users can't tell what session, context, or spec a starter came from. **Refuse promotion until provenance is inspectable.**
+3. **Stale starter** — points at outdated doctrine, missing files, or invalid native session source. **Inspect must report staleness honestly.**
+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)
+
+```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>"
+```
+
+Member usage:
+
+```yaml
+members:
+  - id: reviewer
+    starter_ref:
+      name: velocity-reviewer-v1
+```
+
+When a starter points at a primed session produced from a Composable
+Priming Pack, record:
+- manifest id/version
+- runtime
+- source session id or transcript path
+- ready-check evidence
+- freshness state
+
+## Proof matrix
+
+| Surface | Test type | Authority |
+|---|---|---|
+| Registry schema accepts minimal starter | unit | daemon or config-layer prototype |
+| Inspect shows provenance and included context | unit / snapshot | daemon or CLI |
+| Member can use `starter_ref` | integration | daemon |
+| Unsupported runtime or stale source refuses honestly | unit + integration | daemon |
+| No secret material copied into starter artifact | grep / fixture | tester |
+| Bundle can include or reference starter | package inspection | bundle layer |
+
+## Dependencies on other primitives
+
+- **Firm**: `session-source-fork` — native conversation-source continuity for fork-based starters
+- **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
+- **Soft**: `seat-continuity-and-handover` — refresh and swap workflows over starters
+
+## Required-before-RSI
+
+Agent Starters need queryable provenance and honest inspect output before
+RSI loops can rely on them for seat refresh. A workflow must be able to
+answer: "what starter did this seat use, what source session or context was
+included, and is that starter still recommended?"
+
+## See also
+
+- `session-source-fork` skill — low-level fork primitive that makes native session-based starters possible
+- `composable-priming-packs` skill — manifest-driven layer for producing primed sessions starters reference