open-plan-annotator 1.8.6 → 1.9.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Interactive plan annotation plugin for Claude Code",
-    "version": "1.8.6"
+    "version": "1.9.0"
   },
   "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.8.6",
+      "version": "1.9.0",
       "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.8.6",
+  "version": "1.9.0",
   "author": {
     "name": "ndom91"
   },

package/README.md

@@ -11,19 +11,19 @@ Select text to <code>strikethrough</code>, <code>replace</code>, <code>insert</c
 
 ## How It Works
 
-1. Your coding agent (Claude Code or OpenCode) finishes writing a plan
+1. Your coding agent (Claude Code, OpenCode, and pi) finishes writing a plan
 2. The plugin launches an ephemeral HTTP server and opens a React UI in your browser
 3. You review the plan and annotate it — strikethrough, replace, insert, or comment on any section
 4. **Approve** to let the agent proceed, or **Request Changes** to send your annotations back as structured feedback
 5. The agent revises the plan and the cycle repeats until you're satisfied
 
-Everything runs locally. Nothing leaves your machine.
+Everything runs locally.
 
-![](.github/assets/screenshot_light_004.png)
+![](.github/assets/screenshot_005.png)
 
 ## Install
 
-`open-plan-annotator` is package-managed: the plugin package installs the local platform runtime it needs. There is no first-run binary download and no in-app updater.
+`open-plan-annotator` is package-managed as a plugin within your harness of choice. The main plugin package then installs the specific local platform runtime it needs for your host (`linux`/`darwin`, `x86_64`/`arm64`, etc). After installing the plugin, your agent will call `open-plan-annotator` autonomously when you ask it to "make a plan" or any similar such comment, including in claude-code specifically as a hook when exiting `PlanMode`. Alternatively, you can call it yourself explicitly via the exposed command. See below for more details.
 
 ### Claude Code
 
@@ -48,7 +48,7 @@ Add the plugin to your OpenCode config (`opencode.json` or `.opencode/config.jso
 
 ```json
 {
-  "plugin": ["open-plan-annotator@latest"]
+  "plugin": ["open-plan-annotator@1.8.7"]
 }
 ```
 
@@ -96,12 +96,27 @@ This adds the `open-plan-annotator` command. To verify the resolved runtime:
 open-plan-annotator doctor
 ```
 
+You can also review a Markdown plan directly from disk, which is useful for agents without a native plugin:
+
+```sh
+open-plan-annotator review /absolute/path/to/plan.md
+```
+
+The command opens the same local review UI and blocks until approval or requested changes. It prints review result JSON to stdout when the user is done.
+
+Generic agent setup instructions are available with:
+
+```sh
+open-plan-annotator agent-setup
+open-plan-annotator help agent
+```
+
 ## Updates
 
-- Claude Code: update the marketplace/plugin install, then restart Claude Code.
-- OpenCode: update the installed npm plugin through OpenCode, then restart OpenCode.
-- Pi: update the Pi extension, then restart Pi.
-- Manual/global install: update the npm package, then rerun `open-plan-annotator`.
+- **Claude Code**: navigate to the `/plugin` -> "Installed" -> `open-plan-annotator` entry and select "Update", then restart Claude Code.
+- **OpenCode**: bump the version number in your `opencode.jsonc` `plugins` `open-plan-annotator` entry, then restart OpenCode.
+- **Pi**: update the Pi extension, then restart Pi.
+- **Manual/global install**: update the npm package, then rerun `open-plan-annotator`.
 
 ## Keyboard Shortcuts
 

package/bin/open-plan-annotator.mjs

@@ -4,10 +4,12 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { buildCliHelpText, buildUnknownCommandPrefix } from "../shared/cliHelp.mjs";
+import { AGENT_SETUP_TEXT } from "../shared/agentSetup.mjs";
+import { buildCliHelpText, buildUnknownCommandPrefix, isAgentHelpTopic } from "../shared/cliHelp.mjs";
 import { resolveCliMode } from "../shared/cliMode.mjs";
 import { detectPackageManager } from "../shared/packageManager.mjs";
 import { resolveRuntimeBinary } from "../shared/runtimeResolver.mjs";
+import { buildRuntimeEnv } from "../shared/runtimeEnv.mjs";
 import { buildUpdateMessage } from "../shared/updateMessage.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -22,10 +24,20 @@ if (cliMode === "version") {
 }
 
 if (cliMode === "help") {
+  if (isAgentHelpTopic(process.argv[3])) {
+    console.log(AGENT_SETUP_TEXT);
+    process.exit(0);
+  }
+
   console.log(buildCliHelpText(VERSION));
   process.exit(0);
 }
 
+if (cliMode === "agentSetup") {
+  console.log(AGENT_SETUP_TEXT);
+  process.exit(0);
+}
+
 if (cliMode === "doctor") {
   await printDoctor();
   process.exit(0);
@@ -68,14 +80,15 @@ try {
   process.exit(1);
 }
 
+const childEnv = buildRuntimeEnv({
+  cliMode,
+  packageManager: detectPackageManager({ installPath: fileURLToPath(import.meta.url) }),
+});
+
 const child = spawn(runtime.binaryPath, process.argv.slice(2), {
   stdio: ["pipe", "pipe", "inherit"],
   detached: true,
-  env: {
-    ...process.env,
-    OPEN_PLAN_HOST: process.env.OPEN_PLAN_HOST || "claude-code",
-    OPEN_PLAN_PKG_MANAGER: detectPackageManager({ installPath: fileURLToPath(import.meta.url) }),
-  },
+  env: childEnv,
 });
 
 child.stdin.write(stdinBuffer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.8.6",
+  "version": "1.9.0",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -28,12 +28,14 @@
   "files": [
     "bin/open-plan-annotator.mjs",
     "scripts/install-runtime.mjs",
+    "shared/agentSetup.mjs",
     "scripts/session-context.mjs",
     "shared/cliHelp.mjs",
     "shared/cliMode.mjs",
     "shared/packageManager.mjs",
     "shared/updateMessage.mjs",
     "shared/runtimeResolver.mjs",
+    "shared/runtimeEnv.mjs",
     "shared/updateHints.mjs",
     "shared/versionInfo.mjs",
     "shared/planReview.mjs",
@@ -82,10 +84,10 @@
     }
   },
   "optionalDependencies": {
-    "@open-plan-annotator/runtime-darwin-arm64": "1.8.6",
-    "@open-plan-annotator/runtime-darwin-x64": "1.8.6",
-    "@open-plan-annotator/runtime-linux-arm64": "1.8.6",
-    "@open-plan-annotator/runtime-linux-x64": "1.8.6"
+    "@open-plan-annotator/runtime-darwin-arm64": "1.9.0",
+    "@open-plan-annotator/runtime-darwin-x64": "1.9.0",
+    "@open-plan-annotator/runtime-linux-arm64": "1.9.0",
+    "@open-plan-annotator/runtime-linux-x64": "1.9.0"
   },
   "overrides": {
     "uuid": "^14.0.0"

package/shared/agentSetup.mjs

@@ -0,0 +1,20 @@
+const REVIEW_COMMAND = 'open-plan-annotator review "/absolute/path/to/plan.md"';
+
+export const AGENT_SETUP_TEXT = `## Open Plan Annotator
+
+Use Open Plan Annotator when the user wants to review a plan, proposal, implementation strategy, migration path, rollout plan, or other approval-oriented plan before code is written.
+
+For agents without a native Open Plan Annotator integration:
+
+1. Write the plan to a Markdown file on disk.
+2. Run:
+
+\`\`\`sh
+${REVIEW_COMMAND}
+\`\`\`
+
+3. Leave the command running until the user approves or requests changes.
+4. If the result is approved, proceed with implementation immediately.
+5. If changes are requested, revise the plan using the returned feedback and submit the revised Markdown file for review again.
+
+After approval, do not open another plan review unless the user explicitly asks to revise or re-plan.`;

package/shared/cliHelp.mjs

@@ -3,6 +3,9 @@ const REPOSITORY_URL = "https://github.com/ndom91/open-plan-annotator";
 const HELP_USAGE_LINES = [
   "open-plan-annotator              Show this help",
   "open-plan-annotator < event.json Run as a Claude Code hook (debug)",
+  "open-plan-annotator review <file> Review a Markdown plan from disk",
+  "open-plan-annotator agent-setup  Print generic agent setup instructions",
+  "open-plan-annotator help agent   Print generic agent setup instructions",
   "open-plan-annotator doctor       Show resolved runtime details",
   "open-plan-annotator update       Show package-managed update guidance",
   "open-plan-annotator upgrade      Alias for update",
@@ -19,6 +22,14 @@ export function buildCliHelpText(version) {
   return `open-plan-annotator v${version}\n\nUsage:\n${usage}\n\n${REPOSITORY_URL}`;
 }
 
+/**
+ * @param {string | undefined} topic
+ * @returns {boolean}
+ */
+export function isAgentHelpTopic(topic) {
+  return topic === "agent" || topic === "agent-setup";
+}
+
 /**
  * @param {string | undefined} command
  * @returns {string}

package/shared/cliMode.mjs

@@ -1,5 +1,5 @@
 /**
- * @typedef {"hook" | "update" | "doctor" | "help" | "version" | "unknown"} CliMode
+ * @typedef {"hook" | "review" | "agentSetup" | "update" | "doctor" | "help" | "version" | "unknown"} CliMode
  */
 
 /**
@@ -18,6 +18,9 @@ export function resolveCliMode(arg, options = {}) {
 
   if (arg === "update" || arg === "upgrade") return "update";
   if (arg === "doctor") return "doctor";
+  if (arg === "review") return "review";
+  if (arg === "agent-setup") return "agentSetup";
+  if (arg === "help") return "help";
   if (arg === "--help" || arg === "-h") return "help";
   if (arg === "--version" || arg === "-v") return "version";
   return "unknown";

package/shared/runtimeEnv.mjs

@@ -0,0 +1,16 @@
+/**
+ * @param {{ cliMode: string, baseEnv?: NodeJS.ProcessEnv, packageManager: string }} options
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function buildRuntimeEnv({ cliMode, baseEnv = process.env, packageManager }) {
+  const env = {
+    ...baseEnv,
+    OPEN_PLAN_PKG_MANAGER: packageManager,
+  };
+
+  if (!env.OPEN_PLAN_HOST && cliMode === "hook") {
+    env.OPEN_PLAN_HOST = "claude-code";
+  }
+
+  return env;
+}