feat: add /edit-plan command and stable release cleanup

Author: timrichardson

.github/workflows/release.yml

@@ -27,15 +27,10 @@ jobs:
         run: |
           version="${GITHUB_REF_NAME#v}"
           if [[ "$version" == *-* ]]; then
-            prerelease_part="${version#*-}"
-            dist_tag="${prerelease_part%%.*}"
-            echo "prerelease=true" >> "$GITHUB_OUTPUT"
-          else
-            dist_tag="latest"
-            echo "prerelease=false" >> "$GITHUB_OUTPUT"
+            echo "Only stable release tags are supported: $version" >&2
+            exit 1
           fi
           echo "version=$version" >> "$GITHUB_OUTPUT"
-          echo "dist_tag=$dist_tag" >> "$GITHUB_OUTPUT"
       - name: Ensure tag matches package version
         shell: bash
         run: |
@@ -44,25 +39,15 @@ jobs:
             echo "Tag version ${{ steps.meta.outputs.version }} does not match package.json version $package_version" >&2
             exit 1
           fi
-      - run: npm publish --access public --tag "${{ steps.meta.outputs.dist_tag }}"
-      - name: Mirror stable release to beta dist-tag
-        if: steps.meta.outputs.dist_tag == 'latest'
-        run: npm dist-tag add "opencode-planner@${{ steps.meta.outputs.version }}" beta
+      - run: npm publish --access public --tag latest
       - name: Create GitHub release
         shell: bash
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PRERELEASE: ${{ steps.meta.outputs.prerelease }}
         run: |
           if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
             echo "GitHub release for $GITHUB_REF_NAME already exists."
             exit 0
           fi
 
-          args=(release create "$GITHUB_REF_NAME" --verify-tag --generate-notes)
-
-          if [[ "$PRERELEASE" == "true" ]]; then
-            args+=(--prerelease)
-          fi
-
-          gh "${args[@]}"
+          gh release create "$GITHUB_REF_NAME" --verify-tag --generate-notes

AGENTS.md

@@ -49,5 +49,5 @@ Use `npm test` for normal code changes. Use the runtime debug and sandbox comman
 ## Notes For Agents
 
 - This repo currently has no dedicated lint or format script; preserve the existing style manually.
-- The package is published from version tags, and the README documents the prerelease `@beta` install path.
+- The package is published from version tags, and the README documents the stable install path.
 - Changes around `plan_exit` should preserve the current runtime contract: only mention or allow it when experimental plan mode is enabled and the client is `cli`.

CHANGELOG.md

@@ -1,9 +1,14 @@
 # Changelog
 
+## Unreleased
+
+- add an `/edit-plan` command that routes to the `plan` agent and reuses the existing `edit_plan` tool flow
+- document `/edit-plan` and surface it in the runtime debug output
+
 ## 0.2.0
 
-- promote `opencode-planner` from beta to its stable release line
-- keep the npm `beta` dist-tag aligned with the current stable release until the next prerelease cycle
+- promote `opencode-planner` to its stable release line
+- publish stable releases to npm `latest`
 
 ## 0.1.1-beta.11
 

README.md

@@ -1,16 +1,27 @@
 # opencode-planner
 
-`opencode-planner` is an OpenCode plugin that adds a dedicated `plan` agent for read-only planning before implementation. Its functionality is an emulation of the experimental plan agent (it has no hard dependency on EXPERIMENTAL_PLAN_MODE=1, altough that setting enables a tool called plan_exit which this plugin will use if available). That is, it likes to use sub-agents and a structured approach to planning, asks clarifying questions, and finally it produces a markdown file. 
+`opencode-planner` is an OpenCode plugin that adds a dedicated `plan` agent for read-only planning before implementation. Its functionality is an emulation of the experimental plan agent (it has no hard dependency on `EXPERIMENTAL_PLAN_MODE=1`, although that setting enables a tool called plan_exit which this plugin will use if available). That is, it likes to use sub-agents and a structured approach to planning, asks clarifying questions, and finally it produces a markdown file. 
+
+
+When Plannotator is installed, it can submit the finished plan for richer review. 
+
+Without Plannotator, it can open the plan in your configured external editor for review. A new command `/edit-plan` will open the plan in the editor if needed. 
+
+In either case, changes made while editing will trigger a revision of the plan. 
 
-When Plannotator is installed, it can submit the finished plan for richer review. Without Plannotator, it can open the plan in your configured external editor for review.
 
 After review, the agent can hand back to implementation mode by calling `plan_exit` only when the host runtime exposes that tool. In current OpenCode builds, that means experimental plan mode must be enabled and the client must be `cli`. If it's not enabled, you need to prompt the build agent to start work.
 
 Repository: <https://github.com/timrichardson/opencode-planner>
 
+
+### Rationale
+Experimental plan mode is not a focus for the core devs, who point out that a plugin can do it, which I set out to prove, at least as a concept. This plugin means, at least for me, a development path for a stronger Plan agent independent of core OpenCode priorities.
+
+
 ## Install for OpenCode
 
-Add this to `opencode.json`:
+Add this to `opencode.jsonc` (or `opencode.json`):
 
 ```json
 {
@@ -40,9 +51,10 @@ If you want reproducible installs instead of automatic plugin refreshes, pin an
 - denies `submit_plan`, `edit_plan`, and `plan_exit` to the built-in `general` and `explore` subagents so review and implementation handoff stay on the primary `plan` agent
 - exposes a `plan_prompt` tool so the `plan` agent can reveal the plugin's prompt basis for customization
 - exposes an `edit_plan` tool so the `plan` agent can open the current plan in the configured external editor
+- registers an `/edit-plan` command that routes to the `plan` agent and asks it to call `edit_plan`
 - uses `submit_plan` for review when available, otherwise falls back to external-editor review
 - keeps the agent in planner mode if the plan file changed after `submit_plan`; the revised plan must be resubmitted before `plan_exit`
-- can leave planner mode with `plan_exit` after approval when experimental plan mode is enabled in the CLI runtime
+- can leave planner mode with `plan_exit` after approval when experimental plan mode is enabled in the CLI runtime (because the plan_exit tool is only available with `EXPERIMENTAL_PLAN_MODE` enabled; se OpenCode docs for Experiments)
 
 ## Customize the plan agent
 
@@ -80,6 +92,16 @@ The tool returns:
 
 ## Review Without Plannotator
 
+In the TUI, you can use `/edit-plan` as a shortcut to ask the `plan` agent to reopen the current plan in your configured external editor. This routes through the existing `edit_plan` tool behavior.
+
+Example:
+
+```text
+/edit-plan
+```
+
+This expects the current session to already have a plan file, and it still requires `PLAN_VISUAL`, `VISUAL`, or `EDITOR` to launch a blocking editor command.
+
 If `submit_plan` is not registered by the runtime, the plugin's `edit_plan` tool gives the `plan` agent a fallback way to open the current plan in your configured external editor.
 
 Example:
@@ -126,10 +148,7 @@ If you edit the plan after calling `submit_plan`, the plugin treats that as a ne
 
 OpenCode installs and updates npm plugins automatically. `opencode-planner` tracks `@latest` by default, which is the recommended channel for most users.
 
-The `beta` dist-tag currently points at the same release as `latest`. That keeps existing beta installs on the current stable build until a future prerelease line resumes.
-
 - `@latest`: pick up stable plugin versions on restart
-- `@beta`: currently follows the same version as `@latest`
 - exact version pin: stay fixed until the config is changed deliberately
 
 If OpenCode appears to keep an older cached plugin, clear the cache under `~/.cache/opencode/` and restart.
@@ -162,8 +181,8 @@ It starts OpenCode with an isolated temporary home/config, keeps the local repo
 1. Update `CHANGELOG.md`.
 2. Bump the version in `package.json`.
 3. Commit the release.
-4. Create and push a git tag like `v0.1.1-beta.1` for prereleases or `v0.1.1` for stable releases.
-5. Let GitHub Actions publish to npm using the correct dist-tag.
+4. Create and push a git tag like `v0.2.0` for the release.
+5. Let GitHub Actions publish to npm `latest`.
 6. Publish matching GitHub release notes.
 
 The repository includes GitHub Actions templates for CI and npm publishing from version tags.
@@ -179,7 +198,7 @@ Configure npm Trusted Publishing for this package:
    - Repository: `opencode-planner`
    - Workflow filename: `release.yml`
 
-The release workflow publishes prerelease tags like `v0.1.1-beta.1` to the npm `beta` dist-tag, stable tags like `v0.1.1` to `latest`, and creates matching GitHub release notes automatically.
+The release workflow publishes stable tags like `v0.2.0` to npm `latest` and creates matching GitHub release notes automatically.
 
 Trusted Publishing uses GitHub OIDC and does not require an `NPM_TOKEN` secret for publishing.
 

index.js

@@ -7,6 +7,12 @@ import process from "node:process"
 const agent = "plan"
 const root = ".opencode/plans"
 const defaultPlanTarget = file("<session-id>")
+const editPlanCommand = {
+  description: "Reopen the current plan in your editor",
+  agent,
+  template:
+    "Reopen the current markdown plan in the configured external editor by calling the edit_plan tool. If the tool reports that the user changed the plan externally, treat those edits as review feedback, summarize what changed, and continue planning from the updated plan.",
+}
 
 function truthy(key) {
   const value = process.env[key]?.toLowerCase()
@@ -60,7 +66,7 @@ function promptDisclosure(target = defaultPlanTarget) {
     "This reminder is injected by the plugin at runtime to keep the `plan` agent in planner mode and enforce the review handoff workflow. It is plugin-controlled and is not customized through `agent.plan.prompt`.",
     note(target.replace(`${root}/`, "").replace(/\.md$/, "")),
     "## How to customize it",
-    "Only the Base prompt above is replaced by `agent.plan.prompt`. Add this to `opencode.json` to replace that base prompt:",
+    "Only the Base prompt above is replaced by `agent.plan.prompt`. Add this to `opencode.jsonc` to replace that base prompt:",
     [
       "```json",
       "{",
@@ -353,6 +359,10 @@ export default async function plannerPlugin() {
     },
     async config(cfg) {
       cfg.agent ??= {}
+      cfg.command = {
+        "edit-plan": editPlanCommand,
+        ...cfg.command,
+      }
       cfg.agent[agent] = mode(cfg.agent[agent])
       cfg.agent.general = restrictPlannerSubagent(cfg.agent.general)
       cfg.agent.explore = restrictPlannerSubagent(cfg.agent.explore)

scripts/debug-plan-runtime.js

@@ -36,10 +36,12 @@ const config = runJSON(["debug", "config"])
 const plan = runJSON(["debug", "agent", "plan"])
 
 const plugins = config.plugin ?? []
+const commands = config.command ?? {}
 const permissions = plan.permission ?? []
 const tools = plan.tools ?? {}
 const prompt = plan.prompt ?? ""
 
+const editPlanCommandConfigured = Boolean(commands["edit-plan"])
 const planPromptAllowed = hasAllowedPermission("plan_prompt", permissions)
 const editPlanAllowed = hasAllowedPermission("edit_plan", permissions)
 const planExitAllowed = hasAllowedPermission("plan_exit", permissions)
@@ -54,6 +56,7 @@ const promptMentionsPlanExit = prompt.includes("plan_exit")
 console.log("OpenCode plan runtime check")
 console.log("")
 line("Repo plugin loaded", usingLocalPlugin ? "yes" : "no")
+line("/edit-plan command", editPlanCommandConfigured ? "yes" : "no")
 line("plan_prompt allowed", planPromptAllowed ? "yes" : "no")
 line("plan_prompt tool", planPromptTool ? "yes" : "no")
 line("edit_plan allowed", editPlanAllowed ? "yes" : "no")
@@ -78,6 +81,9 @@ console.log("\nAssessment:")
 if (!usingLocalPlugin) {
   console.log(`- OpenCode is not using the local repo plugin at ${localPlugin}.`)
 }
+if (!editPlanCommandConfigured) {
+  console.log("- /edit-plan is not configured in the resolved command list.")
+}
 if (!planPromptTool) {
   console.log("- plan_prompt is not registered as a runtime tool.")
 }

scripts/run-opencode-sandbox.js

@@ -8,7 +8,11 @@ import { fileURLToPath } from "node:url"
 const here = path.dirname(fileURLToPath(import.meta.url))
 const root = path.resolve(here, "..")
 const localPlanner = `file://${path.join(root, "index.js")}`
-const globalConfigPath = path.join(os.homedir(), ".config", "opencode", "opencode.json")
+const globalConfigDir = path.join(os.homedir(), ".config", "opencode")
+const globalConfigPaths = [
+  path.join(globalConfigDir, "opencode.jsonc"),
+  path.join(globalConfigDir, "opencode.json"),
+]
 
 function usage() {
   console.log(`Usage: node scripts/run-opencode-sandbox.js [--without-plannotator] [opencode args...]
@@ -24,18 +28,82 @@ function normalizePlugin(entry) {
 }
 
 function parseLooseJSON(text) {
-  return JSON.parse(
-    text
-      .replace(/^\uFEFF/, "")
-      .replace(/,\s*([}\]])/g, "$1"),
-  )
+  const source = text.replace(/^\uFEFF/, "")
+  let out = ""
+  let inString = false
+  let quote = ""
+  let escaped = false
+
+  for (let i = 0; i < source.length; i++) {
+    const char = source[i]
+    const next = source[i + 1]
+
+    if (inString) {
+      out += char
+      if (escaped) {
+        escaped = false
+        continue
+      }
+      if (char === "\\") {
+        escaped = true
+        continue
+      }
+      if (char === quote) {
+        inString = false
+        quote = ""
+      }
+      continue
+    }
+
+    if (char === '"') {
+      inString = true
+      quote = char
+      out += char
+      continue
+    }
+
+    if (char === "/" && next === "/") {
+      i += 2
+      while (i < source.length && source[i] !== "\n") i += 1
+      if (i < source.length) out += "\n"
+      continue
+    }
+
+    if (char === "/" && next === "*") {
+      i += 2
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/")) i += 1
+      i += 1
+      continue
+    }
+
+    out += char
+  }
+
+  return JSON.parse(out.replace(/,\s*([}\]])/g, "$1"))
 }
 
 function keepWithoutPlannotator(entry) {
   const id = normalizePlugin(entry)
   return id !== "@plannotator/opencode@latest" && id !== "@plannotator/opencode"
 }
 
+async function readGlobalConfig() {
+  for (const file of globalConfigPaths) {
+    try {
+      return parseLooseJSON(await fs.readFile(file, "utf8"))
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        continue
+      }
+      throw error
+    }
+  }
+
+  throw new Error(
+    `No OpenCode config found. Checked: ${globalConfigPaths.map((file) => `\`${file}\``).join(", ")}`,
+  )
+}
+
 const rawArgs = process.argv.slice(2)
 if (rawArgs.includes("-h") || rawArgs.includes("--help")) {
   usage()
@@ -45,7 +113,7 @@ if (rawArgs.includes("-h") || rawArgs.includes("--help")) {
 const stripPlannotator = rawArgs.includes("--without-plannotator")
 const opencodeArgs = rawArgs.filter((arg) => arg !== "--without-plannotator")
 
-const baseConfig = parseLooseJSON(await fs.readFile(globalConfigPath, "utf8"))
+const baseConfig = await readGlobalConfig()
 const plugin = (baseConfig.plugin ?? []).filter((entry) => !stripPlannotator || keepWithoutPlannotator(entry))
 
 const filtered = plugin.filter((entry) => normalizePlugin(entry) !== localPlanner)

test/plugin.test.js

@@ -59,6 +59,9 @@ test("config hook registers the plan agent without plan_exit by default", async
       assert.equal(cfg.agent.plan.permission.plan_prompt, "allow")
       assert.equal(cfg.agent.plan.permission.submit_plan, "allow")
       assert.equal(cfg.agent.plan.permission.plan_exit, undefined)
+      assert.equal(cfg.command["edit-plan"].description, "Reopen the current plan in your editor")
+      assert.equal(cfg.command["edit-plan"].agent, "plan")
+      assert.match(cfg.command["edit-plan"].template, /calling the edit_plan tool/i)
       assert.match(cfg.agent.plan.prompt, /if the submit_plan tool is available/i)
       assert.match(cfg.agent.plan.prompt, /call edit_plan to open the markdown plan/i)
       assert.match(cfg.agent.plan.prompt, /treat that as review feedback on the plan/i)
@@ -68,6 +71,29 @@ test("config hook registers the plan agent without plan_exit by default", async
   )
 })
 
+test("config hook adds edit-plan without overwriting user commands", async () => {
+  const plugin = await plannerPlugin()
+  const cfg = {
+    command: {
+      custom: {
+        template: "Do something custom.",
+      },
+      "edit-plan": {
+        template: "Use my custom edit-plan flow.",
+        description: "Custom edit plan",
+        agent: "general",
+      },
+    },
+  }
+
+  await plugin.config(cfg)
+
+  assert.equal(cfg.command.custom.template, "Do something custom.")
+  assert.equal(cfg.command["edit-plan"].template, "Use my custom edit-plan flow.")
+  assert.equal(cfg.command["edit-plan"].description, "Custom edit plan")
+  assert.equal(cfg.command["edit-plan"].agent, "general")
+})
+
 test("config hook lets users replace the plugin prompt", async () => {
   await withEnv(
     {