@dreki-gg/pi-plan-mode 0.10.1 → 0.14.0

package/extensions/plan-mode/index.ts

@@ -3,7 +3,7 @@
  *
  * Two-phase workflow:
  *   1. PLAN phase  — read-only tools + submit_plan tool + medium thinking
- *   2. EXECUTE phase — full tools + update_step tool + low thinking
+ *   2. EXECUTE phase — full tools + update_task tool + low thinking
  *
  * Commands:
  *   /plan [prompt]  — enter plan mode
@@ -21,14 +21,16 @@ import { Key } from '@earendil-works/pi-tui';
 import { PLAN_TOOLS, EXEC_TOOLS, PLAN_MODEL, PLAN_THINKING, EXEC_MODEL, EXEC_THINKING } from './constants.js';
 import type { ThinkingLevel } from './types.js';
 import { PlanModeState } from './state.js';
-import { savePlanToDisk, loadPlanFromDisk, readAndClearExecPending, updatePlansManifest } from './plan-storage.js';
+import { loadHandoff, readAndClearExecPending } from './storage/plan-storage.js';
+import { readTasksJsonl, writeTasksJsonl } from './storage/task-storage.js';
+import { upsertPlanEntry } from './storage/plans-manifest.js';
 import { updateUI } from './ui.js';
 import { buildPlanModePrompt, buildExecutionPrompt } from './prompts.js';
 import { filterExecutionMessages, filterStalePlanMessages } from './context-filter.js';
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
-import { registerUpdateStepTool } from './tools/update-step.js';
+import { registerUpdateTaskTool } from './tools/update-task.js';
 import { isSafeCommand } from './utils.js';
 
 export default function planMode(pi: ExtensionAPI): void {
@@ -50,12 +52,20 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
-  registerUpdateStepTool(pi, {
+  registerUpdateTaskTool(pi, {
     getPlan: () => state.plan,
-    onStepUpdated: (step, status, notes) => {
-      if (!state.plan) return;
-      state.plan.steps[step - 1].status = status;
-      if (notes) state.plan.steps[step - 1].notes = notes;
+    onTaskUpdated: async (taskId, status, notes) => {
+      if (!state.plan || !state.planDir) return;
+      const task = state.plan.tasks.find((candidate) => candidate.id === taskId);
+      if (!task) return;
+      task.status = status;
+      task.updated_at = new Date().toISOString();
+      if (notes) task.notes = notes;
+      await writeTasksJsonl(
+        state.planDir,
+        { _type: 'meta', title: state.plan.title, plan_name: state.plan.planName, created_at: state.plan.tasks[0]?.created_at ?? task.updated_at },
+        state.plan.tasks,
+      );
       state.persist(pi);
     },
   });
@@ -85,8 +95,9 @@ export default function planMode(pi: ExtensionAPI): void {
         ctx.ui.notify('No plan to execute.', 'error');
         return;
       }
-      const stepList = state.plan.steps.map((s, i) => `${i + 1}. ${s.description}`).join('\n');
-      const kickoff = `Execute the following plan: "${state.plan.title}"\n\nSteps:\n${stepList}\n\nStart with step 1. Call update_step after completing each step.`;
+      const taskList = state.plan.tasks.map((task) => `${task.id}. ${task.description}`).join('\n');
+      const first = state.plan.tasks.find((task) => task.status === 'pending')?.id ?? state.plan.tasks[0]?.id;
+      const kickoff = `Execute the following plan: "${state.plan.title}"\n\nTasks:\n${taskList}\n\nStart with ${first}. Call update_task after completing each task.`;
       await executeInNewSession(ctx, state.planDir, state.plan, kickoff);
     },
   });
@@ -94,13 +105,13 @@ export default function planMode(pi: ExtensionAPI): void {
   pi.registerCommand('todos', {
     description: 'Show current plan progress',
     handler: async (_args, ctx) => {
-      if (!state.plan || state.plan.steps.length === 0) {
+      if (!state.plan || state.plan.tasks.length === 0) {
         ctx.ui.notify('No plan yet. Use /plan to start planning.', 'info');
         return;
       }
       const statusIcon = { pending: '○', done: '✓', skipped: '⊘', blocked: '✗' } as const;
-      const list = state.plan.steps
-        .map((s, i) => `${i + 1}. ${statusIcon[s.status]} ${s.description}`)
+      const list = state.plan.tasks
+        .map((s) => `${s.id}. ${statusIcon[s.status]} ${s.description}`)
         .join('\n');
       ctx.ui.notify(`Plan Progress:\n${list}`, 'info');
     },
@@ -157,42 +168,42 @@ export default function planMode(pi: ExtensionAPI): void {
     }
   });
 
-  // ── Event: agent_end — blocked steps, completion, post-plan menu ──────────
+  // ── Event: agent_end — blocked tasks, completion, post-plan menu ──────────
   pi.on('agent_end', async (_event, ctx) => {
-    // ── During execution: handle blocked steps and completion ──
+    // ── During execution: handle blocked tasks and completion ──
     if (state.executing && state.plan) {
-      const blocked = state.plan.steps
-        .map((s, i) => ({ ...s, num: i + 1 }))
-        .filter((s) => s.status === 'blocked');
+      const blocked = state.plan.tasks.filter((s) => s.status === 'blocked');
 
       if (blocked.length > 0) {
         const bs = blocked[0];
         const info = bs.notes
-          ? `Step ${bs.num}: ${bs.description}\nReason: ${bs.notes}`
-          : `Step ${bs.num}: ${bs.description}`;
+          ? `Task ${bs.id}: ${bs.description}\nReason: ${bs.notes}`
+          : `Task ${bs.id}: ${bs.description}`;
 
-        const choice = await ctx.ui.select(`Step blocked — ${info}\n\nWhat next?`, [
-          'Skip this step', 'Provide instructions', 'Re-plan', 'Abort execution',
+        const choice = await ctx.ui.select(`Task blocked — ${info}\n\nWhat next?`, [
+          'Skip this task', 'Provide instructions', 'Re-plan', 'Abort execution',
         ]);
 
-        if (choice === 'Skip this step') {
-          state.plan.steps[bs.num - 1].status = 'skipped';
-          await savePlanToDisk(state.planDir!, state.plan);
+        if (choice === 'Skip this task') {
+          bs.status = 'skipped';
+          bs.updated_at = new Date().toISOString();
+          await writeTasksJsonl(state.planDir!, { _type: 'meta', title: state.plan.title, plan_name: state.plan.planName, created_at: state.plan.tasks[0]?.created_at ?? bs.updated_at }, state.plan.tasks);
           updateUI(state, ctx);
           state.persist(pi);
-          if (state.plan.steps.some((s) => s.status === 'pending')) {
-            pi.sendUserMessage('The blocked step has been skipped. Continue with the next step.', { deliverAs: 'followUp' });
+          if (state.plan.tasks.some((s) => s.status === 'pending')) {
+            pi.sendUserMessage('The blocked task has been skipped. Continue with the next task.', { deliverAs: 'followUp' });
           }
         } else if (choice === 'Provide instructions') {
-          const instructions = await ctx.ui.editor('Instructions for the blocked step:', '');
+          const instructions = await ctx.ui.editor('Instructions for the blocked task:', '');
           if (instructions?.trim()) {
-            state.plan.steps[bs.num - 1].status = 'pending';
-            state.plan.steps[bs.num - 1].notes = undefined;
-            await savePlanToDisk(state.planDir!, state.plan);
+            bs.status = 'pending';
+            bs.notes = undefined;
+            bs.updated_at = new Date().toISOString();
+            await writeTasksJsonl(state.planDir!, { _type: 'meta', title: state.plan.title, plan_name: state.plan.planName, created_at: state.plan.tasks[0]?.created_at ?? bs.updated_at }, state.plan.tasks);
             updateUI(state, ctx);
             state.persist(pi);
             pi.sendUserMessage(
-              `Retry step ${bs.num} with these additional instructions: ${instructions.trim()}`,
+              `Retry task ${bs.id} with these additional instructions: ${instructions.trim()}`,
               { deliverAs: 'followUp' },
             );
           }
@@ -200,7 +211,7 @@ export default function planMode(pi: ExtensionAPI): void {
         } else if (choice === 'Re-plan') {
           await enterPlanMode(state, pi, ctx);
           pi.sendUserMessage(
-            `Step ${bs.num} was blocked: ${bs.notes ?? 'no details'}. Re-analyze and create a revised plan.`,
+            `Task ${bs.id} was blocked: ${bs.notes ?? 'no details'}. Re-analyze and create a revised plan.`,
             { deliverAs: 'followUp' },
           );
           return;
@@ -211,17 +222,40 @@ export default function planMode(pi: ExtensionAPI): void {
       }
 
       // Check completion
-      const allResolved = state.plan.steps.every((s) => s.status === 'done' || s.status === 'skipped');
+      const allResolved = state.plan.tasks.every((s) => s.status === 'done' || s.status === 'skipped');
       if (allResolved) {
         if (state.planDir) {
-          await updatePlansManifest(state.planDir.replace(/^\.plans\//, ''), 'done', state.plan.title);
-          await savePlanToDisk(state.planDir, state.plan);
+          await upsertPlanEntry(state.plan.planName, { status: 'done', title: state.plan.title });
+          await writeTasksJsonl(state.planDir, { _type: 'meta', title: state.plan.title, plan_name: state.plan.planName, created_at: state.plan.tasks[0]?.created_at ?? new Date().toISOString() }, state.plan.tasks);
         }
-        const list = state.plan.steps
-          .map((s) => s.status === 'done' ? `~~${s.description}~~` : `⊘ ~~${s.description}~~`)
+        const done = state.plan.tasks.filter((s) => s.status === 'done').length;
+        const skipped = state.plan.tasks.filter((s) => s.status === 'skipped').length;
+        const total = state.plan.tasks.length;
+        const stats = skipped > 0
+          ? `${done}/${total} done, ${skipped} skipped`
+          : `${done}/${total} done`;
+
+        // Build a summary of what was actually done from task notes
+        const changeSummary = state.plan.tasks
+          .map((s) => {
+            const icon = s.status === 'done' ? '✓' : '⊘';
+            const label = `${s.id}. ${icon} ${s.description}`;
+            return s.notes ? `${label}\n   ${s.notes}` : label;
+          })
           .join('\n');
+
+        const summary = [
+          `**Plan Complete!** ✓ — ${state.plan.title}`,
+          '',
+          `> ${stats}`,
+          '',
+          '## Summary',
+          '',
+          changeSummary,
+        ].join('\n');
+
         pi.sendMessage(
-          { customType: 'plan-complete', content: `**Plan Complete!** ✓\n\n${list}`, display: true },
+          { customType: 'plan-complete', content: summary, display: true },
           { triggerTurn: false },
         );
 
@@ -253,8 +287,8 @@ export default function planMode(pi: ExtensionAPI): void {
 
 - Missing edge cases or error handling
 - Incorrect assumptions about the codebase
-- Steps that are too vague or could be misinterpreted
-- Missing dependencies between steps
+- Tasks that are too vague or could be misinterpreted
+- Missing dependencies between tasks
 - Simpler alternatives that were overlooked
 
 After your review, call submit_plan again with the improved plan.`,
@@ -279,7 +313,10 @@ After your review, call submit_plan again with the improved plan.`,
     const pending = await readAndClearExecPending();
     if (pending) {
       state.planDir = pending.planDir;
-      state.plan = await loadPlanFromDisk(pending.planDir);
+      {
+        const snapshot = await readTasksJsonl(pending.planDir);
+        state.plan = snapshot ? { title: snapshot.meta.title, planName: snapshot.meta.plan_name, handoff: (await loadHandoff(pending.planDir)) ?? '', tasks: snapshot.tasks } : undefined;
+      }
       if (state.plan) {
         state.executing = true;
         state.planEnabled = false;

package/extensions/plan-mode/plan-storage.ts

@@ -1,67 +1 @@
-/**
- * Plan disk I/O — save/load plans, exec-pending markers, and manifest updates.
- */
-
-import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
-import { readPlansJson, serializePlansJson } from './plans-json.js';
-import type { PlanData, ExecPendingConfig } from './types.js';
-import { EXEC_PENDING_FILE } from './constants.js';
-
-export async function savePlanToDisk(planDir: string, plan: PlanData): Promise<void> {
-  await mkdir(planDir, { recursive: true });
-  await writeFile(`${planDir}/plan.json`, JSON.stringify(plan, null, 2) + '\n', 'utf-8');
-}
-
-export async function loadPlanFromDisk(dir: string): Promise<PlanData | undefined> {
-  try {
-    const text = await readFile(`${dir}/plan.json`, 'utf-8');
-    return JSON.parse(text) as PlanData;
-  } catch {
-    return undefined;
-  }
-}
-
-export async function writeExecPending(dir: string, config: ExecPendingConfig): Promise<void> {
-  await mkdir(dir, { recursive: true });
-  await writeFile(`${dir}/${EXEC_PENDING_FILE}`, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-}
-
-export async function readAndClearExecPending(): Promise<{ planDir: string; config: ExecPendingConfig } | undefined> {
-  try {
-    const entries = await readdir('.plans', { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const dir = `.plans/${entry.name}`;
-      const markerPath = `${dir}/${EXEC_PENDING_FILE}`;
-      try {
-        const text = await readFile(markerPath, 'utf-8');
-        const config = JSON.parse(text) as ExecPendingConfig;
-        await unlink(markerPath);
-        return { planDir: dir, config };
-      } catch {
-        // No marker in this directory
-      }
-    }
-  } catch {
-    // .plans/ doesn't exist
-  }
-  return undefined;
-}
-
-export async function updatePlansManifest(
-  planName: string,
-  status: 'in-progress' | 'done',
-  title?: string,
-): Promise<void> {
-  const manifest = await readPlansJson();
-  const existing = manifest[planName];
-  const now = new Date().toISOString();
-  manifest[planName] = {
-    status,
-    title: title ?? existing?.title ?? 'Untitled plan',
-    created: existing?.created ?? now,
-    completed: status === 'done' ? now : null,
-  };
-  await mkdir('.plans', { recursive: true });
-  await writeFile('.plans/plans.json', serializePlansJson(manifest), 'utf-8');
-}
+export { loadHandoff, readAndClearExecPending, saveHandoff, writeExecPending } from './storage/plan-storage.js';

package/extensions/plan-mode/prompts.ts

@@ -7,61 +7,62 @@ import { PLAN_TOOLS } from './constants.js';
 
 export function buildPlanModePrompt(): string {
   return `[PLAN MODE ACTIVE]
-You are in plan mode — a planning phase with strict bash restrictions.
+You are in conversational plan mode — a planning dialogue with strict bash restrictions.
 
 Restrictions:
 - Available tools: ${PLAN_TOOLS.join(', ')}
 - Bash is restricted to read-only commands (ls, grep, git status, etc.)
+- Do NOT make product code changes during planning.
 
-Your task:
-1. Analyze the codebase thoroughly using the available read-only tools
-2. Ask clarifying questions if needed (use the questionnaire tool)
-3. Produce a detailed, concrete plan
+Your job is to reach shared understanding before formalizing a plan:
+1. Understand the user's intent through dialogue. Push back on weak assumptions, name trade-offs, and ask clarifying questions when needed.
+2. Investigate the codebase with read-only tools. Use questionnaire when explicit choices are needed.
+3. Maintain .plans/<plan-name>/context.md with the write tool as the living planning context in caveman-lite style: professional, tight, no filler. Capture intent, decisions, constraints, open questions, and discarded options.
+4. Only call submit_plan after the user and agent have converged on the approach.
 
-When you are ready to finalize the plan, call the submit_plan tool with:
+When you are ready to finalize the plan, call submit_plan with:
 - name: a short kebab-case name (e.g. "add-auth-middleware")
 - title: a human-readable plan title
-- context: complete codebase context including relevant file paths, APIs, patterns, constraints, and gotchas — this must be thorough enough that an implementor with zero prior context can execute the plan
-- steps: an array of steps, each with a short description (≤60 chars for display) and detailed implementation instructions
-- risks: any open questions, assumptions, or concerns
+- handoff: a markdown document that explains what is changing, why it matters, approach, decisions, file paths, APIs, patterns, constraints, and gotchas
+- tasks: an array of tasks with id (e.g. "t-001"), description (≤60 chars), details, and optional depends_on task IDs
+- prototype: optional Pug markup for a creative prototype section in the generated plan.html
 
-Do NOT attempt to make product code changes — only analyze and plan.
-Do NOT write files manually — use submit_plan to finalize the plan.`;
+submit_plan is finalization, not the starting point. The generated plan.html is written but not opened automatically.
+
+When facing a significant technical decision with multiple viable approaches (architecture, API design, implementation strategy), use the technical-options skill: you generate the competing proposals yourself, then use the subagent tool to fan out voting agents for evaluation. Do not delegate the entire workflow to a subagent — you are the planner, you drive the process.`;
 }
 
 export function buildExecutionPrompt(plan: PlanData): string | undefined {
-  const remaining = plan.steps
-    .map((s, i) => ({ ...s, num: i + 1 }))
-    .filter((s) => s.status === 'pending');
+  const remaining = plan.tasks.filter((task) => task.status === 'pending');
 
   if (remaining.length === 0) return undefined;
 
-  const stepList = remaining
-    .map((s) => `${s.num}. ${s.description}\n   Details: ${s.details}`)
+  const taskList = remaining
+    .map((task) => `${task.id}. ${task.description}\n   Details: ${task.details}`)
     .join('\n\n');
 
-  const currentStep = remaining[0];
+  const currentTask = remaining[0];
 
   return `[EXECUTING PLAN — FOLLOW THE PLAN EXACTLY]
 
-You are executing a structured plan. Your ONLY job is to implement the plan steps below, one at a time.
+You are executing a structured plan. Your ONLY job is to implement the plan tasks below, one at a time.
 
 Rules:
-- Work on ONE step at a time, starting with step ${currentStep.num}
-- After completing each step, IMMEDIATELY call update_step to mark it done
-- Do NOT run diagnostics, linters, test suites, or skills unless a step explicitly asks for it
-- Do NOT explore the codebase beyond what the current step requires
-- Do NOT deviate from the plan — if something seems wrong, call update_step with status "blocked"
+- Work on ONE task at a time, starting with ${currentTask.id}
+- After completing each task, IMMEDIATELY call update_task to mark it done with notes summarizing what you changed (files modified, key decisions)
+- Do NOT run diagnostics, linters, test suites, or skills unless a task explicitly asks for it
+- Do NOT explore the codebase beyond what the current task requires
+- Do NOT deviate from the plan — if something seems wrong, call update_task with status "blocked"
 
-## Current step
-Step ${currentStep.num}: ${currentStep.description}
-Details: ${currentStep.details}
+## Current task
+${currentTask.id}: ${currentTask.description}
+Details: ${currentTask.details}
 
-## Codebase context
-${plan.context}
+## Handoff
+${plan.handoff}
 
-## All remaining steps
-${stepList}
+## All remaining tasks
+${taskList}
 
-Start with step ${currentStep.num} NOW. When done, call update_step(step=${currentStep.num}, status="done").`;
+Start with ${currentTask.id} NOW. When done, call update_task(task_id="${currentTask.id}", status="done", notes="<brief summary of what you did>").`;
 }

package/extensions/plan-mode/pug.d.ts

@@ -0,0 +1,5 @@
+declare module 'pug' {
+  export function render(template: string, options?: Record<string, unknown>): string;
+  const pug: { render: typeof render };
+  export default pug;
+}

package/extensions/plan-mode/resume.ts

@@ -6,13 +6,12 @@ import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@e
 import type { PlanModeState } from './state.js';
 import type { PlanData } from './types.js';
 import { EXEC_THINKING, EXEC_MODEL_OPTIONS } from './constants.js';
-import { readPlansJson } from './plans-json.js';
-import { loadPlanFromDisk, writeExecPending, savePlanToDisk } from './plan-storage.js';
+import { readPlansManifest } from './storage/plans-manifest.js';
+import { loadHandoff, writeExecPending } from './storage/plan-storage.js';
+import { readTasksJsonl, writeTasksJsonl } from './storage/task-storage.js';
 import { enterPlanMode } from './phase-transitions.js';
 
-export async function pickExecutionModel(
-  ctx: ExtensionContext,
-): Promise<{ provider: string; id: string } | undefined> {
+export async function pickExecutionModel(ctx: ExtensionContext): Promise<{ provider: string; id: string } | undefined> {
   const labels = EXEC_MODEL_OPTIONS.map((o) => o.label);
   const choice = await ctx.ui.select('Execute with:', labels);
   if (!choice) return undefined;
@@ -39,20 +38,16 @@ export async function executeInNewSession(
   });
 }
 
-export async function resumePlan(
-  state: PlanModeState,
-  pi: ExtensionAPI,
-  ctx: ExtensionCommandContext,
-): Promise<void> {
-  const manifest = await readPlansJson();
-  const inProgress = Object.entries(manifest).filter(([, e]) => e.status === 'in-progress');
+export async function resumePlan(state: PlanModeState, pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+  const manifest = await readPlansManifest();
+  const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
 
   if (inProgress.length === 0) {
-    ctx.ui.notify('No in-progress plans found in .plans/plans.json', 'info');
+    ctx.ui.notify('No in-progress plans found in .plans/plans.jsonl', 'info');
     return;
   }
 
-  const options = inProgress.map(([name, entry]) => `${name} — ${entry.title}`);
+  const options = inProgress.map((entry) => `${entry.name} — ${entry.title}`);
   options.push('Cancel');
 
   const choice = await ctx.ui.select('Resume which plan?', options);
@@ -60,32 +55,38 @@ export async function resumePlan(
 
   const planName = choice.split(' — ')[0];
   const dir = `.plans/${planName}`;
-  const loaded = await loadPlanFromDisk(dir);
+  const snapshot = await readTasksJsonl(dir);
 
-  if (!loaded) {
-    ctx.ui.notify(`Could not load ${dir}/plan.json`, 'error');
+  if (!snapshot) {
+    ctx.ui.notify(`Could not load ${dir}/tasks.jsonl`, 'error');
     return;
   }
 
   state.planDir = dir;
-  state.plan = loaded;
+  state.plan = {
+    title: snapshot.meta.title,
+    planName: snapshot.meta.plan_name,
+    handoff: (await loadHandoff(dir)) ?? '',
+    tasks: snapshot.tasks,
+  };
 
-  const doneCount = state.plan.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
-  const pendingCount = state.plan.steps.filter((s) => s.status === 'pending').length;
-  const blockedCount = state.plan.steps.filter((s) => s.status === 'blocked').length;
+  const doneCount = state.plan.tasks.filter((task) => task.status === 'done' || task.status === 'skipped').length;
+  const pendingCount = state.plan.tasks.filter((task) => task.status === 'pending').length;
+  const blockedCount = state.plan.tasks.filter((task) => task.status === 'blocked').length;
 
   if (pendingCount === 0 && blockedCount === 0) {
-    ctx.ui.notify(`Plan "${state.plan.title}" is already complete (${doneCount}/${state.plan.steps.length} done).`, 'info');
+    ctx.ui.notify(`Plan "${state.plan.title}" is already complete (${doneCount}/${state.plan.tasks.length} done).`, 'info');
     state.plan = undefined;
     state.planDir = undefined;
     return;
   }
 
-  const summary = `${doneCount}/${state.plan.steps.length} done, ${pendingCount} pending${blockedCount ? `, ${blockedCount} blocked` : ''}`;
-  const action = await ctx.ui.select(
-    `Resume "${state.plan.title}" (${summary}) — what next?`,
-    ['Continue execution', 'Re-plan from scratch', 'Cancel'],
-  );
+  const summary = `${doneCount}/${state.plan.tasks.length} done, ${pendingCount} pending${blockedCount ? `, ${blockedCount} blocked` : ''}`;
+  const action = await ctx.ui.select(`Resume "${state.plan.title}" (${summary}) — what next?`, [
+    'Continue execution',
+    'Re-plan from scratch',
+    'Cancel',
+  ]);
 
   if (!action || action === 'Cancel') {
     state.plan = undefined;
@@ -98,24 +99,24 @@ export async function resumePlan(
     const planDirPath = state.planDir;
     await enterPlanMode(state, pi, ctx);
     pi.sendUserMessage(
-      `There is an existing plan "${planTitle}" at ${planDirPath}/plan.json. Review it and create a revised plan using submit_plan. Keep the same plan name ("${planName}").`,
+      `There is an existing plan "${planTitle}" at ${planDirPath}/tasks.jsonl. Review it and create a revised plan using submit_plan. Keep the same plan name ("${planName}").`,
     );
     return;
   }
 
-  // Unblock any blocked steps
   if (blockedCount > 0) {
-    for (const step of state.plan.steps) {
-      if (step.status === 'blocked') step.status = 'pending';
+    for (const task of state.plan.tasks) {
+      if (task.status === 'blocked') {
+        task.status = 'pending';
+        task.updated_at = new Date().toISOString();
+      }
     }
-    await savePlanToDisk(dir, state.plan);
+    await writeTasksJsonl(dir, snapshot.meta, state.plan.tasks);
   }
 
-  const remaining = state.plan.steps
-    .map((s, i) => ({ ...s, num: i + 1 }))
-    .filter((s) => s.status === 'pending');
-  const stepList = remaining.map((s) => `${s.num}. ${s.description}`).join('\n');
-  const kickoff = `Resuming plan: "${state.plan.title}"\n\nCompleted: ${doneCount}/${state.plan.steps.length} steps\n\nRemaining steps:\n${stepList}\n\nContinue from step ${remaining[0].num}. Call update_step after completing each step.`;
+  const remaining = state.plan.tasks.filter((task) => task.status === 'pending');
+  const taskList = remaining.map((task) => `${task.id}. ${task.description}`).join('\n');
+  const kickoff = `Resuming plan: "${state.plan.title}"\n\nCompleted: ${doneCount}/${state.plan.tasks.length} tasks\n\nRemaining tasks:\n${taskList}\n\nContinue from ${remaining[0]?.id}. Call update_task after completing each task.`;
 
   await executeInNewSession(ctx, dir, state.plan, kickoff);
 }

package/extensions/plan-mode/storage/atomic-write.ts

@@ -0,0 +1,53 @@
+import { createWriteStream } from 'node:fs';
+import { open, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export interface AtomicWriteOptions {
+  /** Test seam: file mode for the temporary file. */
+  mode?: number;
+}
+
+export async function writeFileAtomic(path: string, data: string | Buffer, options: AtomicWriteOptions = {}): Promise<void> {
+  const dir = dirname(path);
+  const tempPath = join(dir, `.${process.pid}.${randomUUID()}.tmp`);
+  let completed = false;
+
+  try {
+    await writeAndSync(tempPath, data, options.mode);
+    await rename(tempPath, path);
+    completed = true;
+    await syncDirectory(dir);
+  } finally {
+    if (!completed) {
+      await rm(tempPath, { force: true }).catch(() => undefined);
+    }
+  }
+}
+
+async function writeAndSync(path: string, data: string | Buffer, mode?: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const stream = createWriteStream(path, { flags: 'wx', mode });
+    stream.once('error', reject);
+    stream.once('finish', resolve);
+    stream.end(data);
+  });
+
+  const handle = await open(path, 'r+');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function syncDirectory(dir: string): Promise<void> {
+  // Directory fsync is best-effort: supported on Unix, not always elsewhere.
+  const handle = await open(dir, 'r').catch(() => undefined);
+  if (!handle) return;
+  try {
+    await handle.sync().catch(() => undefined);
+  } finally {
+    await handle.close().catch(() => undefined);
+  }
+}

package/extensions/plan-mode/storage/plan-storage.ts

@@ -0,0 +1,47 @@
+/**
+ * Plan disk I/O — exec-pending markers and handoff documents.
+ */
+
+import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import type { ExecPendingConfig } from '../types.js';
+import { EXEC_PENDING_FILE } from '../constants.js';
+
+export async function writeExecPending(dir: string, config: ExecPendingConfig): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  await writeFile(`${dir}/${EXEC_PENDING_FILE}`, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+export async function readAndClearExecPending(): Promise<{ planDir: string; config: ExecPendingConfig } | undefined> {
+  try {
+    const entries = await readdir('.plans', { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dir = `.plans/${entry.name}`;
+      const markerPath = `${dir}/${EXEC_PENDING_FILE}`;
+      try {
+        const text = await readFile(markerPath, 'utf-8');
+        const config = JSON.parse(text) as ExecPendingConfig;
+        await unlink(markerPath);
+        return { planDir: dir, config };
+      } catch {
+        // No marker in this directory
+      }
+    }
+  } catch {
+    // .plans/ doesn't exist
+  }
+  return undefined;
+}
+
+export async function saveHandoff(planDir: string, content: string): Promise<void> {
+  await mkdir(planDir, { recursive: true });
+  await writeFile(`${planDir}/HANDOFF.md`, content, 'utf-8');
+}
+
+export async function loadHandoff(planDir: string): Promise<string | undefined> {
+  try {
+    return await readFile(`${planDir}/HANDOFF.md`, 'utf-8');
+  } catch {
+    return undefined;
+  }
+}