opencode-enhance-plan 1.0.0 → 1.5.1

package/README.md

@@ -4,45 +4,29 @@
 
 `opencode-enhance-plan` is an enhanced planning workflow plugin for OpenCode.
 
-It does not replace the built-in `plan` mode. Instead, it adds a stronger planning mode for feature work that needs:
-- persistent feature artifacts
-- explicit review before execution
-- structured todo state
-- feature switching and resume support
-- minimal build handoff
+It keeps the built-in `plan` mode for lightweight analysis and adds a stronger planning workflow for feature work.
 
-### Why not just use the built-in `plan` mode?
+The plugin is installed globally through OpenCode, but it writes planning artifacts into each project that uses `/init-plan` and `/plan-feature`.
 
-The built-in `plan` mode is still useful for lightweight read-only analysis.
+### What it does
 
-`enhance-plan` is intended for heavier feature planning where the default planning experience is often too weak in practice.
+- keeps one active feature at a time
+- stores plan artifacts under `plan/active/<feature>/`
+- allows restricted writes to planning files during planning
+- requires explicit approval before final handoff
+- restores plan state when switching features
 
-### Built-in `plan` vs `enhance-plan`
+### Planning boundary
 
-| Area | Built-in `plan` | `enhance-plan` |
-| --- | --- | --- |
-| Primary use | quick analysis | feature planning workflow |
-| Todo persistence | limited | explicit, structured, feature-scoped |
-| Plan state model | implicit | `prepare -> ready -> approved -> building -> ...` |
-| Feature switching | not a core workflow | built in via `/feature-switch` |
-| Execution handoff | loose | focused `handoff.md` |
-| Plan artifacts | optional | required per feature |
-| Review gate | informal | explicit approval before handoff |
+`enhance-plan` may update planning files only:
 
-### What this repository includes
+- `AGENTS.md`
+- `.opencode/README.md`
+- `plan/**`
 
-- `agents/` - custom agent definitions
-- `commands/` - custom slash commands
-- `templates/` - project templates used by `/init-plan`
-- `src/` - TypeScript plugin source (auto-deploys agents/commands/templates)
-- `docs/` - installation, usage, upgrade, and maintainer workflow notes
-- `scripts/` - shared repository maintenance helper for commit/release flows
-- `.codebuddy/skills/` - project-level CodeBuddy skill entrypoint for repository maintenance
-- `.opencode/skills/` - project-level OpenCode skill entrypoint for repository maintenance
-- `legacy/` - archived docs superseded by agent definitions
+It must not modify implementation files such as source code, dependency manifests, CI config, build config, or release scripts.
 
-
-### Install as OpenCode Plugin (recommended)
+### Install
 
 Add `opencode-enhance-plan` to your `opencode.json`:
 
@@ -52,92 +36,55 @@ 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/`).
+Restart OpenCode. The plugin deploys its agents, commands, and templates to `~/.config/opencode/`.
+
+### Main commands
 
-### Core idea
+- `/init-plan` - initialize project planning files
+- `/plan-feature <feature-name>` - create or resume a feature plan
+- `/feature-switch` - switch the active feature context
+- `/plan-handoff` - generate the build-facing handoff
 
-Use the built-in `plan` mode when you want lightweight investigation.
+### What it does not do
 
-Use `enhance-plan` when you want a full planning loop with:
-- one active feature at a time
-- persistent plan artifacts under `plan/active/<feature>/`
-- explicit option comparison
-- explicit user confirmation before build
-- a small execution context through `handoff.md`
+- it does not replace build mode
+- it does not implement application code while planning
+- it does not run build, install, release, deploy, or migration steps from `enhance-plan`
 
-### Start here
+### Docs
 
 - Installation: [`docs/installation.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/installation.md)
 - Usage: [`docs/usage.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/usage.md)
+- Upgrade guide: [`docs/upgrade-compatibility.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/upgrade-compatibility.md)
 - Maintainer release workflow: [`docs/repo-release-workflow.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/repo-release-workflow.md)
-- Upgrade checklist: [`docs/upgrade-compatibility.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/upgrade-compatibility.md)
-
-
-### Quick path
-
-1. Install this workflow into your OpenCode config.
-2. Restart OpenCode.
-3. Switch to `enhance-plan`.
-4. Run `/init-plan` inside a project.
-5. Run `/plan-feature <feature-name>`.
-6. Review and approve the plan.
-7. Run `/plan-handoff` before switching to build mode.
-
-### Maintainer repo skill
-
-This repository also tracks a cross-tool maintainer skill named `repo-release-workflow`.
-
-- **CodeBuddy entrypoint**: `.codebuddy/skills/repo-release-workflow/`
-- **OpenCode entrypoint**: `.opencode/skills/repo-release-workflow/`
-- **Standard triggers**: `提交` and `发版`
-- **`提交` behavior**: `git add -A` + `git commit`
-- **`发版` behavior**: version bump + `npm run build` + release commit + `git tag` + `git push` + GitHub Actions npm publish and GitHub Release latest update triggered by the pushed tag
-
-
-
-Implementation details live in `docs/repo-release-workflow.md` and `scripts/release-workflow.mjs`.
 
 ## 中文
 
-
 `opencode-enhance-plan` 是一个构建在 OpenCode 之上的增强规划工作流插件。
 
-它不是用来替代内置 `plan` 模式，而是新增一个更强的规划模式，专门处理这类 feature 任务：
-- 需要持久化 feature 工件
-- 需要执行前明确审阅
-- 需要结构化 todo 状态
-- 需要 feature 切换与恢复
-- 需要最小化 build handoff
+它保留内置 `plan` 处理轻量分析，并为 feature 级任务提供更强的规划工作流。
 
-### 为什么不直接用内置 `plan`？
+插件通过 OpenCode 全局安装，但实际的 planning artifacts 会落到执行 `/init-plan` 与 `/plan-feature` 的项目中。
 
-内置 `plan` 仍然适合做轻量级只读分析。
+### 它能做什么
 
-`enhance-plan` 的目标是解决更重的 feature planning 场景：默认 planning 体验在这些场景里通常不够强，尤其是在 todo 持久化、状态管理、feature 切换、handoff 收敛这几个方面。
+- 同一时间只维护一个 active feature
+- 将规划工件持久化到 `plan/active/<feature>/`
+- 在规划阶段允许对 planning 文件做受限写入
+- 最终 handoff 前必须显式批准
+- 切换 feature 时可以恢复 plan state
 
-### 内置 `plan` 与 `enhance-plan` 的区别
+### Planning 边界
 
-| 维度 | 内置 `plan` | `enhance-plan` |
-| --- | --- | --- |
-| 主要用途 | 快速分析 | feature 级 planning workflow |
-| todo 持久化 | 较弱 | 明确、结构化、按 feature 隔离 |
-| plan 状态模型 | 隐式 | `prepare -> ready -> approved -> building -> ...` |
-| feature 切换 | 不是核心能力 | 通过 `/feature-switch` 内建支持 |
-| 执行交接 | 较松散 | 使用聚焦的 `handoff.md` |
-| plan 工件 | 可选 | 每个 feature 都要求具备 |
-| 审阅门槛 | 偏口头化 | handoff 前必须显式批准 |
+`enhance-plan` 只允许更新 planning 文件：
 
-### 仓库包含什么
+- `AGENTS.md`
+- `.opencode/README.md`
+- `plan/**`
 
-- `agents/` - 自定义 agent 定义
-- `commands/` - 自定义斜杠命令
-- `templates/` - `/init-plan` 使用的项目模板
-- `src/` - TypeScript 插件源码（自动部署 agents/commands/templates）
-- `docs/` - 安装、使用、升级兼容说明
-- `scripts/` - Windows（PowerShell）和 Linux/macOS（bash）安装脚本
-- `legacy/` - 已被 agent 定义取代的归档文档
+它不得修改源码、依赖清单、CI 配置、构建配置或发版脚本等实现相关文件。
 
-### 作为 OpenCode Plugin 安装（推荐）
+### 安装
 
 在 `opencode.json` 中添加：
 
@@ -147,53 +94,30 @@ Implementation details live in `docs/repo-release-workflow.md` and `scripts/rele
 }
 ```
 
-OpenCode 下次启动时会自动安装并加载插件，自动将 agents、commands、templates 部署到 OpenCode 配置目录（`~/.config/opencode/`）。
+重启 OpenCode。插件会将 agents、commands、templates 部署到 `~/.config/opencode/`。
 
-### 核心思路
+### 主要命令
 
-如果你只是想做轻量调研，就继续用内置 `plan`。
+- `/init-plan` - 初始化项目 planning 文件
+- `/plan-feature <feature-name>` - 创建或恢复 feature 计划
+- `/feature-switch` - 切换 active feature context
+- `/plan-handoff` - 生成面向 build 的 handoff
 
-如果你想要完整的 planning loop，就用 `enhance-plan`，它强调：
-- 同一时间只维护一个 active feature
-- feature 工件持久化到 `plan/active/<feature>/`
-- 明确的方案比较
-- build 前必须有显式确认
-- 通过 `handoff.md` 压缩执行上下文
+### 它不会做什么
+
+- 不会替代 build mode
+- 不会在 planning 阶段实现业务代码
+- 不会在 `enhance-plan` 中执行 build、install、release、deploy、migration
 
-### 从这里开始读
+### 文档
 
 - 安装说明：[`docs/installation.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/installation.md)
 - 使用说明：[`docs/usage.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/usage.md)
+- 升级指南：[`docs/upgrade-compatibility.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/upgrade-compatibility.md)
 - 仓库维护流程：[`docs/repo-release-workflow.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/repo-release-workflow.md)
-- 升级检查清单：[`docs/upgrade-compatibility.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/upgrade-compatibility.md)
-
-
-### 最短使用路径
-
-1. 把这套 workflow 安装到你的 OpenCode 配置目录。
-2. 重启 OpenCode。
-3. 切换到 `enhance-plan`。
-4. 在项目里运行 `/init-plan`。
-5. 运行 `/plan-feature <feature-name>`。
-6. 审阅并批准计划。
-7. 在切到 build 前运行 `/plan-handoff`。
-
-### 仓库维护 skill
-
-这个仓库还额外跟踪了一套跨工具维护 skill：`repo-release-workflow`。
-
-- **CodeBuddy 入口**：`.codebuddy/skills/repo-release-workflow/`
-- **OpenCode 入口**：`.opencode/skills/repo-release-workflow/`
-- **标准触发词**：`提交` 与 `发版`
-- **`提交` 行为**：`git add -A` + `git commit`
-- **`发版` 行为**：版本号更新 + `npm run build` + release commit + `git tag` + `git push` + 由推送的 tag 触发 GitHub Actions 发布到 npm
-
-
-具体执行细节记录在 `docs/repo-release-workflow.md` 与 `scripts/release-workflow.mjs`。
 
 ## Scope note / 范围说明
 
-
 This repository is not a fork of OpenCode. It is a public workflow layer built on top of OpenCode's documented extension points.
 
 本仓库不是 OpenCode 的源码 fork，而是建立在 OpenCode 官方扩展点之上的公开工作流层。

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.1",
   "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: