open-plan-annotator 1.5.3 → 1.5.5

package/.claude-plugin/marketplace.json

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

package/CLAUDE.md

@@ -1,42 +1,86 @@
 # 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.
 
-**Prefer this workflow whenever the user is expected to give structured feedback on a multi-section proposal.**
+**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.
 
-## ALWAYS Use Plan Mode for Non-Trivial Tasks
+## 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.
 
-Enter plan mode (which triggers the annotator on `ExitPlanMode`) before implementation that involves:
+## 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
-- Anything the user hasn't explicitly described step-by-step
 - 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".
 
-## Also Trigger When Drafting Plans Outside Plan Mode
+## Self-Check Before Sending
 
-Plan-shaped output happens in many contexts beyond `EnterPlanMode`. Enter plan mode (so the annotator fires on exit) whenever you're about to produce:
+Before emitting any response, scan it for these strings:
 
-- A multi-step proposal with numbered or bulleted action items the user is expected to react to
-- A reply containing phrases like "recommended approach", "implementation plan", "proposed fix", "rollout plan", "here's what I'd do"
-- A response to user prompts like "let's plan X", "draft a plan", "what's the approach", "give me options", "how should we tackle this"
-- Any moment you'd otherwise ask "want me to proceed?" / "shall I draft this?" — enter plan mode instead
+- "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
 
-Rough gate: **structured feedback expected + more than ~5 action items or sections**. Below that bar, a direct answer is fine.
+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 (don't re-prompt)
+- 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
 
@@ -44,15 +88,18 @@ 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're making
+- 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
 
-**In plan mode:** draft plan → call `ExitPlanMode` → annotator opens → user annotates → revise based on feedback → re-exit when aligned.
+**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.
 
-**Outside plan mode (inline plan situations):** invoke the `/open-plan-annotator` slash command instead of pasting a plan inline. That command runs the same plan-mode + draft + `ExitPlanMode` flow and routes the plan through the annotator UI. Do not paste a multi-section plan inline and ask "sound good?" — that bypasses the annotator.
+**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
 
-`/open-plan-annotator <task>` is the canonical entry point for the plan-and-annotate workflow. Users can invoke it explicitly, and you should invoke it yourself any time you'd otherwise draft an inline plan (see "Also Trigger When Drafting Plans Outside Plan Mode" above). The command enters plan mode, drafts a plan for the task, and exits to trigger the annotator — do not skip straight to implementation.
+`/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.

package/README.md

@@ -23,25 +23,28 @@ Everything runs locally. Nothing leaves your machine.
 
 ## Install
 
-> [!NOTE]
-> `open-plan-annotator` now ships as one package-managed install. The npm package
-> contains the plugin glue and resolves a platform runtime package locally. There
-> is no first-run binary download and no in-app self-update path.
+`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.
 
 ### Claude Code
 
-From within Claude Code, add the marketplace and install the plugin:
+Install from inside Claude Code:
 
 ```
 /plugin marketplace add ndom91/open-plan-annotator
 /plugin install open-plan-annotator@ndom91-open-plan-annotator
 ```
 
-This installs the npm-backed plugin and registers the `ExitPlanMode` hook that launches the annotation UI. In Claude Code, third-party marketplaces have auto-update disabled by default, so also enable auto-update for the `ndom91-open-plan-annotator` marketplace in the Marketplace UI.
+What you get:
+
+- `ExitPlanMode` hook: opens the annotation UI whenever Claude submits a plan
+- `/annotate-plan [task description]`: asks Claude to draft a plan and send it to the UI
+- `open-plan-annotator`: runtime command invoked by the hook
+
+Third-party marketplace auto-update is disabled by default in Claude Code. Enable auto-update for the `ndom91-open-plan-annotator` marketplace in the Marketplace UI if you want updates automatically.
 
 ### OpenCode
 
-Add `open-plan-annotator` to the `plugin` array in your OpenCode config (`opencode.json` or `.opencode/config.json`):
+Add the plugin to your OpenCode config (`opencode.json` or `.opencode/config.json`):
 
 ```json
 {
@@ -49,66 +52,57 @@ Add `open-plan-annotator` to the `plugin` array in your OpenCode config (`openco
 }
 ```
 
-OpenCode will install the package and load it automatically. The plugin:
-- Injects plan-mode instructions into the agent's system prompt
-- Registers a `submit_plan` tool that the agent calls after creating a plan
-- Spawns the annotation UI in your browser for review
-- Returns structured feedback to the agent on approval or rejection
-- Optionally hands off to an implementation agent after approval
+What you get:
 
-To update, refresh the plugin through OpenCode and restart the app so it reloads the latest package-managed runtime.
+- `annotate_plan`: tool the agent calls after drafting a markdown plan
+- `open-plan-annotator`: runtime command spawned by the plugin
+- optional implementation-agent handoff after approval
 
-> [!NOTE]
-> The update mechanism changed significantly in `1.0.20+`: OpenCode now loads the npm package plus a platform runtime package instead of using the old in-place binary updater. If OpenCode appears to be stuck on an older plugin build, clear the cached `open-plan-annotator` entries under `~/.cache/opencode/node_modules/` and restart OpenCode.
+Restart OpenCode after installing or updating so it reloads the package-managed runtime.
 
 ### Pi
 
-Install the dedicated Pi package:
+Install the Pi extension:
 
 ```sh
 pi install npm:@open-plan-annotator/pi-extension
 ```
 
-The extension package registers:
-
-- a `submit_plan` tool, exposed to the model with prompt guidance to call it after drafting a concrete markdown plan and before implementation
-- an `/annotate-plan` command for manual review of the latest assistant message or supplied plan text
-
-Typical flow:
+What you get:
 
-1. Ask Pi to make a plan before coding.
-2. Pi drafts the plan and calls `submit_plan`.
-3. The browser review UI opens locally.
-4. Approval returns “Plan approved. Continue with implementation.”; requested changes return the serialized annotations as feedback.
+- `annotate_plan`: tool the agent calls after drafting a markdown plan
+- `/annotate-plan [plan markdown]`: command for manually reviewing supplied text or the latest assistant message
+- `open-plan-annotator`: runtime command used by the extension
 
-You can also trigger review manually:
+Manual review examples:
 
 ```sh
 /annotate-plan
 /annotate-plan # Plan\n\n1. Do the thing
 ```
 
-### Manual Install
+### Manual / CLI
 
-If you want to run the CLI standalone or install the package globally:
+Install globally if you want to run the CLI directly:
 
 ```sh
-pnpm add -g open-plan-annotator
+bun add -g open-plan-annotator
 npm install -g open-plan-annotator
 ```
 
-## Updates
-
-- OpenCode: update the installed npm plugin through OpenCode, then restart OpenCode.
-- Claude Code: update the marketplace/plugin install, then restart Claude Code.
-- Standalone/global install: update the npm package (`npm`, `pnpm`, or `bun`), then rerun `open-plan-annotator`.
-
-The built-in `doctor` command reports the resolved runtime package and runtime path:
+This adds the `open-plan-annotator` command. To verify the resolved runtime:
 
 ```sh
 open-plan-annotator doctor
 ```
 
+## 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`.
+
 ## Keyboard Shortcuts
 
 | Action | Shortcut | Description |

package/commands/{open-plan-annotator.md → annotate-plan.md}

@@ -3,7 +3,7 @@ description: Draft a plan and open it in the annotator UI for user review
 argument-hint: [task description]
 ---
 
-The user wants a plan drafted and reviewed via the open-plan-annotator UI before any implementation.
+The user wants a plan drafted and reviewed via the open-plan-annotator UI before any implementation. This is required, not optional.
 
 **Task to plan:** $ARGUMENTS
 
@@ -13,11 +13,17 @@ Steps:
 2. Investigate the codebase as needed to draft a concrete 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're making
+   - Any assumptions you are making
+   - Tradeoffs and option comparisons inline (do NOT pull these into chat — they belong in the plan body where the user can comment on each one)
    - Explicit questions if anything is ambiguous
 3. Call `ExitPlanMode` with the plan. This triggers the open-plan-annotator browser UI.
 4. The user will annotate the plan (deletions, replacements, insertions, comments) in the browser.
 5. If the user denies with annotations, revise the plan based on their feedback and re-exit plan mode.
 6. Only begin implementation after the user approves.
 
-Do not skip plan mode. Do not paste a plan inline and ask "sound good?" — that bypasses the annotator UI the user installed this plugin for.
+Hard rules:
+
+- Do not skip plan mode.
+- Do not paste a plan inline and ask "sound good?" — that bypasses the annotator UI the user installed this plugin for.
+- Do not collapse into a 2-3 sentence inline response just because the user message contains an exploratory clause like "what do you think?" alongside directive items. Mixed signals still route through the annotator.
+- Self-check the response before sending: if it contains a "Plan:" / "Steps:" / "Concrete changes:" header, 3+ file paths, or ends with "OK to proceed?" — discard and route through the annotator instead.

package/opencode/index.js

@@ -2,7 +2,35 @@ import { tool } from "@opencode-ai/plugin";
 import { runPlanReview } from "./bridge.js";
 import { resolveImplementationHandoff } from "./config.js";
 
-const PLAN_REVIEW_INSTRUCTIONS = `## Plan Review Workflow
+const PLAN_REVIEW_INSTRUCTIONS = `## Plan Review Tool
+
+The "open-plan-annotator plan annotation tool" refers to the \`annotate_plan\` tool.
+
+When the user asks for a plan, proposal, implementation strategy, migration path, rollout plan, or asks "what would it look like," you MUST use the \`annotate_plan\` tool instead of replying with a normal Markdown plan.
+
+Use \`annotate_plan\` when:
+- The user explicitly says "make a plan", "write a plan", "give me a plan", "proposal", or "implementation plan".
+- The user asks to evaluate an approach before code changes.
+- The response contains ordered implementation steps.
+- The plan would benefit from user approval before execution.
+
+Do not use \`annotate_plan\` for:
+- Tiny one-step tasks.
+- Pure explanations with no proposed action.
+- Final summaries after work is complete.
+
+If there is any ambiguity about whether a response is a plan, prefer using \`annotate_plan\`.
+
+The \`annotate_plan\` call should include:
+- \`summary\`: one sentence describing the plan.
+- \`plan\`: the full Markdown plan.
+
+After calling \`annotate_plan\`, follow the returned instruction exactly:
+- If approved, proceed.
+- If revisions are requested, revise the plan and call \`annotate_plan\` again.
+- If the user asks questions, answer them before proceeding.
+
+## Plan Review Workflow
 
 Track planning/execution using this state enum:
 - \`DISCOVERY\`, \`PLAN_DRAFT\`, \`AWAITING_PLAN_DECISION\`, \`EXECUTION\`, \`DONE\`
@@ -10,7 +38,7 @@ Track planning/execution using this state enum:
 State transitions:
 - Start in \`DISCOVERY\`.
 - Move to \`PLAN_DRAFT\` only when a plan is required.
-- From \`PLAN_DRAFT\`, call \`submit_plan\` exactly once, then move to \`AWAITING_PLAN_DECISION\`.
+- From \`PLAN_DRAFT\`, call \`annotate_plan\` exactly once, then move to \`AWAITING_PLAN_DECISION\`.
 - If user approves plan, set \`plan_status=approved\` and move to \`EXECUTION\`.
 - If user rejects or requests plan changes, set \`plan_status=rejected\` and return to \`PLAN_DRAFT\`.
 - When work is complete, move to \`DONE\`.
@@ -21,16 +49,16 @@ Required flags:
 - Set \`explicit_replan=true\` only when user clearly asks to replan (for example: revise/change/new/update plan).
 
 Hard rules:
-1) \`submit_plan\` is allowed only in \`PLAN_DRAFT\`.
-2) If \`plan_status=approved\`, \`submit_plan\` is forbidden unless \`explicit_replan=true\`.
-3) Call \`submit_plan\` at most once per plan draft/version. If rejected, revise and submit once for the new draft.
+1) \`annotate_plan\` is allowed only in \`PLAN_DRAFT\`.
+2) If \`plan_status=approved\`, \`annotate_plan\` is forbidden unless \`explicit_replan=true\`.
+3) Call \`annotate_plan\` at most once per plan draft/version. If rejected, revise and submit once for the new draft.
 4) After approval, treat follow-up user messages as execution refinements by default, not planning triggers.
 5) On conflict, prioritize the approved plan and execute immediately.
 6) Do not ask permission to proceed after approval; execute and report progress/results.
 7) When delegating to subagents, always pass current \`plan_status\` and \`explicit_replan\` values.
-8) If \`plan_status=approved\` and \`explicit_replan=false\`, subagents must execute and must not call \`submit_plan\`.
+8) If \`plan_status=approved\` and \`explicit_replan=false\`, subagents must execute and must not call \`annotate_plan\`.
 
-Tool guard before calling \`submit_plan\`:
+Tool guard before calling \`annotate_plan\`:
 - assert \`state == PLAN_DRAFT\`
 - assert \`plan_status != approved || explicit_replan == true\`
 - if an assertion fails, continue execution without submitting a new plan.`;
@@ -40,7 +68,7 @@ const IMPLEMENTATION_PROMPT = [
   "State transition: next_state=EXECUTION.",
   "Replan intent: explicit_replan=false unless the user explicitly asks to revise the plan.",
   "Execute the approved plan directly now — write code, create files, and make changes.",
-  "Do not call `submit_plan` again unless the user explicitly requests re-planning.",
+  "Do not call `annotate_plan` again unless the user explicitly requests re-planning.",
 ].join(" ");
 
 function getErrorMessage(error) {
@@ -151,7 +179,7 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
         return;
       }
 
-      if (!currentSystem.includes("submit_plan")) {
+      if (!currentSystem.includes("annotate_plan")) {
         const shouldInject = await shouldInjectPlanReviewInstructions(input?.sessionID);
         if (shouldInject) {
           output.system.push(PLAN_REVIEW_INSTRUCTIONS);
@@ -160,7 +188,7 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
     },
 
     tool: {
-      submit_plan: tool({
+      annotate_plan: tool({
         description:
           "Submit a markdown plan for interactive user review. Returns plain-text execution or revision instructions for the agent.",
 
@@ -196,7 +224,7 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
 
             lines.push("Replan intent: explicit_replan=false unless the user explicitly asks to revise the plan.");
             lines.push("Execute the approved plan directly now — write code, create files, and make changes.");
-            lines.push("Do not call `submit_plan` again unless the user explicitly requests re-planning.");
+            lines.push("Do not call `annotate_plan` again unless the user explicitly requests re-planning.");
 
             return lines.join("\n\n");
           }
@@ -209,7 +237,7 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
             "",
             feedback,
             "",
-            "Revise the plan using this feedback, then submit the revised draft once via `submit_plan`.",
+            "Revise the plan using this feedback, then submit the revised draft once via `annotate_plan`.",
           ].join("\n");
         },
       }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -42,6 +42,7 @@
     "opencode/index.js",
     "hooks/",
     "commands/",
+    "skills/",
     "CLAUDE.md",
     "README.md"
   ],
@@ -82,10 +83,10 @@
     }
   },
   "optionalDependencies": {
-    "@open-plan-annotator/runtime-darwin-arm64": "1.5.3",
-    "@open-plan-annotator/runtime-darwin-x64": "1.5.3",
-    "@open-plan-annotator/runtime-linux-arm64": "1.5.3",
-    "@open-plan-annotator/runtime-linux-x64": "1.5.3"
+    "@open-plan-annotator/runtime-darwin-arm64": "1.5.5",
+    "@open-plan-annotator/runtime-darwin-x64": "1.5.5",
+    "@open-plan-annotator/runtime-linux-arm64": "1.5.5",
+    "@open-plan-annotator/runtime-linux-x64": "1.5.5"
   },
   "overrides": {
     "uuid": "^14.0.0"

package/shared/piExtension.mjs

@@ -4,7 +4,7 @@ import { detectPackageManager } from "./packageManager.mjs";
 import { runPlanReviewBinary } from "./planReview.mjs";
 import { resolveRuntimeBinary } from "./runtimeResolver.mjs";
 
-const TOOL_NAME = "submit_plan";
+const TOOL_NAME = "annotate_plan";
 
 function getSessionId(ctx) {
   try {
@@ -65,7 +65,7 @@ export function registerPiExtension(pi) {
     description: "Open the browser-based plan annotation UI and return approval or revision feedback.",
     promptSnippet: "Use this tool after drafting a plan that needs human review before implementation.",
     promptGuidelines: [
-      "Call submit_plan when you have a concrete plan in markdown form.",
+      "Call annotate_plan when you have a concrete plan in markdown form.",
       "Include the full plan text, including numbered steps if available.",
       "Wait for the review result before proceeding with implementation.",
     ],

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

@@ -0,0 +1,94 @@
+---
+name: plan-review-triggers
+description: Required reading whenever drafting any multi-step proposal, implementation plan, refactor approach, or response containing file paths and decision points. Use BEFORE writing any response that lists 3+ file paths, 2+ option-tradeoffs, a "Plan:"/"Steps:"/"Concrete changes:" section, or ends with "OK to proceed?" / "sound good?" / "shall I…?". Use whenever the 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", or asks for a "recommended approach" / "implementation plan" / "proposed fix" / "rollout plan". Also use when modifying more than 2 files, doing architectural/structural changes, refactoring, migration, feature additions, or investigation-based bug fixes. Routes the response through the open-plan-annotator browser UI instead of pasting plans inline.
+---
+
+# 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 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.
+
+## Hard Rule: Annotator Required When Triggers Match
+
+Inline plans are a bug. When any trigger below fires, route through the annotator:
+
+- Assistant-initiated (you decided a plan is needed): call `EnterPlanMode`, draft, then `ExitPlanMode` — fires the annotator hook.
+- User-initiated ("draft a plan", "/plan", etc.): invoke `/annotate-plan <task>`.
+
+## Mechanical Heuristic
+
+Annotator REQUIRED when the response would contain ANY of:
+
+- 3 or more file paths to create or modify
+- 2 or more option/tradeoff comparisons for the user to choose between
+- A `Plan:`, `Steps:`, `Concrete changes:`, `Implementation:`, `Approach:` section header
+- A numbered/bulleted list of action items the user is expected to react to
+- A multi-section proposal with decision points
+
+Hard gate. Count file paths. Count options. If the count crosses the line, the inline response is not allowed.
+
+## Task Shape Triggers
+
+- 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
+
+## Phrase Triggers
+
+- 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"
+- Response would contain "recommended approach", "implementation plan", "proposed fix", "rollout plan", "here's what I'd do", "concrete file changes"
+- Any moment you'd ask "want me to proceed?" / "shall I draft this?" / "OK to proceed?" / "sound good?"
+
+## Mixed Signals Still Trigger
+
+User messages combining directives ("let's add X", "can we Y") with an exploratory clause ("what do you think?") still trigger the annotator. Do NOT collapse into a short inline response 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. Treat exploratory clauses as "include alternatives in the plan", not "skip the plan".
+
+## Self-Check Before Sending
+
+Scan the drafted response for:
+
+- "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
+
+ANY match → discard inline response, route through annotator.
+
+## Do NOT Trigger For
+
+- Single-line fixes, typos, renames
+- Direct factual answers
+- Status updates or progress reports
+- Already-approved plans (do not re-prompt)
+- Pure research / exploration with no proposed actions
+- Trivial questions where a plan is overhead
+- Answering questions ABOUT an already-submitted plan (answer the question, do not re-submit)
+
+## Plan Quality Standards
+
+Include in every plan:
+
+- Brief summary of the task as you understood it
+- Specific files to create or modify and why
+- Assumptions you are making
+- Explicit questions if anything is ambiguous
+- Tradeoffs / option comparisons inline (since mixed-signal user messages route here)
+
+## Workflow
+
+**Assistant-initiated:** `EnterPlanMode` → draft → `ExitPlanMode` → user annotates → revise on feedback → re-exit when aligned.
+
+**User-initiated:** invoke `/annotate-plan <task>`. Same flow under the hood.
+
+The slash command is for user invocation. When you decide a plan is needed without the user invoking it, prefer `EnterPlanMode` directly. Both paths fire the same annotator hook.