opencode-enhance-plan 1.5.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +54 -137
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -4,46 +4,29 @@
4
4
 
5
5
  `opencode-enhance-plan` is an enhanced planning workflow plugin for OpenCode.
6
6
 
7
- It does not replace the built-in `plan` mode. Instead, it adds a stronger planning mode for feature work that needs:
8
- - persistent feature artifacts
9
- - explicit review before execution
10
- - structured todo state
11
- - feature switching and resume support
12
- - minimal build handoff
13
- - restricted write access for planning artifacts and project-level planning files
7
+ It keeps the built-in `plan` mode for lightweight analysis and adds a stronger planning workflow for feature work.
14
8
 
15
- ### Why not just use the built-in `plan` mode?
9
+ The plugin is installed globally through OpenCode, but it writes planning artifacts into each project that uses `/init-plan` and `/plan-feature`.
16
10
 
17
- The built-in `plan` mode is still useful for lightweight read-only analysis.
11
+ ### What it does
18
12
 
19
- `enhance-plan` is intended for heavier feature planning where the default planning experience is often too weak in practice.
13
+ - keeps one active feature at a time
14
+ - stores plan artifacts under `plan/active/<feature>/`
15
+ - allows restricted writes to planning files during planning
16
+ - requires explicit approval before final handoff
17
+ - restores plan state when switching features
20
18
 
21
- ### Built-in `plan` vs `enhance-plan`
19
+ ### Planning boundary
22
20
 
23
- | Area | Built-in `plan` | `enhance-plan` |
24
- | --- | --- | --- |
25
- | Primary use | quick analysis | feature planning workflow |
26
- | Todo persistence | limited | explicit, structured, feature-scoped |
27
- | Plan state model | implicit | `prepare -> ready -> approved -> building -> ...` |
28
- | Feature switching | not a core workflow | built in via `/feature-switch` |
29
- | Execution handoff | loose | focused `handoff.md` |
30
- | Plan artifacts | optional | required per feature |
31
- | Review gate | informal | explicit approval before handoff |
21
+ `enhance-plan` may update planning files only:
32
22
 
33
- ### What this repository includes
23
+ - `AGENTS.md`
24
+ - `.opencode/README.md`
25
+ - `plan/**`
34
26
 
35
- - `agents/` - custom agent definitions
36
- - `commands/` - custom slash commands
37
- - `templates/` - project templates used by `/init-plan`
38
- - `src/` - TypeScript plugin source (auto-deploys agents/commands/templates)
39
- - `docs/` - installation, usage, upgrade, and maintainer workflow notes
40
- - `scripts/` - shared repository maintenance helper for commit/release flows
41
- - `.codebuddy/skills/` - project-level CodeBuddy skill entrypoint for repository maintenance
42
- - `.opencode/skills/` - project-level OpenCode skill entrypoint for repository maintenance
43
- - `legacy/` - archived docs superseded by agent definitions
27
+ It must not modify implementation files such as source code, dependency manifests, CI config, build config, or release scripts.
44
28
 
45
-
46
- ### Install as OpenCode Plugin (recommended)
29
+ ### Install
47
30
 
48
31
  Add `opencode-enhance-plan` to your `opencode.json`:
49
32
 
@@ -53,95 +36,55 @@ Add `opencode-enhance-plan` to your `opencode.json`:
53
36
  }
54
37
  ```
55
38
 
56
- 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/`).
39
+ Restart OpenCode. The plugin deploys its agents, commands, and templates to `~/.config/opencode/`.
57
40
 
58
- The plugin is installed globally through OpenCode, but `enhance-plan` writes planning artifacts into each project that uses `/init-plan` and `/plan-feature`.
41
+ ### Main commands
59
42
 
60
- ### Core idea
43
+ - `/init-plan` - initialize project planning files
44
+ - `/plan-feature <feature-name>` - create or resume a feature plan
45
+ - `/feature-switch` - switch the active feature context
46
+ - `/plan-handoff` - generate the build-facing handoff
61
47
 
62
- Use the built-in `plan` mode when you want lightweight investigation.
48
+ ### What it does not do
63
49
 
64
- Use `enhance-plan` when you want a full planning loop with:
65
- - one active feature at a time
66
- - persistent plan artifacts under `plan/active/<feature>/`
67
- - explicit option comparison
68
- - explicit user confirmation before build
69
- - a small execution context through `handoff.md`
70
- - project-local planning files that can be updated during planning without editing implementation code
50
+ - it does not replace build mode
51
+ - it does not implement application code while planning
52
+ - it does not run build, install, release, deploy, or migration steps from `enhance-plan`
71
53
 
72
- ### Start here
54
+ ### Docs
73
55
 
74
56
  - Installation: [`docs/installation.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/installation.md)
75
57
  - Usage: [`docs/usage.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/usage.md)
58
+ - Upgrade guide: [`docs/upgrade-compatibility.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/upgrade-compatibility.md)
76
59
  - Maintainer release workflow: [`docs/repo-release-workflow.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/repo-release-workflow.md)
77
- - Upgrade checklist: [`docs/upgrade-compatibility.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/upgrade-compatibility.md)
78
-
79
-
80
- ### Quick path
81
-
82
- 1. Install this workflow into your OpenCode config.
83
- 2. Restart OpenCode.
84
- 3. Switch to `enhance-plan`.
85
- 4. Run `/init-plan` inside a project.
86
- 5. Run `/plan-feature <feature-name>`.
87
- 6. Review and approve the plan.
88
- 7. Run `/plan-handoff` before switching to build mode.
89
-
90
- ### Maintainer repo skill
91
-
92
- This repository also tracks a cross-tool maintainer skill named `repo-release-workflow`.
93
-
94
- - **CodeBuddy entrypoint**: `.codebuddy/skills/repo-release-workflow/`
95
- - **OpenCode entrypoint**: `.opencode/skills/repo-release-workflow/`
96
- - **Standard triggers**: `提交` and `发版`
97
- - **`提交` behavior**: `git add -A` + `git commit`
98
- - **`发版` 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
99
-
100
-
101
-
102
- Implementation details live in `docs/repo-release-workflow.md` and `scripts/release-workflow.mjs`.
103
60
 
104
61
  ## 中文
105
62
 
106
-
107
63
  `opencode-enhance-plan` 是一个构建在 OpenCode 之上的增强规划工作流插件。
108
64
 
109
- 它不是用来替代内置 `plan` 模式，而是新增一个更强的规划模式，专门处理这类 feature 任务：
110
- - 需要持久化 feature 工件
111
- - 需要执行前明确审阅
112
- - 需要结构化 todo 状态
113
- - 需要 feature 切换与恢复
114
- - 需要最小化 build handoff
65
+ 它保留内置 `plan` 处理轻量分析，并为 feature 级任务提供更强的规划工作流。
115
66
 
116
- ### 为什么不直接用内置 `plan`？
67
+ 插件通过 OpenCode 全局安装，但实际的 planning artifacts 会落到执行 `/init-plan` 与 `/plan-feature` 的项目中。
117
68
 
118
- 内置 `plan` 仍然适合做轻量级只读分析。
69
+ ### 它能做什么
119
70
 
120
- `enhance-plan` 的目标是解决更重的 feature planning 场景：默认 planning 体验在这些场景里通常不够强，尤其是在 todo 持久化、状态管理、feature 切换、handoff 收敛这几个方面。
71
+ - 同一时间只维护一个 active feature
72
+ - 将规划工件持久化到 `plan/active/<feature>/`
73
+ - 在规划阶段允许对 planning 文件做受限写入
74
+ - 最终 handoff 前必须显式批准
75
+ - 切换 feature 时可以恢复 plan state
121
76
 
122
- ### 内置 `plan` 与 `enhance-plan` 的区别
77
+ ### Planning 边界
123
78
 
124
- | 维度 | 内置 `plan` | `enhance-plan` |
125
- | --- | --- | --- |
126
- | 主要用途 | 快速分析 | feature 级 planning workflow |
127
- | todo 持久化 | 较弱 | 明确、结构化、按 feature 隔离 |
128
- | plan 状态模型 | 隐式 | `prepare -> ready -> approved -> building -> ...` |
129
- | feature 切换 | 不是核心能力 | 通过 `/feature-switch` 内建支持 |
130
- | 执行交接 | 较松散 | 使用聚焦的 `handoff.md` |
131
- | plan 工件 | 可选 | 每个 feature 都要求具备 |
132
- | 审阅门槛 | 偏口头化 | handoff 前必须显式批准 |
79
+ `enhance-plan` 只允许更新 planning 文件：
133
80
 
134
- ### 仓库包含什么
81
+ - `AGENTS.md`
82
+ - `.opencode/README.md`
83
+ - `plan/**`
135
84
 
136
- - `agents/` - 自定义 agent 定义
137
- - `commands/` - 自定义斜杠命令
138
- - `templates/` - `/init-plan` 使用的项目模板
139
- - `src/` - TypeScript 插件源码（自动部署 agents/commands/templates）
140
- - `docs/` - 安装、使用、升级兼容说明
141
- - `scripts/` - Windows（PowerShell）和 Linux/macOS（bash）安装脚本
142
- - `legacy/` - 已被 agent 定义取代的归档文档
85
+ 它不得修改源码、依赖清单、CI 配置、构建配置或发版脚本等实现相关文件。
143
86
 
144
- ### 作为 OpenCode Plugin 安装（推荐）
87
+ ### 安装
145
88
 
146
89
  在 `opencode.json` 中添加：
147
90
 
@@ -151,56 +94,30 @@ Implementation details live in `docs/repo-release-workflow.md` and `scripts/rele
151
94
  }
152
95
  ```
153
96
 
154
- OpenCode 下次启动时会自动安装并加载插件，自动将 agents、commands、templates 部署到 OpenCode 配置目录（`~/.config/opencode/`）。
97
+ 重启 OpenCode。插件会将 agents、commands、templates 部署到 `~/.config/opencode/`。
155
98
 
156
- 插件是通过 OpenCode 全局安装的，但 `enhance-plan` 写入的 planning artifacts 会落到每个实际执行 `/init-plan` 与 `/plan-feature` 的项目中。
99
+ ### 主要命令
157
100
 
158
- ### 核心思路
101
+ - `/init-plan` - 初始化项目 planning 文件
102
+ - `/plan-feature <feature-name>` - 创建或恢复 feature 计划
103
+ - `/feature-switch` - 切换 active feature context
104
+ - `/plan-handoff` - 生成面向 build 的 handoff
159
105
 
160
- 如果你只是想做轻量调研，就继续用内置 `plan`。
106
+ ### 它不会做什么
161
107
 
162
- 如果你想要完整的 planning loop，就用 `enhance-plan`，它强调：
163
- - 同一时间只维护一个 active feature
164
- - feature 工件持久化到 `plan/active/<feature>/`
165
- - 明确的方案比较
166
- - build 前必须有显式确认
167
- - 通过 `handoff.md` 压缩执行上下文
168
- - 在规划阶段可受限写入项目级 planning 文件，但不修改实现代码
108
+ - 不会替代 build mode
109
+ - 不会在 planning 阶段实现业务代码
110
+ - 不会在 `enhance-plan` 中执行 build、install、release、deploy、migration
169
111
 
170
- ### 从这里开始读
112
+ ### 文档
171
113
 
172
114
  - 安装说明：[`docs/installation.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/installation.md)
173
115
  - 使用说明：[`docs/usage.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/usage.md)
116
+ - 升级指南：[`docs/upgrade-compatibility.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/upgrade-compatibility.md)
174
117
  - 仓库维护流程：[`docs/repo-release-workflow.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/repo-release-workflow.md)
175
- - 升级检查清单：[`docs/upgrade-compatibility.md`](https://github.com/spartawhy117/opencode-enhance-plan/blob/main/docs/upgrade-compatibility.md)
176
-
177
-
178
- ### 最短使用路径
179
-
180
- 1. 把这套 workflow 安装到你的 OpenCode 配置目录。
181
- 2. 重启 OpenCode。
182
- 3. 切换到 `enhance-plan`。
183
- 4. 在项目里运行 `/init-plan`。
184
- 5. 运行 `/plan-feature <feature-name>`。
185
- 6. 审阅并批准计划。
186
- 7. 在切到 build 前运行 `/plan-handoff`。
187
-
188
- ### 仓库维护 skill
189
-
190
- 这个仓库还额外跟踪了一套跨工具维护 skill：`repo-release-workflow`。
191
-
192
- - **CodeBuddy 入口**：`.codebuddy/skills/repo-release-workflow/`
193
- - **OpenCode 入口**：`.opencode/skills/repo-release-workflow/`
194
- - **标准触发词**：`提交` 与 `发版`
195
- - **`提交` 行为**：`git add -A` + `git commit`
196
- - **`发版` 行为**：版本号更新 + `npm run build` + release commit + `git tag` + `git push` + 由推送的 tag 触发 GitHub Actions 发布到 npm
197
-
198
-
199
- 具体执行细节记录在 `docs/repo-release-workflow.md` 与 `scripts/release-workflow.mjs`。
200
118
 
201
119
  ## Scope note / 范围说明
202
120
 
203
-
204
121
  This repository is not a fork of OpenCode. It is a public workflow layer built on top of OpenCode's documented extension points.
205
122
 
206
123
  本仓库不是 OpenCode 的源码 fork，而是建立在 OpenCode 官方扩展点之上的公开工作流层。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-enhance-plan",
3
- "version": "1.5.0",
3
+ "version": "1.5.1",
4
4
  "description": "An enhanced planning workflow plugin for OpenCode — persistent plan artifacts, explicit review gates, structured todo state, and multi-feature switching",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",