open-plan-annotator 1.0.9 → 1.0.11

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "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.0.9",
+      "version": "1.0.11",
       "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.0.9",
+  "version": "1.0.11",
   "author": {
     "name": "ndom91"
   },

package/opencode/index.js

@@ -4,15 +4,44 @@ import { resolveImplementationHandoff } from "./config.js";
 
 const PLAN_REVIEW_INSTRUCTIONS = `## Plan Review Workflow
 
-For non-trivial implementation work, create a plan first and call the \`submit_plan\` tool.
-The user will review the plan in a browser UI and either approve it or request changes.
-
-- If the tool returns that the plan was **approved**: immediately begin writing code. Do NOT call \`submit_plan\` again — the plan phase is complete.
-- If the tool returns **revision feedback**: revise the plan based on the feedback, then call \`submit_plan\` again with the updated plan.
-
-Only call \`submit_plan\` once per plan version. After approval, your sole job is to implement what was approved.`;
-
-const IMPLEMENTATION_PROMPT = "The plan has been approved by the user. Begin implementing it now — write code, create files, and make changes as described in the plan. Do not re-submit or re-review the plan.";
+Track planning/execution using this state enum:
+- \`DISCOVERY\`, \`PLAN_DRAFT\`, \`AWAITING_PLAN_DECISION\`, \`EXECUTION\`, \`DONE\`
+
+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\`.
+- 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\`.
+
+Required flags:
+- \`plan_status\` in \`{none, submitted, approved, rejected}\`
+- \`explicit_replan\` in \`{true,false}\` (default \`false\`)
+- 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.
+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\`.
+
+Tool guard before calling \`submit_plan\`:
+- assert \`state == PLAN_DRAFT\`
+- assert \`plan_status != approved || explicit_replan == true\`
+- if an assertion fails, continue execution without submitting a new plan.`;
+
+const IMPLEMENTATION_PROMPT = [
+  "Plan review status: plan_status=approved.",
+  "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.",
+].join(" ");
 
 function getErrorMessage(error) {
   if (error instanceof Error && error.message) {
@@ -133,7 +162,7 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
     tool: {
       submit_plan: tool({
         description:
-          "Submit a markdown plan for interactive user review. Returns approval status or structured revision feedback.",
+          "Submit a markdown plan for interactive user review. Returns a structured result with plan_status, next_state, approved, and feedback fields.",
 
         args: {
           plan: tool.schema.string().describe("The complete implementation plan in markdown format"),
@@ -147,6 +176,13 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
             cwd: ctx.directory,
           });
 
+          const basePayload = {
+            plan_status: result.approved ? "approved" : "rejected",
+            next_state: result.approved ? "EXECUTION" : "PLAN_DRAFT",
+            approved: result.approved,
+            feedback: result.approved ? null : (result.feedback ?? "Plan changes requested."),
+          };
+
           if (result.approved) {
             const lines = [
               "Plan approved by the user.",
@@ -167,18 +203,24 @@ export const OpenPlanAnnotatorPlugin = async (ctx) => {
             }
 
             lines.push("Begin implementing the approved plan now — write code and make changes.");
-            return lines.join("\n\n");
+            return {
+              ...basePayload,
+              guidance: lines.join("\n\n"),
+            };
           }
 
-          return [
-            "Plan needs revision.",
-            "",
-            "## User feedback",
-            "",
-            result.feedback ?? "Plan changes requested.",
-            "",
-            "Revise the plan using this feedback, then call `submit_plan` again.",
-          ].join("\n");
+          return {
+            ...basePayload,
+            guidance: [
+              "Plan needs revision.",
+              "",
+              "## User feedback",
+              "",
+              basePayload.feedback,
+              "",
+              "Revise the plan using this feedback, then submit the revised draft once via `submit_plan`.",
+            ].join("\n"),
+          };
         },
       }),
     },

package/opencode/index.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+afterEach(() => {
+  mock.restore();
+});
+
+function createPluginContext() {
+  return {
+    directory: process.cwd(),
+    client: {
+      session: {
+        messages: async () => ({ data: [] }),
+        prompt: async () => ({ data: null }),
+      },
+      app: {
+        agents: async () => ({ data: [] }),
+      },
+    },
+  };
+}
+
+describe("submit_plan return schema contract", () => {
+  test("approved decision maps to approved execution payload", async () => {
+    mock.module("./bridge.js", () => ({
+      runPlanReview: async () => ({ approved: true }),
+    }));
+
+    const { OpenPlanAnnotatorPlugin } = await import(`./index.js?approved-${Date.now()}`);
+    const plugin = await OpenPlanAnnotatorPlugin(createPluginContext());
+
+    const result = await plugin.tool.submit_plan.execute({ plan: "# Plan" }, { sessionID: "session-1" });
+
+    expect(result.plan_status).toBe("approved");
+    expect(result.next_state).toBe("EXECUTION");
+    expect(result.approved).toBe(true);
+    expect(result.feedback).toBeNull();
+  });
+
+  test("rejected decision maps to plan redraft payload with bridge feedback", async () => {
+    const bridgeFeedback = "Need to add rollback steps.";
+
+    mock.module("./bridge.js", () => ({
+      runPlanReview: async () => ({ approved: false, feedback: bridgeFeedback }),
+    }));
+
+    const { OpenPlanAnnotatorPlugin } = await import(`./index.js?rejected-${Date.now()}`);
+    const plugin = await OpenPlanAnnotatorPlugin(createPluginContext());
+
+    const result = await plugin.tool.submit_plan.execute({ plan: "# Plan" }, { sessionID: "session-2" });
+
+    expect(result.plan_status).toBe("rejected");
+    expect(result.next_state).toBe("PLAN_DRAFT");
+    expect(result.approved).toBe(false);
+    expect(result.feedback).toBe(bridgeFeedback);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-plan-annotator",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "type": "module",
   "description": "Fully local plugin for interactive plan annotation from your Agentic assistants",
   "author": "ndom91",