audit-tools 0.28.0

package/scripts/remediate/postinstall.mjs

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { fileURLToPath } from "url";
+
+const pkgRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const packageVersion = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version ?? '0.0.0';
+const promptSourceFile = join(
+  pkgRoot,
+  "skills",
+  "remediate-code",
+  "remediate-code.prompt.md",
+);
+const skillSourceFile = join(pkgRoot, "skills", "remediate-code", "SKILL.md");
+const codexOpenAiAgentSourceFile = join(
+  pkgRoot,
+  "skills",
+  "remediate-code",
+  "agents",
+  "openai.yaml",
+);
+
+function readRequiredSource(path, label) {
+  if (!existsSync(path)) {
+    console.warn(
+      `remediate-code: ${label} source not found at ${path} - skipping global command install`,
+    );
+    process.exitCode = 0;
+    return null;
+  }
+  return readFileSync(path);
+}
+
+function readOptionalSource(path, label) {
+  if (!existsSync(path)) {
+    console.warn(
+      `remediate-code: ${label} source not found at ${path} - skipping optional install`,
+    );
+    return null;
+  }
+  return readFileSync(path);
+}
+
+// splitFrontmatter, writeGeneratedFile, and objectValue are single-sourced in
+// src/utils/hostAssets.ts. Import them from the compiled output best-effort;
+// fall back to inline definitions so postinstall works even on a fresh checkout
+// where dist/ may not be built yet.
+let _hostAssets = null;
+try {
+  _hostAssets = await import(join(pkgRoot, "dist", "remediate", "utils", "hostAssets.js"));
+} catch {
+  // dist not built yet — inline fallbacks below will be used.
+}
+
+function writeGeneratedFile(path, content) {
+  if (_hostAssets) return _hostAssets.writeGeneratedFile(path, content);
+  const action = existsSync(path) ? "updated" : "installed";
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+  return action;
+}
+
+function splitFrontmatter(text) {
+  if (_hostAssets) return _hostAssets.splitFrontmatter(text);
+  const normalized = text.replace(/\r\n/g, "\n");
+  const match = normalized.match(/^---\n[\s\S]*?\n---\n?/u);
+  return { body: match ? normalized.slice(match[0].length) : normalized };
+}
+
+const OPENCODE_REMEDIATE_EDIT_PERMISSION = {
+  "*": "ask",
+  ".remediation-artifacts/**": "allow",
+  "remediation-report.md": "allow",
+  "remediation-report.json": "allow",
+  "remediation-closing-result.json": "allow",
+};
+
+const OPENCODE_REMEDIATE_BASH_PERMISSION = {
+  "*": "ask",
+  "remediate-code": "allow",
+  "remediate-code ensure*": "allow",
+  "remediate-code next-step*": "allow",
+  "remediate-code prepare-document-dispatch*": "allow",
+  "remediate-code merge-document-results*": "allow",
+  "remediate-code prepare-implement-dispatch*": "allow",
+  "remediate-code merge-implement-results*": "allow",
+  "remediate-code validate-artifacts*": "allow",
+  "*remediate-code.mjs": "allow",
+  "*remediate-code.mjs* ensure*": "allow",
+  "*remediate-code.mjs* next-step*": "allow",
+  "*remediate-code.mjs* prepare-document-dispatch*": "allow",
+  "*remediate-code.mjs* merge-document-results*": "allow",
+  "*remediate-code.mjs* prepare-implement-dispatch*": "allow",
+  "*remediate-code.mjs* merge-implement-results*": "allow",
+  "*remediate-code.mjs* validate-artifacts*": "allow",
+  "git status*": "allow",
+  "git diff*": "allow",
+  "grep *": "allow",
+  "Select-String *": "allow",
+  "rm *": "deny",
+};
+
+function objectValue(value) {
+  if (_hostAssets) return _hostAssets.objectValue(value);
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+}
+
+// The scoped OpenCode permission merge helpers are single-sourced in
+// audit-tools/shared (global top-level scope vs. remediator agent scope).
+// Resolve them best-effort: on a fresh workspace checkout the shared dist may
+// not be built yet, in which case the OpenCode config deployment below is
+// skipped with a warning instead of failing the whole install.
+let sharedOpenCodePermissions = null;
+try {
+  const shared = await import("audit-tools/shared");
+  if (
+    typeof shared.mergeOpenCodeAgentPermissionRule === "function" &&
+    typeof shared.mergeOpenCodeGlobalPermissionRule === "function" &&
+    typeof shared.migrateOpenCodeGlobalExternalDirectory === "function" &&
+    typeof shared.withoutOpenCodeWildcard === "function"
+  ) {
+    sharedOpenCodePermissions = shared;
+  }
+} catch {
+  // Leave null; the OpenCode deployment step reports the skip.
+}
+
+// Remediator agent scope: managed rules win for specific patterns; an
+// existing user wildcard survives (the managed set is passed without "*").
+function renderOpenCodeAgentPermissionConfig(existing) {
+  const { mergeOpenCodeAgentPermissionRule, withoutOpenCodeWildcard } =
+    sharedOpenCodePermissions;
+  const existingPermission = objectValue(existing);
+  return {
+    ...existingPermission,
+    read: "allow",
+    glob: "allow",
+    grep: "allow",
+    edit: mergeOpenCodeAgentPermissionRule(
+      existingPermission.edit,
+      OPENCODE_REMEDIATE_EDIT_PERMISSION,
+      withoutOpenCodeWildcard(OPENCODE_REMEDIATE_EDIT_PERMISSION),
+    ),
+    bash: mergeOpenCodeAgentPermissionRule(
+      existingPermission.bash,
+      OPENCODE_REMEDIATE_BASH_PERMISSION,
+      withoutOpenCodeWildcard(OPENCODE_REMEDIATE_BASH_PERMISSION),
+    ),
+  };
+}
+
+// Global top-level scope: never seeds a bash wildcard or
+// external_directory['*']='allow', keeps the denylist hygiene rules, and
+// migrates away previously deployed broad rules whose value exactly matches
+// the historically managed value ('allow'). Non-matching values are untouched.
+function renderOpenCodeGlobalPermissionConfig(existing) {
+  const {
+    mergeOpenCodeAgentPermissionRule,
+    mergeOpenCodeGlobalPermissionRule,
+    migrateOpenCodeGlobalExternalDirectory,
+    withoutOpenCodeWildcard,
+  } = sharedOpenCodePermissions;
+  const existingPermission = objectValue(existing);
+  const merged = {
+    ...existingPermission,
+    read: "allow",
+    glob: "allow",
+    grep: "allow",
+    edit: mergeOpenCodeAgentPermissionRule(
+      existingPermission.edit,
+      OPENCODE_REMEDIATE_EDIT_PERMISSION,
+      withoutOpenCodeWildcard(OPENCODE_REMEDIATE_EDIT_PERMISSION),
+    ),
+    bash: mergeOpenCodeGlobalPermissionRule(
+      existingPermission.bash,
+      OPENCODE_REMEDIATE_BASH_PERMISSION,
+      withoutOpenCodeWildcard(OPENCODE_REMEDIATE_BASH_PERMISSION),
+    ),
+  };
+  const externalDirectory = migrateOpenCodeGlobalExternalDirectory(
+    existingPermission.external_directory,
+  );
+  if (externalDirectory === undefined) {
+    delete merged.external_directory;
+  } else {
+    merged.external_directory = externalDirectory;
+  }
+  return merged;
+}
+
+function mergeOpenCodeGlobalConfig(existing, promptBody) {
+  const parsed = existing ? JSON.parse(existing) : {};
+  const agent = objectValue(parsed.agent);
+  const existingRemediator = objectValue(agent.remediator);
+  return {
+    ...parsed,
+    command: {
+      ...objectValue(parsed.command),
+      "remediate-code": {
+        template: promptBody.trimStart(),
+        description: "Conversation-first code remediation",
+        agent: "remediator",
+        subtask: false,
+      },
+    },
+    permission: renderOpenCodeGlobalPermissionConfig(parsed.permission),
+    agent: {
+      ...agent,
+      remediator: {
+        ...existingRemediator,
+        description:
+          "Bounded remediation orchestration agent for the /remediate-code workflow.",
+        permission: renderOpenCodeAgentPermissionConfig(existingRemediator.permission),
+      },
+    },
+  };
+}
+
+function installMergedJson(path, buildMerged) {
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+  const merged = buildMerged(existing);
+  const action = existing ? "updated" : "installed";
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  return action;
+}
+
+const promptSource = readRequiredSource(promptSourceFile, "prompt");
+const skillSource = readRequiredSource(skillSourceFile, "skill");
+
+if (!promptSource || !skillSource) {
+  process.exit(0);
+}
+
+const postinstallStart = Date.now();
+let succeeded = 0;
+let failed = 0;
+
+const promptBody = splitFrontmatter(promptSource.toString("utf8")).body;
+const codexOpenAiAgentSource = readOptionalSource(
+  codexOpenAiAgentSourceFile,
+  "Codex skill UI metadata",
+);
+
+const installs = [
+  {
+    label: "Claude command",
+    path: join(homedir(), ".claude", "commands", "remediate-code.md"),
+    sourcePath: promptSourceFile,
+    content: Buffer.from(promptBody, "utf8"),
+  },
+  {
+    label: "Codex skill",
+    path: join(homedir(), ".codex", "skills", "remediate-code", "SKILL.md"),
+    sourcePath: skillSourceFile,
+    content: skillSource,
+  },
+  {
+    label: "Codex prompt",
+    path: join(
+      homedir(),
+      ".codex",
+      "skills",
+      "remediate-code",
+      "remediate-code.prompt.md",
+    ),
+    sourcePath: promptSourceFile,
+    content: promptSource,
+  },
+  ...(codexOpenAiAgentSource
+    ? [
+        {
+          label: "Codex skill UI metadata",
+          path: join(
+            homedir(),
+            ".codex",
+            "skills",
+            "remediate-code",
+            "agents",
+            "openai.yaml",
+          ),
+          sourcePath: codexOpenAiAgentSourceFile,
+          content: codexOpenAiAgentSource,
+        },
+      ]
+    : []),
+];
+
+for (const install of installs) {
+  try {
+    const action = writeGeneratedFile(install.path, install.content);
+    console.log(
+      `remediate-code: ${action} global ${install.label} at ${install.path}`,
+    );
+    succeeded++;
+  } catch (err) {
+    console.warn(
+      `remediate-code: could not install global ${install.label} (${err.message})`,
+    );
+    console.warn("  To install manually, copy from:");
+    console.warn(`    ${install.sourcePath}`);
+    console.warn("  to:");
+    console.warn(`    ${install.path}`);
+    failed++;
+  }
+}
+
+const opencodeGlobalConfig = join(
+  homedir(),
+  ".config",
+  "opencode",
+  "opencode.json",
+);
+if (!sharedOpenCodePermissions) {
+  // Expected when audit-tools/shared isn't built yet — notably during `npm ci`
+  // in CI, where postinstall runs before the shared build step. This is a SKIP,
+  // not a failure: counting it would trip the `failed > 0` exit-1 guard below and
+  // break `npm ci`. Genuine OpenCode write errors are still counted as failures.
+  console.warn(
+    "remediate-code: audit-tools/shared is unavailable (build the shared workspace first); skipping OpenCode config deployment",
+  );
+} else {
+  try {
+    const action = installMergedJson(opencodeGlobalConfig, (existing) =>
+      mergeOpenCodeGlobalConfig(existing, promptBody),
+    );
+    console.log(
+      `remediate-code: ${action} global OpenCode command in ${opencodeGlobalConfig}`,
+    );
+    succeeded++;
+  } catch (err) {
+    console.warn(
+      `remediate-code: could not install global OpenCode command (${err.message})`,
+    );
+    failed++;
+  }
+}
+
+// Install Antigravity plugin (global skill for Gemini IDE / Antigravity Hub)
+const antigravityPluginDir = join(
+  homedir(),
+  ".gemini",
+  "config",
+  "plugins",
+  "remediate-code",
+);
+const antigravityPluginJsonPath = join(antigravityPluginDir, "plugin.json");
+const antigravityPluginSkillPath = join(
+  antigravityPluginDir,
+  "skills",
+  "SKILL.md",
+);
+
+try {
+  const pluginJsonAction = writeGeneratedFile(
+    antigravityPluginJsonPath,
+    Buffer.from(
+      JSON.stringify(
+        { name: "remediate-code", version: packageVersion },
+        null,
+        2,
+      ) + "\n",
+    ),
+  );
+  console.log(
+    `remediate-code: ${pluginJsonAction} Antigravity plugin manifest at ${antigravityPluginJsonPath}`,
+  );
+
+  const skillAction = writeGeneratedFile(antigravityPluginSkillPath, skillSource);
+  console.log(
+    `remediate-code: ${skillAction} Antigravity plugin skill at ${antigravityPluginSkillPath}`,
+  );
+  succeeded++;
+} catch (err) {
+  console.warn(
+    `remediate-code: could not install Antigravity plugin (${err.message})`,
+  );
+  failed++;
+}
+
+console.log(`remediate-code: postinstall complete — ${succeeded} succeeded, ${failed} failed (${Date.now() - postinstallStart}ms)`);
+if (failed > 0) {
+  process.exitCode = 1;
+}

package/skills/audit-code/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: audit-code
+description: Conversation-first autonomous code auditing workflow for the /audit-code command.
+---
+
+# audit-code skill
+
+The canonical entrypoint is `/audit-code` in conversation.
+
+This skill should be treated as a conversational product surface first.
+
+## Primary contract
+
+Normal usage should:
+
+- run from conversation, not from manual shell arguments
+- avoid manual paths, provider flags, and model-selection arguments
+- advance the audit automatically until it completes or no further automatic progress is possible
+
+Semantic review should be delegated to bounded subagents whenever the host can
+dispatch them. The conversation orchestrator owns dispatch and ingestion control;
+it should not perform broad review itself when subagents are available.
+Entering `/audit-code` is explicit user authorization to fan out those review
+subagents; do not require a separate delegation request before parallel
+dispatch — unless `confirmation_recommended` is true (agent_count exceeds
+`sessionConfig.dispatch.confirm_threshold`, default 10), in which case pause for
+user confirmation.
+
+If the host cannot delegate to subagents, the conversation orchestrator may
+complete exactly one assigned review task, ingest it through the provided backend
+command, then stop so the user can rerun `/audit-code` from fresh context.
+In that fallback path it should not prepare packet dispatch, probe alternate
+backend subcommands, synthesize reports, or choose a smaller task; the first
+pending task and the exact worker command are the boundary.
+The backend writes a deterministic single-task fallback prompt for that case so
+the orchestrator does not need to infer the first task from a broad batch prompt.
+
+Subagent fan-out belongs to the host agent runtime rather than to repo-local
+backend provider settings.
+
+### Scope confirmation
+
+The loader emits a scope summary after the intake step (the first `next-step`):
+the resolved repo root, the auditable file count, whether git is available, and
+any mis-scope smells. It echoes `Auditing <root>, <N> files, git: yes/no` so the
+operator can see exactly what is about to be audited. When a mis-scope smell is
+set — the resolved root has no `.git` but an ancestor does, or the root is a
+workspace member of a parent monorepo — the loader pauses and requires explicit
+confirmation before continuing. Expect the workflow to pause on the first step
+when targeting a workspace subdirectory or a non-git root whose ancestor is a
+repo; in the normal case the echo is informational and the run proceeds without
+interruption. Resolution behaviour is unchanged — only the visibility and the
+confirm gate are added.
+
+When dispatch-plan entries include provider-neutral complexity and
+`model_hint.tier` metadata, a capable host may map those tiers to its own
+subagent models. The backend should not prescribe concrete model names.
+
+Bounded steps are a backend implementation detail, not the intended user experience.
+
+## Loader Protocol
+
+After `audit-code ensure --quiet` bootstraps the repository, ask the backend for
+exactly one next step. This is also the **capability handshake**: report what you
+can dispatch to *right now* on every `next-step` call so the backend sizes review
+packets to your real model instead of a conservative 32k floor.
+
+```bash
+audit-code next-step --host-max-active-subagents 4 --host-models '[{"rank":"small","context_tokens":32000,"output_tokens":8000},{"rank":"standard","context_tokens":200000,"output_tokens":32000},{"rank":"deep","context_tokens":200000,"output_tokens":64000}]'
+```
+
+Or with a single dispatch model:
+
+```bash
+audit-code next-step --host-max-active-subagents 4 --host-context-tokens 200000 --host-output-tokens 32000
+```
+
+Key flags:
+
+- `--host-max-active-subagents` — parallel subagent capacity (via the `Agent`/`task`
+  tool). Without it the backend assumes serial dispatch.
+- `--host-models` — ordered JSON array (lowest rank first) of models you can dispatch
+  subagents to *right now*, one entry per relative rank
+  (`"small"`, `"standard"`, `"deep"`). Ranks are relative capability labels — never
+  report model names to the backend. Each entry may carry an optional opaque
+  `model_id` used only to key per-model quota learning.
+- `--host-context-tokens` / `--host-output-tokens` — single-model shorthand. When
+  `--host-models` is also given, the roster wins.
+
+When a step prompt tells you to continue, repeat `audit-code next-step` with the
+same capability flags and follow only the newly returned `prompt_path`. Stop when
+the current step prompt tells you to stop.
+
+## Embedded Prompt Payload
+
+The prompt payload in `audit-code.prompt.md` remains the canonical instruction asset.
+
+The intended user setup is one global package install:
+
+```bash
+npm install -g auditor-lambda
+```
+
+That makes `audit-code` available on `PATH` and seeds user-level command/skill
+assets for hosts the package can safely update. The prompt self-bootstraps the
+current repository before advancing the audit:
+
+```bash
+audit-code ensure --quiet
+```
+
+That idempotent bootstrap writes repo-local fallback/guidance assets for
+supported hosts plus shared MCP setup guidance only when they are missing or
+stale. Codex uses the global skill installed by npm rather than a repo-local
+skill bundle.
+
+Use the explicit installer for repair or forced refresh:
+
+```bash
+audit-code install
+```
+
+Use direct prompt import only when the target host still needs it after bootstrap.
+
+## Repo-local fallback
+
+The repository still exposes a backend CLI wrapper:
+
+```bash
+audit-code
+```
+
+from the target repository root.
+
+When developing `auditor-lambda` itself, prefer the local wrapper at
+`packages/audit-code/audit-code.mjs` (there is no `audit-code.mjs` at the
+monorepo root):
+
+```bash
+node packages/audit-code/audit-code.mjs   # from the monorepo root
+```
+
+That keeps the run pinned to the local wrapper and local `dist/` output instead
+of whichever global `audit-code` binary happens to be on `PATH`.
+
+Debug one-step mode (prints the execution envelope for one bounded advance):
+
+```bash
+audit-code advance-audit
+```
+
+## Backend mode note
+
+For repo-local backend usage:
+
+- omitted provider remains `local-subprocess`
+- `local-subprocess` should stop cleanly once semantic review is needed and
+  expose scoped task artifacts for the slash-command orchestrator
+- `provider: "auto"` is the explicit opt-in best-effort routing mode
+- explicit provider names remain available when an operator wants a specific backend
+
+Those explicit provider names are backend compatibility bridges, not the intended default review owner.
+
+## Development rule
+
+Prefer the skill-first conversational contract over the CLI-first backend shape.

package/skills/audit-code/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "audit-code"
+  short_description: "Run the autonomous /audit-code repository audit workflow."
+  default_prompt: "Start /audit-code for this repository and continue until the audit completes or blocks for operator input."

package/skills/audit-code/audit-code.prompt.md

@@ -0,0 +1,112 @@
+---
+description: Autonomous local loop code auditing - loads one backend-rendered audit step at a time
+argument-hint: [target-dir]
+allowed-tools: [Read, Bash, Glob, Grep, Agent]
+---
+
+# `/audit-code` Loader
+
+You are the audit-code orchestrator for this conversation. The user-facing
+surface is `/audit-code`, but the backend owns every audit workflow branch.
+
+## Loader
+
+First, make sure the repository has current local audit assets:
+
+```bash
+audit-code ensure --quiet
+```
+
+When developing `auditor-lambda` itself, the entrypoint lives at
+`packages/audit-code/audit-code.mjs` (there is no `audit-code.mjs` at the
+monorepo root). From the monorepo root use:
+
+```bash
+node packages/audit-code/audit-code.mjs ensure --quiet
+```
+
+Then ask the backend for exactly one next step. This is also the **capability
+handshake**: report what you can dispatch to *right now* on every `next-step`
+call, so the backend sizes review packets to your real model instead of a
+conservative 32k floor. Report:
+
+- `--host-max-active-subagents` — how many review subagents you can run in
+  parallel (via the `Agent`/`task` tool). Without it the backend assumes serial
+  dispatch and sizes waves to one packet at a time.
+- `--host-models` — an ordered JSON array (lowest rank first) of the models you
+  can dispatch subagents to *right now*, one entry per relative rank:
+  `{"rank": "small"|"standard"|"deep", "context_tokens": N, "output_tokens": N}`.
+  Ranks are relative capability labels that line up with each packet's
+  `model_hint.tier` — never report model names to the backend. Report only ranks
+  you can actually dispatch to; the backend partitions and budgets each packet
+  against the window of the rank its risk routes it to. Discover the real
+  windows, do not guess smaller-than-real values. Each entry may carry an
+  optional opaque `model_id` (and `--host-model-id` is the single-model
+  equivalent) used only to key per-model quota learning — it is never
+  interpreted.
+- `--host-context-tokens` / `--host-output-tokens` — single-model shorthand when
+  every subagent runs on one model: the context window and output cap of that
+  model. When `--host-models` is also given, the roster wins. Omit both and
+  dispatch falls back to the conservative 32k default (many tiny packets).
+
+```bash
+audit-code next-step --host-max-active-subagents 4 --host-models '[{"rank":"small","context_tokens":32000,"output_tokens":8000},{"rank":"standard","context_tokens":200000,"output_tokens":32000},{"rank":"deep","context_tokens":200000,"output_tokens":64000}]'
+```
+
+Or with a single dispatch model:
+
+```bash
+audit-code next-step --host-max-active-subagents 4 --host-context-tokens 200000 --host-output-tokens 32000
+```
+
+`4` is a safe concurrency default for this host; raise it for more parallelism or
+lower it under rate-limit pressure. The backend's learned quota adapts from
+there. The token values should match the window of the model(s) dispatching the
+packets (e.g. 200000 / 32000 for a 200k-context model).
+
+When developing `auditor-lambda` itself, from the monorepo root use:
+
+```bash
+node packages/audit-code/audit-code.mjs next-step --host-max-active-subagents 4 --host-context-tokens 200000 --host-output-tokens 32000
+```
+
+Read the returned JSON only far enough to find `prompt_path`, then read and
+follow only that prompt. Do not read packet prompts, schemas, command catalogs,
+or handoff files unless the current step prompt explicitly instructs you to do
+so.
+
+If the returned step is a dispatch step, before launching subagents check
+`progress.confirmation_recommended` in `steps/current-step.json`:
+
+- If `progress.confirmation_recommended` is `true`, pause and ask the user:
+  "Ready to launch **{progress.dispatch_summary}** — continue?"
+  Wait for an affirmative reply before proceeding with subagent dispatch.
+- If `progress.confirmation_recommended` is `false` (or absent), proceed
+  immediately.
+
+After the **first** `next-step` (the intake step) completes, confirm the audit
+scope before proceeding. Read `scope_summary.json` from the `.audit-tools/audit/`
+directory. It contains `repo_root`, `auditable_file_count`, `git_available`, and
+`mis_scope_smells`. Then:
+
+- Echo one informational line to the user:
+  `Auditing <repo_root>, <auditable_file_count> files, git: <yes|no>`.
+- If `mis_scope_smells` is **non-empty**, display each smell as a warning and ask
+  `Auditing <repo_root>, <auditable_file_count> files, git: <yes|no> — proceed? (yes/no)`.
+  Wait for an affirmative reply before the next `next-step`. If the user declines,
+  stop and suggest the correct root (e.g. the ancestor git repo or monorepo root
+  named in the smell).
+- If `mis_scope_smells` is empty, the echo is informational only — continue
+  automatically without interrupting the workflow.
+
+Use MCP tools only as a compatibility adapter when direct shell access to
+`audit-code next-step` is unavailable. The MCP `start_audit` and
+`continue_audit` tools return the same one-step contract; they are not a
+separate orchestration path.
+
+When a step prompt tells you to continue, run `audit-code next-step` again with
+the same capability flags (`--host-max-active-subagents`, `--host-models`,
+`--host-context-tokens`, `--host-output-tokens`) and follow only the newly
+returned `prompt_path`.
+
+Stop when the current step prompt tells you to stop.

package/skills/audit-code/opencode-command-template.txt

@@ -0,0 +1,13 @@
+# audit-code
+
+Use `audit-code next-step` as the primary interface to the audit workflow.
+
+1. Run `audit-code next-step` directly when shell access is available.
+2. If MCP is your only available interface, call `start_audit` or `continue_audit`; both return the same one-step contract.
+3. Read `prompt_content` in the response and follow it.
+4. When a step completes (not blocked), run `audit-code next-step` again or call `continue_audit` as the compatibility adapter.
+5. Stop when the step instructions say to stop.
+
+Use the `task` tool or equivalent for subagent dispatch when the step tells you to fan out review work.
+
+If neither shell access nor `start_audit` is available, stop and report that no next-step interface is connected.