open-plan-annotator 1.7.0 → 1.8.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Interactive plan annotation plugin for Claude Code",
-    "version": "1.7.0"
+    "version": "1.8.1"
   },
   "plugins": [
     {
       "name": "open-plan-annotator",
       "source": "./",
       "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-      "version": "1.7.0",
+      "version": "1.8.1",
       "author": {
         "name": "ndom91"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "open-plan-annotator",
   "description": "Interactive plan annotation UI: review, strikethrough, and comment on Claude's plans before approving. Fully local, no external services.",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "author": {
     "name": "ndom91"
   },

package/hooks/hooks.json

@@ -1,12 +1,29 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/install-runtime.mjs\"",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-context.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "PermissionRequest": [
       {
         "matcher": "ExitPlanMode",
         "hooks": [
           {
             "type": "command",
-            "command": "open-plan-annotator-binary",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/open-plan-annotator.mjs\"",
             "timeout": 345600
           }
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -27,7 +27,8 @@
   },
   "files": [
     "bin/open-plan-annotator.mjs",
-    "bin/open-plan-annotator-binary",
+    "scripts/install-runtime.mjs",
+    "scripts/session-context.mjs",
     "shared/cliHelp.mjs",
     "shared/cliMode.mjs",
     "shared/packageManager.mjs",
@@ -44,7 +45,6 @@
     "hooks/",
     "commands/",
     "skills/",
-    "CLAUDE.md",
     "README.md"
   ],
   "scripts": {
@@ -61,19 +61,17 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
-    "do-release": "./scripts/release.sh",
-    "prepack": "bun scripts/claude-pack-docs.mjs prepack",
-    "postpack": "bun scripts/claude-pack-docs.mjs postpack"
+    "do-release": "./scripts/release.sh"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.13",
-    "@types/node": "^25.6.0",
+    "@biomejs/biome": "^2.4.15",
+    "@types/node": "^25.6.2",
     "@types/bun": "^1.3.13",
-    "@typescript/native-preview": "^7.0.0-dev.20260430.1",
-    "typebox": "^1.1.37"
+    "@typescript/native-preview": "^7.0.0-dev.20260511.1",
+    "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "^1.14.30"
+    "@opencode-ai/plugin": "^1.14.48"
   },
   "peerDependencies": {
     "typebox": "*"
@@ -84,12 +82,13 @@
     }
   },
   "optionalDependencies": {
-    "@open-plan-annotator/runtime-darwin-arm64": "1.7.0",
-    "@open-plan-annotator/runtime-darwin-x64": "1.7.0",
-    "@open-plan-annotator/runtime-linux-arm64": "1.7.0",
-    "@open-plan-annotator/runtime-linux-x64": "1.7.0"
+    "@open-plan-annotator/runtime-darwin-arm64": "1.8.1",
+    "@open-plan-annotator/runtime-darwin-x64": "1.8.1",
+    "@open-plan-annotator/runtime-linux-arm64": "1.8.1",
+    "@open-plan-annotator/runtime-linux-x64": "1.8.1"
   },
   "overrides": {
     "uuid": "^14.0.0"
-  }
+  },
+  "packageManager": "bun@1.3.9"
 }

package/scripts/install-runtime.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// Installs the per-platform Bun-compiled runtime binary for open-plan-annotator
+// from the npm registry. Intended to run as a Claude Code SessionStart hook.
+//
+// Behavior:
+//   1. Determines plugin version from the sibling package.json.
+//   2. Picks the runtime package matching the host platform/arch.
+//   3. If the target binary already exists at the resolver's fallback path
+//      (`packages/runtime-<platform>-<arch>/bin/open-plan-annotator`), exits 0.
+//   4. Otherwise fetches the package manifest from the npm registry,
+//      downloads the tarball, verifies its integrity against `dist.integrity`,
+//      extracts it via system `tar`, and atomically moves the binary into place.
+//
+// Logs go to stderr only — stdout is reserved for hook protocol output.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { get as httpsGet } from "node:https";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SUPPORTED_PLATFORMS = new Set([
+  "darwin-arm64",
+  "darwin-x64",
+  "linux-arm64",
+  "linux-x64",
+]);
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = resolve(here, "..");
+
+const pkg = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf8"));
+const version = pkg.version;
+
+const platformKey = `${process.platform}-${process.arch}`;
+if (!SUPPORTED_PLATFORMS.has(platformKey)) {
+  process.stderr.write(
+    `open-plan-annotator: unsupported platform ${platformKey}. Supported: ${[...SUPPORTED_PLATFORMS].join(", ")}\n`,
+  );
+  process.exit(1);
+}
+
+const runtimePackage = `@open-plan-annotator/runtime-${platformKey}`;
+const targetDir = join(pluginRoot, "packages", `runtime-${platformKey}`, "bin");
+const targetBinary = join(targetDir, "open-plan-annotator");
+
+if (existsSync(targetBinary)) {
+  // Fast path: nothing to do.
+  process.exit(0);
+}
+
+process.stderr.write(
+  `open-plan-annotator: installing runtime ${runtimePackage}@${version} for ${platformKey}…\n`,
+);
+
+const start = Date.now();
+
+try {
+  const manifest = await fetchJson(
+    `https://registry.npmjs.org/${encodeURIComponent(runtimePackage)}/${encodeURIComponent(version)}`,
+  );
+
+  const tarballUrl = manifest?.dist?.tarball;
+  const integrity = manifest?.dist?.integrity;
+  if (typeof tarballUrl !== "string" || typeof integrity !== "string") {
+    throw new Error(
+      `npm manifest for ${runtimePackage}@${version} missing dist.tarball or dist.integrity`,
+    );
+  }
+
+  const tarballBuf = await fetchBuffer(tarballUrl);
+  verifyIntegrity(tarballBuf, integrity, runtimePackage, version);
+
+  const tmp = mkdtempSync(join(tmpdir(), "opa-runtime-"));
+  try {
+    const tarPath = join(tmp, "runtime.tgz");
+    writeFileSync(tarPath, tarballBuf);
+    execFileSync("tar", ["-xzf", tarPath, "-C", tmp], { stdio: "ignore" });
+
+    // npm tarballs always extract to a `package/` directory.
+    const extractedBinary = join(tmp, "package", "bin", "open-plan-annotator");
+    if (!existsSync(extractedBinary)) {
+      throw new Error(
+        `expected ${extractedBinary} after extracting ${runtimePackage}@${version}, not found`,
+      );
+    }
+
+    mkdirSync(targetDir, { recursive: true });
+    // renameSync may fail across filesystems; tmpdir is usually on the same
+    // device as the plugin cache, but if not, fall back to copy+unlink.
+    try {
+      renameSync(extractedBinary, targetBinary);
+    } catch (err) {
+      if (err?.code === "EXDEV") {
+        const buf = readFileSync(extractedBinary);
+        writeFileSync(targetBinary, buf);
+      } else {
+        throw err;
+      }
+    }
+    chmodSync(targetBinary, 0o755);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+
+  const elapsedMs = Date.now() - start;
+  process.stderr.write(
+    `open-plan-annotator: installed ${targetBinary} (${elapsedMs}ms)\n`,
+  );
+  process.exit(0);
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(
+    `open-plan-annotator: failed to install runtime ${runtimePackage}@${version}: ${message}\n`,
+  );
+  process.stderr.write(
+    `open-plan-annotator: rerun a Claude Code session to retry; ExitPlanMode will not work until install succeeds.\n`,
+  );
+  process.exit(1);
+}
+
+/**
+ * Fetch a URL with redirect handling and return the response buffer.
+ *
+ * @param {string} url
+ * @param {number} [maxRedirects]
+ * @returns {Promise<Buffer>}
+ */
+function fetchBuffer(url, maxRedirects = 5) {
+  return new Promise((resolveFetch, rejectFetch) => {
+    httpsGet(
+      url,
+      {
+        headers: {
+          "user-agent": `open-plan-annotator-installer/${version}`,
+          accept: "*/*",
+        },
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        if ((status === 301 || status === 302 || status === 307 || status === 308) && res.headers.location) {
+          if (maxRedirects <= 0) {
+            rejectFetch(new Error(`too many redirects for ${url}`));
+            res.resume();
+            return;
+          }
+          const next = new URL(res.headers.location, url).toString();
+          res.resume();
+          fetchBuffer(next, maxRedirects - 1).then(resolveFetch, rejectFetch);
+          return;
+        }
+        if (status !== 200) {
+          rejectFetch(new Error(`GET ${url} -> HTTP ${status}`));
+          res.resume();
+          return;
+        }
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => resolveFetch(Buffer.concat(chunks)));
+        res.on("error", rejectFetch);
+      },
+    ).on("error", rejectFetch);
+  });
+}
+
+/**
+ * @param {string} url
+ * @returns {Promise<unknown>}
+ */
+async function fetchJson(url) {
+  const buf = await fetchBuffer(url);
+  return JSON.parse(buf.toString("utf8"));
+}
+
+/**
+ * Verify a buffer against an npm Subresource Integrity string (e.g. "sha512-…").
+ *
+ * @param {Buffer} buf
+ * @param {string} integrity
+ * @param {string} pkgName
+ * @param {string} pkgVersion
+ */
+function verifyIntegrity(buf, integrity, pkgName, pkgVersion) {
+  const match = integrity.match(/^(sha\d+)-([A-Za-z0-9+/=]+)$/);
+  if (!match) {
+    throw new Error(
+      `unrecognized integrity format "${integrity}" for ${pkgName}@${pkgVersion}`,
+    );
+  }
+  const [, algo, expectedB64] = match;
+  const actualB64 = createHash(algo).update(buf).digest("base64");
+  if (actualB64 !== expectedB64) {
+    throw new Error(
+      `integrity mismatch for ${pkgName}@${pkgVersion}\n  expected ${algo}: ${expectedB64}\n  actual   ${algo}: ${actualB64}`,
+    );
+  }
+}

package/scripts/session-context.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// SessionStart hook: inject non-negotiable plan-routing instructions into
+// Claude's session context. Returns a JSON `hookSpecificOutput.additionalContext`
+// payload that Claude Code reads and injects into the session prompt.
+//
+// Why this is a hook and not a skill: skills are advisory and load lazily —
+// Claude judges relevance from frontmatter and can rationalize past it,
+// resulting in inline plans that bypass the annotator. Hook-injected context
+// is unconditional and always present, matching the binary nature of the
+// "always route plans through annotator" requirement.
+
+const additionalContext = `[open-plan-annotator] This session has the open-plan-annotator plugin installed.
+
+HARD RULE — any response that would contain ANY of the following MUST be routed through EnterPlanMode → ExitPlanMode (which fires the annotator UI):
+  • a multi-step proposal
+  • 3 or more file paths to create or modify
+  • 2 or more option/tradeoff comparisons for the user to choose between
+  • a section header like "Plan:" / "Steps:" / "Approach:" / "Implementation:" / "Concrete changes:"
+  • a numbered or bulleted list of action items the user is expected to react to
+  • a closing question like "OK to proceed?" / "sound good?" / "shall I…?"
+
+Never paste plans inline. The annotator IS the discussion surface — tradeoffs, options, and open questions belong inside the plan body where the user can comment on each one. Mixed-signal user messages (a directive plus "what do you think?") still route through the annotator; the exploratory clause means "include alternatives in the plan", not "skip the plan".
+
+Workflow:
+  • Assistant-initiated (you decided a plan is needed): call EnterPlanMode → draft → ExitPlanMode.
+  • User-initiated ("draft a plan", "/plan", etc.): invoke /annotate-plan <task>.
+
+Full trigger list and self-check rules in skill plan-review-triggers.`;
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext,
+    },
+  }),
+);

package/shared/runtimeResolver.mjs

@@ -1,6 +1,7 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
-import path from "node:path";
 import { createRequire } from "node:module";
+import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const RUNTIME_PACKAGE_MAP = {
@@ -19,12 +20,45 @@ export function getRuntimePackageName(platform = process.platform, arch = proces
 }
 
 export function resolveRuntimeBinary(options = {}) {
+  const attempt = () => tryResolveRuntimeBinary(options);
+
+  const first = attempt();
+  if (first.ok) return first.value;
+
+  // Skip installer for hard-failure conditions (unsupported platform): no
+  // amount of installing will produce a binary, and we'd waste a network
+  // round trip downloading the host's binary unnecessarily.
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  if (!getRuntimePackageName(platform, arch)) {
+    throw first.error;
+  }
+
+  // Last-resort recovery: invoke the SessionStart installer synchronously and
+  // retry resolution once. Useful for hosts that fetch this package without
+  // running `npm install` (and therefore skip the optionalDependencies that
+  // would otherwise pull the matching runtime binary). The Claude Code plugin
+  // install path is the canonical example, but it triggers the same script
+  // earlier via its SessionStart hook; this branch covers everyone else.
+  if (runInstaller(options)) {
+    const second = attempt();
+    if (second.ok) return second.value;
+    throw second.error;
+  }
+
+  throw first.error;
+}
+
+function tryResolveRuntimeBinary(options = {}) {
   const platform = options.platform ?? process.platform;
   const arch = options.arch ?? process.arch;
   const packageName = getRuntimePackageName(platform, arch);
 
   if (!packageName) {
-    throw new Error(`Unsupported platform ${getRuntimePlatformKey(platform, arch)}`);
+    return {
+      ok: false,
+      error: new Error(`Unsupported platform ${getRuntimePlatformKey(platform, arch)}`),
+    };
   }
 
   const requireFrom = createRequire(options.parentUrl ?? import.meta.url);
@@ -37,27 +71,66 @@ export function resolveRuntimeBinary(options = {}) {
     const workspaceBinaryPath = path.join(workspaceRoot, "packages", packageName.split("/").at(-1) ?? "", "bin", "open-plan-annotator");
     if (fs.existsSync(workspaceBinaryPath)) {
       return {
-        packageName,
-        packageRoot: path.dirname(path.dirname(workspaceBinaryPath)),
-        binaryPath: workspaceBinaryPath,
+        ok: true,
+        value: {
+          packageName,
+          packageRoot: path.dirname(path.dirname(workspaceBinaryPath)),
+          binaryPath: workspaceBinaryPath,
+        },
       };
     }
 
-    throw new Error(
-      `Missing runtime package ${packageName}. Reinstall open-plan-annotator for ${getRuntimePlatformKey(platform, arch)}.`,
-    );
+    return {
+      ok: false,
+      error: new Error(
+        `Missing runtime package ${packageName}. Reinstall open-plan-annotator for ${getRuntimePlatformKey(platform, arch)}.`,
+      ),
+    };
   }
 
   const packageRoot = path.dirname(packageJsonPath);
   const binaryPath = path.join(packageRoot, "bin", "open-plan-annotator");
 
   if (!fs.existsSync(binaryPath)) {
-    throw new Error(`Runtime package ${packageName} is installed but ${binaryPath} is missing. Rebuild or reinstall it.`);
+    return {
+      ok: false,
+      error: new Error(`Runtime package ${packageName} is installed but ${binaryPath} is missing. Rebuild or reinstall it.`),
+    };
   }
 
   return {
-    packageName,
-    packageRoot,
-    binaryPath,
+    ok: true,
+    value: {
+      packageName,
+      packageRoot,
+      binaryPath,
+    },
   };
 }
+
+/**
+ * Run `scripts/install-runtime.mjs` synchronously to lay down the per-platform
+ * runtime binary. Returns true if the installer ran successfully, false if it
+ * was unavailable or failed. Diagnostics go to stderr; this function never
+ * throws so a failure here falls through to the original missing-runtime
+ * error from the caller.
+ */
+function runInstaller(_options = {}) {
+  // Opt-out for callers that want to keep the old behavior (e.g. tests that
+  // assert the error path) or environments where re-entry would be harmful.
+  if (process.env.OPEN_PLAN_ANNOTATOR_SKIP_INSTALL === "1") return false;
+
+  const workspaceRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const installerPath = path.join(workspaceRoot, "scripts", "install-runtime.mjs");
+  if (!fs.existsSync(installerPath)) return false;
+
+  try {
+    execFileSync(process.execPath, [installerPath], {
+      stdio: ["ignore", "ignore", "inherit"],
+      timeout: 60_000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/skills/plan-review-triggers/SKILL.md

@@ -6,10 +6,10 @@ description: Required reading whenever drafting any multi-step proposal, impleme
 # Plan Review Triggers
 
 <!--
-Maintainer note: trigger rules below are mirrored in `CLAUDE.plugin.md` at the
-repo root. Skills are how the rules reach users who installed the Claude Code
-plugin via the marketplace (repo-root markdown does not load through that
-path). Keep both files in sync when editing trigger rules.
+This skill is the long-form trigger reference for end users who have the
+open-plan-annotator plugin installed. The terse always-on reminder lives in
+`scripts/session-context.mjs` (injected via the `SessionStart` hook); keep
+the two in rough sync when editing trigger rules.
 -->
 
 This plugin (open-plan-annotator) installs a hook on `ExitPlanMode` that opens a browser UI where the user marks up plans directly — deletions, replacements, insertions, comments — and returns structured feedback. Inline markdown plans bypass that workflow.

package/CLAUDE.md

@@ -1,105 +0,0 @@
-# open-plan-annotator: Plan Review Instructions
-
-<!--
-Maintainer note: this file's content is mirrored in
-`skills/plan-review-triggers/SKILL.md` because Claude Code plugin installs do
-not load repo-root markdown — only skills/, commands/, hooks/. Keep both files
-in sync when editing trigger rules. Sections that diverge intentionally
-(audience, framing) are still close enough that a side-by-side diff catches
-drift quickly.
--->
-
-## Why This Plugin Exists
-
-Markdown plans rendered in chat are read-only for the user. To give feedback they have to retype sections inline, which is awkward in a terminal. open-plan-annotator opens a browser UI where the user can mark up your plan directly — delete lines, replace text, insert steps, leave comments. Their annotations come back to you as structured feedback.
-
-**This is the user's required review surface for any multi-section proposal.** Inline plans bypass the tool the user installed and silently lose their preferred feedback workflow.
-
-This is distinct from `plannotator-review` (post-implementation code review). open-plan-annotator runs *before* code is written.
-
-## Hard Rule: Annotator Required When Triggers Match
-
-When any trigger below fires, you MUST route through the annotator. "Prefer" / "consider" do not apply. Inline plans are a bug.
-
-- Assistant-initiated (you decided a plan is needed): call `EnterPlanMode`, draft, then `ExitPlanMode` — this fires the annotator hook.
-- User-initiated ("draft a plan", "/plan", etc.): invoke the `/annotate-plan <task>` slash command. It runs the same plan-mode flow.
-
-## Trigger: Mechanical Heuristic
-
-Annotator REQUIRED when the response would contain ANY of:
-
-- 3 or more file paths to be created or modified
-- 2 or more option/tradeoff comparisons the user is asked to choose between
-- A `Plan:`, `Steps:`, `Concrete changes:`, `Implementation:`, `Approach:`, or similar section header
-- A numbered or bulleted list of action items the user is expected to react to
-- A multi-section proposal with decision points
-
-This is a hard gate. Count file paths. Count options. If the count crosses the line, you do not get to write the inline response.
-
-## Trigger: Task Shape
-
-Enter plan mode (or invoke the slash command) before any of:
-
-- Creating or modifying more than 2 files
-- Architectural or structural changes
-- Refactoring, migration, or feature additions
-- Bug fixes that require investigation
-- Anything the user has not explicitly described step-by-step
-
-## Trigger: Phrase Match
-
-Treat these as plan triggers regardless of length:
-
-- User says "draft a plan", "let's plan X", "what's the approach", "give me options", "how should we tackle this", "what would it look like"
-- Your response would contain "recommended approach", "implementation plan", "proposed fix", "rollout plan", "here's what I'd do", or "concrete file changes"
-- Any moment you would otherwise ask "want me to proceed?" / "shall I draft this?" / "OK to proceed?" / "sound good?"
-
-## Mixed Signals: Still Trigger
-
-When a user message combines directives ("let's add X", "can we Y") with an exploratory question ("what do you think?"), the annotator still applies. Do NOT collapse into a 2-3 sentence inline response just because one clause was exploratory.
-
-The annotator IS the discussion surface. Tradeoffs, options, and open questions belong inside the plan body where the user can comment on each one — not in flat chat where they would have to retype your bullets to push back. Treat exploratory clauses as "include alternatives in the plan", not "skip the plan".
-
-## Self-Check Before Sending
-
-Before emitting any response, scan it for these strings:
-
-- "Concrete file changes", "Concrete changes", "Plan:", "Steps:", "Implementation:", "Approach:"
-- "OK to proceed?", "Want me to proceed?", "Shall I…?", "Sound good?", "Confirm…?"
-- 3+ lines that look like file paths (`foo/bar.tsx`, `path/to/file.ts`)
-- Numbered list of more than 2 items each describing a code change
-- "**N.**" / "**Fix N —**" headers introducing proposed changes
-
-If ANY match: stop, discard the inline response, route through the annotator instead.
-
-## Do NOT Trigger For
-
-- Single-line fixes, typos, renames
-- Direct factual answers
-- Status updates or progress reports
-- Plans the user has already approved (do not re-prompt)
-- Pure research or exploration with no proposed actions
-- Trivial questions where a plan would be overhead
-- Replies to the user's questions ABOUT an already-submitted plan (answer the question, do not re-submit)
-
-## Plan Quality Standards
-
-When writing a plan, include:
-
-- Brief summary of what you understood the task to require
-- Specific files you intend to create or modify and why
-- Any assumptions you are making
-- Explicit question if anything is ambiguous
-- Tradeoffs / option comparisons inline in the plan (since mixed-signal user messages route here)
-
-## Workflow
-
-**Assistant-initiated (you decided a plan is needed):**
-draft mentally → call `EnterPlanMode` → draft plan → call `ExitPlanMode` → annotator opens → user annotates → revise based on feedback → re-exit when aligned.
-
-**User-initiated (user asked for a plan):**
-invoke `/annotate-plan <task>`. The command enters plan mode, drafts a plan, and exits to fire the annotator. Do not paste a multi-section plan inline and ask "sound good?" — that bypasses the annotator.
-
-## Slash Command
-
-`/annotate-plan <task>` is the canonical user-invoked entry point. When the user invokes it, follow the command body exactly. When you (the assistant) decide a plan is needed without the user invoking the command, prefer `EnterPlanMode` directly — the slash command is for user invocation, the tool is for assistant initiation. Both paths fire the same annotator hook.