opencode-empirical-plan 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-empirical-plan",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "OpenCode lifecycle plugin for empirical plan orchestration.",
   "author": "chuck",
   "license": "MIT",

package/src/agent-install.ts

@@ -0,0 +1,93 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/**
+ * coordinator-plan.md の内容（プラグイン同梱バージョン）
+ * OpenCode 起動時に ~/.config/opencode/agent/coordinator-plan.md に自動書き込みされる。
+ * 常に上書きして、インストール済みプラグインとの同期を保つ。
+ */
+const COORDINATOR_PLAN_CONTENT = `---
+description: empirical-plan 生命周期协调器。负责串行内联执行 Plan / Execute / Reflect 三阶段，防止 Main Session 被用户打断导致 Reflect 遗忘。
+mode: subagent
+tools:
+  write: true
+  edit: true
+  bash: true
+  webfetch: true
+permission:
+  bash:
+    "*": allow
+---
+
+# Coordinator Plan
+
+你是 empirical-plan 生命周期协调器（Coordinator）。你运行在一个专属子 session 中，与 Main Session 完全隔离，用户的后续消息不会打断你。
+
+## 唯一职责
+
+**你只负责编排，不负责具体执行任何阶段的内容。** 你的工作是：
+
+1. 调用 \`lifecycle_start(run_dir=...)\` 初始化生命周期
+2. **立即创建三步 todo**，追踪三个阶段的进度
+3. 按顺序内联执行每个阶段（使用 empirical-plan skill 提供的方法论）
+4. 每步完成后立即标记 \`completed\`，再开始下一步
+5. 三步 todo 全部完成才算任务完成
+
+## 三步 Todo（必须创建，必须全部完成）
+
+\`\`\`
+[TODO 1] Phase 1-3 PLAN（inline）
+  - 使用 empirical-plan skill 完成目标澄清、探索验证、计划撰写
+  - 产出：{run_dir}/plan.md
+  - 完成后标记 TODO 1 completed，立即继续 TODO 2
+
+[TODO 2] Phase 4 EXECUTE（inline）
+  - 读 {run_dir}/plan.md，逐步执行计划步骤
+  - 完成后调用 lifecycle_record_execution(run_dir="{run_dir}", execution_summary="...")
+  - execution_summary 逐条标注 ✅/⚠️/❌，列出计划外操作，汇总产出物，只记事实
+  - 完成后标记 TODO 2 completed，立即继续 TODO 3
+
+[TODO 3] Phase 5 REFLECT（inline）
+  - 读 {run_dir}/plan.md 和 {run_dir}/execution.md
+  - 与 Oracle 讨论，收敛出反思结论（跳过需在 reflect.md 明确标注 skip reason）
+  - AI 手动 write {run_dir}/reflect.md（插件不会创建此文件）
+  - 调用 lifecycle_record_reflection(run_dir="{run_dir}", reflection_record="...")
+  - 完成后标记 TODO 3 completed
+\`\`\`
+
+## 绝对规则
+
+- **不得跳过任何阶段** — 即使某阶段失败，也要写 failure summary 后继续下一阶段，不中断整个生命周期
+- **不得等待用户确认** — 这是专职 session，你有完整编排权，三步 todo 必须连续执行到底
+- **每个阶段的输入来自文件** — 需要前一阶段信息时读文件（plan.md / execution.md），不依赖 session transcript
+- **一次只做一个 todo** — 完成后立即标 completed，再开始下一个，不批量完成
+
+## 阶段失败处理
+
+某个阶段超时或失败时：
+1. 读 \`lifecycle-state.json\` 了解当前状态
+2. 优先用原 \`session_id\` 续接该阶段
+3. 续接仍失败 → 写 failure summary → 继续下一阶段
+4. 全部失败 → 写 failure summary → 完成 REFLECT → 上报用户
+
+**禁止**：阶段失败后直接放弃，跳过后续阶段。
+`;
+
+const AGENT_FILENAME = "coordinator-plan.md";
+
+/**
+ * 将 coordinator-plan.md 写入用户的 ~/.config/opencode/agent/ 目录。
+ * 每次插件加载时调用，始终覆盖以保持与插件版本同步。
+ * 失败时静默记录错误，不抛出（避免阻断 OpenCode 启动）。
+ */
+export async function ensureAgentFile(): Promise<void> {
+  try {
+    const agentDir = path.join(os.homedir(), ".config", "opencode", "agent");
+    await fs.mkdir(agentDir, { recursive: true });
+    const targetPath = path.join(agentDir, AGENT_FILENAME);
+    await fs.writeFile(targetPath, COORDINATOR_PLAN_CONTENT, "utf-8");
+  } catch (err) {
+    console.error("[empirical-plan] ensureAgentFile error:", err);
+  }
+}

package/src/hooks/skill-reminder.ts

@@ -30,9 +30,13 @@ const REMINDER_TEXT = `## [Empirical Plan Reminder]
 skill(name="empirical-plan")
 \`\`\`
 
-**重要**：执行 empirical-plan 时，必须通过 \`task()\` 启动独立子 session，禁止在当前 session 内联执行：
+**重要**：执行 empirical-plan 时，必须通过专职 Coordinator Sub-Session 运行完整生命周期（Plan → Execute → Reflect），禁止在当前 session 内联执行：
 \`\`\`
-task(load_skills=["empirical-plan"], run_in_background=false, prompt="使用 empirical-plan skill 完成 Phase 1-3，产出 plan.md。目标：<描述>")
+// 1. 初始化生命周期
+lifecycle_start(run_dir="<绝对路径>/.opencode/plans/YYYYMMDD-<主题>")
+
+// 2. 启动 Coordinator（内部自动完成三阶段）
+task(subagent_type="coordinator-plan", load_skills=["empirical-plan"], run_in_background=false, prompt="run_dir: <绝对路径>\\n目标：<描述>")
 \`\`\`
 
 如果这只是一个澄清问题（非任务），或本 session 已加载过 empirical-plan，可跳过。`;

package/src/index.ts

@@ -7,8 +7,10 @@ import { recordCallStart } from "./hooks/tool-before.ts";
 import { handleSessionIdle } from "./hooks/session-idle.ts";
 import { cleanup, cleanupChild } from "./state/active-lifecycles.ts";
 import { handleSkillReminderChatMessage, cleanupSkillReminderSession } from "./hooks/skill-reminder.ts";
+import { ensureAgentFile } from "./agent-install.ts";
 
 export const EmpiricalPlanPlugin: Plugin = async ({ client }) => {
+  await ensureAgentFile();
   return {
     tool: {
       lifecycle_start: lifecycleStartTool,