open-plan-annotator 1.2.1 → 1.4.0

package/.claude-plugin/marketplace.json

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

package/CLAUDE.md

@@ -1,28 +1,58 @@
 # open-plan-annotator: Plan Review Instructions
 
+## 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 distinct from `plannotator-review` (post-implementation code review). open-plan-annotator runs *before* code is written.
+
 ## ALWAYS Use Plan Mode for Non-Trivial Tasks
 
-Before beginning any implementation that involves:
+Enter plan mode (which triggers the annotator on `ExitPlanMode`) before implementation that involves:
+
 - 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
 
-You MUST use plan mode to present your approach first.
+## Also Trigger When Drafting Plans Outside Plan Mode
+
+Plan-shaped output happens in many contexts beyond `EnterPlanMode`. Enter plan mode (so the annotator fires on exit) whenever you're about to produce:
 
-## Why This Matters
+- 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
 
-The user has installed the open-plan-annotator plugin specifically to review and annotate your plans before you write code. Skipping plan mode bypasses this workflow entirely and removes the user's ability to give structured feedback.
+Rough gate: **structured feedback expected + more than ~5 action items or sections**. Below that bar, a direct answer is fine.
+
+## 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)
+- Pure research or exploration with no proposed actions
+- Trivial questions where a plan would be overhead
 
 ## Plan Quality Standards
 
 When writing a plan, include:
-- A brief summary of what you understood the task to require
-- The specific files you intend to create or modify and why
-- Any assumptions you are making
-- An explicit question if anything is ambiguous
 
-## When Plan Mode Is Optional
+- 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
+- Explicit question if anything is ambiguous
+
+## Workflow
+
+**In plan mode:** 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.
+
+## Slash Command
 
-For truly trivial tasks (fix a typo, rename a single variable, answer a factual question), plan mode is not required. When in doubt, use it anyway — the user can always approve immediately.
+`/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.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Nico Domino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/commands/open-plan-annotator.md

@@ -0,0 +1,23 @@
+---
+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.
+
+**Task to plan:** $ARGUMENTS
+
+Steps:
+
+1. Enter plan mode (`EnterPlanMode`).
+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
+   - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -39,6 +39,7 @@
     "opencode/config.js",
     "opencode/index.js",
     "hooks/",
+    "commands/",
     "CLAUDE.md",
     "README.md"
   ],
@@ -70,9 +71,9 @@
     "@opencode-ai/plugin": "^1.2.14"
   },
   "optionalDependencies": {
-    "@open-plan-annotator/runtime-darwin-arm64": "1.2.1",
-    "@open-plan-annotator/runtime-darwin-x64": "1.2.1",
-    "@open-plan-annotator/runtime-linux-arm64": "1.2.1",
-    "@open-plan-annotator/runtime-linux-x64": "1.2.1"
+    "@open-plan-annotator/runtime-darwin-arm64": "1.4.0",
+    "@open-plan-annotator/runtime-darwin-x64": "1.4.0",
+    "@open-plan-annotator/runtime-linux-arm64": "1.4.0",
+    "@open-plan-annotator/runtime-linux-x64": "1.4.0"
   }
 }