opencode-empirical-plan 0.2.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "opencode-empirical-plan",
+  "version": "0.2.0",
+  "description": "OpenCode lifecycle plugin for empirical plan orchestration.",
+  "author": "chuck",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.2.4"
+  },
+  "devDependencies": {
+    "@tsconfig/bun": "^1.0.10",
+    "@types/bun": "^1.3.3",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/hooks/session-idle.ts

@@ -0,0 +1,15 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+
+interface EventProperties {
+  sessionID?: string;
+  info?: { id?: string };
+  [key: string]: unknown;
+}
+
+export async function handleSessionIdle(
+  _props: EventProperties,
+  _client: PluginInput["client"],
+): Promise<void> {
+  // Phase advancement happens in tool.execute.after on task() completion.
+  // Standalone coordinator self-directs after task() returns.
+}

package/src/hooks/tool-after.ts

@@ -0,0 +1,176 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { lookupParent, lookupRunDir, registerChild } from "../state/active-lifecycles.ts";
+import { readLifecycleState, writeLifecycleState } from "../state/lifecycle-state.ts";
+import { atomicWrite } from "../state/frontmatter.ts";
+import { consumeCallStart } from "./tool-before.ts";
+import type { LifecyclePhase } from "../schema.ts";
+
+interface ToolAfterInput {
+  tool: string;
+  sessionID: string;
+  callID: string;
+  args?: unknown;
+}
+
+interface ToolAfterOutput {
+  output?: unknown;
+  metadata?: Record<string, unknown>;
+}
+
+const TOOL_TRACE_HEADER = `## Tool Trace
+| # | Tool | Args Summary | Output Summary | Duration |
+|---|------|-------------|----------------|----------|`;
+
+const EXECUTION_MD_INIT_MARKER = "<!-- EXECUTION:TRACE -->";
+
+const PHASE_TRANSITIONS: Record<string, LifecyclePhase> = {
+  plan: "execute",
+  execute: "reflect",
+  reflect: "done",
+};
+
+// Per-file serialization: one in-flight write per execution.md path at a time
+const writeQueue = new Map<string, Promise<void>>();
+
+function serialized(filePath: string, fn: () => Promise<void>): Promise<void> {
+  const prev = writeQueue.get(filePath) ?? Promise.resolve();
+  const next = prev.then(fn, fn); // run even if previous failed
+  writeQueue.set(filePath, next);
+  next.finally(() => {
+    if (writeQueue.get(filePath) === next) writeQueue.delete(filePath);
+  });
+  return next;
+}
+
+function truncate(s: string, max: number): string {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > max ? flat.slice(0, max) + "…" : flat;
+}
+
+function argsToString(args: unknown): string {
+  if (!args) return "";
+  try {
+    return truncate(JSON.stringify(args), 120);
+  } catch {
+    return String(args).slice(0, 120);
+  }
+}
+
+function outputToString(output: unknown): string {
+  if (output === undefined || output === null) return "";
+  const s = typeof output === "string" ? output : JSON.stringify(output);
+  return truncate(s, 200);
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureExecutionMd(executionFile: string, planFile: string): Promise<void> {
+  if (await fileExists(executionFile)) return;
+
+  let planTitle = "Empirical Plan";
+  try {
+    const planContent = await fs.readFile(planFile, "utf-8");
+    const m = /^#\s+(.+)$/m.exec(planContent);
+    if (m) planTitle = m[1]!.trim();
+  } catch {}
+
+  const now = new Date().toISOString();
+  const skeleton = `---
+Plan: ./plan.md
+Phase: executing
+StartedAt: ${now}
+---
+
+# Execution — ${planTitle}
+
+${EXECUTION_MD_INIT_MARKER}
+${TOOL_TRACE_HEADER}
+`;
+  await atomicWrite(executionFile, skeleton);
+}
+
+async function appendToolTrace(
+  executionFile: string,
+  rowNum: number,
+  toolName: string,
+  args: unknown,
+  output: unknown,
+  durationMs: number | undefined,
+): Promise<void> {
+  const content = await fs.readFile(executionFile, "utf-8");
+  const duration = durationMs !== undefined ? `${durationMs}ms` : "—";
+  const row = `| ${rowNum} | \`${toolName}\` | ${argsToString(args)} | ${outputToString(output)} | ${duration} |`;
+  const updated = content.trimEnd() + "\n" + row + "\n";
+  await atomicWrite(executionFile, updated);
+}
+
+async function getNextRowNum(executionFile: string): Promise<number> {
+  try {
+    const content = await fs.readFile(executionFile, "utf-8");
+    const rows = content.split("\n").filter((l) => /^\|\s*\d+\s*\|/.test(l));
+    return rows.length + 1;
+  } catch {
+    return 1;
+  }
+}
+
+export async function handleToolAfter(
+  input: ToolAfterInput,
+  output: ToolAfterOutput,
+): Promise<void> {
+  const startTime = consumeCallStart(input.callID);
+  const durationMs = startTime !== undefined ? Date.now() - startTime : undefined;
+
+  // --- Child session registration + phase advancement (task() tool) ---
+  if (input.tool === "task") {
+    const childSessionId = output.metadata?.["sessionId"];
+    if (typeof childSessionId === "string" && childSessionId) {
+      const runDir = lookupRunDir(input.sessionID);
+      if (runDir) {
+        const state = await readLifecycleState(runDir);
+        if (state && state.phase !== "done") {
+          if (!state.childSessionId || state.childSessionId === childSessionId) {
+            registerChild(input.sessionID, childSessionId);
+            const nextPhase: LifecyclePhase = PHASE_TRANSITIONS[state.phase] ?? "done";
+            await writeLifecycleState(runDir, {
+              ...state,
+              phase: nextPhase,
+              seq: state.seq + 1,
+              childSessionId: undefined,
+              updatedAt: new Date().toISOString(),
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // --- Tool Trace append for EXECUTE-phase child sessions ---
+  const parentSessionId = lookupParent(input.sessionID);
+  if (!parentSessionId) return;
+
+  const runDir = lookupRunDir(parentSessionId);
+  if (!runDir) return;
+
+  const state = await readLifecycleState(runDir);
+  if (!state || state.phase !== "execute") return;
+
+  if (state.childSessionId && state.childSessionId !== input.sessionID) return;
+
+  const executionFile = path.join(runDir, "execution.md");
+  const planFile = path.join(runDir, "plan.md");
+
+  await serialized(executionFile, async () => {
+    await ensureExecutionMd(executionFile, planFile);
+    const rowNum = await getNextRowNum(executionFile);
+    await appendToolTrace(executionFile, rowNum, input.tool, input.args, output.output, durationMs);
+  });
+}

package/src/hooks/tool-before.ts

@@ -0,0 +1,11 @@
+const callStartTimes = new Map<string, number>();
+
+export function recordCallStart(callID: string): void {
+  callStartTimes.set(callID, Date.now());
+}
+
+export function consumeCallStart(callID: string): number | undefined {
+  const t = callStartTimes.get(callID);
+  callStartTimes.delete(callID);
+  return t;
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { lifecycleStartTool } from "./tools/lifecycle-start.ts";
+import { lifecycleRecordExecutionTool } from "./tools/lifecycle-record-execution.ts";
+import { lifecycleRecordReflectionTool } from "./tools/lifecycle-record-reflection.ts";
+import { handleToolAfter } from "./hooks/tool-after.ts";
+import { recordCallStart } from "./hooks/tool-before.ts";
+import { handleSessionIdle } from "./hooks/session-idle.ts";
+import { cleanup, cleanupChild } from "./state/active-lifecycles.ts";
+
+export const EmpiricalPlanPlugin: Plugin = async ({ client }) => {
+  return {
+    tool: {
+      lifecycle_start: lifecycleStartTool,
+      lifecycle_record_execution: lifecycleRecordExecutionTool,
+      lifecycle_record_reflection: lifecycleRecordReflectionTool,
+    },
+
+    "tool.execute.before": async (input) => {
+      try {
+        recordCallStart(input.callID);
+      } catch (err) {
+        console.error("[empirical-plan] tool.execute.before error:", err);
+      }
+    },
+
+    "tool.execute.after": async (input, output) => {
+      try {
+        await handleToolAfter(
+          { tool: input.tool, sessionID: input.sessionID, callID: input.callID, args: input.args },
+          { output: output?.output, metadata: output?.metadata as Record<string, unknown> | undefined },
+        );
+      } catch (err) {
+        console.error("[empirical-plan] tool.execute.after error:", err);
+      }
+    },
+
+    event: async ({ event }) => {
+      try {
+        const props = (event as { properties?: Record<string, unknown> }).properties ?? {};
+
+        if (event.type === "session.idle") {
+          await handleSessionIdle(props, client);
+        }
+
+        if (event.type === "session.deleted") {
+          const sessionID =
+            (props.info as { id?: string } | undefined)?.id ??
+            (props.id as string | undefined);
+          if (sessionID) {
+            cleanup(sessionID);
+            cleanupChild(sessionID);
+          }
+        }
+      } catch (err) {
+        console.error("[empirical-plan] event handler error:", err);
+      }
+    },
+  };
+};
+
+export default EmpiricalPlanPlugin;

package/src/schema.ts

@@ -0,0 +1,73 @@
+/**
+ * Lifecycle state schema for opencode-empirical-plan plugin.
+ */
+
+export type LifecyclePhase = "plan" | "execute" | "reflect" | "done";
+export type LifecycleMode = "standalone" | "heartbeat";
+
+export interface LifecycleState {
+  /** Unique lifecycle ID, format "lc-YYYYMMDD-HHmmss" */
+  lifecycleId: string;
+  /** Session ID that triggered lifecycle_start */
+  parentSessionId: string;
+  /** Current lifecycle phase */
+  phase: LifecyclePhase;
+  /** Monotonically increasing idempotency guard */
+  seq: number;
+  /** Current phase's child session ID (if known) */
+  childSessionId?: string;
+  /** Directory containing plan.md / envelope.json / reflect.md */
+  runDir: string;
+  /** Absolute path to plan.md (populated after lifecycle_start) */
+  planFile?: string;
+  /** Whether this lifecycle is driven by standalone plugin or Heartbeat runner */
+  mode: LifecycleMode;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export const STATE_FILENAME = "lifecycle-state.json";
+
+/**
+ * Validate that an object is a well-formed LifecycleState.
+ * Throws if required fields are missing or invalid.
+ */
+export function validateLifecycleState(obj: unknown): LifecycleState {
+  if (!obj || typeof obj !== "object") {
+    throw new Error("lifecycle-state.json: root must be an object");
+  }
+  const s = obj as Record<string, unknown>;
+
+  const required = [
+    "lifecycleId",
+    "parentSessionId",
+    "phase",
+    "seq",
+    "runDir",
+    "mode",
+    "createdAt",
+    "updatedAt",
+  ] as const;
+
+  for (const field of required) {
+    if (!(field in s)) {
+      throw new Error(`lifecycle-state.json: missing required field "${field}"`);
+    }
+  }
+
+  const validPhases: LifecyclePhase[] = ["plan", "execute", "reflect", "done"];
+  if (!validPhases.includes(s["phase"] as LifecyclePhase)) {
+    throw new Error(`lifecycle-state.json: invalid phase "${s["phase"]}"`);
+  }
+
+  const validModes: LifecycleMode[] = ["standalone", "heartbeat"];
+  if (!validModes.includes(s["mode"] as LifecycleMode)) {
+    throw new Error(`lifecycle-state.json: invalid mode "${s["mode"]}"`);
+  }
+
+  if (typeof s["seq"] !== "number" || !Number.isInteger(s["seq"]) || s["seq"] < 0) {
+    throw new Error(`lifecycle-state.json: "seq" must be a non-negative integer`);
+  }
+
+  return s as unknown as LifecycleState;
+}

package/src/state/active-lifecycles.ts

@@ -0,0 +1,44 @@
+const KEY = Symbol.for("opencode-empirical-plan.activeLifecycles");
+
+interface ActiveStore {
+  parentToRunDir: Map<string, string>;
+  childToParent: Map<string, string>;
+}
+
+if (!(globalThis as Record<symbol, unknown>)[KEY]) {
+  (globalThis as Record<symbol, unknown>)[KEY] = {
+    parentToRunDir: new Map<string, string>(),
+    childToParent: new Map<string, string>(),
+  } satisfies ActiveStore;
+}
+
+export const activeLifecycles = (globalThis as Record<symbol, unknown>)[KEY] as ActiveStore;
+
+export function registerParent(parentSessionId: string, runDir: string): void {
+  activeLifecycles.parentToRunDir.set(parentSessionId, runDir);
+}
+
+export function registerChild(parentSessionId: string, childSessionId: string): void {
+  activeLifecycles.childToParent.set(childSessionId, parentSessionId);
+}
+
+export function lookupRunDir(parentSessionId: string): string | undefined {
+  return activeLifecycles.parentToRunDir.get(parentSessionId);
+}
+
+export function lookupParent(childSessionId: string): string | undefined {
+  return activeLifecycles.childToParent.get(childSessionId);
+}
+
+export function cleanup(parentSessionId: string): void {
+  activeLifecycles.parentToRunDir.delete(parentSessionId);
+  for (const [child, parent] of activeLifecycles.childToParent.entries()) {
+    if (parent === parentSessionId) {
+      activeLifecycles.childToParent.delete(child);
+    }
+  }
+}
+
+export function cleanupChild(childSessionId: string): void {
+  activeLifecycles.childToParent.delete(childSessionId);
+}

package/src/state/frontmatter.ts

@@ -0,0 +1,23 @@
+import * as fs from "node:fs/promises";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+const LIFECYCLE_FIELD_RE = /^Lifecycle:\s*.+$/m;
+
+export function applyFrontmatterLifecycle(content: string, value: string): string {
+  const fmMatch = FRONTMATTER_RE.exec(content);
+  if (fmMatch) {
+    const fmBlock = fmMatch[0];
+    if (LIFECYCLE_FIELD_RE.test(fmBlock)) {
+      return content.replace(LIFECYCLE_FIELD_RE, `Lifecycle: ${value}`);
+    }
+    const insertAt = fmMatch.index + fmMatch[0].lastIndexOf("\n---") + 1;
+    return content.slice(0, insertAt) + `Lifecycle: ${value}\n` + content.slice(insertAt);
+  }
+  return `---\nLifecycle: ${value}\n---\n\n` + content;
+}
+
+export async function atomicWrite(filePath: string, content: string): Promise<void> {
+  const tmpPath = filePath + ".tmp";
+  await fs.writeFile(tmpPath, content, "utf-8");
+  await fs.rename(tmpPath, filePath);
+}

package/src/state/lifecycle-state.ts

@@ -0,0 +1,21 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { type LifecycleState, STATE_FILENAME, validateLifecycleState } from "../schema.ts";
+
+export async function readLifecycleState(runDir: string): Promise<LifecycleState | null> {
+  const stateFile = path.join(runDir, STATE_FILENAME);
+  try {
+    const raw = await fs.readFile(stateFile, "utf-8");
+    return validateLifecycleState(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+export async function writeLifecycleState(runDir: string, state: LifecycleState): Promise<void> {
+  await fs.mkdir(runDir, { recursive: true });
+  const stateFile = path.join(runDir, STATE_FILENAME);
+  const tmpFile = path.join(runDir, `.${STATE_FILENAME}.tmp`);
+  await fs.writeFile(tmpFile, JSON.stringify(state, null, 2), "utf-8");
+  await fs.rename(tmpFile, stateFile);
+}

package/src/tools/lifecycle-record-execution.ts

@@ -0,0 +1,119 @@
+import { tool } from "@opencode-ai/plugin";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { atomicWrite } from "../state/frontmatter.ts";
+import { ensureExecutionMd } from "../hooks/tool-after.ts";
+
+const SUMMARY_MARKER = "<!-- EXECUTION:SUMMARY -->";
+
+type RecordResult =
+  | { success: true; execution_file: string }
+  | { success: false; code: string; reason: string; next_action: string };
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const lifecycleRecordExecutionTool = tool({
+  description: `Record Phase 4 (Execution Summary) into execution.md.
+
+execution.md is the dedicated execution record file — separate from plan.md (which stays read-only after Phase 1-3).
+
+Guards (hard-block):
+- plan.md must exist and contain "## Plan Steps" (Phase 1-3 complete)
+- execution.md must already exist (initialized by the tool.execute.after hook when EXECUTE phase began)
+- <!-- EXECUTION:SUMMARY --> must NOT already exist in execution.md (idempotent guard)
+
+On success: appends the execution_summary section into execution.md and updates its Phase frontmatter field to "summarized".
+
+The execution_summary should compare each Plan Step against what actually happened: mark ✅/⚠️/❌, note deviations, list out-of-plan actions, and summarize artifacts produced.`,
+  args: {
+    run_dir: tool.schema
+      .string()
+      .describe("Absolute path to the directory containing plan.md and execution.md"),
+    execution_summary: tool.schema
+      .string()
+      .describe(
+        "Phase 4 summary content generated by the AI: per-step status table, out-of-plan actions, artifacts",
+      ),
+  },
+  async execute(args) {
+    const runDir = path.resolve(args.run_dir);
+    const planFile = path.join(runDir, "plan.md");
+    const executionFile = path.join(runDir, "execution.md");
+
+    const result = await doRecord(planFile, executionFile, args.execution_summary);
+    return JSON.stringify(result);
+  },
+});
+
+async function doRecord(
+  planFile: string,
+  executionFile: string,
+  executionSummary: string,
+): Promise<RecordResult> {
+  // Guard 1: plan.md must exist with Phase 1-3 complete
+  if (!(await fileExists(planFile))) {
+    return {
+      success: false,
+      code: "PHASE_NOT_READY",
+      reason: `plan.md not found at ${planFile}`,
+      next_action: "Complete the PLAN phase first — run empirical-plan skill to produce plan.md",
+    };
+  }
+
+  const planContent = await fs.readFile(planFile, "utf-8");
+  if (!planContent.includes("## Plan Steps")) {
+    return {
+      success: false,
+      code: "PHASE_NOT_READY",
+      reason: "plan.md does not contain '## Plan Steps' — Phase 1-3 incomplete",
+      next_action: "Complete the PLAN phase using the empirical-plan skill",
+    };
+  }
+
+  // Guard 2: execution.md must exist — auto-create skeleton if EXECUTE ran no tools
+  if (!(await fileExists(executionFile))) {
+    await ensureExecutionMd(executionFile, planFile);
+  }
+
+  const executionContent = await fs.readFile(executionFile, "utf-8");
+
+  // Guard 3: idempotent — summary not already written
+  if (executionContent.includes(SUMMARY_MARKER)) {
+    return {
+      success: false,
+      code: "ALREADY_RECORDED",
+      reason: "Phase 4 summary already recorded (EXECUTION:SUMMARY marker present in execution.md)",
+      next_action: "Execution already recorded — proceed to lifecycle_record_reflection",
+    };
+  }
+
+  // Append summary section + update Phase frontmatter
+  const completedAt = new Date().toISOString();
+  const section = `\n---\n${SUMMARY_MARKER}\n## Execution Summary\n\n${executionSummary.trim()}\n`;
+  const updated = applyExecutionPhase(executionContent + section, "summarized", completedAt);
+  await atomicWrite(executionFile, updated);
+
+  return { success: true, execution_file: executionFile };
+}
+
+function applyExecutionPhase(content: string, phase: string, completedAt: string): string {
+  const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+  const fmMatch = FRONTMATTER_RE.exec(content);
+  if (!fmMatch) return content;
+
+  let fm = fmMatch[1]!;
+  fm = fm.replace(/^Phase:.*$/m, `Phase: ${phase}`);
+  if (fm.includes("CompletedAt:")) {
+    fm = fm.replace(/^CompletedAt:.*$/m, `CompletedAt: ${completedAt}`);
+  } else {
+    fm += `\nCompletedAt: ${completedAt}`;
+  }
+  return `---\n${fm}\n---` + content.slice(fmMatch[0].length);
+}

package/src/tools/lifecycle-record-reflection.ts

@@ -0,0 +1,100 @@
+import { tool } from "@opencode-ai/plugin";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { applyFrontmatterLifecycle, atomicWrite } from "../state/frontmatter.ts";
+
+const EXECUTION_SUMMARY_MARKER = "<!-- EXECUTION:SUMMARY -->";
+const REFLECTION_MARKER = "<!-- LIFECYCLE:REFLECTION -->";
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const lifecycleRecordReflectionTool = tool({
+  description: `Record Phase 5 (Reflection & Optimization) into plan.md.
+
+Guards (hard-block):
+- execution.md must exist and contain <!-- EXECUTION:SUMMARY --> (Phase 4 already recorded)
+- reflect.md must exist in run_dir (REFLECT phase complete)
+- <!-- LIFECYCLE:REFLECTION --> must NOT already exist in plan.md (idempotent guard)
+
+On success: appends the reflection_record block into plan.md and updates frontmatter Lifecycle: complete.
+
+The reflection_record should contain: execution quality assessment, plan design issues found, specific actionable optimization suggestions for next time, and reusable principles to promote to MEMORY.md.`,
+  args: {
+    run_dir: tool.schema
+      .string()
+      .describe("Absolute path to the directory containing plan.md, execution.md, and reflect.md"),
+    reflection_record: tool.schema
+      .string()
+      .describe("Phase 5 content generated by the AI before calling this tool"),
+  },
+  async execute(args) {
+    const runDir = path.resolve(args.run_dir);
+    const planFile = path.join(runDir, "plan.md");
+    const executionFile = path.join(runDir, "execution.md");
+    const reflectFile = path.join(runDir, "reflect.md");
+
+    // Guard 1: plan.md must exist
+    if (!(await fileExists(planFile))) {
+      return JSON.stringify({
+        success: false,
+        code: "PLAN_MISSING",
+        reason: `plan.md not found at ${planFile}`,
+        next_action: "Complete the PLAN phase first",
+      });
+    }
+
+    // Guard 2: execution.md must exist and contain EXECUTION:SUMMARY
+    if (!(await fileExists(executionFile))) {
+      return JSON.stringify({
+        success: false,
+        code: "EXECUTION_NOT_RECORDED",
+        reason: `execution.md not found at ${executionFile}`,
+        next_action: "Call lifecycle_record_execution first to record Phase 4",
+      });
+    }
+
+    const executionContent = await fs.readFile(executionFile, "utf-8");
+    if (!executionContent.includes(EXECUTION_SUMMARY_MARKER)) {
+      return JSON.stringify({
+        success: false,
+        code: "EXECUTION_NOT_RECORDED",
+        reason: "Phase 4 summary (EXECUTION:SUMMARY) not yet recorded in execution.md",
+        next_action: "Call lifecycle_record_execution first to record Phase 4",
+      });
+    }
+
+    // Guard 3: reflect.md must exist
+    if (!(await fileExists(reflectFile))) {
+      return JSON.stringify({
+        success: false,
+        code: "REFLECT_MISSING",
+        reason: `reflect.md not found at ${reflectFile}`,
+        next_action: "Complete the REFLECT phase — the reflector must write reflect.md to run_dir",
+      });
+    }
+
+    // Guard 4: idempotent — reflection not already written into plan.md
+    const planContent = await fs.readFile(planFile, "utf-8");
+    if (planContent.includes(REFLECTION_MARKER)) {
+      return JSON.stringify({
+        success: false,
+        code: "ALREADY_REFLECTED",
+        reason: "Phase 5 already recorded (LIFECYCLE:REFLECTION marker present in plan.md)",
+        next_action: "Reflection already complete — lifecycle is done",
+      });
+    }
+
+    const section = `\n---\n${REFLECTION_MARKER}\n## Phase 5: Reflection & Optimization\n\n${args.reflection_record.trim()}\n`;
+    const updated = applyFrontmatterLifecycle(planContent + section, "complete");
+    await atomicWrite(planFile, updated);
+
+    return JSON.stringify({ success: true, plan_file: planFile });
+  },
+});

package/src/tools/lifecycle-start.ts

@@ -0,0 +1,94 @@
+import { tool } from "@opencode-ai/plugin";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { writeLifecycleState } from "../state/lifecycle-state.ts";
+import { readLifecycleState } from "../state/lifecycle-state.ts";
+import { lookupRunDir, registerParent } from "../state/active-lifecycles.ts";
+import type { LifecycleState, LifecycleMode } from "../schema.ts";
+
+function makeLifecycleId(): string {
+  const now = new Date();
+  const pad = (n: number, len = 2) => String(n).padStart(len, "0");
+  const rand = Math.random().toString(36).slice(2, 6);
+  return [
+    "lc",
+    `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`,
+    `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`,
+    rand,
+  ].join("-");
+}
+
+export const lifecycleStartTool = tool({
+  description: `Start a new empirical-plan lifecycle. Creates run_dir, initializes lifecycle-state.json, and returns the lifecycleId.
+
+Call this at the beginning of a PLAN → EXECUTE → REFLECT workflow. Provide:
+- run_dir: absolute path where lifecycle artifacts (plan.md, execution.md, reflect.md) will be stored
+- mode: "standalone" (default, AI-coordinated) or "heartbeat" (runner-coordinated)
+
+Returns: { success, lifecycleId, runDir, planFile, stateFile, phase }
+No planPrompt is returned — the coordinator AI constructs prompts using the returned runDir.
+
+Phase advancement is automatic: each call to task() that completes a phase sub-session
+advances lifecycle-state.json to the next phase (plan→execute→reflect→done).`,
+  args: {
+    run_dir: tool.schema
+      .string()
+      .describe("Absolute path to the directory for this lifecycle's artifacts"),
+    mode: tool.schema
+      .string()
+      .optional()
+      .describe('Coordination mode: "standalone" (default) or "heartbeat"'),
+  },
+  async execute(args, ctx) {
+    const runDir = path.resolve(args.run_dir);
+    const rawMode = args.mode ?? "standalone";
+    if (rawMode !== "standalone" && rawMode !== "heartbeat") {
+      throw new Error(`Invalid mode "${rawMode}". Must be "standalone" or "heartbeat".`);
+    }
+    const mode: LifecycleMode = rawMode;
+
+    const existingRunDir = lookupRunDir(ctx.sessionID);
+    if (existingRunDir) {
+      const existingState = await readLifecycleState(existingRunDir);
+      if (existingState && existingState.phase !== "done") {
+        return JSON.stringify({
+          success: false,
+          code: "LIFECYCLE_ALREADY_ACTIVE",
+          reason: `Session has an in-progress lifecycle (phase: ${existingState.phase}) at run_dir: ${existingRunDir}`,
+          next_action: "Wait for the current lifecycle to complete before starting a new one.",
+        });
+      }
+      console.log(`[empirical-plan] lifecycle_start: stale map entry for session ${ctx.sessionID} (phase=${existingState?.phase ?? "missing"}), proceeding with new lifecycle`);
+    }
+
+    await fs.mkdir(runDir, { recursive: true });
+
+    const lifecycleId = makeLifecycleId();
+    const now = new Date().toISOString();
+    const planFile = path.join(runDir, "plan.md");
+
+    const state: LifecycleState = {
+      lifecycleId,
+      parentSessionId: ctx.sessionID,
+      phase: "plan",
+      seq: 0,
+      runDir,
+      planFile,
+      mode,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    await writeLifecycleState(runDir, state);
+    registerParent(ctx.sessionID, runDir);
+
+    return JSON.stringify({
+      success: true,
+      lifecycleId,
+      runDir,
+      planFile,
+      stateFile: `${runDir}/lifecycle-state.json`,
+      phase: "plan",
+    });
+  },
+});