@openrig/cli 0.2.0 → 0.3.1

package/daemon/assets/plugins/openrig-core/skills/agent-startup-and-context-ingestion/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: agent-startup-and-context-ingestion
+description: Use when designing or auditing how an agent becomes useful after launch — AGENTS.md overlays, role files, skills, rig specs, workflow specs, startup checklists, refocus messages, "rig context" surface. Covers the 4 failure modes that make startup context fail (old rig spec misses current operating mode; current agents never told about new guidance; startup file as dumping ground; orchestrator transmits implementation without preserving product intent).
+metadata:
+  openrig:
+    stage: factory-approved
+    last_verified: "2026-05-04"
+    distribution_scope: product-bound
+    source_evidence: |
+      Cross-runtime restore/reentry packet standard + externalized memory
+      surfaces convention. Load at agent start; revisit after compaction.
+    sibling_skills:
+      - claude-compaction-restore
+      - seat-continuity-and-handover
+    transfer_test: pending
+---
+
+# Agent Startup and Context Ingestion
+
+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.
+
+It is the current concrete startup path inside the broader
+context-engineering-and-retrieval primitive. Startup gets a seat into
+the right initial shape; context engineering is the larger question of
+how a seat gets the right context for the work it is doing right now.
+
+**Most coordination failures are not tool failures; they are context
+failures.** Agents need to know their role, operating mode, coordination
+convention, boundaries, and current product intent. If startup context
+is scattered or stale, agents execute the wrong thing very efficiently.
+
+## Use this when
+
+- Authoring a new agent's startup files (role / culture / startup-context)
+- Refreshing a seat that's been running on stale guidance
+- Auditing whether agents got the current operating mode (not just what's in old files)
+- Designing the orchestrator → next-agent context-transmission shape
+- Building a startup map for OpenRig-building rigs
+
+## Don't use this when
+
+- The agent is being created via Agent Starter — the starter's manifest carries startup context
+- The work is artifact-backed mental-model rebuild from a packet — that's `claude-compaction-restore`
+- The intent is to ship reusable startup content as a skill — write the skill against the agentskills.io specification, not as inline startup prose
+
+## Failure modes (4)
+
+1. **A new agent starts from an old rig spec and misses the current operating mode.** Specs go stale; current state must be visible at startup, not just historical config.
+2. **Guidance is written to a file that future agents read, but current agents are never told.** File edits don't propagate to running sessions. Cultural rollout (broadcast + fleet-changes-feed) is needed alongside file edits.
+3. **A startup file becomes a dumping ground and loses the map-to-canonical-sources role.** Startup should point AT canonical sources; it shouldn't TRY to be one.
+4. **The orchestrator transmits implementation instructions without preserving product intent.** Instructions decay; intent travels.
+
+## Proof standard
+
+Startup proof should:
+
+1. **Launch or refresh** a seat
+2. **Inspect** what it actually read
+3. **Verify** it can state the current role, mode, active constraints, and next handoff convention **in its own words**
+
+## Cross-runtime startup paths (5; do not collapse)
+
+When a seat's startup is artifact-backed mental-model rebuild (active-work
+reentry case, distinct from reusable Agent Starters / priming packs):
+
+- See the **cross-runtime restore/reentry packet standard v0**
+- Source-trust ranking applies: **`rig whoami` > target rigspec > bounded latest transcript > full transcript > touched-files > `restore-summary.json`**
+
+## Memory surfaces consumed at startup
+
+The primary surfaces a startup ingestion path reads:
+
+- AGENTS / role / CULTURE / startup overlays (the per-seat identity layer)
+- startup replay context (what the agent did before the current boot)
+- restore / reentry packets and Agent Starters (cross-runtime startup path)
+
+Authority-rank + read-vs-write posture governs which surfaces a
+startup-ingestion path can write vs only read; treat overlays as
+write-restricted unless your role explicitly authors them.
+
+## Startup files vs skills (the distinction)
+
+Per `agent-startup-guide.md` (product reference doc) and the team handbook:
+
+| Startup files | Skills |
+|---|---|
+| Rig-specific, role-specific identity | Reusable SOPs / methodology / knowledge |
+| Tell agent WHO it is, WHAT it's working on, HOW this team operates | Tell agent HOW to do something (transferable across rigs) |
+| Examples: `role.md`, `CULTURE.md`, `startup/context.md` | Examples: `openrig-user`, `test-driven-development`, `dogfood` |
+| Authored per-rig | Authored once, used everywhere |
+
+Don't put skill content in startup files. Don't put identity content
+in skills. The 7-layer additive startup model (agent / profile / rig /
+culture / pod / member / operator) handles the layering.
+
+## See also
+
+- `forming-an-openrig-mental-model` skill — orientation for new agents
+- `claude-compaction-restore` skill — restore-time startup ingestion after compaction
+- `seat-continuity-and-handover` skill — packet shape that survives seat resets
+- https://agentskills.io/specification — the cross-runtime skill standard (what skill content should and shouldn't be)

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

@@ -0,0 +1,131 @@
+---
+name: claude-compaction-restore
+description: Use when a Claude Code session has just compacted, is about to compact, reached context limit, resumed after /compact, or needs to rebuild its working mental model from Claude JSONL transcripts and touched files.
+metadata:
+  openrig:
+    stage: factory-approved
+    last_verified: "2026-05-04"
+    distribution_scope: product-bound
+    source_evidence: |
+      Load-bearing for any OpenRig seat that may compact. PreCompact hook
+      is wired into Claude Code's settings (e.g. ~/.claude/settings.json)
+      so the restore packet is generated automatically before compaction.
+    sibling_skills:
+      - agent-startup-and-context-ingestion
+      - seat-continuity-and-handover
+---
+
+# Claude Compaction Restore
+
+Use this skill to preserve continuity before Claude Code compacts and to
+restore continuity after compaction. Do the work described here; do not merely
+explain the protocol.
+
+## If You Are About To Compact
+
+Prepare durable continuity before the context boundary.
+
+1. Identify the active task, queue item, mission/slice, branch or commit, and
+   current working directory.
+2. Record the current state: decisions made, files changed, commands/tests run,
+   evidence produced, blockers, caveats, and the next concrete step.
+3. Create or update a durable mental-model restore map. This map is the main
+   artifact future-you will use to rebuild context after compaction.
+4. In the restore map, write an ASCII file/folder tree of every path that
+   mattered to your working mental model during this session. Include:
+   - the active queue item or mission packet;
+   - mission notes, progress, decisions, and evidence files;
+   - Claude memory/project notes you used or wrote, especially when the memory
+     folder is shared by many agents;
+   - files with active edits or recently inspected source;
+   - root instructions such as `AGENTS.md`, `CLAUDE.md`, or `README.md`;
+   - as-built docs, codemaps, conventions, skills, and product docs needed
+     before code/review work;
+   - source files, tests, scripts, UI evidence, screenshots, logs, or reports
+     that shaped your current state.
+5. For every file or folder in the tree, add a short note explaining why it
+   matters and whether it is required reading after compaction.
+6. Write any important glue context that is not already on disk into the
+   handoff/restore map. This includes assumptions, partial conclusions, failed
+   paths, and why the listed files fit together.
+7. In the compaction summary, include the restore map path and the top required
+   reading paths from that map.
+
+## If You Just Compacted
+
+Treat your memory as unreliable until you restore from durable evidence.
+Restoration is your current task. Do not wait for a future user request or a
+new task assignment before reading the required files.
+
+1. Read any restore prompt, marker path, packet path, transcript path, restore
+   map, or extra instruction file named by the operator or OpenRig.
+2. Run the restore script from this skill:
+
+```bash
+node ~/.claude/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs --out /tmp/claude-compaction-restore
+```
+
+If the prompt names a specific Claude JSONL transcript, pass it explicitly:
+
+```bash
+node ~/.claude/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs /path/to/session.jsonl --out /tmp/claude-compaction-restore
+```
+
+3. Read the generated `restore-instructions.md`.
+4. Read the generated `touched-files.md`.
+5. Find and read the mental-model restore map if one exists. Treat it as the
+   highest-value guide to which memory files, mission files, source files, and
+   docs mattered before compaction.
+6. Identify the important files for the active task. The touched-file list is
+   a triage aid, not a complete inventory.
+7. Read every important file in full. Prioritize the restore map, Claude memory
+   files named in the map, Markdown state/planning files, queue/mission packets,
+   source files with active edits, root instruction files, and as-built or
+   codemap docs.
+8. After the required reads are complete, state:
+
+```text
+restored from packet at <path>; resumed at step <X>
+```
+
+Include the main files you read in full when you make that statement.
+
+## Required Read-Depth Audit
+
+After the first restore pass, audit yourself before continuing.
+
+1. List every file, packet, marker, restore map, instruction file, and source
+   document you were asked to read during restore.
+2. Mark each item as `FULL`, `PARTIAL`, or `NOT_READ`.
+3. You will be given a task where all of these files are required reading in
+   order to understand the task.
+4. Do not optimize for token conservation.
+5. Read every `PARTIAL` or `NOT_READ` item in full now.
+6. Report the final read-depth table before doing any substantive task work.
+
+## Guardrails
+
+- Do not silently launch fresh after compaction.
+- Do not continue from memory when restore evidence exists.
+- Do not defer required restore reading until a later user task. The restore is
+  the current task.
+- Do not skip root instructions, as-built docs, or codemaps before product
+  code/review work.
+- Do not treat the generated touched-file list as exhaustive.
+- Do not mark a file `FULL` unless you actually read the full file content
+  after compaction.
+- Do not resume task work until the restore sentinel and read-depth audit are
+  complete.
+
+## Failure Modes To Avoid
+
+1. **Confidently-wrong restoration**: claiming restoration after reading only
+   the touched-file list or summary.
+2. **Partial restore**: reading the first few files, then continuing before the
+   full reading list is complete.
+3. **Skipping project instructions**: missing `AGENTS.md`, `CLAUDE.md`,
+   `README.md`, as-built docs, or codemaps that govern the task.
+4. **Treating the packet as exhaustive**: ignoring mission or workspace files
+   that are important but were not discovered by the script.
+5. **Waiting for the next task**: treating restore reading as conditional on a
+   future user assignment instead of completing it immediately.

package/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore/scripts/precompact-hook.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const skillRoot = path.resolve(new URL("..", import.meta.url).pathname);
+const restoreScript = path.join(skillRoot, "scripts", "restore-from-jsonl.mjs");
+const outRoot = "/tmp/claude-compaction-restore";
+const defaultRestoreInstruction =
+  "Read the claude-compaction-restore skill and follow its \"If You Just Compacted\" protocol.";
+
+function emit(payload) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+function readHookInput() {
+  const raw = fs.readFileSync(0, "utf8").trim();
+  if (!raw) return {};
+  return JSON.parse(raw);
+}
+
+function getOpenRigHome() {
+  return process.env.OPENRIG_HOME || process.env.RIGGED_HOME || path.join(os.homedir(), ".openrig");
+}
+
+function expandInstructionPath(filePath) {
+  if (filePath.startsWith("~/")) return path.join(os.homedir(), filePath.slice(2));
+  if (filePath.startsWith("${OPENRIG_HOME}/")) {
+    return path.join(getOpenRigHome(), filePath.slice("${OPENRIG_HOME}/".length));
+  }
+  if (filePath.startsWith("$OPENRIG_HOME/")) {
+    return path.join(getOpenRigHome(), filePath.slice("$OPENRIG_HOME/".length));
+  }
+  return filePath;
+}
+
+function readInstructionFile(filePath) {
+  const expanded = expandInstructionPath(filePath);
+  if (!fs.existsSync(expanded)) return "";
+  return fs.readFileSync(expanded, "utf8");
+}
+
+function sessionKey(input) {
+  const raw = [
+    process.env.OPENRIG_SESSION_NAME,
+    process.env.RIGGED_SESSION_NAME,
+    input.session_id,
+    input.sessionId,
+    input.session_name,
+    input.sessionName,
+    input.transcript_path ? path.basename(input.transcript_path, ".jsonl") : "",
+  ].find((value) => typeof value === "string" && value.trim().length > 0) || "unknown-session";
+  return raw.replace(/[^a-zA-Z0-9_.@-]/g, "_");
+}
+
+function pendingMarkerPath(input) {
+  return path.join(getOpenRigHome(), "compaction", "restore-pending", `${sessionKey(input)}.json`);
+}
+
+function writePendingRestoreMarker(input, parsed, restoreInstruction, customMessage) {
+  const markerPath = pendingMarkerPath(input);
+  fs.mkdirSync(path.dirname(markerPath), { recursive: true });
+  const payload = {
+    version: 1,
+    createdAt: new Date().toISOString(),
+    sessionName: process.env.OPENRIG_SESSION_NAME || process.env.RIGGED_SESSION_NAME || null,
+    sessionId: input.session_id || input.sessionId || null,
+    transcriptPath: input.transcript_path || null,
+    cwd: input.cwd || null,
+    outputDir: parsed.outputDir,
+    restoreInstruction,
+    postCompactInstruction: customMessage || "",
+    expectedAck: "restored from packet at <path>; resumed at step <X>",
+    deliveredAt: null,
+    deliveryCount: 0,
+  };
+  fs.writeFileSync(markerPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  return markerPath;
+}
+
+// Slice 27 — read the OpenRig config directly (no daemon HTTP dependency
+// so the hook still works when the daemon isn't running or isn't
+// reachable from this process). Returns "" for either field when the
+// config is missing, malformed, or the policy isn't set. If the policy is
+// enabled but restore text has not been written yet, use OpenRig's default
+// instruction to load the canonical restore skill. Inline instructions and
+// file-path content are both included when both are configured.
+function readClaudeCompactionMessage() {
+  const configPath = path.join(getOpenRigHome(), "config.json");
+  let inline = "";
+  let filePath = "";
+  let inlineConfigured = false;
+  let filePathConfigured = false;
+  let policyEnabled = false;
+  try {
+    if (!fs.existsSync(configPath)) return "";
+    const raw = fs.readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const policy = parsed?.policies?.claudeCompaction;
+    if (policy && typeof policy === "object") {
+      policyEnabled = policy.enabled === true;
+      if (typeof policy.messageInline === "string") {
+        inlineConfigured = true;
+        inline = policy.messageInline;
+      }
+      if (typeof policy.messageFilePath === "string") {
+        filePathConfigured = true;
+        filePath = policy.messageFilePath;
+      }
+    }
+  } catch {
+    return "";
+  }
+
+  const parts = [];
+  if (inline && inline.length > 0) {
+    parts.push(`Inline restore instruction:\n${inline}`);
+  }
+  if (filePath && filePath.length > 0) {
+    try {
+      const fileText = readInstructionFile(filePath);
+      if (fileText) {
+        parts.push(`Additional restore instruction file (${filePath}):\n${fileText}`);
+      }
+    } catch {
+      // Keep any inline instruction; unreadable extra files degrade quietly.
+    }
+  }
+  if (parts.length > 0) return parts.join("\n\n");
+  if (policyEnabled && !inlineConfigured && !filePathConfigured) {
+    return defaultRestoreInstruction;
+  }
+  return "";
+}
+
+function buildSystemMessage(restoreInstruction, customMessage) {
+  if (!customMessage) return restoreInstruction;
+  return `${restoreInstruction}\n\n--- Operator-configured post-compaction restore instruction ---\n${customMessage}`;
+}
+
+try {
+  const input = readHookInput();
+  const args = [restoreScript, "--out", outRoot, "--json"];
+  if (input.cwd) args.push("--cwd", input.cwd);
+  if (input.transcript_path && input.transcript_path.endsWith(".jsonl") && fs.existsSync(input.transcript_path)) {
+    args.push(input.transcript_path);
+  }
+
+  const customMessage = readClaudeCompactionMessage();
+
+  const result = spawnSync("node", args, { encoding: "utf8" });
+  if (result.status !== 0) {
+    const baseFailure = `Claude compaction restore packet generation failed: ${(result.stderr || result.stdout || "unknown error").trim()}. After compaction, load the claude-compaction-restore skill and run restore-from-jsonl manually.`;
+    emit({
+      continue: true,
+      systemMessage: buildSystemMessage(baseFailure, customMessage),
+    });
+    process.exit(0);
+  }
+
+  const parsed = JSON.parse(result.stdout);
+  const baseRestore = `Pre-compaction restore seed packet prepared at ${parsed.outputDir}. This hook output is informational. After compaction, OpenRig may send a later normal user message asking you to restore from this packet; treat that later normal user message as the action request. The restore protocol is: load/read the claude-compaction-restore skill, run "node ~/.claude/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs --out /tmp/claude-compaction-restore --json" yourself when needed, read the generated restore-instructions.md, read the generated touched-files.md, identify remembered important files, read those files in full, read root/as-built/codemap docs before real work, then reply with "restored from packet at <path>; resumed at step <X>" with the files you read in full. If any step fails, report the failure explicitly.`;
+  const markerPath = writePendingRestoreMarker(input, parsed, baseRestore, customMessage);
+  emit({
+    continue: true,
+    systemMessage: buildSystemMessage(`${baseRestore} OpenRig also wrote a pending restore marker at ${markerPath}.`, customMessage),
+  });
+} catch (error) {
+  emit({
+    continue: true,
+    systemMessage: `Claude compaction restore hook errored: ${error.message}. After compaction, load the claude-compaction-restore skill and run restore-from-jsonl manually.`,
+  });
+}