chore(release): publish 0.1.1-beta.6

Author: timrichardson

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1-beta.6
+
+- let users replace the plugin's base `agent.plan.prompt` instead of appending to it
+- add a `plan_prompt` tool so the `plan` agent can reveal the plugin prompt basis for customization
+
 ## 0.1.1-beta.5
 
 - gate `plan_exit` instructions on the OpenCode experimental plan-mode runtime flags

README.md

@@ -34,9 +34,43 @@ If you want reproducible installs instead of automatic plugin refreshes, pin an
 - adds a `plan` agent intended for design and implementation planning
 - constrains that agent to read-only tools plus markdown plan editing
 - injects a system reminder that keeps the planning workflow explicit
+- lets users replace the plugin's base `plan` prompt with their own `agent.plan.prompt`
+- exposes a `plan_prompt` tool so the `plan` agent can show the plugin's prompt basis for customization
 - uses `submit_plan` for review when available, otherwise falls back to manual chat review
 - can leave planner mode with `plan_exit` after approval when experimental plan mode is enabled in the CLI runtime
 
+## Customize the plan prompt
+
+If you set `agent.plan.prompt`, it replaces the plugin's base prompt instead of being appended to it.
+
+```json
+{
+  "agent": {
+    "plan": {
+      "prompt": "You are my planning agent. Focus on migration risk, rollout steps, and testing strategy."
+    }
+  }
+}
+```
+
+The runtime planner reminder still applies, so the agent stays in planner mode and continues to use the review handoff flow. That reminder is injected by the plugin at runtime and is not customized through `agent.plan.prompt`.
+
+## Reveal the plugin prompt basis
+
+The plugin also adds a read-only `plan_prompt` tool. Ask the `plan` agent to use it when you want the plugin's own prompt text as a starting point for customization.
+
+Example:
+
+```text
+Use the plan_prompt tool and show me the plugin prompt so I can customize it.
+```
+
+The tool returns:
+
+- the plugin base prompt
+- the injected planner reminder, which is plugin-controlled runtime guidance and is not customized via `agent.plan.prompt`
+- a short note explaining that the final runtime prompt can still differ because of user config, other plugins, or runtime tool availability like `plan_exit`
+
 ## Auto-updates
 
 OpenCode installs npm plugins automatically. During the prerelease phase, `opencode-planner@beta` gives the smoothest update path for most users.
@@ -57,7 +91,7 @@ npm run debug:plan
 npm run opencode:no-plannotator -- debug config
 ```
 
-`npm run debug:plan` checks the active OpenCode runtime and reports whether the local repo plugin is loaded, whether `submit_plan` and `plan_exit` are allowed by the `plan` agent, and whether they are actually registered as runtime tools.
+`npm run debug:plan` checks the active OpenCode runtime and reports whether the local repo plugin is loaded, whether `plan_prompt`, `submit_plan`, and `plan_exit` are allowed by the `plan` agent, and whether they are actually registered as runtime tools.
 
 This is the fastest way to distinguish:
 

index.js

@@ -2,6 +2,7 @@ import path from "path"
 
 const agent = "plan"
 const root = ".opencode/plans"
+const defaultPlanTarget = file("<session-id>")
 
 function truthy(key) {
   const value = process.env[key]?.toLowerCase()
@@ -25,6 +26,50 @@ function reviewInstruction(target) {
   ].join(" ")
 }
 
+function agentPrompt(target = defaultPlanTarget) {
+  const planExit = hasPlanExit()
+
+  return [
+    "Use this agent when the user wants a design, implementation plan, or scoped investigation before coding.",
+    "Stay in planning mode: inspect the codebase, ask targeted questions when needed, and write a concise execution plan before implementation.",
+    `Default plan path: ${target}.`,
+    "Prefer the task tool with the explore and general subagents for deeper research.",
+    reviewInstruction(target),
+    ...(planExit
+      ? [
+          "After approval, if the user or Plannotator says something like 'Proceed with implementation', call plan_exit to hand off back to implementation mode.",
+        ]
+      : []),
+  ].join("\n\n")
+}
+
+function promptDisclosure(target = defaultPlanTarget) {
+  return [
+    "# opencode-planner prompt basis",
+    "This tool shows the prompt text and planner reminder supplied by the opencode-planner plugin itself.",
+    "The final runtime prompt can still differ if the user overrides `agent.plan.prompt`, another plugin edits `agent.plan`, or runtime tool availability changes.",
+    "## Base prompt",
+    agentPrompt(defaultPlanTarget),
+    "## Planner reminder",
+    "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:",
+    [
+      "```json",
+      "{",
+      '  "agent": {',
+      '    "plan": {',
+      '      "prompt": "You are my planning agent. Focus on migration risk, rollout steps, and testing strategy."',
+      "    }",
+      "  }",
+      "}",
+      "```",
+    ].join("\n"),
+    "Ask the `plan` agent to call `plan_prompt` when you want a fresh copy of the plugin prompt as a starting point.",
+  ].join("\n\n")
+}
+
 function note(id) {
   const out = [
     "<system-reminder>",
@@ -74,23 +119,11 @@ function merge(a, b) {
 }
 
 function mode(input = {}) {
-  const planExit = hasPlanExit()
   const base = {
     mode: "primary",
     color: "info",
     description: "Researches the codebase and writes execution plans without editing source files.",
-    prompt: [
-      "Use this agent when the user wants a design, implementation plan, or scoped investigation before coding.",
-      "Stay in planning mode: inspect the codebase, ask targeted questions when needed, and write a concise execution plan before implementation.",
-      "Default plan path: .opencode/plans/<session-id>.md.",
-      "Prefer the task tool with the explore and general subagents for deeper research.",
-      reviewInstruction(".opencode/plans/<session-id>.md"),
-      ...(planExit
-        ? [
-            "After approval, if the user or Plannotator says something like 'Proceed with implementation', call plan_exit to hand off back to implementation mode.",
-          ]
-        : []),
-    ].join("\n\n"),
+    prompt: agentPrompt(),
     permission: {
       "*": "deny",
       read: {
@@ -111,8 +144,9 @@ function mode(input = {}) {
       websearch: "allow",
       codesearch: "allow",
       batch: "allow",
+      plan_prompt: "allow",
       submit_plan: "allow",
-      ...(planExit ? { plan_exit: "allow" } : {}),
+      ...(hasPlanExit() ? { plan_exit: "allow" } : {}),
       edit: {
         "*": "deny",
         [path.posix.join(root, "*.md")]: "allow",
@@ -130,7 +164,7 @@ function mode(input = {}) {
   return {
     ...base,
     ...input,
-    prompt: [base.prompt, input?.prompt].filter(Boolean).join("\n\n"),
+    prompt: input && Object.hasOwn(input, "prompt") ? input.prompt : base.prompt,
     permission: merge(base.permission, input?.permission),
   }
 }
@@ -139,6 +173,15 @@ export default async function plannerPlugin() {
   const seen = new Set()
 
   return {
+    tool: {
+      plan_prompt: {
+        description: "Reveal the planner plugin prompt basis",
+        args: {},
+        async execute(_, context) {
+          return promptDisclosure(context.sessionID ? file(context.sessionID) : defaultPlanTarget)
+        },
+      },
+    },
     async config(cfg) {
       cfg.agent ??= {}
       cfg.agent[agent] = mode(cfg.agent[agent])

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-planner",
-  "version": "0.1.1-beta.5",
+  "version": "0.1.1-beta.6",
   "description": "Experimental OpenCode plugin that adds a dedicated planning agent with read-only planning constraints.",
   "type": "module",
   "author": "Tim Richardson",

scripts/debug-plan-runtime.js

@@ -40,8 +40,10 @@ const permissions = plan.permission ?? []
 const tools = plan.tools ?? {}
 const prompt = plan.prompt ?? ""
 
+const planPromptAllowed = hasAllowedPermission("plan_prompt", permissions)
 const planExitAllowed = hasAllowedPermission("plan_exit", permissions)
 const submitPlanAllowed = hasAllowedPermission("submit_plan", permissions)
+const planPromptTool = Boolean(tools.plan_prompt)
 const planExitTool = Boolean(tools.plan_exit)
 const submitPlanTool = Boolean(tools.submit_plan)
 const usingLocalPlugin = plugins.includes(localPlugin)
@@ -50,6 +52,8 @@ const promptMentionsPlanExit = prompt.includes("plan_exit")
 console.log("OpenCode plan runtime check")
 console.log("")
 line("Repo plugin loaded", usingLocalPlugin ? "yes" : "no")
+line("plan_prompt allowed", planPromptAllowed ? "yes" : "no")
+line("plan_prompt tool", planPromptTool ? "yes" : "no")
 line("submit_plan allowed", submitPlanAllowed ? "yes" : "no")
 line("plan_exit allowed", planExitAllowed ? "yes" : "no")
 line("submit_plan tool", submitPlanTool ? "yes" : "no")
@@ -70,6 +74,9 @@ console.log("\nAssessment:")
 if (!usingLocalPlugin) {
   console.log(`- OpenCode is not using the local repo plugin at ${localPlugin}.`)
 }
+if (!planPromptTool) {
+  console.log("- plan_prompt is not registered as a runtime tool.")
+}
 if (!submitPlanTool) {
   console.log("- submit_plan is not registered as a runtime tool.")
 }

test/plugin.test.js

@@ -40,6 +40,7 @@ test("config hook registers the plan agent without plan_exit by default", async
 
       assert.equal(cfg.agent.plan.mode, "primary")
       assert.equal(cfg.agent.plan.permission.bash, "deny")
+      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.match(cfg.agent.plan.prompt, /if the submit_plan tool is available/i)
@@ -49,6 +50,37 @@ test("config hook registers the plan agent without plan_exit by default", async
   )
 })
 
+test("config hook lets users replace the plugin prompt", async () => {
+  await withEnv(
+    {
+      OPENCODE_EXPERIMENTAL: undefined,
+      OPENCODE_EXPERIMENTAL_PLAN_MODE: undefined,
+      OPENCODE_CLIENT: undefined,
+    },
+    async () => {
+      const plugin = await plannerPlugin()
+      const cfg = {
+        agent: {
+          plan: {
+            prompt: "Use my custom plan instructions only.",
+            permission: {
+              webfetch: "deny",
+            },
+          },
+        },
+      }
+
+      await plugin.config(cfg)
+
+      assert.equal(cfg.agent.plan.prompt, "Use my custom plan instructions only.")
+      assert.equal(cfg.agent.plan.permission.webfetch, "deny")
+      assert.equal(cfg.agent.plan.permission.bash, "deny")
+      assert.equal(cfg.agent.plan.permission.plan_prompt, "allow")
+      assert.doesNotMatch(cfg.agent.plan.prompt, /if the submit_plan tool is available/i)
+    },
+  )
+})
+
 test("config hook enables plan_exit when experimental plan mode is active", async () => {
   await withEnv(
     {
@@ -139,3 +171,54 @@ test("system transform only applies after planner messages", async () => {
     },
   )
 })
+
+test("plan_prompt tool returns the plugin prompt basis without plan_exit by default", async () => {
+  await withEnv(
+    {
+      OPENCODE_EXPERIMENTAL: undefined,
+      OPENCODE_EXPERIMENTAL_PLAN_MODE: undefined,
+      OPENCODE_CLIENT: undefined,
+    },
+    async () => {
+      const plugin = await plannerPlugin()
+      const output = await plugin.tool.plan_prompt.execute(
+        {},
+        {
+          sessionID: "ses_tool",
+        },
+      )
+
+      assert.match(output, /# opencode-planner prompt basis/)
+      assert.match(output, /## Base prompt/)
+      assert.match(output, /## Planner reminder/)
+      assert.match(output, /injected by the plugin at runtime/i)
+      assert.match(output, /not customized through `agent\.plan\.prompt`/i)
+      assert.match(output, /```json/)
+      assert.match(output, /"agent": \{/)
+      assert.match(output, /\.opencode\/plans\/ses_tool\.md/)
+      assert.match(output, /agent\.plan\.prompt/)
+      assert.doesNotMatch(output, /call plan_exit/)
+    },
+  )
+})
+
+test("plan_prompt tool mentions plan_exit when experimental plan mode is active", async () => {
+  await withEnv(
+    {
+      OPENCODE_EXPERIMENTAL: undefined,
+      OPENCODE_EXPERIMENTAL_PLAN_MODE: "1",
+      OPENCODE_CLIENT: "cli",
+    },
+    async () => {
+      const plugin = await plannerPlugin()
+      const output = await plugin.tool.plan_prompt.execute(
+        {},
+        {
+          sessionID: "ses_tool",
+        },
+      )
+
+      assert.match(output, /call plan_exit/)
+    },
+  )
+})