open-plan-annotator 1.8.0 → 1.8.2

package/.claude-plugin/marketplace.json

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

package/hooks/hooks.json

@@ -8,6 +8,11 @@
             "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
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",
@@ -28,6 +28,7 @@
   "files": [
     "bin/open-plan-annotator.mjs",
     "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.8.0",
-    "@open-plan-annotator/runtime-darwin-x64": "1.8.0",
-    "@open-plan-annotator/runtime-linux-arm64": "1.8.0",
-    "@open-plan-annotator/runtime-linux-x64": "1.8.0"
+    "@open-plan-annotator/runtime-darwin-arm64": "1.8.2",
+    "@open-plan-annotator/runtime-darwin-x64": "1.8.2",
+    "@open-plan-annotator/runtime-linux-arm64": "1.8.2",
+    "@open-plan-annotator/runtime-linux-x64": "1.8.2"
   },
   "overrides": {
     "uuid": "^14.0.0"
-  }
+  },
+  "packageManager": "bun@1.3.9"
 }

package/scripts/session-context.mjs

@@ -0,0 +1,39 @@
+#!/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>.
+
+After approval: the approved ExitPlanMode response is the user's go-ahead to implement. Do not ask for another confirmation, do not say "ready when you are", and do not wait. Immediately continue with the approved plan unless the approval response explicitly requests changes or says not to proceed.
+
+Full trigger list and self-check rules in skill plan-review-triggers.`;
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext,
+    },
+  }),
+);

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.
@@ -92,3 +92,9 @@ Include in every plan:
 **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.
+
+## After Approval
+
+Plan approval is the user's go-ahead to implement. Once `ExitPlanMode` returns an approved decision, immediately start executing the approved plan.
+
+Do not ask for another confirmation, do not say "ready when you are", and do not wait for a separate go-ahead unless the approval response explicitly requests changes or says not to proceed.

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.