@openrig/cli 0.4.6 → 0.4.8

package/daemon/assets/plugins/openrig-core/skills/messaging-the-human/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: messaging-the-human
+description: |
+  When and who should send a message to the human operator, at
+  operator-human@your-rig — which routes straight to his Slack. Role-gated:
+  orchestrators and PMs use discretion to send anything worth his attention
+  (blockers, ships/completions, changes, good news); every other agent may
+  message him ONLY for a real blocker he can personally unblock, and routes
+  everything else through an orchestrator. Use to protect a scarce human's
+  manage-by-exception attention. NOT for agent-to-agent coordination (send/queue
+  a peer) or durable agent work-handoffs (use the queue to the owning seat).
+metadata:
+  openrig:
+    stage: provisional   # operator-directed, freshly authored 2026-07-30; hardens as agents use it
+    audience: ALL agents (universal); orchestrators + PMs are the primary discretionary senders
+    sibling_skills:
+      - queue-handoff
+      - status-not-chat-orchestrator
+      - human-in-the-loop
+      - openrig-user
+---
+
+# Messaging the Human
+
+## The one-line mechanism
+
+```bash
+rig send operator-human@your-rig "your message"
+```
+
+That goes straight to the human's Slack. That is the entire *how*. Everything
+below is the *when* and the *who* — which is the part that actually matters.
+
+## The mental model: the human is a scarce attention resource managing by exception
+
+There is one human. He is single-threaded across many agents, so his attention
+is the bottleneck of the whole system. He operates **by exception**: he wants to
+be pulled in when it genuinely matters and left alone when it doesn't. Every
+message you send spends a slice of that scarce attention.
+
+So the rule is not "can I reach him" (you can, trivially — one `rig send`). The
+rule is **should this reach him, coming from me**. Two things decide that: **who
+you are** (your role sets how much of his attention you're trusted to spend) and
+**what it is** (does it clear the bar for that role). Get the altitude wrong in
+either direction and you fail him: spam his Slack with noise, or sit silently on
+something he needed to know or could have unblocked.
+
+## WHO sends WHAT
+
+### If you are an ORCHESTRATOR or a PRODUCT MANAGER — use discretion
+
+You are the primary channel to the human. You may send **more than blockers** —
+anything you judge he would want to know:
+
+- something **shipped**, **completed**, or a **milestone** was hit
+- something **important happened**, or something **changed**
+- **environmental** changes (infra, hosts, tools, external state)
+- **good news**
+- anything that needs his attention, or is simply **good for him to know**
+
+There is no hard trigger here — it is judgment, and you are trusted with it. The
+test is: **"would he want to know this?"** If yes, send it. Lean toward sending
+genuine signal and real good news; do not manufacture noise or narrate routine
+churn. Discernment is the skill: you are curating his attention, not flooding it.
+
+### If you are ANY OTHER agent — blockers only
+
+You may message the human **only** when you are **blocked** and **he** is the one
+who can unblock you. That authority is universal — you do **not** have to be an
+orchestrator to raise a real blocker. But a blocker is the **only** thing you may
+send him directly.
+
+For anything that is **not** a blocker — an update, an idea, a question, an
+interesting finding — do **not** message the human. Send it to your
+**orchestrator**, who decides whether it is the human's role to handle or whether
+it is handled another way. The orchestrator/PM layer is the filter that protects
+the human's attention; routing through it is how the system keeps his queue at
+manage-by-exception altitude.
+
+## What counts as a real blocker (for non-orchestrator / non-PM agents)
+
+You are **blocked** AND **only the human** can clear it:
+
+- a **decision** only he can make,
+- **access / a credential / an authority** only he holds,
+- an **external action** only he can take (something in the real world, an
+  account or service he owns).
+
+Not a blocker: "I'd like a second opinion," "which approach do you prefer,"
+"here's a cool thing I found." Those go to your **orchestrator**. And if an
+orchestrator or PM *could* unblock you, route to them first — reserve the human
+for what genuinely only he can do.
+
+## How to write it (so it earns the interruption)
+
+- **Lead with the point.** Blocker: what is blocked + exactly what you need from
+  him. Update: the headline first, detail after.
+- **Full absolute paths.** No internal jargon he can't parse. **No backticks** in
+  `rig send` bodies (they trigger shell substitution).
+- `rig send` is an **ephemeral conversation** to his Slack. For a durable *agent*
+  work-handoff, use the queue to the owning seat — not the human.
+
+## Quick reference
+
+| You are… | You may send the human… |
+|---|---|
+| Orchestrator / PM | anything worth his attention — blockers, ships, completions, changes, good news (your discretion) |
+| Any other agent | a real blocker only he can unblock — **and nothing else** (everything else → your orchestrator) |

package/daemon/assets/plugins/openrig-core/skills/mission-slice-sop/SKILL.md

@@ -1,18 +1,9 @@
 ---
 name: mission-slice-sop
-description: Use when working a mission or slice — the full SDLC flow (intent → mini-requirements + proof contract → mockups → plan-lock → build → QA visual compare → `rig proof` drops → proof-lock) plus how to track, prove, hand off, and carry state across agents and compaction via the canonical files (PROGRESS.md / PROOF.md / MISSION_NOTES.md / MISSION_BRIEF.md / README.md / IMPLEMENTATION-PRD.md). Covers the convention sections the Living Notes UI projects, the two locks, the three role contracts, per-file WHO/WHEN/HOW rules, the four-legs lifecycle, hot-potato queue handoffs, the moment-of-truth checklist, the deterministic `rig scope audit` backstop, and the ghost-text capture gotcha.
+description: "Use when working a mission or slice: the SDLC flow (intent -> mini-requirements + proof contract -> mockups -> plan-lock -> build -> QA -> `rig proof` drops -> proof-lock), and how to track, prove, and hand off state across agents and compaction via PROGRESS.md / PROOF.md / MISSION_NOTES.md. Covers the two locks, role contracts, hot-potato queue handoff, and the `rig scope audit` backstop."
 metadata:
   openrig:
     stage: shipped
-    last_verified: "2026-07-06"
-    distribution_scope: product-bound
-    source_evidence: |
-      The canonical product SDLC skill: it teaches the full SDLC flow the
-      Living Notes UI projects — the convention sections, the proof-contract
-      pairing, the two staged-approval locks, C1 proof drops, and the three
-      role contracts. Conventions SSOT: docs/reference/sdlc-conventions.md
-      (shipped with the CLI package). The deterministic backstop is the
-      `rig scope audit` classifier.
     sibling_skills:
       - queue-handoff
       - seat-continuity-and-handover
@@ -21,7 +12,7 @@ metadata:
 
 # Mission/Slice SOP — how you work a mission & slice
 
-Use this skill to actually **do** mission/slice work the way OpenRig expects: author the convention sections, track on the canonical files, prove on them, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.** The deterministic backstop is `rig scope audit` — the audit classifier is the source of truth for adherence. The conventions themselves live in ONE place: **`docs/reference/sdlc-conventions.md`** (shipped with the CLI package) — this skill teaches the flow; the SSOT defines the formats.
+Use this skill to actually **do** mission/slice work the way OpenRig expects: author the convention sections, track on the canonical files, prove on them, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.** The deterministic backstop is `rig scope audit` — the audit classifier is the source of truth for adherence. The conventions themselves live in ONE document: **`docs/reference/sdlc-conventions.md`** in the repo, materialized by the daemon at **`$OPENRIG_HOME/reference/sdlc-conventions.md`** (default `~/.openrig/reference/sdlc-conventions.md`) on an installed package — this skill teaches the flow; the SSOT defines the formats.
 
 ## The SDLC flow (intent → proof)
 
@@ -36,7 +27,10 @@ intent → mini-requirements + proof contract → (UI slices: mockups)
 
 1. **Record intent** verbatim in the slice's `## Intent` section (`rig scope slice create` scaffolds it — every template kind).
 2. **Author the mini-requirements + proof contract**: `## Mini-requirements` is the concise one-glance tier (approval starts there); `## Proof contract` is a checkbox list of promised deliverables, each written as an observable outcome. UI deliverables name their planned mockup. The IMPLEMENTATION-PRD opens with the mini-requirements; everything between intent and proof is **elastic** — for a small slice the mini-requirements may BE the whole PRD.
+   - **PARSER CONTRACT (README AND IMPLEMENTATION-PRD, from first draft — a parser contract, not stylistic):** each doc carries a verbatim, **undecorated** `## Mini-requirements` heading with a **numbered list**, and a verbatim, **undecorated** `## Proof contract` heading whose checkbox (`- [ ]`) lines are **character-identical** across the two files. `rig scope audit` parses the PRD's `## Proof contract`; a prose rollup (e.g. `## Required proof …`) or any renamed/decorated heading trips **`proof_contract_missing_or_malformed`** and forces a post-lock format patch. Never rename or decorate these two headings, and keep the PRD's checkbox lines byte-for-byte equal to the README's.
+   - **REFERENCE-NOT-RESTATE (public / runnable examples — an honesty rail, from first draft):** any example that shows output or a value the referenced file/command **derives** — repo/runtime counts, current-state totals, hashes, timestamps — must **reference the source/derivation, omit the volatile value, or pin an explicitly stable fixture**; never hardcode the live count/state in a public or shipped doc. "Illustrative" derived output is a lie on a timer: `OK registry (2 manifests)` goes false the instant an entry lands. Write the invariant form (`OK registry (<N> manifests)`, N = entries in `registry.json`) or name the fixture instead of the momentary number. Restated derivable state in a public doc is a defect `rig scope audit` will not catch — the author owns it.
 3. **Plan-lock**: `rig scope slice approve <slice> --scope spec` — "the PRD matches the intent; THIS artifact set is what gets built." One daemon-side write: frontmatter stamp + append-only audit row.
+   - **PRE-PLAN-LOCK SELF-CHECK (MANDATORY):** before requesting `--scope spec`, run `rig scope audit --mission <mission> --json`, inspect the target slice's entry, and request the lock **only when that slice shows ZERO findings**. Do not carry a format defect (e.g. `proof_contract_missing_or_malformed`) into the lock and force a post-lock correction.
 4. **Build the locked set** — look at the mockups, not just the spec text.
 5. **QA visual compare**: for each deliverable, load the planned mockup, produce the real artifact in a test/demo environment, visually compare, and record the verdict.
 6. **Drop proof**: `rig proof add <slice> --artifact-type qa --verdict PASS --candidate-sha <tip> --money-evidence "…" --evidences "1,3" --media "walk.webm,panel.png" --self-check "…"` — the C1 header's closed sets validate at drop time; `--evidences` joins the drop to its proof-contract items and `--media` names the curated proof/-relative media the drop stands behind (that pairing + media set is what the UI's DELIVERED section renders).
@@ -106,8 +100,8 @@ When you `rig capture` a pane, **greyed / ghost autocomplete suggestions are NOT
 
 ## Moment-of-truth checklist
 
-- **Starting a slice?** → intent recorded verbatim? mini-requirements + proof contract authored? mockups attached (UI slices)? plan locked (`--scope spec`)?
+- **Starting a slice?** → intent recorded verbatim? **PRD carries a verbatim numbered `## Mini-requirements` + a verbatim `## Proof contract` whose `- [ ]` lines are character-identical to the README's** (parser contract)? **no example restates derivable state** — counts/hashes/timestamps referenced, omitted, or pinned to a stable fixture, never hardcoded (reference-not-restate)? mockups attached (UI slices)? **`rig scope audit --mission <m> --json` shows ZERO findings for this slice** BEFORE plan-lock (`--scope spec`)?
 - **Finishing a slice?** → every proof-contract item has curated evidence via `rig proof add … --evidences --media` (C1 drops — never only hand-placed files)? PROGRESS updated? MISSION_NOTES `§1` refreshed? proof locked (`--scope delivery`)? Handed off via queue?
 - **Committing?** → PROGRESS updated?
 - **Compacting?** → filed your state in MISSION_NOTES?
-- **Starting on a mission?** → read the mission README (incl. this SOP) + MISSION_NOTES + `docs/reference/sdlc-conventions.md`?
+- **Starting on a mission?** → read the mission README (incl. this SOP) + MISSION_NOTES + the conventions SSOT (`docs/reference/sdlc-conventions.md` in the repo, `$OPENRIG_HOME/reference/sdlc-conventions.md` on an installed package)?

package/daemon/assets/plugins/openrig-core/skills/openrig-skills/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: openrig-skills
+description: "Use when you're operating OpenRig and don't know which skill or context applies — this is the index of what ships with OpenRig, when to reach for each, and how to load it. Start here from a cold boot when nothing else is projected."
+metadata:
+  openrig:
+    stage: shipped
+---
+
+# OpenRig skills — the index (start here)
+
+You're running inside OpenRig. OpenRig ships a set of **skills** — small documents that tell you *when* to do something and *how*. This file is the map: what ships, when to reach for each, and how to load it. If you don't know which skill applies, or nothing is projected into your context, **start here.**
+
+## How OpenRig context works (30 seconds)
+
+Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file is the index over the whole shipped set. (For the full model of building/operating agent software, open `software-for-agents`.)
+
+Every row below names **how to reach the skill** — already-hot, or an exact load path. No row is a dead end.
+
+## The index
+
+### Always loaded — the universal spine (open its body when its moment hits)
+These are auto-delivered to every rig; their name+description are already in your context. Open the body when the "when" matches.
+
+- **forming-an-openrig-mental-model** — first boot, or you're unsure how the pieces fit. The runtime mental model.
+- **openrig-user** — you need a `rig` CLI command (send / queue / ps / whoami / scope / broadcast). The daily CLI surface.
+- **claude-compaction-restore** — you just compacted (Claude). Restore from durable evidence before resuming real work.
+- **session-compaction-and-restore** — preparing for, or recovering from, compaction (any runtime). The write- and read-side protocol.
+- **queue-handoff** — you're passing durable work to another seat or ending your turn. The queue is the work ledger, not chat.
+- **seat-continuity-and-handover** — handing your seat's work across a restart or to another owner.
+- **mission-slice-sop** — you're working a mission/slice (the SDLC: intent → mini-requirements + proof contract → build → QA → proof). The operating manual.
+- **messaging-the-human** — composing a message to the human. Plain language, no insider jargon.
+- **software-for-agents** — you want the full first-load model of how agent software is built and operated here.
+- **openrig-skills** — this index (you're reading it). Always loaded; the entry point to everything below.
+
+### Load when your role or task calls for it (repo-shipped, profile-selected)
+These ship in the OpenRig repo and reach a seat when its profile selects them. To use one, select it in your profile's `uses.skills`, or open it directly at `packages/daemon/specs/agents/shared/skills/core/<skill>/SKILL.md`.
+
+- **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `openrig-builder`).
+- **openrig-cmux** — driving the `cmux` terminal provider.
+- **openrig-herdr** — opening/managing seat terminals via the default proof-gated provider.
+- **agent-startup-and-context-ingestion** — a seat is booting and ingesting its startup context.
+- **topology-mutation-and-seat-management** — adding, removing, renaming seats or otherwise mutating rig topology.
+- **rig-lifecycle** — rig up / down / pause / resume lifecycle operations.
+- **applying-a-permission-policy** — a rig/seat has a permission policy attached, or you're setting one up (Locked / Standard / Open): translate it into the live harness config (Claude `settings.json` / Codex `config.toml`), agent-driven + interactive. Reached at onboarding and at rig setup/preflight. (YOLO / bypass is a launch-flag OpenRig sets, not this skill.)
+- **rig-bundles-and-shareable-artifacts** — packaging or installing a rig bundle / shareable artifact.
+- **cross-host-rig-commands** — reaching seats or queues on another host (`--host`).
+- **openrig-upgrade** — upgrading OpenRig or the daemon.
+- **agent-starters** — composing an agent's starter context / priming packs.
+- **specification-system** — authoring or reading AgentSpecs and rig specs.
+- **attention-queue** — managing the attention / needs-attention surface.
+- **human-in-the-loop** — deciding when to involve the human vs. proceed on your own authority.
+- **delegating-work** — deciding WHO does a task: yourself, a spawned subagent, or another agent that already holds the context (the when/whether decision, not the fan-out mechanics).
+- **watchdog** — monitoring or recovering a seat (health, restore, stuck state).
+- **session-source-fork** — forking a session's source/context.
+
+Pod handbooks (load when you're in that pod):
+- **orchestration-team** — you're orchestrating a rig: dispatching, monitoring, keeping the loop moving.
+- **development-team** — you're on the dev pod: building and shipping product changes.
+- **review-team** — you're reviewing: fresh scrutiny, anti-slop, empirical verification.
+
+Product-management craft (load when shaping/reviewing work):
+- **requirements-writer** — turning intent into clear requirements.
+- **plan-review** — reviewing a plan before it's built.
+- **exec-summary** — writing a decision-ready summary for a human.
+- **office-hours** — running a structured advisory / decision session.
+- **context-builder** — assembling the context a task or seat needs.
+- **backlog-capture** — capturing and shaping backlog items.
+- **ui-mockup** — producing a UI mockup for a slice.
+
+### Vendored craft — load when you're coding (ships with upstream provenance)
+General engineering skills OpenRig ships as vendored copies. Open when the task matches; they carry "modified by OpenRig" provenance.
+
+- **test-driven-development** — implementing a feature or bugfix: write the failing test first.
+- **verification-before-completion** — about to claim done / passing / fixed: run the check and read the output first.
+- **systematic-debugging** — debugging: find the root cause before the fix.
+- **writing-plans** — writing an implementation plan.
+- **executing-plans** — working through a written plan.
+- **brainstorming** — divergent ideation before converging.
+- **using-superpowers** — discovering and using the vendored "superpowers" skill set.
+- **agent-browser** — driving a browser (screenshot / screencast) from an agent.
+- **frontend-design** — designing frontend / UI.
+- **dogfood** — web-QA / dogfooding a shipped UI.
+
+## Need more than what ships here?
+
+This index covers the **shipped** surface. A dev host carries far more (factory, architecture, PM-craft, studio skills) reached through the host's own routers/codemaps — if you're on a builder host and need something not listed above, that deeper routing is the next hop, not a wall. (Host-scale routing is the subject of the context-routing architecture doc; at product scale, this one file is the whole map.)
+
+> Membership note: this index lists exactly the skills that ship with OpenRig. When a skill graduates into the shipped set it joins this index — the index and the shipped set stay one scope.