@openrig/cli 0.5.5 → 0.5.7

package/daemon/context-packs/skills/forming-an-openrig-mental-model/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: forming-an-openrig-mental-model
+description: >-
+  Use when the system around you does not make sense yet: you just booted into a seat and do not
+  know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not
+  certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do
+  not know how skills reach you or where context comes from; or you are about to act on a guess
+  about how OpenRig works. Gives the runtime mental model fast, so you stop guessing.
+metadata:
+  cli_surfaces_referenced:
+    - ask
+    - capture
+    - down
+    - ps
+    - send
+    - transcript
+    - up
+    - whoami
+  openrig:
+    stage: factory-approved
+    sibling_skills:
+      - openrig-user
+      - openrig-operator
+      - openrig-builder
+      - openrig-architect
+      - openrig-upgrade
+      - ai-dev-workflows
+      - software-for-agents
+---
+
+# Forming an OpenRig Mental Model
+
+You're new to OpenRig — or returning after time away — and you need to
+quickly understand what kind of system this is, what your seat is, and what
+the moves are. This skill is the fast on-ramp.
+
+For depth, read the canonical reference docs the skill points to. This
+skill's job is to get you *oriented* — accurate enough to operate, fast
+enough to be useful — not to replace the canonical docs.
+
+---
+
+## The 60-second mental model
+
+OpenRig is a **local control plane for multi-agent coding topologies**. You
+declare a topology of agents in YAML, boot it with one command, and OpenRig
+manages tmux sessions, harness lifecycles, transcripts, snapshots, and
+restoration. When the system goes down, OpenRig snapshots; when it comes
+back, agents resume their conversations.
+
+The product loop:
+
+```
+down (auto-snapshot) → up <rig-name> (auto-restore) → work → repeat
+```
+
+The unit of work is the **rig** — a topology of agents working together as
+a single system.
+
+---
+
+## The four-layer model (where you live)
+
+Everything in agent engineering happens at one of four layers. **OpenRig
+operates at Layer 3.**
+
+| Layer | Name | Analogy | What it is |
+|---|---|---|---|
+| L0 | Model | CPU | Foundation model — Claude, GPT, Gemini. Stateless tokens-in/tokens-out. |
+| L1 | Agent Core | Process loop | The reason-and-act cycle: observe, plan, choose, act, repeat. |
+| L2 | Harness | Container / OS | Tools, memory, lifecycle around the model. Examples: Claude Code, Codex CLI. |
+| L3 | Rig | Docker Compose / Terraform | Multi-agent topology — what agents exist, how they relate. **OpenRig.** |
+
+You are an agent at L1 inside an L2 harness, configured by L3 OpenRig.
+OpenRig manages your harness; the harness wraps the model; the model
+generates your tokens.
+
+---
+
+## Three pillars of context
+
+OpenRig is built on three context-engineering pillars. When you're oriented,
+you should know which pillar you're operating in:
+
+| Pillar | What it is | Where it lives |
+|---|---|---|
+| **Ontology** | What exists. Curated knowledge — facts, code maps, as-built docs. | Corpus (planned future system). Today: substrate prose docs. |
+| **Epistemology** | Why an agent believes what it believes — reasoning, instincts, decisions. | Transcripts (auto-captured). Session logs. ADRs. |
+| **Topology** | How agents are connected — pods, edges, communication paths. | OpenRig itself. RigSpec YAML. |
+
+OpenRig **manages the topology pillar**. The other two are filled by Corpus
+(future) and transcripts (now). Most of your work probably touches multiple
+pillars; knowing which one you're operating in helps you reach for the right
+artifacts.
+
+---
+
+## The core vocabulary (read these terms literally)
+
+| Term | What it means |
+|---|---|
+| **Rig** | A topology of agents working together as a single system. Defined in YAML (RigSpec). The top-level object. |
+| **Pod** | A bounded context group within a rig. Members of a pod share a context domain and continuity responsibility. Think Kubernetes pod for knowledge. |
+| **Member / Node** | A single agent (or terminal-node service) within a pod. |
+| **Edge** | A relationship between members or pods. Kinds: `delegates_to`, `spawned_by`, `can_observe`, `collaborates_with`, `escalates_to`. |
+| **Topology** | The shape of the rig — how agents are grouped into pods, how edges connect them, how the whole thing fits together. |
+| **AgentSpec** | A reusable agent blueprint. Defines skills, guidance, hooks, profiles, startup. File: `agent.yaml`. |
+| **RigSpec** | The topology YAML. Defines pods, members, edges, culture. File: `rig.yaml`. |
+| **RigBundle** | A portable archive of a RigSpec + vendored AgentSpecs. Move topologies across machines. |
+| **Agent Starter** | A named, reusable starting context bundle. RigSpec member can declare `starter_ref`. |
+| **Skill** | A markdown file with frontmatter that an agent loads at boot or on activation. Cross-runtime standard at `agentskills.io`. |
+| **Profile** | A named configuration within an AgentSpec. The rig spec's member field selects which profile to use. |
+| **Culture** | Rig-wide constitution — how the team communicates, what "done" means, escalation rules. File: `CULTURE.md`. |
+| **Snapshot** | Point-in-time capture of a rig — sessions, conversations, state. Restorable. |
+| **Session name** | `{pod}-{member}@{rig}`. The canonical address for tmux sessions and agent-to-agent messaging. |
+
+The session-name format `{pod}-{member}@{rig}` is your address. When you
+run `rig whoami --json`, you get back your full topology context: rig name,
+pod, member, peers, edges, transcript path.
+
+---
+
+## Rig classes (what kind of rig am I in?)
+
+OpenRig has five rig classes. The class determines authoring discipline,
+supervision, and lifecycle policy.
+
+| Class | Purpose | Lifecycle |
+|---|---|---|
+| **kernel** | Host-level supervision, intake, authoring. One per host. | Always on; never auto-hibernated. |
+| **project** | Long-lived team bound to a codebase. | Stays hot when active; hibernates on explicit request. |
+| **ephemeral** | Short-lived mission (research, build, migration, spike). | Spawn → work → retire. |
+| **infra-build** | Subclass of ephemeral whose output becomes permanent infrastructure. | Retired only after output verified in place. |
+| **managed-app** | Services-backed rig with specialist agents (e.g., a vault specialist, a skill librarian). | Long-lived; accessed by other rigs. |
+
+You're probably in a project rig or managed-app rig if you're doing
+substantive work. Knowing your class helps you understand the supervisory
+expectations on your seat.
+
+---
+
+## How skills load (the most important thing to get right)
+
+Skills are an **established cross-runtime standard** at
+`https://agentskills.io/specification`. Both Claude Code and Codex build on it.
+
+### The shape
+
+A skill is a directory containing `SKILL.md` (uppercase). The SKILL.md has
+YAML frontmatter (`name`, `description`) and a Markdown body. Optional
+sibling directories: `references/`, `scripts/`, `assets/`.
+
+### Progressive disclosure (why skills scale)
+
+The harness reads frontmatter cheaply at boot — names + descriptions of all
+available skills. Body content loads only when a skill activates. This is
+**ambient awareness** — you know all the skills exist; you only pay token
+cost when you reach for one.
+
+### Where skills come from in OpenRig
+
+- **Per-agent loadout:** your AgentSpec's `profile.uses.skills: [...]`
+  determines what skills get projected into your runtime skill folder
+  (`.claude/skills/` or `.agents/skills/`) before your harness boots. This
+  is the **structural composition** layer.
+- **Cross-pod sharing:** AgentSpecs can `imports: [shared]` to access a
+  shared skill pool. Built-in agents commonly do this.
+- **Belt-and-suspenders:** the spec projects skill files; startup guidance
+  also tells you to load specific skills. Both paths matter — if the
+  projection silently fails, the guidance still tells you what to read.
+
+### Where skills live (sources of truth)
+
+| Home | Purpose |
+|---|---|
+| `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.agents/skills/` | Where the harness actually loads from. Populated by `rig up`. |
+| `~/.claude/skills/`, `~/.agents/skills/` | Your personal / user-installed global skills, loaded by the harness itself (independent of OpenRig). NOT where OpenRig's own bootstrap skills live — those ship in the product (below) and project into the cwd `.claude/skills/` at `rig up`. |
+| `openrig/packages/daemon/{specs/agents/shared/skills,assets/plugins/*/skills}/` | Product skills that ship with OpenRig — the spec pool + the bundled plugin assets (openrig-user, openrig-operator, openrig-architect, forming-an-openrig-mental-model, queue-handoff, claude-compaction-restore, …). |
+| `~/.openrig/skills/` | Future runtime install home for OpenRig-shipped skills. |
+| the skills authoring workspace | Skill authoring source (not runtime-loaded). |
+
+The harness only sees the first two. Other locations are authoring,
+shipping, and source-of-truth — they reach the harness via projection or
+NPM install, not directly.
+
+---
+
+## The product loop (your day-to-day)
+
+```
+rig up <rig-name>         # boot or restore the topology
+rig ps --nodes            # see what's running
+rig whoami --json         # know who you are
+rig send <session> "msg"  # talk to a peer
+rig capture <session>     # see a peer's terminal
+rig transcript <session>  # read a peer's history
+rig down <rigId>          # snapshot and tear down
+rig up <rig-name>         # restore from snapshot
+```
+
+The first command in any new seat is `rig whoami --json`. It tells you your
+rig, pod, member, peers, edges, and transcript path. **Treat it as ground
+truth — your CLAUDE.md or AGENTS.md startup overlay can be wrong; whoami
+is authoritative.**
+
+---
+
+## Cultural posture (how to behave)
+
+OpenRig has a few load-bearing cultural principles. Internalize these:
+
+- **Honesty over convenience.** If resume fails, say so loudly. Don't
+  silently launch fresh.
+- **The agent is the power user.** The CLI is designed for a 10x staff
+  engineer at the terminal. You're that user.
+- **CLI is context engineering.** Every error message and help text gives
+  you information to act on. Read errors carefully.
+- **Convention over invention.** Follow docker/git/kubectl patterns. Agent
+  muscle memory is real.
+- **Semi-deterministic is OK.** Core contracts are solid; edge cases are
+  agent-handled.
+- **Pets, not cattle (today).** OpenRig is currently optimized for long-lived
+  agents that develop instincts over sessions. Cattle support is on the
+  roadmap.
+
+---
+
+## What you should do in your first 10 minutes
+
+If you're booting into a new seat in an OpenRig rig:
+
+1. **`rig whoami --json`** — recover identity. Know your rig, pod, member,
+   peers.
+2. **Read your role guidance** — typically delivered via startup files.
+   `guidance/role.md` for your specific seat.
+3. **Read the rig's `CULTURE.md`** if it has one — the team operating
+   manual.
+4. **Check what skills you have** — list `.claude/skills/` or
+   `.agents/skills/` in your cwd. Each skill has a frontmatter description
+   that tells you when to reach for it.
+5. **Check your peers** — `rig capture <peer-session>` to see what they're
+   doing.
+6. **Check the transcripts** if you're returning to an in-flight workstream
+   — `rig transcript <session> --tail 100` for recent context.
+7. **Ask `rig ask <rig> "<question>"`** if you need cross-cutting evidence
+   from the rig's transcripts and chat.
+
+You're now oriented enough to start doing useful work.
+
+**Permission policy (at setup):** OpenRig sets only a minimal usability floor on your harness permissions, then offers recommended policies you opt into (Locked / Standard / Open — or YOLO to bypass). If you're creating or bringing up a rig, that's a choice you make, not something OpenRig decides for you — see openrig-user's "Permission policy — pick one at setup" and the `applying-a-permission-policy` skill.
+
+---
+
+## Going deeper (canonical references)
+
+For real depth, these are the load-bearing canonical docs:
+
+| Reference | What it covers |
+|---|---|
+| `openrig/docs/as-built/README.md` | As-built map of territory — daemon architecture, system overview, package boundaries; routes to the 13 `architecture/` + 4 `ui/` modules via `codemap.md` |
+| `openrig/docs/as-built/cli-reference.md` | The full `rig` CLI surface with all subcommands and flags |
+| `openrig/docs/reference/rig-spec.md` | The RigSpec YAML format — pods, members, edges, all fields |
+| `openrig/docs/reference/agent-spec.md` | The AgentSpec YAML format — resources, profiles, imports |
+| `openrig/docs/reference/agent-startup-guide.md` | The 7-layer startup layering model; delivery hints |
+| the product taxonomy | Canonical vocabulary (read literally) |
+| `openrig-operating-model` skill | Placement and operating-model guidance — topology and work trees, context altitude |
+| `openrig-architect` skill | Rig and topology authoring |
+| `https://agentskills.io/specification` | The cross-runtime skill standard |
+
+If you're going to be authoring rigs, use the `openrig-architect` skill before
+touching YAML.
+
+---
+
+## What this skill is NOT for
+
+- **Compaction recovery.** That's `claude-compaction-restore`. Different
+  skill, different scenario.
+- **Operating a specific rig.** Specific rigs have their own DESIGN.md and
+  CULTURE.md. Read those.
+- **Authoring a new rig.** Use the `openrig-architect` skill for that.
+- **Day-to-day OpenRig operation.** Use `openrig-user` for that.
+- **Administering an OpenRig install.** Use `openrig-operator`.
+
+This skill exists to **form your initial mental model of OpenRig as a
+system**. Once oriented, reach for the role-specific or task-specific skills
+that fit your actual work.
+
+---
+
+## Common misorientations to avoid
+
+| Misorientation | Reality |
+|---|---|
+| "OpenRig is a chat interface or assistant" | No. OpenRig is a control plane that *manages* your harness sessions. The chat happens inside the harness; OpenRig is around it. |
+| "Pods are workflow groups" | No. Pods are **context domains** — agents that share working context. If two agents communicate every turn, they should be in one pod; if they communicate rarely, they shouldn't be. |
+| "Edges represent reporting hierarchy" | No. Edges describe *coordination shape* — who delegates to whom, who observes whom. Avoid hierarchy interpretations; they distort behavior. |
+| "I should manage Codex's compaction the way I manage Claude's" | No. Codex auto-compacts cleanly; Claude doesn't. Different runtimes, different lifecycles. |
+| "MEMORY.md auto-loads, so I don't need to read it" | Maybe. Sometimes MEMORY.md auto-loads via system reminders; sometimes not. Don't assume. If your work touches the topics it covers, read it explicitly. |
+| "Skills inherit from a parent or compose like classes" | No. Skills are flat artifacts; composition happens via AgentSpec `profile.uses.skills` (structural) or soft cross-references in skill bodies (advisory). Not via OO-style inheritance. |
+| "The substrate `shared-docs/skills/` folder is the canonical runtime path" | No. The harness doesn't read there. It's an authoring workspace. Runtime loads from `.claude/skills/`, `.agents/skills/`, and product built-in. |
+
+---
+
+## Disaster-recovery test for this skill
+
+If you read only this skill, can you:
+
+1. State what kind of system OpenRig is, in one sentence?
+2. Name the four layers and where you live?
+3. Run `rig whoami --json` and interpret the output?
+4. Find your role guidance and your peers?
+5. Identify what kind of rig you're in (kernel / project / ephemeral / etc.)?
+6. Know where to look for a skill body (which folder)?
+7. Know what to read next for depth (the canonical references)?
+
+If yes — you're oriented. If no — tell your peer or the human; missing
+context is fixable, but only if surfaced.

package/daemon/context-packs/skills/forming-an-openrig-mental-model/manifest.yaml

@@ -0,0 +1,10 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "forming-an-openrig-mental-model"
+version: "0.5.7"
+taxonomy: "skills"
+purpose: "Use when the system around you does not make sense yet: you just booted into a seat and do not know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do not know how skills reach you or where context comes from; or you are about to act on a guess about how OpenRig works. Gives the runtime mental model fast, so you stop guessing."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when the system around you does not make sense yet: you just booted into a seat and do not know how the pieces fit; someone said rig, pod, seat, fleet, topology, or slice and you are not certain what they mean here; you are unsure what kind of rig you are in or what it is for; you do not know how skills reach you or where context comes from; or you are about to act on a guess about how OpenRig works. Gives the runtime mental model fast, so you stop guessing."

package/daemon/context-packs/skills/loading-addressable-markdown/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: loading-addressable-markdown
+description: Use when a mission, slice, dashboard, or task references Markdown as path#h2-slug or path#h2-slug/h3-slug outside the OpenRig context-pack library.
+---
+
+# Loading Addressable Markdown
+
+## Overview
+
+Load exactly one addressed Markdown section from any filesystem tree. The resolver mirrors OpenRig's shipped H2/H3 grammar without requiring the file to live in the context library.
+
+## Use
+
+Run the bundled script. Relative file references resolve from `--root`; without it they resolve from the current directory.
+
+```bash
+node ~/.agents/skills/loading-addressable-markdown/scripts/resolve-markdown.mjs \
+  --root /path/to/mission \
+  'slices/09-source-cleanup/SPEC.md#proposal'
+```
+
+The accepted forms are:
+
+- `file.md` — whole file
+- `file.md#h2-slug` — full H2 span, including child sections
+- `file.md#h2-slug/h3-slug` — full H3 span
+
+Slugs are lowercase; Markdown emphasis/code markers are removed; each other non-alphanumeric run becomes `-`. Duplicate or missing paths fail loudly. Headings inside fenced code blocks are ignored.
+
+## Common mistakes
+
+- Do not use `rig context get` for an arbitrary filesystem path; that command resolves context-library refs.
+- Do not hand-slice headings with `sed` or line numbers; the bundled resolver owns span and fence behavior.
+- Quote addresses in shell commands.

package/daemon/context-packs/skills/loading-addressable-markdown/manifest.yaml

@@ -0,0 +1,12 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "loading-addressable-markdown"
+version: "0.5.7"
+taxonomy: "skills"
+purpose: "Use when a mission, slice, dashboard, or task references Markdown as path#h2-slug or path#h2-slug/h3-slug outside the OpenRig context-pack library."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when a mission, slice, dashboard, or task references Markdown as path#h2-slug or path#h2-slug/h3-slug outside the OpenRig context-pack library."
+  - path: "scripts/resolve-markdown.mjs"
+    role: "reference"

package/daemon/context-packs/skills/loading-addressable-markdown/scripts/resolve-markdown.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MIN_LEVEL = 2;
+const MAX_LEVEL = 3;
+
+export class AddressResolutionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AddressResolutionError";
+  }
+}
+
+export function slugifyHeader(title) {
+  return title
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function parseAddress(address) {
+  const hashCount = (address.match(/#/g) ?? []).length;
+  if (hashCount > 1) {
+    throw new AddressResolutionError(`address '${address}' must contain at most one '#' separator`);
+  }
+
+  const [ref, headerPart] = hashCount === 1 ? address.split("#") : [address, undefined];
+  if (!ref) throw new AddressResolutionError(`address '${address}' has no file before '#'`);
+  if (headerPart === undefined) return { ref, headerPath: [] };
+
+  const headerPath = headerPart.split("/");
+  if (headerPath.some((segment) => segment.length === 0)) {
+    throw new AddressResolutionError(`address '${address}' has an empty header segment`);
+  }
+  if (headerPath.length > MAX_LEVEL - MIN_LEVEL + 1) {
+    throw new AddressResolutionError(`address '${address}' is too deep; addresses target H2 and H3 only`);
+  }
+  return { ref, headerPath };
+}
+
+function scanHeaders(lines) {
+  const hits = [];
+  let fence = null;
+
+  for (let lineNumber = 0; lineNumber < lines.length; lineNumber++) {
+    const line = lines[lineNumber];
+    const fenceMatch = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1][0];
+      const length = fenceMatch[1].length;
+      if (!fence) fence = { marker, length };
+      else if (fence.marker === marker && length >= fence.length) fence = null;
+      continue;
+    }
+    if (fence) continue;
+
+    const heading = line.match(/^(#{1,6})\s+(.*\S)\s*$/);
+    if (heading) hits.push({ level: heading[1].length, title: heading[2], line: lineNumber });
+  }
+  return hits;
+}
+
+export function parseMarkdownSections(text) {
+  const lines = text.split("\n");
+  const headers = scanHeaders(lines);
+  const sections = [];
+  let currentH2 = null;
+
+  for (let index = 0; index < headers.length; index++) {
+    const heading = headers[index];
+    if (heading.level < MIN_LEVEL || heading.level > MAX_LEVEL) {
+      if (heading.level < MIN_LEVEL) currentH2 = null;
+      continue;
+    }
+
+    const slug = slugifyHeader(heading.title);
+    if (heading.level === 2) currentH2 = slug;
+    const headerPath = heading.level === 2
+      ? [slug]
+      : currentH2 !== null
+        ? [currentH2, slug]
+        : [slug];
+    const fullEnd = headers.slice(index + 1).find((next) => next.level <= heading.level)?.line ?? lines.length;
+    const ownEnd = headers[index + 1]?.line ?? lines.length;
+
+    sections.push({
+      level: heading.level,
+      title: heading.title,
+      headerPath,
+      headerLine: heading.line,
+      text: lines.slice(heading.line, fullEnd).join("\n"),
+      ownText: lines.slice(heading.line, ownEnd).join("\n"),
+    });
+  }
+  return sections;
+}
+
+export function resolveAddress(text, headerPath) {
+  if (headerPath.length === 0) {
+    throw new AddressResolutionError("a bare file resolves without section lookup");
+  }
+
+  const sections = parseMarkdownSections(text);
+  const wanted = headerPath.join("/");
+  const hits = sections.filter((section) => section.headerPath.join("/") === wanted);
+  if (hits.length > 1) {
+    throw new AddressResolutionError(
+      `address '#${wanted}' is AMBIGUOUS: ${hits.length} sections match at lines ${hits.map((hit) => hit.headerLine + 1).join(", ")}`,
+    );
+  }
+  if (hits.length === 1) return hits[0];
+
+  const parentPath = headerPath.slice(0, -1).join("/");
+  const candidates = sections
+    .filter((section) => section.headerPath.slice(0, -1).join("/") === parentPath)
+    .map((section) => section.headerPath.join("/"));
+  throw new AddressResolutionError(
+    `address '#${wanted}' matches no header. ` +
+      (candidates.length > 0
+        ? `Addressable sections under '${parentPath || "(top)"}': ${candidates.join(", ")}.`
+        : `Addressable sections: ${sections.map((section) => section.headerPath.join("/")).join(", ") || "(none)"}.`),
+  );
+}
+
+function usage() {
+  return "Usage: resolve-markdown.mjs [--root DIR] FILE[#h2-slug[/h3-slug]]\n";
+}
+
+async function main(argv) {
+  let root = process.cwd();
+  const args = [...argv];
+
+  if (args[0] === "--help" || args[0] === "-h") {
+    process.stdout.write(usage());
+    return;
+  }
+  if (args[0] === "--root") {
+    if (!args[1]) throw new AddressResolutionError("--root needs a directory");
+    root = path.resolve(args[1]);
+    args.splice(0, 2);
+  }
+  if (args.length !== 1) throw new AddressResolutionError(usage().trim());
+
+  const { ref, headerPath } = parseAddress(args[0]);
+  const filePath = path.isAbsolute(ref) ? ref : path.resolve(root, ref);
+  const text = await readFile(filePath, "utf8");
+  process.stdout.write(headerPath.length === 0 ? text : resolveAddress(text, headerPath).text);
+}
+
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error.name ?? "Error"}: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/daemon/context-packs/skills/mission-slice-sop/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: mission-slice-sop
+description: >-
+  Use when starting, building, handing off, restoring, or closing a mission or slice under the default lightweight SDLC.
+metadata:
+  openrig:
+    stage: shipped
+    sibling_skills:
+      - queue-handoff
+      - seat-continuity-and-handover
+      - claude-compaction-restore
+---
+
+# Mission/Slice SOP — Part A
+
+Use this skill to actually **do** mission/slice work: track on the canonical files, record what you proved, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.**
+
+**Full convention SSOT:** repo `docs/reference/sdlc-conventions.md`; installed `$OPENRIG_HOME/reference/sdlc-conventions.md`. This skill is the concise Part-A teaching surface and does not replace the full convention.
+
+## THIS IS THE LIGHT DEFAULT — read this before anything else
+
+**The default for any slice is the inner loop:** ground yourself → build → **test with your own eyes** → iterate → **ONE** full-breadth review at the end. That is the whole process. It is not a reduced form of a better process; it IS the process.
+
+**Part B is defined in the SSOT above and applies only when the human operator — or an orchestrator explicitly relaying that decision — assigns it to a named piece of work.** You may not select it yourself. If you believe something earns it, say so in one sentence and **continue on Part A** until told otherwise.
+
+## Proportionality — this SOP serves shipping; it is not the work itself
+
+The working product is the deliverable. This bookkeeping exists so the work survives handoff, compaction, and review — nothing more. **Match it to stakes.** The `rig scope audit` backstop is **advisory and fail-open**: it never blocks a build and is not a gate you clear before proceeding. If you're spending more time on the convention files or the audit than on the running product, stop and go build. Running the full apparatus on a small change is the letter-worship failure, not diligence.
+
+## The three role contracts
+
+- **Planning agent:** records what the slice is for and what "done" looks like, in the slice's own words; produces mockups for UI deliverables so the builder has something to look at (a UI slice with no mockup is an incomplete plan; non-UI slices have none — not a gate).
+- **Build agent:** builds it, and **looks at the mockups**. Verifies by running the thing.
+- **QA agent (owns the compare):** compares planned vs delivered per deliverable, records the verdict and the note. On mismatch: fix-and-re-review, or kick back with the reason — never escalate a raw mismatch to the human.
+
+These three are a division of labour, not a chain of gates. One agent may hold all three on a small slice.
+
+## The current file contract
+
+> These files are the **operating surface of the work** — you track on them, record on them, hand off through them, and survive compaction on them. Keep them current because that is what lets the work survive. But they **serve** the product; they are not the product. If you're polishing files while the actual thing isn't shipping, you've inverted it: go build, then update them.
+
+- **Slice:** `SPEC.md`, `PROGRESS.md`, `PROOF.md`, and `proof/`.
+- **Mission:** `SPEC.md` and `NOTES.md`.
+
+## Per-file rules — WHO / WHEN / HOW
+
+### SPEC.md
+- **WHO:** the planning owner authors it; builders and reviewers read it as the scope and intent source.
+- **WHEN:** at creation and whenever scope changes.
+- **HOW:** a slice carries `intent:` in frontmatter and opens with `## Intent`, `## Mini-requirements`, and `## Proof contract`. A mission carries its intent and mission-level specification in the same authored node file. Keep depth proportional to the work.
+
+### PROGRESS.md
+- **WHO:** the orchestrator owns `§1` (current state); every agent logs its own outcomes.
+- **WHEN:** on material delivery-state changes and at acceptance.
+- **HOW:** one line per outcome (checkbox), link down for detail; keep frontmatter `stage`/`verified` honest.
+
+### PROOF.md + proof/
+- **WHO:** the impl/QA pair that worked the slice.
+- **WHEN:** before you call a slice done.
+- **HOW:** say what you verified and how you verified it — **by effect**: you ran it and looked at the result. Put supporting media under `proof/`. State plainly what is proven and what is **not**; an honest "this half is untested" is worth more than a checkmark. If a drop verb is in play for this slice, prefer it over hand-placing files so the artifact carries its own provenance.
+
+### NOTES.md
+- **WHO:** any agent updates `§1` (top-of-mind); each seat owns and appends to its own `§A–§X`.
+- **WHEN:** on material mission-context changes; a compacting agent **files its state here BEFORE compaction and reads it on restore.**
+- **HOW:** accruing tribal knowledge — `§1` ≤ 5–15 lines (gates, open decisions, surprises); per-seat continuation entries (latest = truth; other seats read-only). Pointer-first; don't duplicate.
+
+## The lifecycle (4 legs)
+
+**SCAFFOLD** (`rig scope` creates the files from templates) → **POPULATE** (agents fill them as work happens) → **PROJECT** (the Living Notes UI reads them into INTENT → PLAN → DELIVERED) → **VERIFY** (`rig scope audit`, advisory). "Loose freeform write + deterministic verify."
+
+## Hot-potato (handoffs)
+
+End every turn by passing the ball — a `rig queue handoff` to the next agent. The handoff verb is **transactional**: it closes the source as handed-off and mints the successor owned by `--to`, so the baton cannot be dropped. A handoff terminates only at the orchestrator seat, which holds the context to judge whether a park is legitimate.
+
+**A plain `rig queue create` row is informational** — a durable message. It is not a baton and does not carry this obligation. Use `handoff` when you are passing real work; use `create` when you are informing.
+
+Never go idle holding a baton.
+
+## Verify (deterministic backstop)
+
+Run `rig scope audit` at slice-close. Every convention check is **advisory / fail-open** — it records and advises, never blocks a write. Fix what's real, skip what isn't, keep moving. **A clean audit score is not required to proceed.**
+
+## Reading terminal captures — KNOWN GOTCHA: ghost-text autocomplete is NOT real
+
+When you `rig capture` a pane, **greyed / ghost autocomplete suggestions are NOT real content** — they are autocomplete *previews*, not typed, staged, or committed input. **This has been faking agents out a lot**: reading a ghost suggestion in a peer's input box as "staged text they're about to send," then reasoning on a string that was never there.
+
+**Rule:** ignore ghost/autosuggest text entirely. Only *committed/rendered* pane output is real. When it matters, verify at source (git, the queue, the actual event) — never off a capture's ghost line.
+
+## Moment-of-truth checklist
+
+- **Starting a slice?** → do you know what it's for and what done looks like? mockups attached (UI slices)? **Are you on the light path?** (You are, unless the mission owner assigned the overlay.)
+- **Finishing a slice?** → does `PROOF.md` say what you actually verified, by effect, including what is NOT covered? `PROGRESS.md` updated? mission `NOTES.md` refreshed? handed off via `rig queue handoff`?
+- **Compacting?** → file your state in mission `NOTES.md`; on restore, read it plus the active slice's `SPEC.md`, `PROGRESS.md`, and `PROOF.md`.
+- **Starting on a mission?** → read mission `SPEC.md`, `NOTES.md`, and the conventions SSOT.

package/daemon/context-packs/skills/mission-slice-sop/manifest.yaml

@@ -0,0 +1,10 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "mission-slice-sop"
+version: "0.5.7"
+taxonomy: "skills"
+purpose: "Use when starting, building, handing off, restoring, or closing a mission or slice under the default lightweight SDLC."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when starting, building, handing off, restoring, or closing a mission or slice under the default lightweight SDLC."