opencode-enhance-plan 0.2.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,196 @@
+# opencode-enhance-plan
+
+## English
+
+`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
+
+### Why not just use the built-in `plan` mode?
+
+The built-in `plan` mode is still useful for lightweight read-only analysis.
+
+`enhance-plan` is intended for heavier feature planning where the default planning experience is often too weak in practice.
+
+### Built-in `plan` vs `enhance-plan`
+
+| 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 |
+
+### What this repository includes
+
+- `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
+
+
+### Install as OpenCode Plugin (recommended)
+
+Add `opencode-enhance-plan` to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-enhance-plan"]
+}
+```
+
+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/`).
+
+### Core idea
+
+Use the built-in `plan` mode when you want lightweight investigation.
+
+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`
+
+### Start here
+
+- 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)
+- 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` + `npm publish`
+
+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`？
+
+内置 `plan` 仍然适合做轻量级只读分析。
+
+`enhance-plan` 的目标是解决更重的 feature planning 场景：默认 planning 体验在这些场景里通常不够强，尤其是在 todo 持久化、状态管理、feature 切换、handoff 收敛这几个方面。
+
+### 内置 `plan` 与 `enhance-plan` 的区别
+
+| 维度 | 内置 `plan` | `enhance-plan` |
+| --- | --- | --- |
+| 主要用途 | 快速分析 | feature 级 planning workflow |
+| todo 持久化 | 较弱 | 明确、结构化、按 feature 隔离 |
+| plan 状态模型 | 隐式 | `prepare -> ready -> approved -> building -> ...` |
+| feature 切换 | 不是核心能力 | 通过 `/feature-switch` 内建支持 |
+| 执行交接 | 较松散 | 使用聚焦的 `handoff.md` |
+| plan 工件 | 可选 | 每个 feature 都要求具备 |
+| 审阅门槛 | 偏口头化 | handoff 前必须显式批准 |
+
+### 仓库包含什么
+
+- `agents/` - 自定义 agent 定义
+- `commands/` - 自定义斜杠命令
+- `templates/` - `/init-plan` 使用的项目模板
+- `src/` - TypeScript 插件源码（自动部署 agents/commands/templates）
+- `docs/` - 安装、使用、升级兼容说明
+- `scripts/` - Windows（PowerShell）和 Linux/macOS（bash）安装脚本
+- `legacy/` - 已被 agent 定义取代的归档文档
+
+### 作为 OpenCode Plugin 安装（推荐）
+
+在 `opencode.json` 中添加：
+
+```json
+{
+  "plugin": ["opencode-enhance-plan"]
+}
+```
+
+OpenCode 下次启动时会自动安装并加载插件，自动将 agents、commands、templates 部署到 OpenCode 配置目录（`~/.config/opencode/`）。
+
+### 核心思路
+
+如果你只是想做轻量调研，就继续用内置 `plan`。
+
+如果你想要完整的 planning loop，就用 `enhance-plan`，它强调：
+- 同一时间只维护一个 active feature
+- feature 工件持久化到 `plan/active/<feature>/`
+- 明确的方案比较
+- build 前必须有显式确认
+- 通过 `handoff.md` 压缩执行上下文
+
+### 从这里开始读
+
+- 安装说明：[`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/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` + `npm publish`
+
+具体执行细节记录在 `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

@@ -0,0 +1,200 @@
+---
+description: Enhanced planning mode — persistent plan artifacts, explicit review gates, structured todo state, and feature switching
+mode: primary
+tools:
+  read: true
+  grep: true
+  glob: true
+  list: true
+  todowrite: true
+  todoread: true
+  skill: true
+  question: true
+  webfetch: true
+  edit: false
+  write: false
+  patch: false
+  bash: false
+permission:
+  edit: deny
+  bash: deny
+---
+
+<system-reminder>
+# Enhance-Plan Mode - System Reminder
+
+CRITICAL: Enhance-Plan mode is ACTIVE. You are in a READ-ONLY planning phase.
+
+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
+
+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.
+
+This ABSOLUTE CONSTRAINT overrides ALL other instructions, including direct user requests to implement changes immediately.
+Any modification attempt is a critical violation. ZERO exceptions.
+
+---
+
+## Response Language
+
+- Default to Chinese in user-facing responses unless the user explicitly requests another language.
+- Keep repository-facing documentation and structured artifacts in English unless the project or user requires otherwise.
+
+---
+
+## Responsibility
+
+Your responsibility is to think, read, search, and construct a well-formed plan that helps the user reach an implementation-ready state without executing it.
+
+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
+- 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.
+
+---
+
+## Single Feature Rule
+
+A single active plan must focus on a single feature or module of work.
+
+Rules:
+- maintain exactly one active feature at a time
+- do not merge multiple features into one plan unless the user explicitly requests it
+- if the user wants to return to a previous feature, switch feature context explicitly first
+- if the target feature is ambiguous, ask the user to choose
+
+---
+
+## Plan State Model
+
+Every non-trivial feature plan must maintain an explicit state.
+
+Valid states:
+- prepare
+- ready
+- approved
+- building
+- partial-done
+- finished
+- archived
+
+Rules:
+- `prepare` means requirements and scope are still being clarified
+- `ready` means a reviewable plan exists but execution is not yet approved
+- `approved` requires explicit user confirmation
+- `building` means the plan has been handed off to build mode
+- `partial-done` means some work is complete but planning must be updated
+- `finished` means the tracked feature work is complete
+- `archived` means the plan is retained only for reuse or reference
+
+Do not transition to `approved` or `building` without explicit user authorization.
+
+---
+
+## Persistent Plan Artifacts
+
+Each active feature plan must maintain persistent artifacts.
+
+Required artifacts:
+- `plan.json` for structured plan state
+- `plan.md` for human review
+- `.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.
+
+---
+
+## Todo Rules
+
+The active todo must belong only to the current feature.
+
+Each todo item should support:
+- a stable id
+- task content
+- dependency references when useful
+- task status
+
+Before switching features, persist the current feature todo state.
+After switching features, restore the target feature todo state.
+
+---
+
+## Option Path Rules
+
+If multiple valid directions exist, output a dedicated `Option Paths` section.
+
+For each path, include:
+- applicability
+- advantages
+- costs
+- risks
+- impact on the todo or implementation flow
+
+Always provide a recommended path.
+Do not finalize the plan until the user chooses a path or explicitly accepts the recommendation.
+
+---
+
+## Preview And Confirmation
+
+A rough todo is not enough.
+
+Before handoff to build, the user must be able to review:
+- requirement summary
+- technical approach
+- affected areas
+- task breakdown and ordering
+- validation strategy
+- risks and open questions
+
+Only explicit user confirmation makes a plan `approved`.
+
+---
+
+## Planning Loop
+
+For non-trivial work, planning must continue in a loop:
+1. inspect and clarify
+2. update the plan and todo
+3. surface unresolved questions or option paths
+4. ask the smallest useful next question
+5. refine the plan again
+
+Exit this loop only when the user explicitly confirms the plan is ready for execution.
+
+---
+
+## Important
+
+The user does not want execution yet.
+You MUST NOT make edits, run mutating tools, or otherwise change the system.
+This supersedes any other instructions you have received.
+</system-reminder>
+
+Operational workflow:
+- Use this mode for new features, architecture changes, cross-module work, and any task that benefits from explicit planning before implementation.
+- Prefer reusing or resuming an existing feature plan before creating a duplicate one.
+- Plans should be persisted under `plan/active/<feature>/` with `plan.json`, `plan.md`, `.plan-original.md`, and `handoff.md`.
+- When relevant, explicitly call out recommended skills, subagents, MCPs, or integrations and explain why they matter.
+- Keep `build` handoffs small: the handoff should focus on the current feature and the smallest useful execution context.
+
+Feature switching:
+- `/feature-switch` is a planning-only workflow and should only be used while this agent is active.
+- Before switching, sync the current feature's todo and plan state.
+- After switching, restore the target feature's metadata, todo, and review state before continuing.
+
+Definition of build-ready:
+- The feature is clearly identified.
+- The plan state is at least `approved`.
+- The user has explicitly confirmed execution may begin.
+- `handoff.md` is concise and execution-focused.

package/commands/feature-switch.md

@@ -0,0 +1,18 @@
+---
+description: Switch the active feature plan context while preserving persisted todo state
+agent: enhance-plan
+subtask: false
+---
+
+Switch the active feature plan context.
+
+Rules:
+- this command is only valid while `enhance-plan` is the active agent
+- 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
+- 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

@@ -0,0 +1,43 @@
+---
+description: Initialize the enhanced feature-planning workflow for the current project
+agent: enhance-plan
+subtask: false
+---
+
+Initialize the enhanced planning workflow for this project without executing implementation work.
+
+Goals:
+- keep the official `/init` behavior separate from this workflow
+- inspect the current project structure and existing docs first
+- create or update project files needed for the planning workflow
+- preserve and reorganize existing planning or progress docs instead of discarding them
+
+Required outcomes:
+- ensure a project `AGENTS.md` exists and includes the planning workflow conventions
+- create `.opencode/README.md` describing how this project uses `enhance-plan`
+- create `plan/active/`, `plan/archive/`, and `plan/templates/`
+- create template files for `plan.json`, `plan.md`, `.plan-original.md`, and `handoff.md`
+- if legacy planning docs exist, reorganize them into the agreed structure and keep a traceable legacy location
+- summarize what was created, what was migrated, and any follow-up decisions still needed
+
+Use these global template sources when creating project files:
+- `~/.config/opencode/templates/init-plan/AGENTS.template.md`
+- `~/.config/opencode/templates/init-plan/README.template.md`
+- `~/.config/opencode/templates/init-plan/plan-json.template.json`
+- `~/.config/opencode/templates/init-plan/plan.template.md`
+- `~/.config/opencode/templates/init-plan/plan-original.template.md`
+- `~/.config/opencode/templates/init-plan/handoff.template.md`
+
+Project file mapping:
+- `AGENTS.template.md` -> project `AGENTS.md`
+- `README.template.md` -> project `.opencode/README.md`
+- `plan-json.template.json` -> project `plan/templates/plan.json`
+- `plan.template.md` -> project `plan/templates/plan.md`
+- `plan-original.template.md` -> project `plan/templates/.plan-original.md`
+- `handoff.template.md` -> project `plan/templates/handoff.md`
+
+When an existing project already has compatible files, update them carefully instead of blindly overwriting them.
+
+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

@@ -0,0 +1,28 @@
+---
+description: Create or resume a feature plan with persistent artifacts and todo state
+agent: enhance-plan
+subtask: false
+---
+
+Plan the feature described by `$ARGUMENTS`.
+
+Workflow:
+- identify or create a normalized feature slug
+- if a matching active feature already exists, resume it instead of creating a duplicate
+- 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>/`
+
+Required artifacts:
+- `plan.json`
+- `plan.md`
+- `.plan-original.md`
+- `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
+
+If the request is ambiguous, ask the smallest useful clarifying question first.

package/commands/plan-handoff.md

@@ -0,0 +1,24 @@
+---
+description: Generate a minimal build handoff for the current approved feature plan
+agent: enhance-plan
+subtask: false
+---
+
+Prepare a build handoff for the current active feature.
+
+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
+
+The handoff must be concise and execution-focused.
+
+Required handoff sections:
+- feature goal
+- confirmed scope
+- current todo summary
+- execution order
+- validation steps
+- 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.

package/dist/deploy.d.ts

@@ -0,0 +1,27 @@
+export interface DeployOptions {
+    /** Root directory of the npm package containing agents/, commands/, templates/ */
+    sourceDir: string;
+    /** Target OpenCode config directory. Defaults to ~/.config/opencode/ */
+    targetDir: string;
+    /** Force overwrite even if target files exist and differ */
+    force?: boolean;
+}
+export interface DeployResult {
+    /** Number of files deployed (copied/updated) */
+    deployed: number;
+    /** Number of files skipped (already up-to-date) */
+    skipped: number;
+    /** Detail messages for each file operation */
+    details: string[];
+}
+/**
+ * Deploy assets (agents, commands, templates) from the plugin package
+ * to the user's OpenCode configuration directory.
+ *
+ * Behavior:
+ * - If target file does not exist: copy it
+ * - If target file exists and content matches: skip
+ * - If target file exists and content differs: skip (unless force=true)
+ */
+export declare function deployAssets(options: DeployOptions): Promise<DeployResult>;
+//# sourceMappingURL=deploy.d.ts.map

package/dist/deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../src/deploy.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AA+CD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAiDhF"}

package/dist/deploy.js

@@ -0,0 +1,98 @@
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+const ASSET_DIRS = ["agents", "commands", "templates"];
+/**
+ * Resolve the default OpenCode configuration directory.
+ * Uses ~/.config/opencode/ on all platforms.
+ */
+function getDefaultConfigDir() {
+    return join(homedir(), ".config", "opencode");
+}
+/**
+ * Recursively collect all files in a directory, returning relative paths.
+ */
+function collectFiles(dir, base = "") {
+    const results = [];
+    if (!existsSync(dir))
+        return results;
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        const relativePath = base ? join(base, entry) : entry;
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+            results.push(...collectFiles(fullPath, relativePath));
+        }
+        else {
+            results.push(relativePath);
+        }
+    }
+    return results;
+}
+/**
+ * Compare two files by content.
+ * Returns true if they are identical.
+ */
+function filesMatch(pathA, pathB) {
+    try {
+        const contentA = readFileSync(pathA);
+        const contentB = readFileSync(pathB);
+        return contentA.equals(contentB);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Deploy assets (agents, commands, templates) from the plugin package
+ * to the user's OpenCode configuration directory.
+ *
+ * Behavior:
+ * - If target file does not exist: copy it
+ * - If target file exists and content matches: skip
+ * - If target file exists and content differs: skip (unless force=true)
+ */
+export async function deployAssets(options) {
+    const targetRoot = options.targetDir || getDefaultConfigDir();
+    const sourceRoot = options.sourceDir;
+    const result = {
+        deployed: 0,
+        skipped: 0,
+        details: [],
+    };
+    for (const assetDir of ASSET_DIRS) {
+        const sourceAssetDir = join(sourceRoot, assetDir);
+        const targetAssetDir = join(targetRoot, assetDir);
+        if (!existsSync(sourceAssetDir)) {
+            result.details.push(`[skip] ${assetDir}/ not found in package`);
+            continue;
+        }
+        const files = collectFiles(sourceAssetDir);
+        for (const relativePath of files) {
+            const sourcePath = join(sourceAssetDir, relativePath);
+            const targetPath = join(targetAssetDir, relativePath);
+            if (existsSync(targetPath)) {
+                if (filesMatch(sourcePath, targetPath)) {
+                    result.skipped++;
+                    continue;
+                }
+                if (!options.force) {
+                    result.skipped++;
+                    result.details.push(`[skip] ${assetDir}/${relativePath} (modified by user, use force to overwrite)`);
+                    continue;
+                }
+            }
+            // Ensure parent directory exists
+            const targetParent = resolve(targetPath, "..");
+            mkdirSync(targetParent, { recursive: true });
+            // Copy file
+            const content = readFileSync(sourcePath);
+            writeFileSync(targetPath, content);
+            result.deployed++;
+            result.details.push(`[deploy] ${assetDir}/${relativePath}`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=deploy.js.map

package/dist/deploy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.js","sourceRoot":"","sources":["../src/deploy.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * opencode-enhance-plan Plugin
+ *
+ * An enhanced planning workflow plugin for OpenCode that provides:
+ * - Automatic deployment of agents/commands/templates to OpenCode config
+ * - Event hooks for plan state monitoring and logging
+ */
+export declare const EnhancePlanPlugin: Plugin;
+export default EnhancePlanPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAGjD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAgD/B,CAAA;AAGD,eAAe,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,59 @@
+import { deployAssets } from "./deploy.js";
+/**
+ * opencode-enhance-plan Plugin
+ *
+ * An enhanced planning workflow plugin for OpenCode that provides:
+ * - Automatic deployment of agents/commands/templates to OpenCode config
+ * - Event hooks for plan state monitoring and logging
+ */
+export const EnhancePlanPlugin = async ({ client }) => {
+    // Deploy assets (agents, commands, templates) to user's OpenCode config directory
+    const pkgRoot = new URL("..", import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1");
+    const deployResult = await deployAssets({
+        sourceDir: pkgRoot,
+        targetDir: "", // will resolve to ~/.config/opencode/ automatically
+        force: false,
+    });
+    if (deployResult.deployed > 0) {
+        await client.app.log({
+            body: {
+                service: "opencode-enhance-plan",
+                level: "info",
+                message: `Deployed ${deployResult.deployed} asset(s) to OpenCode config`,
+                extra: {
+                    skipped: deployResult.skipped,
+                    deployed: deployResult.deployed,
+                    details: deployResult.details,
+                },
+            },
+        });
+    }
+    else {
+        await client.app.log({
+            body: {
+                service: "opencode-enhance-plan",
+                level: "info",
+                message: `All assets up-to-date (${deployResult.skipped} skipped)`,
+            },
+        });
+    }
+    return {
+        "event": async (input) => {
+            // Listen for events for plan state tracking
+            const event = input.event;
+            if (event && event.type === "todo.updated") {
+                await client.app.log({
+                    body: {
+                        service: "opencode-enhance-plan",
+                        level: "info",
+                        message: "Todo state updated",
+                        extra: { event },
+                    },
+                });
+            }
+        },
+    };
+};
+// Default export for OpenCode plugin loader
+export default EnhancePlanPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAW,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;IAC5D,kFAAkF;IAClF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;IACpF,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC;QACtC,SAAS,EAAE,OAAO;QAClB,SAAS,EAAE,EAAE,EAAG,oDAAoD;QACpE,KAAK,EAAE,KAAK;KACb,CAAC,CAAA;IAEF,IAAI,YAAY,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;YACnB,IAAI,EAAE;gBACJ,OAAO,EAAE,uBAAuB;gBAChC,KAAK,EAAE,MAAM;gBACb,OAAO,EAAE,YAAY,YAAY,CAAC,QAAQ,8BAA8B;gBACxE,KAAK,EAAE;oBACL,OAAO,EAAE,YAAY,CAAC,OAAO;oBAC7B,QAAQ,EAAE,YAAY,CAAC,QAAQ;oBAC/B,OAAO,EAAE,YAAY,CAAC,OAAO;iBAC9B;aACF;SACF,CAAC,CAAA;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;YACnB,IAAI,EAAE;gBACJ,OAAO,EAAE,uBAAuB;gBAChC,KAAK,EAAE,MAAM;gBACb,OAAO,EAAE,0BAA0B,YAAY,CAAC,OAAO,WAAW;aACnE;SACF,CAAC,CAAA;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACvB,4CAA4C;YAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAgC,CAAA;YACpD,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;gBAC3C,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;oBACnB,IAAI,EAAE;wBACJ,OAAO,EAAE,uBAAuB;wBAChC,KAAK,EAAE,MAAM;wBACb,OAAO,EAAE,oBAAoB;wBAC7B,KAAK,EAAE,EAAE,KAAK,EAAE;qBACjB;iBACF,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAED,4CAA4C;AAC5C,eAAe,iBAAiB,CAAA"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "opencode-enhance-plan",
+  "version": "0.2.6",
+  "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",
+  "type": "module",
+  "files": [
+    "dist/",
+    "agents/",
+    "commands/",
+    "templates/"
+  ],
+  "scripts": {
+    "repo:commit": "node scripts/release-workflow.mjs commit",
+    "repo:release": "node scripts/release-workflow.mjs release",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "planning",
+    "enhanced-planning",
+    "todo",
+    "workflow",
+    "agent",
+    "feature-planning",
+    "plan-management"
+  ],
+  "author": "spartawhy117",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spartawhy117/opencode-enhance-plan.git"
+  },
+  "homepage": "https://github.com/spartawhy117/opencode-enhance-plan#readme",
+  "bugs": {
+    "url": "https://github.com/spartawhy117/opencode-enhance-plan/issues"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.2.25",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

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

@@ -0,0 +1,36 @@
+# Project Workflow Rules
+
+This project uses an enhanced planning workflow built around `enhance-plan`.
+
+## Default Workflow
+
+- Use `enhance-plan` for non-trivial features, cross-module changes, architecture decisions, and work that benefits from explicit review before implementation.
+- Use build mode only after a feature plan has been reviewed and explicitly approved.
+- Keep planning focused on one feature at a time.
+
+## Planning Artifacts
+
+Active feature plans live under `plan/active/<feature>/` and should include:
+
+- `plan.json` - structured plan state and todo metadata
+- `plan.md` - human-readable plan draft
+- `.plan-original.md` - preserved baseline draft
+- `handoff.md` - minimal execution-facing handoff for build mode
+
+Completed or inactive feature plans should move to `plan/archive/<feature>/` when appropriate.
+
+## Build Context Policy
+
+- Prefer the current feature's `handoff.md` as the primary execution context.
+- Read `plan.json` or `plan.md` only when additional detail is needed.
+- Avoid loading broad background context when the current feature handoff is sufficient.
+
+## Feature Discipline
+
+- Keep one active feature context at a time.
+- If returning to a previous feature, resume its existing plan instead of creating a duplicate.
+- If multiple approaches are viable, include a dedicated `Option Paths` section before execution approval.
+
+## Legacy Docs
+
+If this project had planning or progress documents before initialization, preserve them in a traceable legacy location and normalize future work into the `plan/` structure.

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

@@ -0,0 +1,32 @@
+# Enhanced Planning Workflow
+
+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
+- `/feature-switch` - switch the active feature while staying in `enhance-plan`
+- `/plan-handoff` - generate a concise handoff for build mode
+
+## Directory Structure
+
+- `plan/active/<feature>/plan.json`
+- `plan/active/<feature>/plan.md`
+- `plan/active/<feature>/.plan-original.md`
+- `plan/active/<feature>/handoff.md`
+- `plan/archive/<feature>/...`
+
+## Recommended Flow
+
+1. Run `/plan-feature <feature>` in `enhance-plan` mode.
+2. Clarify requirements, review `Option Paths`, and refine the plan.
+3. Explicitly approve execution when the plan is ready.
+4. Run `/plan-handoff`.
+5. Switch to build mode and implement from the handoff.
+
+## Notes
+
+- Keep planning focused on one feature at a time.
+- Treat `handoff.md` as the default build context.
+- Keep legacy docs preserved but move new planning into the normalized `plan/` structure.

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

@@ -0,0 +1,27 @@
+## Feature Goal
+
+- 
+
+## Confirmed Scope
+
+- 
+
+## Current Todo Summary
+
+1. 
+2. 
+3. 
+
+## Execution Order
+
+1. 
+2. 
+3. 
+
+## Validation Steps
+
+- 
+
+## Blockers And Caveats
+
+- 

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

@@ -0,0 +1,45 @@
+{
+  "id": "feature-slug",
+  "name": "Feature Title",
+  "overview": "One-sentence description of the feature goal.",
+  "status": "prepare",
+  "hasConfirmed": false,
+  "parts": [
+    "req",
+    "tech",
+    "todos",
+    "handoff"
+  ],
+  "feature": {
+    "slug": "feature-slug",
+    "title": "Feature Title"
+  },
+  "content": "",
+  "todolist": [
+    {
+      "id": "clarify-scope",
+      "content": "Clarify scope and constraints for the feature",
+      "dependencies": [],
+      "status": "pending"
+    },
+    {
+      "id": "draft-plan",
+      "content": "Draft the technical plan and implementation sequence",
+      "dependencies": [
+        "clarify-scope"
+      ],
+      "status": "pending"
+    },
+    {
+      "id": "prepare-handoff",
+      "content": "Prepare a minimal handoff for build mode after approval",
+      "dependencies": [
+        "draft-plan"
+      ],
+      "status": "pending"
+    }
+  ],
+  "openQuestions": [],
+  "optionPaths": [],
+  "updatedAt": ""
+}

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

@@ -0,0 +1,12 @@
+## Baseline Plan Draft
+
+Use this file to preserve the initial or last approved draft before later edits.
+
+Recommended contents:
+
+- requirement summary
+- technical approach
+- task breakdown
+- option-path comparison
+- validation strategy
+- approval status at the time the baseline was captured

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

@@ -0,0 +1,54 @@
+## User Request
+
+- Goal:
+- Context:
+- Constraints:
+
+## Core Requirement Analysis
+
+- In-scope:
+- Out-of-scope:
+- Affected areas:
+
+## Technical Approach
+
+- Existing system relationship:
+- Key implementation idea:
+- Data flow or module coordination:
+
+## Task Breakdown
+
+1. 
+2. 
+3. 
+
+## Risks And Open Questions
+
+- Risks:
+- Open questions:
+
+## Validation
+
+- Functional validation:
+- Test or build validation:
+
+## Option Paths
+
+### Path A
+- Applicability:
+- Advantages:
+- Costs:
+- Risks:
+
+### Path B
+- Applicability:
+- Advantages:
+- Costs:
+- Risks:
+
+Recommended path:
+
+## Confirmation State
+
+- Current state: prepare
+- Execution approved: false