feat: scaffold opencode planner plugin

Author: timrichardson

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm test

.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npm publish --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+npm-debug.log*
+*.tgz

CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- initial standalone npm package for the `plan` agent plugin
+- includes OpenCode install instructions, CI, and npm publish workflow templates

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Richardson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,69 @@
+# opencode-planner
+
+`opencode-planner` is an OpenCode plugin that adds a dedicated `plan` agent for read-only planning before implementation.
+
+Repository: <https://github.com/timrichardson/opencode-planner>
+
+## Install for OpenCode
+
+Add this to `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-planner@latest"]
+}
+```
+
+Then restart OpenCode.
+
+If you want reproducible installs instead of automatic plugin refreshes, pin an exact version:
+
+```json
+{
+  "plugin": ["opencode-planner@0.1.0"]
+}
+```
+
+## What it does
+
+- 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
+
+## Auto-updates
+
+OpenCode installs npm plugins automatically. Using `opencode-planner@latest` gives the smoothest update path for most users.
+
+- `@latest`: pick up new published plugin versions on restart
+- 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.
+
+## Development
+
+```bash
+npm test
+```
+
+## Release process
+
+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`.
+5. Publish to npm.
+6. Publish matching GitHub release notes.
+
+The repository includes GitHub Actions templates for CI and npm publishing from version tags.
+
+## GitHub Actions setup
+
+Set this repository secret for automated npm publishing:
+
+- `NPM_TOKEN`
+
+The release workflow publishes on version tags like `v0.1.0` and creates GitHub release notes automatically.
+
+## License
+
+MIT

index.js

@@ -0,0 +1,132 @@
+import path from "path"
+
+const agent = "plan"
+const root = ".opencode/plans"
+
+function file(id) {
+  return path.posix.join(root, `${id}.md`)
+}
+
+function note(id) {
+  return [
+    "<system-reminder>",
+    "Planner mode is active.",
+    "You must not edit source files, run bash, change config, or make commits.",
+    "You may only use read-only tools, ask clarifying questions, delegate exploration or design with the task tool, and edit allowed markdown plan files.",
+    `Write the plan to ${file(id)} or another allowed *.plan.md/*.spec.md file.`,
+    "When the plan is complete, call the submit_plan tool to open Plannotator for review.",
+    "</system-reminder>",
+  ].join("\n")
+}
+
+function partID() {
+  return `prt_${crypto.randomUUID()}`
+}
+
+function rules(input) {
+  if (!input) return {}
+  if (typeof input === "string") return { "*": input }
+  return input
+}
+
+function merge(a, b) {
+  const left = rules(a)
+  const right = rules(b)
+  const out = { ...left, ...right }
+
+  for (const key of Object.keys(left)) {
+    const x = left[key]
+    const y = right[key]
+    if (!x || !y || typeof x !== "object" || typeof y !== "object") continue
+    if (Array.isArray(x) || Array.isArray(y)) continue
+    out[key] = { ...x, ...y }
+  }
+
+  return out
+}
+
+function mode(input = {}) {
+  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.",
+      "Do not stop after writing the plan; call submit_plan to submit the plan for review.",
+    ].join("\n\n"),
+    permission: {
+      "*": "deny",
+      read: {
+        "*": "allow",
+        "*.env": "ask",
+        "*.env.*": "ask",
+        "*.env.example": "allow",
+      },
+      glob: "allow",
+      grep: "allow",
+      question: "allow",
+      task: {
+        "*": "deny",
+        explore: "allow",
+        general: "allow",
+      },
+      webfetch: "allow",
+      websearch: "allow",
+      codesearch: "allow",
+      batch: "allow",
+      submit_plan: "allow",
+      edit: {
+        "*": "deny",
+        [path.posix.join(root, "*.md")]: "allow",
+        "plans/*.md": "allow",
+        "specs/*.md": "allow",
+        "**/*.plan.md": "allow",
+        "**/*.spec.md": "allow",
+      },
+      bash: "deny",
+      skill: "deny",
+      todowrite: "deny",
+    },
+  }
+
+  return {
+    ...base,
+    ...input,
+    prompt: [base.prompt, input?.prompt].filter(Boolean).join("\n\n"),
+    permission: merge(base.permission, input?.permission),
+  }
+}
+
+export default async function plannerPlugin() {
+  const seen = new Set()
+
+  return {
+    async config(cfg) {
+      cfg.agent ??= {}
+      cfg.agent[agent] = mode(cfg.agent[agent])
+    },
+    async "chat.message"(input, output) {
+      if (input.agent !== agent) {
+        seen.delete(input.sessionID)
+        return
+      }
+
+      seen.add(input.sessionID)
+      output.parts.push({
+        id: partID(),
+        messageID: output.message.id,
+        sessionID: output.message.sessionID,
+        type: "text",
+        text: note(input.sessionID),
+        synthetic: true,
+      })
+    },
+    async "experimental.chat.system.transform"(input, output) {
+      if (!input.sessionID || !seen.has(input.sessionID)) return
+      output.system.push(note(input.sessionID))
+    },
+  }
+}

package-lock.json

@@ -0,0 +1,33 @@
+{
+  "name": "opencode-planner",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that adds a dedicated planning agent with read-only planning constraints.",
+  "type": "module",
+  "author": "Tim Richardson",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "planning",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timrichardson/opencode-planner.git"
+  },
+  "homepage": "https://github.com/timrichardson/opencode-planner#readme",
+  "bugs": {
+    "url": "https://github.com/timrichardson/opencode-planner/issues"
+  },
+  "license": "MIT"
+}

package.json

@@ -0,0 +1,64 @@
+import test from "node:test"
+import assert from "node:assert/strict"
+
+import plannerPlugin from "../index.js"
+
+test("config hook registers the plan agent", async () => {
+  const plugin = await plannerPlugin()
+  const cfg = {}
+
+  await plugin.config(cfg)
+
+  assert.equal(cfg.agent.plan.mode, "primary")
+  assert.equal(cfg.agent.plan.permission.bash, "deny")
+  assert.equal(cfg.agent.plan.permission.submit_plan, "allow")
+})
+
+test("chat.message injects a planner reminder part", async () => {
+  const plugin = await plannerPlugin()
+  const input = {
+    agent: "plan",
+    sessionID: "ses_123",
+  }
+  const output = {
+    message: {
+      id: "msg_123",
+      sessionID: "ses_123",
+    },
+    parts: [],
+  }
+
+  await plugin["chat.message"](input, output)
+
+  assert.equal(output.parts.length, 1)
+  assert.equal(output.parts[0].type, "text")
+  assert.match(output.parts[0].id, /^prt_/)
+  assert.match(output.parts[0].text, /Planner mode is active\./)
+})
+
+test("system transform only applies after planner messages", async () => {
+  const plugin = await plannerPlugin()
+  const system = { system: [] }
+
+  await plugin["experimental.chat.system.transform"]({ sessionID: "ses_other" }, system)
+  assert.deepEqual(system.system, [])
+
+  await plugin["chat.message"](
+    {
+      agent: "plan",
+      sessionID: "ses_plan",
+    },
+    {
+      message: {
+        id: "msg_plan",
+        sessionID: "ses_plan",
+      },
+      parts: [],
+    },
+  )
+
+  await plugin["experimental.chat.system.transform"]({ sessionID: "ses_plan" }, system)
+
+  assert.equal(system.system.length, 1)
+  assert.match(system.system[0], /submit_plan/)
+})