feat(submit-plan): replace dual-mode with edit-based interface (#730)

* feat(submit-plan): replace text/file-path mode with edit-based interface

Switches the OpenCode submit_plan tool from a dual-mode interface
(inline text or file path) to an edit-based one. The plugin now owns a
backing file at .opencode/plans/_active-plan.md; the agent never reads
or writes it directly. On denial, the response includes the current plan
with line numbers so the agent can apply surgical edits instead of
resubmitting the entire document, reducing token waste on iterative
revisions.

- Add applyEdits, validateEdits, formatWithLineNumbers, and
  getPlanBackingPath helpers to the plugin
- Validate edit ranges (bounds, overlap, size limit) before mutating the
  backing file
- Return line-numbered plan in denial responses to anchor targeted edits
- Remove getPlanDirectory, validatePlanPath, and file-path auto-
  detection from plan-mode.ts
- Replace plan-mode.test.ts path-validation coverage with submit-
  plan.test.ts for the edit engine
- Update custom-feedback.md and opencode.md docs for edit-based
  semantics

Refs #365

* chore(opencode): drop unused buildPlanFileRule import

Removed in PR #730 deny path along with the only call site, but the
import was left behind.

---------

Co-authored-by: Michael Ramos <mdramos8@gmail.com>

Author: rcdailey

apps/marketing/src/content/docs/guides/custom-feedback.md

@@ -67,8 +67,8 @@ Templates use `{{variable}}` placeholders. Here's what each one contains:
 |----------|-------------|
 | `{{feedback}}` | Your annotations, exported as structured text. This is the main content. |
 | `{{toolName}}` | The tool the agent needs to call to resubmit (`ExitPlanMode`, `submit_plan`, etc.). Varies by runtime. |
-| `{{planFileRule}}` | A conditional line telling the agent where the plan file is saved and how to edit it. Empty string when there's no file path. |
-| `{{planFilePath}}` | Path to the plan file being reviewed. |
+| `{{planFileRule}}` | A conditional line about the plan file location. In edit-based mode (OpenCode), this is always empty since the plugin manages the backing file internally. |
+| `{{planFilePath}}` | Path to the plan's backing file. In edit-based mode (OpenCode), this points to the plugin-managed backing file. |
 | `{{doneMsg}}` | Optional checklist instruction or save-path info, depending on the runtime. |
 | `{{fileHeader}}` | Either `"File"` or `"Folder"`, depending on what was annotated. |
 | `{{filePath}}` | Path to the annotated file or folder. |
@@ -137,6 +137,7 @@ Here's a config that customizes several messages at once:
 If you don't set any `prompts` config, everything works the same as it always has. The built-in defaults are the exact messages Plannotator has always sent. Here are the key ones for reference:
 
 **Plan denied (default):**
+
 ```
 YOUR PLAN WAS NOT APPROVED.
 
@@ -152,12 +153,14 @@ Rules:
 ```
 
 **Plan approved (default, Pi runtime):**
+
 ```
 Plan approved. You now have full tool access (read, bash, edit,
 write). Execute the plan in {{planFilePath}}. {{doneMsg}}
 ```
 
 **Annotate file feedback (default):**
+
 ```
 # Markdown Annotations
 

apps/marketing/src/content/docs/guides/opencode.md

@@ -15,10 +15,10 @@ If you are upgrading from an older OpenCode setup, read the [0.19.1 migration gu
 The OpenCode plugin (`@plannotator/opencode`) hooks into OpenCode's plugin system:
 
 1. The plugin registers a `submit_plan` tool for OpenCode's built-in `plan` agent and any extra planning agents you configure
-2. When `submit_plan` is called with a plan, Plannotator starts a local server and opens the browser
+2. When `submit_plan` is called, Plannotator starts a local server and opens the browser
 3. The user reviews and annotates the plan
 4. On approval, the plugin returns a success response to the agent
-5. On denial, the plugin returns the feedback for the agent to revise
+5. On denial, the plugin returns feedback with the current plan state, and the agent applies targeted edits
 
 ## Workflow modes
 

apps/opencode-plugin/index.ts

@@ -1,12 +1,10 @@
 /**
  * Plannotator Plugin for OpenCode
  *
- * Provides interactive browser-based plan review via a single tool:
- *   submit_plan(plan) — accepts either markdown text or a file path
- *
- * First submission: agent passes plan as text. On deny, the response includes
- * the path where the plan was saved, enabling the agent to use Edit for targeted
- * revisions and resubmit with the file path.
+ * POC: Edit-based submit_plan. The tool accepts line-range edits instead of
+ * full plan text or file paths. A backing file is managed by the plugin;
+ * the agent never touches it directly. On denial, the tool response includes
+ * the plan with line numbers so the agent can target surgical edits.
  *
  * Environment variables:
  *   PLANNOTATOR_REMOTE - Set to "1"/"true" for remote, "0"/"false" for local
@@ -18,7 +16,7 @@
  */
 
 import { type Plugin, tool } from "@opencode-ai/plugin";
-import { existsSync, readFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import path from "path";
 
 // OpenCode's @hono/node-server patches global.Response with a polyfill that
@@ -61,7 +59,6 @@ import {
   getPlanApprovedPrompt,
   getPlanApprovedWithNotesPrompt,
   getPlanToolName,
-  buildPlanFileRule,
   getAnnotateMessageFeedbackPrompt,
 } from "@plannotator/shared/prompts";
 import { loadConfig } from "@plannotator/shared/config";
@@ -119,35 +116,107 @@ function getReviewHtml(): string {
 }
 
 const DEFAULT_PLAN_TIMEOUT_SECONDS = 345_600; // 96 hours
+const MAX_PLAN_SIZE = 5 * 1024 * 1024; // 5MB
+
+// ── Edit-based plan management ────────────────────────────────────────────
 
-// ── Auto-detection ────────────────────────────────────────────────────────
+interface PlanEdit {
+  start: number;
+  end?: number | null;
+  content: string;
+}
 
 /**
- * Detect whether the submit_plan argument is a file path.
- * Must be an absolute path, end in .md, and exist on disk.
- * Anything that doesn't match is treated as plan text.
+ * Backing file for the current plan. Managed entirely by the plugin;
+ * the agent never sees or touches this file directly.
  */
-function isFilePath(value: string): boolean {
-  return path.isAbsolute(value) && value.endsWith(".md") && existsSync(value);
+export function getPlanBackingPath(directory: string): string {
+  const planDir = path.join(directory, ".opencode", "plans");
+  return path.join(planDir, "_active-plan.md");
+}
+
+/**
+ * Apply line-range edits to a plan stored as an array of lines.
+ *
+ * Edit semantics:
+ *   - start/end are 1-indexed line numbers (inclusive)
+ *   - end omitted or null: replace from start through end of file
+ *     (on first call with start=1, this writes the entire plan)
+ *   - content="" with start/end: delete those lines
+ *   - edits are applied in order; line numbers refer to the document
+ *     state BEFORE any edits in this batch (offsets are adjusted internally)
+ */
+export function applyEdits(existingLines: string[], edits: PlanEdit[]): string[] {
+  // Sort by start ascending so offset adjustment works correctly
+  const sorted = [...edits].sort((a, b) => a.start - b.start);
+  const lines = [...existingLines];
+  let offset = 0;
+
+  for (const edit of sorted) {
+    const start = edit.start - 1 + offset; // convert to 0-indexed + adjust
+    const end = edit.end != null
+      ? edit.end + offset   // end is inclusive, so this becomes the exclusive upper bound
+      : lines.length;       // null/omitted = through end of file
+
+    const newLines = edit.content ? edit.content.split("\n") : [];
+    const removedCount = end - start;
+    lines.splice(start, removedCount, ...newLines);
+    offset += newLines.length - removedCount;
+  }
+
+  return lines;
 }
 
 /**
- * Resolve the plan content from the submit_plan argument.
- * Returns the markdown text and optionally the source file path.
+ * Validate a batch of edits against the current file state.
+ * Returns an error string if invalid, or null if all edits are acceptable.
  */
-function resolvePlanContent(plan: string): { content: string; filePath?: string } {
-  if (isFilePath(plan)) {
-    const content = readFileSync(plan, "utf-8");
-    if (!content.trim()) {
-      throw new Error(`Plan file at ${plan} is empty. Write your plan content first, then call submit_plan.`);
+export function validateEdits(existingLines: string[], edits: PlanEdit[]): string | null {
+  const lineCount = existingLines.length;
+
+  for (const edit of edits) {
+    if (!Number.isInteger(edit.start) || edit.start < 1) {
+      return `start must be a positive integer >= 1, got ${edit.start}`;
+    }
+    if (edit.start > lineCount + 1) {
+      return `start (${edit.start}) exceeds file length + 1 (${lineCount + 1})`;
+    }
+    if (edit.end != null) {
+      if (!Number.isInteger(edit.end) || edit.end < edit.start) {
+        return `end (${edit.end}) must be >= start (${edit.start})`;
+      }
+      if (edit.end > lineCount) {
+        return `end (${edit.end}) exceeds file length (${lineCount})`;
+      }
     }
-    return { content, filePath: plan };
   }
-  // Catch typos: looks like a file path but doesn't exist
-  if (path.isAbsolute(plan) && plan.endsWith(".md")) {
-    throw new Error(`File not found: ${plan}. Check the path and try again.`);
+
+  // Check for overlapping ranges (sorted by start ascending)
+  const sorted = [...edits].sort((a, b) => a.start - b.start);
+  for (let i = 1; i < sorted.length; i++) {
+    const prev = sorted[i - 1];
+    const curr = sorted[i];
+    // Appending edits (start > lineCount) have no range that can overlap
+    if (prev.start > lineCount) continue;
+    const prevEnd = prev.end ?? lineCount;
+    if (curr.start <= prevEnd) {
+      return `edits overlap: [${prev.start},${prevEnd}] and [${curr.start},${curr.end ?? "end"}]`;
+    }
   }
-  return { content: plan };
+
+  return null;
+}
+
+/**
+ * Format the plan content with line numbers for the agent's reference.
+ * Returned in the tool response so the agent can track line positions.
+ */
+export function formatWithLineNumbers(content: string): string {
+  const lines = content.split("\n");
+  const width = String(lines.length).length;
+  return lines
+    .map((line, i) => `${String(i + 1).padStart(width)}| ${line}`)
+    .join("\n");
 }
 
 // ── Planning prompt ───────────────────────────────────────────────────────
@@ -159,7 +228,7 @@ function resolvePlanContent(plan: string): { content: string; filePath?: string
  * - Explain the WHY — the model is smart, give it context
  * - Keep it lean — every line should pull its weight
  * - Don't overfit — let the agent and user dictate the workflow
- * - One tool, two modes — text for first submission, file path for revisions
+ * - Edit-based: all submissions use line-range edits against a backing file
  */
 function getPlanningPrompt(): string {
   return `## Plannotator — Plan Review
@@ -168,10 +237,26 @@ You have a plan submission tool called \`submit_plan\`. It opens an interactive
 
 **How to use it:**
 
-- Pass your plan as markdown text — \`submit_plan(plan: "# My Plan\\n...")\`.
-- Or pass an absolute file path to a .md file — \`submit_plan(plan: "/path/to/plan.md")\`.
+\`submit_plan\` accepts an array of line-range edits. On first submission, pass the full plan as a single edit starting at line 1:
+
+\`\`\`json
+{ "edits": [{ "start": 1, "content": "# My Plan\\n\\n## Goals\\n..." }] }
+\`\`\`
 
-The tool auto-detects whether you passed text or a file path. Both open the same review UI.
+If the user denies and requests changes, apply surgical edits using line ranges. The tool response includes your plan with line numbers so you can target specific ranges:
+
+\`\`\`json
+{ "edits": [
+  { "start": 12, "end": 14, "content": "revised section content" },
+  { "start": 30, "end": 30, "content": "" }
+] }
+\`\`\`
+
+Edit semantics:
+- \`start\` and \`end\` are 1-indexed, inclusive line numbers
+- Omit \`end\` to replace from \`start\` through end of file (use this for the initial full write)
+- Empty \`content\` with \`start\`/\`end\` deletes those lines
+- Multiple edits in one call are applied in order; line numbers refer to the state before edits
 
 ### Before you write a plan
 
@@ -376,9 +461,9 @@ tools (except writing markdown files), or otherwise make changes to the system.
 
       output.system.push(`## Plan Submission
 
-When you have completed your plan, call the \`submit_plan\` tool to submit it for user review. Pass your plan as markdown text, or pass an absolute file path to a .md file.
+When you have completed your plan, call the \`submit_plan\` tool to submit it for user review. Pass your full plan as a single edit: \`{ "edits": [{ "start": 1, "content": "..." }] }\`.
 
-The user will review your plan in a visual UI where they can annotate, approve, or request changes. If rejected, revise based on their feedback and call submit_plan again.
+The user will review your plan in a visual UI where they can annotate, approve, or request changes. If rejected, the response includes your plan with line numbers; use targeted edits to revise specific sections.
 
 Do NOT proceed with implementation until your plan is approved.`);
     },
@@ -449,11 +534,17 @@ Do NOT proceed with implementation until your plan is approved.`);
     plugin.tool = {
       submit_plan: tool({
         description:
-          "Planning tool used to submit a plan to the user for review. Before calling this tool you must conduct interactive and exploratory analysis in order to submit a quality plan. Ask questions. Explore the codebase for context if needed. Only call submit_plan once you have enough details to create a quality plan. Work with the user to get those details. Pass either markdown text or an absolute path to a .md file.",
+          "Submit a plan for user review via line-range edits. First call: pass a single edit with start=1 and your full plan as content (omit end). Subsequent calls after denial: pass targeted edits using the line numbers from the previous response. The tool manages a backing file; you never touch the file directly.",
         args: {
-          plan: tool.schema
-            .string()
-            .describe("The plan — either markdown text or an absolute path to a .md file on disk."),
+          edits: tool.schema
+            .array(
+              tool.schema.object({
+                start: tool.schema.number().describe("1-indexed start line (inclusive)"),
+                end: tool.schema.number().optional().describe("1-indexed end line (inclusive). Omit to replace from start through end of file."),
+                content: tool.schema.string().describe("Replacement content. Empty string deletes the line range."),
+              }),
+            )
+            .describe("Array of line-range edits to apply to the plan."),
         },
 
         async execute(args, context) {
@@ -464,21 +555,46 @@ Do NOT proceed with implementation until your plan is approved.`);
 Use /plannotator-last or /plannotator-annotate for manual review, or set workflow to all-agents to allow broader submit_plan access.`;
           }
 
-          // Auto-detect: file path or plan text
-          let planContent: string;
-          let sourceFilePath: string | undefined;
+          if (!args.edits || args.edits.length === 0) {
+            return "Error: No edits provided. Pass at least one edit with start and content.";
+          }
+
+          // Read existing backing file (empty on first call)
+          const backingPath = getPlanBackingPath(ctx.directory);
+          const backingDir = path.dirname(backingPath);
+          mkdirSync(backingDir, { recursive: true });
+
+          let existingContent = "";
+          if (existsSync(backingPath)) {
+            existingContent = readFileSync(backingPath, "utf-8");
+          }
+
+          // Validate and apply edits
+          const existingLines = existingContent ? existingContent.split("\n") : [];
+
+          const validationError = validateEdits(existingLines, args.edits);
+          if (validationError) {
+            return `Error: ${validationError}`;
+          }
+
+          let resultLines: string[];
           try {
-            const resolved = resolvePlanContent(args.plan);
-            planContent = resolved.content;
-            sourceFilePath = resolved.filePath;
+            resultLines = applyEdits(existingLines, args.edits);
           } catch (err) {
-            return `Error: ${err instanceof Error ? err.message : String(err)}`;
+            return `Error applying edits: ${err instanceof Error ? err.message : String(err)}`;
           }
 
+          const planContent = resultLines.join("\n");
+          if (planContent.length > MAX_PLAN_SIZE) {
+            return `Error: Plan content exceeds the maximum size of ${MAX_PLAN_SIZE / (1024 * 1024)}MB.`;
+          }
           if (!planContent.trim()) {
-            return "Error: Plan content is empty. Write your plan first, then call submit_plan.";
+            return "Error: Plan content is empty after applying edits.";
           }
 
+          // Write backing file
+          writeFileSync(backingPath, planContent, "utf-8");
+
           const sharingEnabled = await getSharingEnabled();
           const server = await startPlannotatorServer({
             plan: planContent,
@@ -540,7 +656,7 @@ Use /plannotator-last or /plannotator-annotate for manual review, or set workflo
 
             if (result.feedback) {
               return getPlanApprovedWithNotesPrompt("opencode", undefined, {
-                planFilePath: sourceFilePath,
+                planFilePath: backingPath,
                 doneMsg: result.savedPath ? `Saved to: ${result.savedPath}` : "",
                 feedback: result.feedback,
                 proceedSuffix: shouldSwitchAgent
@@ -550,15 +666,18 @@ Use /plannotator-last or /plannotator-annotate for manual review, or set workflo
             }
 
             return getPlanApprovedPrompt("opencode", undefined, {
-              planFilePath: sourceFilePath,
+              planFilePath: backingPath,
               doneMsg: result.savedPath ? ` Saved to: ${result.savedPath}` : "",
             });
           } else {
+            const lineNumberedPlan = formatWithLineNumbers(planContent);
+            const totalLines = planContent.split("\n").length;
+
             return getPlanDeniedPrompt("opencode", undefined, {
               toolName: getPlanToolName("opencode"),
-              planFileRule: buildPlanFileRule(getPlanToolName("opencode"), sourceFilePath),
+              planFileRule: "",
               feedback: result.feedback || "Plan changes requested",
-            }) + "\n\nAfter making your revisions, call `submit_plan` again to resubmit for review.";
+            }) + `\n\n## Current Plan (${totalLines} lines)\n\nThe plan below shows the current state with line numbers. Use these exact line numbers in your next \`submit_plan\` call:\n\n\`\`\`\n${lineNumberedPlan}\n\`\`\`\n\nCall \`submit_plan\` with targeted edits to address the feedback above.`;
           }
         },
       }),