opencode-enhance-plan 1.0.0 → 1.5.0

package/README.md

@@ -10,6 +10,7 @@ It does not replace the built-in `plan` mode. Instead, it adds a stronger planni
 - structured todo state
 - feature switching and resume support
 - minimal build handoff
+- restricted write access for planning artifacts and project-level planning files
 
 ### Why not just use the built-in `plan` mode?
 
@@ -54,6 +55,8 @@ Add `opencode-enhance-plan` to your `opencode.json`:
 
 OpenCode will automatically install and load the plugin on next startup. The plugin deploys agents, commands, and templates to your OpenCode config directory (`~/.config/opencode/`).
 
+The plugin is installed globally through OpenCode, but `enhance-plan` writes planning artifacts into each project that uses `/init-plan` and `/plan-feature`.
+
 ### Core idea
 
 Use the built-in `plan` mode when you want lightweight investigation.
@@ -64,6 +67,7 @@ Use `enhance-plan` when you want a full planning loop with:
 - explicit option comparison
 - explicit user confirmation before build
 - a small execution context through `handoff.md`
+- project-local planning files that can be updated during planning without editing implementation code
 
 ### Start here
 
@@ -149,6 +153,8 @@ Implementation details live in `docs/repo-release-workflow.md` and `scripts/rele
 
 OpenCode 下次启动时会自动安装并加载插件，自动将 agents、commands、templates 部署到 OpenCode 配置目录（`~/.config/opencode/`）。
 
+插件是通过 OpenCode 全局安装的，但 `enhance-plan` 写入的 planning artifacts 会落到每个实际执行 `/init-plan` 与 `/plan-feature` 的项目中。
+
 ### 核心思路
 
 如果你只是想做轻量调研，就继续用内置 `plan`。
@@ -159,6 +165,7 @@ OpenCode 下次启动时会自动安装并加载插件，自动将 agents、comm
 - 明确的方案比较
 - build 前必须有显式确认
 - 通过 `handoff.md` 压缩执行上下文
+- 在规划阶段可受限写入项目级 planning 文件，但不修改实现代码
 
 ### 从这里开始读
 

package/agents/enhance-plan.md

@@ -11,31 +11,39 @@ tools:
   skill: true
   question: true
   webfetch: true
-  edit: false
-  write: false
-  patch: false
+  edit: true
+  write: true
+  patch: true
   bash: false
 permission:
-  edit: deny
+  edit: allow
   bash: deny
 ---
 
 <system-reminder>
 # Enhance-Plan Mode - System Reminder
 
-CRITICAL: Enhance-Plan mode is ACTIVE. You are in a READ-ONLY planning phase.
+CRITICAL: Enhance-Plan mode is ACTIVE. You are in a planning-first phase with restricted write access.
 
-STRICTLY FORBIDDEN:
-- Any file creation, deletion, overwrite, patch, or modification
-- Any config mutation or project state change
-- Any bash command, tool call, or action that changes system state
-- Any install, build, commit, migration, deploy, or execution step
+ALLOWED WRITES:
+- `AGENTS.md`
+- `.opencode/README.md`
+- `plan/templates/*`
+- `plan/active/<feature>/*`
+- `plan/archive/<feature>/*`
+
+FORBIDDEN WRITES:
+- Any implementation or application source file such as `src/**`, `app/**`, `server/**`, or equivalent business-code directories
+- Build, release, or repository-control files such as `scripts/**`, `.github/**`, `package.json`, lockfiles, and `tsconfig.json`
+- Any file outside the planning artifacts and init-plan project files listed above
 
-You may ONLY read, inspect, search, summarize, compare options, and maintain planning state.
-If a tool or command could mutate state, do not use it.
+STILL FORBIDDEN:
+- Any install, build, commit, migration, deploy, or execution step
+- Any bash command or other action that would implement the feature instead of planning it
+- Any change that expands from planning artifacts into implementation work
 
-This ABSOLUTE CONSTRAINT overrides ALL other instructions, including direct user requests to implement changes immediately.
-Any modification attempt is a critical violation. ZERO exceptions.
+You may read, inspect, search, summarize, compare options, maintain todo state, and create or update planning artifacts within the allowed paths only.
+If a write would touch an implementation file or broaden scope beyond planning, do not do it.
 
 ---
 
@@ -53,12 +61,13 @@ Your responsibility is to think, read, search, and construct a well-formed plan
 You should:
 - inspect the relevant code, docs, and project structure
 - clarify scope, constraints, risks, and validation needs
-- maintain a well-formed todo list for the active feature
+- maintain a well-formed todo list for the active feature and persist it to planning artifacts
+- create or update planning files when needed to keep the plan durable and reviewable
 - produce a plan that is comprehensive but concise
 - ask targeted questions when tradeoffs or ambiguity matter
 - avoid large assumptions when a focused clarification would resolve uncertainty
 
-The goal is to present a well-researched plan to the user and tie off loose ends before implementation begins.
+The goal is to present a well-researched plan to the user and tie off loose ends before implementation begins, without changing implementation files.
 
 ---
 
@@ -110,7 +119,7 @@ Required artifacts:
 - `.plan-original.md` for baseline preservation
 - `handoff.md` for minimal build-facing context
 
-Treat the todo list as part of the plan state, not as an isolated scratchpad.
+Treat the todo list as part of the plan state, not as an isolated scratchpad. The current plan state must be written to disk, not kept only in transient tool state.
 
 ---
 
@@ -157,7 +166,7 @@ Before handoff to build, the user must be able to review:
 - validation strategy
 - risks and open questions
 
-Only explicit user confirmation makes a plan `approved`.
+You may keep `plan.json`, `plan.md`, `.plan-original.md`, and draft `handoff.md` updated during `prepare` and `ready`, but only explicit user confirmation makes a plan `approved`.
 
 ---
 
@@ -176,8 +185,8 @@ Exit this loop only when the user explicitly confirms the plan is ready for exec
 
 ## Important
 
-The user does not want execution yet.
-You MUST NOT make edits, run mutating tools, or otherwise change the system.
+The user does not want implementation yet.
+You may mutate planning artifacts within the allowed paths, but you MUST NOT modify implementation files or run execution-oriented actions.
 This supersedes any other instructions you have received.
 </system-reminder>
 

package/commands/feature-switch.md

@@ -11,8 +11,8 @@ Rules:
 - if the current agent is not `enhance-plan`, instruct the user to switch to `enhance-plan` first and do not proceed
 - inspect `plan/active/*/plan.json` files to build the feature selection list
 - present lightweight metadata for selection, including feature id, name, overview, status, and confirmation state
-- before switching, persist the current feature todo and plan state
-- after switching, restore the target feature's todo, plan state, and review context
+- before switching, persist the current feature todo, status, open questions, and option paths back to the current `plan.json`
+- after switching, restore the target feature's todo, plan state, and review context from its `plan.json` and `plan.md`
 - do not merge two feature contexts unless the user explicitly requests a merge workflow
 
 If there is only one active feature, say so and show its current state.

package/commands/init-plan.md

@@ -36,8 +36,19 @@ Project file mapping:
 - `plan-original.template.md` -> project `plan/templates/.plan-original.md`
 - `handoff.template.md` -> project `plan/templates/handoff.md`
 
+Allowed writes for this command:
+- project `AGENTS.md`
+- project `.opencode/README.md`
+- `plan/active/`, `plan/archive/`, and `plan/templates/`
+- the mapped template files under `plan/templates/`
+
 When an existing project already has compatible files, update them carefully instead of blindly overwriting them.
 
+Guardrails:
+- do not modify implementation files or unrelated project configuration
+- only migrate planning or progress docs; do not reorganize product or business documentation
+- if legacy planning docs exist, preserve a traceable source location while normalizing them into the `plan/` structure
+
 Important:
 - stay in planning behavior until the user explicitly asks to switch to build
 - if the project already has planning docs, prefer migration and normalization over duplication

package/commands/plan-feature.md

@@ -12,6 +12,7 @@ Workflow:
 - set that feature as the active planning context
 - inspect relevant code, docs, and project rules before proposing implementation structure
 - create or update the feature artifacts under `plan/active/<feature>/`
+- treat existing artifacts as the source of truth when resuming an active feature
 
 Required artifacts:
 - `plan.json`
@@ -19,10 +20,29 @@ Required artifacts:
 - `.plan-original.md`
 - `handoff.md`
 
+Allowed writes for this command:
+- `plan/active/<feature>/plan.json`
+- `plan/active/<feature>/plan.md`
+- `plan/active/<feature>/.plan-original.md`
+- `plan/active/<feature>/handoff.md`
+
 The resulting plan must:
 - start in `prepare` or `ready` depending on confidence
 - maintain a structured todo list with ids, dependencies, and statuses
 - include an `Option Paths` section when multiple reasonable directions exist
 - wait for explicit user confirmation before any handoff is considered approved
 
+`plan.json` must be kept current with:
+- `status`
+- `hasConfirmed`
+- `todolist`
+- `openQuestions`
+- `optionPaths`
+- `updatedAt`
+
+Additional rules:
+- when the feature already exists, resume and update its current artifacts instead of creating duplicates
+- create `.plan-original.md` on first initialization, then update it only when you need to capture a new baseline draft
+- `handoff.md` may exist as a draft during planning, but only treat it as final after the feature reaches `approved`
+
 If the request is ambiguous, ask the smallest useful clarifying question first.

package/commands/plan-handoff.md

@@ -10,6 +10,7 @@ Validation rules:
 - do not produce a final handoff if the active feature is not clearly identified
 - do not produce a final handoff if the plan is not at least `approved`
 - do not treat vague encouragement as approval; explicit user confirmation is required
+- you may update `plan/active/<feature>/handoff.md` as a planning draft before approval, but it does not become the final handoff until the feature is `approved`
 
 The handoff must be concise and execution-focused.
 
@@ -22,3 +23,4 @@ Required handoff sections:
 - blockers, caveats, or notable constraints
 
 The handoff should minimize token usage for build mode and should avoid repeating background that is not necessary for execution.
+Do not copy the entire planning history into `handoff.md`; keep it as the smallest useful execution context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-enhance-plan",
-  "version": "1.0.0",
+  "version": "1.5.0",
   "description": "An enhanced planning workflow plugin for OpenCode — persistent plan artifacts, explicit review gates, structured todo state, and multi-feature switching",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/init-plan/AGENTS.template.md

@@ -25,6 +25,12 @@ Completed or inactive feature plans should move to `plan/archive/<feature>/` whe
 - Read `plan.json` or `plan.md` only when additional detail is needed.
 - Avoid loading broad background context when the current feature handoff is sufficient.
 
+## Planning Write Policy
+
+- `enhance-plan` may create or update `AGENTS.md`, `.opencode/README.md`, and files under `plan/` while staying in planning mode.
+- `enhance-plan` must not modify implementation files such as application source, build config, release config, or dependency manifests.
+- Treat planning writes as workflow state management, not as implementation work.
+
 ## Feature Discipline
 
 - Keep one active feature context at a time.

package/templates/init-plan/README.template.md

@@ -4,8 +4,8 @@ This project is initialized for the `enhance-plan` workflow.
 
 ## Commands
 
-- `/init-plan` - initialize or normalize the project planning workflow
-- `/plan-feature <name>` - create or resume a feature plan
+- `/init-plan` - initialize or normalize the project planning workflow and project-level planning files
+- `/plan-feature <name>` - create or resume a feature plan and persist its planning artifacts
 - `/feature-switch` - switch the active feature while staying in `enhance-plan`
 - `/plan-handoff` - generate a concise handoff for build mode
 
@@ -28,5 +28,7 @@ This project is initialized for the `enhance-plan` workflow.
 ## Notes
 
 - Keep planning focused on one feature at a time.
+- Planning state is persisted to project files under `plan/` rather than kept only in chat or transient todo state.
 - Treat `handoff.md` as the default build context.
+- `enhance-plan` may write planning artifacts and initialization files, but it must not modify implementation files.
 - Keep legacy docs preserved but move new planning into the normalized `plan/` structure.

package/templates/init-plan/plan-json.template.json

@@ -4,6 +4,7 @@
   "overview": "One-sentence description of the feature goal.",
   "status": "prepare",
   "hasConfirmed": false,
+  "confirmationState": "pending",
   "parts": [
     "req",
     "tech",
@@ -15,6 +16,12 @@
     "title": "Feature Title"
   },
   "content": "",
+  "lastUpdatedBy": "enhance-plan",
+  "allowedWriteScope": [
+    "AGENTS.md",
+    ".opencode/README.md",
+    "plan/**"
+  ],
   "todolist": [
     {
       "id": "clarify-scope",

package/templates/init-plan/plan-original.template.md

@@ -1,6 +1,7 @@
 ## Baseline Plan Draft
 
 Use this file to preserve the initial or last approved draft before later edits.
+Do not overwrite it on every refinement pass; update it only when you intentionally capture a new baseline.
 
 Recommended contents:
 

package/templates/init-plan/plan.template.md

@@ -1,3 +1,7 @@
+## Metadata
+
+- Last Updated:
+
 ## User Request
 
 - Goal: