simt-dev 0.6.3 → 0.7.0

package/src/agenthooks/render.mjs

@@ -1,6 +1,6 @@
 // One renderer per harness: the payload in, the decision out, and the config written.
 //
-// Five harnesses read a hook and no two agree on anything. The config path, the event
+// Six harnesses read a hook and no two agree on anything. The config path, the event
 // name, the shape of the document, the tool name for a shell command, the key holding
 // the command, and the JSON a hook answers with are all different, and none of them is
 // the same fact. So this module owns the differences and `policy.mjs` owns none of
@@ -11,9 +11,10 @@
 //   cursor       .cursor/hooks.json      preToolUse      {"version":1,"hooks":{E:[h]}}
 //   antigravity  .agents/hooks.json      PreToolUse      {"<name>":{E:[{matcher,hooks:[h]}]}}
 //   gemini       .gemini/settings.json   BeforeTool      {"hooks":{E:[{matcher,hooks:[h]}]}}
+//   opencode     .opencode/plugins/      execute.before  a JS plugin the tool owns whole
 //
 // The prompt-submit event (R29) is a second table, and it is shorter because the vendors
-// are: three of the five document a prompt event that can put text into the model's context,
+// are: four of the six document a prompt event that can put text into the model's context,
 // and a delivery is the only thing this tool does there. None takes a matcher — all
 // document that field for tool events, and a matcher a harness ignores is a matcher the
 // next person believes is filtering something.
@@ -21,6 +22,7 @@
 //   claude       .claude/settings.json   UserPromptSubmit   hookSpecificOutput.additionalContext
 //   codex        .codex/hooks.json       UserPromptSubmit   hookSpecificOutput.additionalContext
 //   gemini       .gemini/settings.json   BeforeAgent        hookSpecificOutput.additionalContext
+//   opencode     .opencode/plugins/      prompt             event.prompt.text, prepended
 //   cursor       .cursor/hooks.json      beforeSubmitPrompt CANNOT INJECT: block-only
 //   antigravity  .agents/hooks.json      (no prompt event documented)
 //
@@ -46,7 +48,9 @@
 
 import { CLI } from '../name.mjs';
 import { LOADERS } from '../projection/loaders.mjs';
+import { renderOpencodePlugin } from './opencode.mjs';
 import { EVENTS } from './policy.mjs';
+import { AGENT_HOOK_SHIM } from './shim.mjs';
 
 /** The seconds a hook is allowed before the harness gives up on it. */
 const TIMEOUT_SECONDS = 10;
@@ -54,13 +58,15 @@ const TIMEOUT_SECONDS = 10;
 /**
  * The hook's own entry point, as it appears inside every harness's config.
  *
- * A repository that has this tool has its binary on PATH, and `--harness` is explicit
- * rather than detected from the payload: a hook that guessed would answer in the wrong
- * harness's dialect when a payload arrived in an unexpected shape, and the harness would
+ * The shim, never the bare binary: a harness does not share the shell's PATH,
+ * so a config naming `simt` runs nothing on Claude and blocks everything on
+ * Cursor (review 0003 Q21). `--harness` stays explicit rather than detected
+ * from the payload: a hook that guessed would answer in the wrong harness's
+ * dialect when a payload arrived in an unexpected shape, and the harness would
  * read a decision it does not understand as no decision at all.
  */
 export function hookCommand(id, event = EVENTS[0]) {
-  return `${CLI} agent-hook ${event} --harness ${id}`;
+  return `${AGENT_HOOK_SHIM} ${event} --harness ${id}`;
 }
 
 /** The path a config file lives at, from the reader table rather than a second list. */
@@ -79,6 +85,104 @@ export function hookRows() {
   }));
 }
 
+/**
+ * The files an apply_patch body writes, one per header line.
+ *
+ * `Update`/`Add`/`Delete` name their file on the header itself. A move is the
+ * one header whose target is not on its own line: `*** Move File: <old>` is
+ * followed by the destination on the `+++` line, and a body that spells the
+ * destination as `*** Move to: <new>` says it outright. A move with neither
+ * spelling still writes its source out of the way, so the source is the floor
+ * a move guards.
+ */
+function asString(value) {
+  return typeof value === 'string' && value !== '' ? value : null;
+}
+
+function editFields(input = {}) {
+  const edit = {};
+  const oldString = asString(input.old_string ?? input.oldString ?? input.OldText ?? input.old_text);
+  const newString = asString(input.new_string ?? input.newString ?? input.NewText ?? input.new_text);
+  const content = asString(input.content ?? input.CodeContent ?? input.file_content ?? input.new_source ?? input.newSource);
+  if (oldString !== null) edit.old_string = oldString;
+  if (newString !== null) edit.new_string = newString;
+  if (content !== null) edit.content = content;
+  if (Array.isArray(input.edits)) {
+    const edits = input.edits
+      .filter((e) => e && typeof e === 'object')
+      .map((e) => ({
+        old_string: asString(e.old_string ?? e.oldString),
+        new_string: asString(e.new_string ?? e.newString),
+      }))
+      .filter((e) => e.old_string !== null || e.new_string !== null);
+    if (edits.length > 0) edit.edits = edits;
+  }
+  return edit;
+}
+
+function writeOf(path, input) {
+  if (!path) return null;
+  return { path, ...editFields(input ?? {}) };
+}
+
+/**
+ * The files an apply_patch body writes, one per header line.
+ *
+ * `Update`/`Add`/`Delete` name their file on the header itself. A move is the
+ * one header whose target is not on its own line: `*** Move File: <old>` is
+ * followed by the destination on the `+++` line, and a body that spells the
+ * destination as `*** Move to: <new>` says it outright. A move with neither
+ * spelling still writes its source out of the way, so the source is the floor
+ * a move guards.
+ *
+ * Each entry keeps its hunk text: without it the generated-region check cannot
+ * tell an edit outside the region from one inside it (review 0003 Q17), and
+ * every patch would deny as though it touched the region.
+ */
+function patchWrites(text) {
+  return patchFiles(text).map((f) => ({ path: f.path, patch: f.hunks }));
+}
+
+function patchFiles(text) {
+  const lines = String(text ?? '').split('\n');
+  const files = [];
+  let current = null;
+  const push = () => {
+    if (current !== null) files.push(current);
+    current = null;
+  };
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    const direct = /^\*\*\* (?:Update|Add|Delete) File: (.+)$/.exec(line);
+    if (direct !== null) {
+      push();
+      current = { path: direct[1].trim(), hunks: '' };
+      continue;
+    }
+    const moveTo = /^\*\*\* Move to: (.+)$/.exec(line);
+    if (moveTo !== null) {
+      push();
+      current = { path: moveTo[1].trim(), hunks: '' };
+      continue;
+    }
+    const moveFile = /^\*\*\* Move File: (.+)$/.exec(line);
+    if (moveFile !== null) {
+      push();
+      const next = lines[i + 1]?.trim();
+      const dest = next !== undefined && next.startsWith('+++ ') ? next.slice(4).trim() : moveFile[1].trim();
+      current = { path: dest, hunks: '' };
+      continue;
+    }
+    if (/^\*\*\* (Begin Patch|End Patch)/.test(line)) {
+      if (line.includes('End Patch')) push();
+      continue;
+    }
+    if (current !== null) current.hunks += `${lines[i]}\n`;
+  }
+  push();
+  return files.filter((f) => f.path !== '');
+}
+
 const ADAPTERS = {
   claude: {
     id: 'claude',
@@ -89,9 +193,15 @@ const ADAPTERS = {
     root: (p) => p.cwd,
     extract: (p) => ({
       command: p.tool_name === 'Bash' ? (p.tool_input?.command ?? null) : null,
-      writes: ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'].includes(p.tool_name)
-        ? [p.tool_input?.file_path].filter(Boolean)
-        : [],
+      // NotebookEdit spells its target `notebook_path`, not `file_path`: a key list
+      // that misses it is a lease the notebook can walk straight through (review
+      // 0003 Q16). Edit details travel with the path so the generated-region
+      // check can tell an edit outside the region from one inside it (Q17).
+      writes: ['Edit', 'Write', 'MultiEdit'].includes(p.tool_name)
+        ? [writeOf(p.tool_input?.file_path, p.tool_input)].filter(Boolean)
+        : p.tool_name === 'NotebookEdit'
+          ? [writeOf(p.tool_input?.notebook_path, p.tool_input)].filter(Boolean)
+          : [],
     }),
     deny: (message) => ({
       hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
@@ -124,11 +234,13 @@ const ADAPTERS = {
     root: (p) => p.cwd,
     extract: (p) => ({
       command: p.tool_name === 'Bash' ? (p.tool_input?.command ?? null) : null,
-      // apply_patch carries its targets inside the patch text, one header line per file.
+      // apply_patch carries its targets inside the patch text, one header line per file;
+      // a move names its destination on the `+++` line after `*** Move File:`, and the
+      // destination is the file the move writes (review 0003 Q16).
       writes:
         p.tool_name === 'apply_patch'
-          ? [...String(p.tool_input?.command ?? '').matchAll(/^\*\*\* (?:Update|Add|Delete) File: (.+)$/gm)].map((m) => m[1].trim())
-          : [],
+          ? patchWrites(String(p.tool_input?.command ?? ''))
+          : [], // entries carry {path, patch} so the region check maps hunks (Q17)
     }),
     deny: (message) => ({
       hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: message },
@@ -155,7 +267,7 @@ const ADAPTERS = {
     extract: (p) => ({
       command: p.tool_name === 'Shell' ? (p.tool_input?.command ?? null) : null,
       writes: ['Write', 'Edit'].includes(p.tool_name)
-        ? [p.tool_input?.file_path ?? p.tool_input?.path].filter(Boolean)
+        ? [writeOf(p.tool_input?.file_path ?? p.tool_input?.path, p.tool_input)].filter(Boolean)
         : [],
     }),
     deny: (message) => ({ permission: 'deny', user_message: message, agent_message: message }),
@@ -181,8 +293,8 @@ const ADAPTERS = {
       return {
         command: call.name === 'run_command' ? (args.CommandLine ?? null) : null,
         writes: ['write_to_file', 'replace_file_content', 'multi_replace_file_content'].includes(call.name)
-          ? [args.TargetFile].filter(Boolean)
-          : [],
+          ? [writeOf(args.TargetFile, args)].filter(Boolean)
+          : [], // CodeContent/old/new travel with the path for the region check (Q17)
       };
     },
     deny: (message) => ({ decision: 'deny', reason: message }),
@@ -207,7 +319,9 @@ const ADAPTERS = {
     root: (p) => p.cwd,
     extract: (p) => ({
       command: p.tool_name === 'run_shell_command' ? (p.tool_input?.command ?? null) : null,
-      writes: ['write_file', 'replace'].includes(p.tool_name) ? [p.tool_input?.file_path].filter(Boolean) : [],
+      writes: ['write_file', 'replace'].includes(p.tool_name)
+        ? [writeOf(p.tool_input?.file_path, p.tool_input)].filter(Boolean)
+        : [],
     }),
     deny: (message) => ({ decision: 'deny', reason: message }),
     // BeforeAgent appends text to the prompt for this turn only — the same lifetime as a
@@ -225,9 +339,34 @@ const ADAPTERS = {
       context: (text) => ({ hookSpecificOutput: { additionalContext: text } }),
     },
   },
+  opencode: {
+    id: 'opencode',
+    event: 'execute.before',
+    matcher: 'shell|write|edit',
+    // The plugin is a file the tool owns whole, not a config entry to merge:
+    // `file` routes `rendered` and `hookDocument` to its source (opencode.mjs).
+    file: true,
+    // A thrown error is the block; exit 2 is how the entry point signals it,
+    // and the reason the plugin throws is what `deny` prints.
+    denyExit: 2,
+    verified: 'opencode.ai/v2/docs/build/plugins/server, read 2026-10-29',
+    root: (p) => p.cwd,
+    extract: (p) => ({
+      command: p.tool === 'shell' ? (p.input?.command ?? null) : null,
+      writes: ['write', 'edit'].includes(p.tool) ? [writeOf(p.input?.path, p.input)].filter(Boolean) : [],
+    }),
+    deny: (message) => ({ reason: message }),
+    // session.hook('prompt') admits the prompt; the packet goes in front of it.
+    prompt: {
+      event: 'prompt',
+      verified: 'opencode.ai/v2/docs/build/plugins/server, read 2026-10-29',
+      context: (text) => ({ text }),
+    },
+    post: null,
+  },
 };
 
-/** The five adapters, in the order the reader table lists them. */
+/** The six adapters, in the order the reader table lists them. */
 export function adapters() {
   return hookRows()
     .filter((r) => r.path !== null)
@@ -240,6 +379,17 @@ export function adapter(id) {
   return row && hookPath(id) !== null ? row : null;
 }
 
+/**
+ * The session a payload claims, when it names one. Harness hook processes rarely
+ * carry `SIMT_SESSION`, so an agent is session `''` and is blocked by its own
+ * lease — the payload's own session id is the fallback (review 0003 Q20).
+ */
+export function payloadSession(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const direct = payload.session_id ?? payload.sessionId ?? payload.session?.id ?? payload.tool_input?.session_id ?? null;
+  return typeof direct === 'string' && direct.trim() !== '' ? direct : null;
+}
+
 /**
  * The facts a payload carries, and the root it names. An unknown shape yields none.
  *
@@ -252,7 +402,11 @@ export function adapter(id) {
  */
 export function factsFrom(row, payload, { root } = {}) {
   const override = typeof root === 'string' && root.trim() !== '' ? root : null;
-  return { root: override ?? row.root(payload) ?? process.cwd(), ...row.extract(payload ?? {}) };
+  return {
+    root: override ?? row.root(payload) ?? process.cwd(),
+    session: payloadSession(payload),
+    ...row.extract(payload ?? {}),
+  };
 }
 
 /** The document to print for a decision, or null when there is nothing to say. */
@@ -352,6 +506,9 @@ function group(row, event = EVENTS[0], command = hookCommand(row.id, event)) {
     // failClosed is set because a hooks file this tool wrote should not silently
     // degrade to fail-open on its own crash: the vendor's default turns a broken hook
     // into an absent one, and the whole point of writing it is that it runs.
+    // It is set only because the command is the repo shim (review 0003 Q21):
+    // failClosed on a bare-PATH binary would block every tool call on the machines
+    // where the binary is not installed, which is exactly the machines the shim exists for.
     return { command, timeout, matcher: row.matcher, failClosed: true };
   }
   return { matcher: row.matcher, hooks: [{ type: 'command', command, timeout }] };
@@ -359,7 +516,10 @@ function group(row, event = EVENTS[0], command = hookCommand(row.id, event)) {
 
 /** Whether a group is this tool's, judged by the command it runs and not by position. */
 function ours(entry) {
-  return JSON.stringify(entry).includes(`${CLI} agent-hook`);
+  const text = JSON.stringify(entry);
+  // The shim spelling first; the bare-binary spelling is the pre-shim install,
+  // still recognised (and migrated on the next install) for one release.
+  return text.includes(AGENT_HOOK_SHIM) || text.includes(`${CLI} agent-hook`);
 }
 
 function entries(row, config, event = EVENTS[0]) {
@@ -399,6 +559,12 @@ function withHook(row, config, { prompt = false, post = false, command } = {}) {
 
 /** The text `install` would write, or the reason the existing file cannot be read. */
 export function rendered(row, existing, options = {}) {
+  if (row.file) {
+    // The tool owns this file whole, so there is nothing to merge: the text is
+    // the plugin source and `updated` means only that the bytes differ.
+    const text = renderOpencodePlugin({ command: options.command ?? hookCommand(row.id), prompt: options.prompt });
+    return { text, action: existing === null ? 'created' : text === existing ? 'unchanged' : 'updated' };
+  }
   if (existing === null) return { text: `${JSON.stringify(withHook(row, {}, options), null, 2)}\n`, action: 'created' };
   let config;
   try {
@@ -422,6 +588,7 @@ export function rendered(row, existing, options = {}) {
 export function hookDocument(id, { command, prompt = false, post = false } = {}) {
   const row = adapter(id);
   if (!row) return null;
+  if (row.file) return renderOpencodePlugin({ command: command ?? hookCommand(id), prompt });
   const config = withHook(row, {}, { prompt, post, command });
   return `${JSON.stringify(config, null, 2)}\n`;
 }

package/src/agenthooks/shim.mjs

@@ -0,0 +1,55 @@
+// The agent-hook shim: how a harness runs this tool without it on PATH.
+//
+// A devDependency install puts `simt` in `node_modules/.bin`, not on a
+// harness's PATH. A harness config naming the bare `simt` binary therefore
+// runs nothing on Claude (a non-2 exit is silent: no enforcement) and blocks
+// every tool call on Cursor (its hook fails closed). The fix is a shim beside
+// the git shims, resolved the same way: `.simt-hooks/agent-hook` locates the
+// dispatcher with the shared `renderLocator` block and hands over, so every
+// harness config names the shim and never the bare binary (review 0003 Q21).
+//
+// The shim passes its own arguments through (`agent-hook "$@"`), so one file
+// serves every event and every harness: the config entry decides the event and
+// the `--harness` decides the dialect.
+
+import { renderLocator } from '../locate.mjs';
+import { BIN_ENV, CLI, PACKAGE_NAME } from '../name.mjs';
+import { HOOKS_DIR } from '../hooks/shim.mjs';
+import { localInstall } from '../distribute/release.mjs';
+import { packageVersion } from '../package-version.mjs';
+
+/** The shim inside the repository, as a harness config names it. */
+export const AGENT_HOOK_SHIM = `${HOOKS_DIR}/agent-hook`;
+
+/**
+ * @param {{npm?: boolean, version?: string}} [opts]
+ * @returns {string} POSIX sh source, LF-terminated, executable
+ */
+export function renderAgentHookShim({ npm = true, version } = {}) {
+  const v = version ?? packageVersion();
+  const install = npm ? `npm i -D ${PACKAGE_NAME}@${v}` : localInstall(v);
+  const D = '$';
+  return `#!/bin/sh
+# Generated by simt-dev. Do not edit.
+#
+# The harness entry point: every harness config runs this file, never the bare
+# \`${CLI}\` binary, because a harness does not share your shell's PATH. It only
+# locates the dispatcher and hands over. Reinstall with:
+# ${CLI} agent-hooks install --yes
+#
+# Resolution order is the git shims' order (src/locate.mjs):
+#   1. ${D}SIMT_DEV_BIN    explicit override, for CI images and odd checkouts
+#   2. node_modules/       the pinned project dependency
+#   3. .simt/bin/          the release binary this repository downloaded
+#   4. ${CLI} on PATH       a global install
+# If none resolves it REFUSES rather than exiting 0.
+
+set -eu
+
+ROOT=\"${D}(git rev-parse --show-toplevel 2>/dev/null || pwd)\"
+
+${renderLocator(`agent-hook \"${D}@\" --root \"${D}ROOT\"`, {
+    subject: 'the agent hook',
+    remedy: `REMEDY run: ${install}, or set ${BIN_ENV} to the ${CLI} binary, or remove the hook entry to opt out`,
+  })}`;
+}

package/src/agents/render.mjs

@@ -0,0 +1,277 @@
+// One renderer per harness for the agent file, and the plan the install writes.
+//
+// Six harnesses read a subagent and no two agree on the file. Five write a
+// markdown file with YAML frontmatter and a body that becomes the system prompt;
+// Codex writes a TOML file whose `developer_instructions` holds the same body.
+// The path, the extension, the frontmatter keys and the document shape are all
+// different, and none of them is the same fact. So this module owns the
+// differences and the command owns none of them:
+//
+//   opencode     .opencode/agents/simt-agent.md   markdown   description
+//   claude       .claude/agents/simt-agent.md     markdown   name, description
+//   cursor       .cursor/agents/simt-agent.md     markdown   name, description
+//   gemini       .gemini/agents/simt-agent.md     markdown   name, description
+//   codex        .codex/agents/simt-agent.toml    TOML       name, description, developer_instructions
+//   antigravity  .agents/agents/simt-agent.md     markdown   name, description
+//
+// The source of truth is ONE file in this repository, `agents/simt-agent.md`:
+// neutral frontmatter plus a harness-agnostic body. The renderer strips that
+// frontmatter and re-emits the keys each harness documents, so the body — the
+// part that says how to act — is written once and cannot drift between
+// harnesses. An agent is a file the tool owns whole, not a config entry to
+// merge, so `rendered` compares bytes and reports created, unchanged or updated.
+
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { PACKAGE_ROOT } from '../workspace.mjs';
+import { splitFrontmatter } from '../memory/decide.mjs';
+import { LOADERS } from '../projection/loaders.mjs';
+import { journaledWriteFile } from '../journal.mjs';
+
+/** The one agent this tool ships, and the filename stem every harness shares. */
+const AGENT_FILE = 'simt-agent.md';
+export const AGENT_STEM = 'simt-agent';
+
+/** The companion skill: the command reference the agent reads on demand. */
+const SKILL_SOURCE = join('skills', 'simt-commands', 'SKILL.md');
+export const SKILL_STEM = 'simt-commands';
+
+/**
+ * The per-harness differences. `frontmatter` returns the ordered [key, value]
+ * pairs a markdown harness documents; Codex has none because its shape is TOML,
+ * not frontmatter. The body is identical everywhere and is not a difference.
+ */
+const ADAPTERS = {
+  opencode: {
+    id: 'opencode',
+    format: 'md',
+    frontmatter: (agent) => [
+      ['description', agent.description],
+    ],
+  },
+  claude: {
+    id: 'claude',
+    format: 'md',
+    frontmatter: (agent) => [
+      ['name', agent.name],
+      ['description', agent.description],
+    ],
+  },
+  cursor: {
+    id: 'cursor',
+    format: 'md',
+    frontmatter: (agent) => [
+      ['name', agent.name],
+      ['description', agent.description],
+    ],
+  },
+  gemini: {
+    id: 'gemini',
+    format: 'md',
+    frontmatter: (agent) => [
+      ['name', agent.name],
+      ['description', agent.description],
+    ],
+  },
+  codex: {
+    id: 'codex',
+    format: 'toml',
+  },
+  antigravity: {
+    id: 'antigravity',
+    format: 'md',
+    frontmatter: (agent) => [
+      ['name', agent.name],
+      ['description', agent.description],
+    ],
+  },
+};
+
+/** The reader-table row for a harness's agents directory, or null when none is documented. */
+function agentInfo(id) {
+  const row = LOADERS.find((l) => l.id === id);
+  return row?.agents ?? null;
+}
+
+/**
+ * The path a harness reads the agent from, sourced from the reader table rather
+ * than spelled here. Null for a harness that documents no agents directory.
+ */
+export function agentPath(id) {
+  const info = agentInfo(id);
+  return info ? join(info.dir, `${AGENT_STEM}${info.ext}`) : null;
+}
+
+/**
+ * Every reader, with the agents path it documents and the note for the ones that
+ * do not. The command reports these so a harness this tool does not write is
+ * named rather than silent.
+ */
+export function agentRows() {
+  return LOADERS.map((l) => ({
+    id: l.id,
+    label: l.label,
+    path: l.agents ? join(l.agents.dir, `${AGENT_STEM}${l.agents.ext}`) : null,
+    note: l.agents ? l.agents.verified : (l.agentsNote ?? 'no agents file is documented'),
+  }));
+}
+
+/** The adapters that both have a reader-table path and a renderer, in reader order. */
+export function adapters() {
+  return agentRows()
+    .filter((r) => r.path !== null)
+    .map((r) => ADAPTERS[r.id])
+    .filter(Boolean);
+}
+
+/** One adapter by id, or null when the harness has no path or no renderer. */
+export function adapter(id) {
+  return ADAPTERS[id] && agentInfo(id) !== null ? ADAPTERS[id] : null;
+}
+
+/** Parse the neutral frontmatter of the source file: `key: value` lines. */
+function parseSimpleFront(front) {
+  const out = {};
+  for (const line of front.split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim();
+    const val = line.slice(idx + 1).trim();
+    if (key) out[key] = val;
+  }
+  return out;
+}
+
+/**
+ * The one agent, read from this repository's `agents/` directory. The body is
+ * the system prompt; `name` and `description` are re-emitted per harness.
+ */
+export async function loadAgent() {
+  const raw = await readFile(join(PACKAGE_ROOT, 'agents', AGENT_FILE), 'utf8');
+  const { front, body } = splitFrontmatter(raw);
+  const meta = parseSimpleFront(front ?? '');
+  if (!meta.name || !meta.description) {
+    throw new Error(`${AGENT_FILE} must declare a name and a description in its frontmatter`);
+  }
+  return { name: meta.name, description: meta.description, body: body.trim() };
+}
+
+/** The companion skill file, read verbatim from this repository. */
+async function loadSkill() {
+  return readFile(join(PACKAGE_ROOT, SKILL_SOURCE), 'utf8');
+}
+
+/**
+ * Where the skill lands in the receiving repo. The same heuristic `skills
+ * install` uses: respect an existing skills directory, default to `.agents/skills`.
+ */
+async function skillDestPath(root) {
+  let entries = [];
+  try {
+    const { readdir } = await import('node:fs/promises');
+    entries = await readdir(root);
+  } catch { /* fresh repo, no entries */ }
+  let dir;
+  if (entries.includes('.agents')) dir = '.agents/skills';
+  else if (entries.includes('.cursor')) dir = '.cursor/skills';
+  else if (entries.includes('.claude')) dir = '.claude/skills';
+  else dir = '.agents/skills';
+  return join(dir, SKILL_STEM, 'SKILL.md');
+}
+
+/** A basic TOML string: double-quoted, with backslashes and quotes escaped. */
+function tomlString(value) {
+  return '"' + String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+/** The markdown form: frontmatter the harness documents, a blank line, the body. */
+function renderMarkdown(adapterRow, agent) {
+  const fm = adapterRow.frontmatter(agent).map(([k, v]) => `${k}: ${v}`).join('\n');
+  return `---\n${fm}\n---\n\n${agent.body}\n`;
+}
+
+/**
+ * The Codex form: a TOML file. The body goes in `developer_instructions` as a
+ * multi-line basic string; a literal `"""` in the body would end the string, so
+ * one of its quotes is escaped.
+ */
+function renderToml(agent) {
+  const body = agent.body.replace(/"""/g, '\\"""');
+  return `name = ${tomlString(agent.name)}\ndescription = ${tomlString(agent.description)}\ndeveloper_instructions = """\n${body}\n"""\n`;
+}
+
+/**
+ * Render the agent for a harness and compare it to what is on disk. The tool
+ * owns the file whole, so the comparison is by bytes and the action is one of
+ * created, unchanged, updated.
+ */
+export function rendered(adapterRow, agent, existing) {
+  const text = adapterRow.format === 'toml' ? renderToml(agent) : renderMarkdown(adapterRow, agent);
+  if (existing === null) return { text, action: 'created' };
+  if (existing === text) return { text, action: 'unchanged' };
+  return { text, action: 'updated' };
+}
+
+/** Read a file as UTF-8, or null when it is not there. */
+async function readIfExists(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The agent files a repository should carry, one per harness that documents an
+ * agents directory, plus the companion skill file. Reads each existing file and
+ * renders what install would write, so a dry run and a run describe the same set
+ * of files. `harness` narrows the agent files to one; the skill is always included.
+ */
+export async function planAgents(root, { harness } = {}) {
+  const agent = await loadAgent();
+  const rows = harness === undefined ? adapters() : adapters().filter((a) => a.id === harness);
+  const plan = [];
+  for (const row of rows) {
+    const path = agentPath(row.id);
+    const existing = await readIfExists(join(root, path));
+    const result = rendered(row, agent, existing);
+    plan.push({ id: row.id, path, action: result.action, text: result.text });
+  }
+  // The companion skill: one file, not per-harness.
+  const skillText = await loadSkill();
+  const skillPath = await skillDestPath(root);
+  const skillExisting = await readIfExists(join(root, skillPath));
+  const skillAction = skillExisting === null ? 'created' : skillExisting === skillText ? 'unchanged' : 'updated';
+  plan.push({ id: 'skill', path: skillPath, action: skillAction, text: skillText });
+  return plan;
+}
+
+/**
+ * Write the agent files a plan names, journaled so `undo` restores the run.
+ * Skips files that are already unchanged. Returns the paths written.
+ */
+export async function writeAgentPlan(root, journal, plan) {
+  const written = [];
+  for (const p of plan.filter((x) => x.action !== 'unchanged')) {
+    await mkdir(join(root, dirname(p.path)), { recursive: true });
+    await journaledWriteFile(root, journal, join(root, p.path), p.text);
+    written.push(p.path);
+  }
+  return written;
+}
+
+/**
+ * Write just the skill file so `installedSkills` can find it before `plan()`
+ * computes the region. Called by `init` before the region is rendered.
+ */
+export async function writeSkillFile(root, journal) {
+  const text = await loadSkill();
+  const path = await skillDestPath(root);
+  const full = join(root, path);
+  const existing = await readIfExists(full);
+  if (existing === text) return null;
+  await mkdir(dirname(full), { recursive: true });
+  await journaledWriteFile(root, journal, full, text);
+  return path;
+}

package/src/argv.mjs

@@ -119,6 +119,14 @@ export const VALUE_FLAGS = new Set([
   'task',
   'workspace',
   'root',
+  // skills/graph: which registry to read. A value rather than a boolean because
+  // "a registry" without a path would have to guess, and the guess is the
+  // defect Q37 exists to remove (review 0003).
+  'registry',
+  // compare: how many repository rows to build at once (review 0003 Q38).
+  // A count, not a switch, because "parallel" without a cap is the burst this
+  // flag exists to prevent.
+  'concurrency',
   // skills install: which body of a multi-variant skill, and which source when the
   // bytes alone do not identify one.
   'variant',