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

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

@@ -1,80 +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 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;
-  }
-}
-
-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,66 +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
-- handoff: a markdown document that explains:
-  1. **What** change is being made and **why** it matters
-  2. The approach and key design decisions
-  3. Relevant codebase context: file paths, APIs, patterns, constraints, and gotchas
-  This document is saved as HANDOFF.md and must be clear to both human reviewers and executor agents.
-- steps: an array of steps, each with a short description (≤60 chars for display) and detailed implementation instructions
+- 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 with notes summarizing what you changed (files modified, key decisions)
-- 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}
 
 ## 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", notes="<brief summary of what you did>").`;
+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;
+  }
+}

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

@@ -0,0 +1,57 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { writeFileAtomic } from './atomic-write.js';
+
+const MANIFEST_PATH = '.plans/plans.jsonl';
+
+export interface PlanManifestEntry {
+  _type: 'plan';
+  name: string;
+  status: 'in-progress' | 'done';
+  title: string;
+  created_at: string;
+  completed_at: string | null;
+}
+
+export async function readPlansManifest(): Promise<PlanManifestEntry[]> {
+  let text: string;
+  try { text = await readFile(MANIFEST_PATH, 'utf8'); } catch { return []; }
+  const entries: PlanManifestEntry[] = [];
+  for (const [index, raw] of text.split(/\r?\n/).entries()) {
+    if (!raw.trim()) continue;
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch (error) { throw new Error(`Invalid plans.jsonl at line ${index + 1}: ${(error as Error).message}`); }
+    if (!isPlanManifestEntry(parsed)) throw new Error(`Invalid plans.jsonl record at line ${index + 1}`);
+    entries.push(parsed);
+  }
+  return entries;
+}
+
+export async function writePlansManifest(entries: PlanManifestEntry[]): Promise<void> {
+  await mkdir('.plans', { recursive: true });
+  const content = entries.map((entry) => JSON.stringify(entry)).join('\n') + (entries.length ? '\n' : '');
+  await writeFileAtomic(MANIFEST_PATH, content);
+}
+
+export async function upsertPlanEntry(name: string, updates: { status: 'in-progress' | 'done'; title?: string }): Promise<void> {
+  const entries = await readPlansManifest();
+  const now = new Date().toISOString();
+  const index = entries.findIndex((entry) => entry.name === name);
+  const existing = index === -1 ? undefined : entries[index];
+  const entry: PlanManifestEntry = {
+    _type: 'plan',
+    name,
+    status: updates.status,
+    title: updates.title ?? existing?.title ?? 'Untitled plan',
+    created_at: existing?.created_at ?? now,
+    completed_at: updates.status === 'done' ? now : null,
+  };
+  if (index === -1) entries.push(entry);
+  else entries[index] = entry;
+  await writePlansManifest(entries);
+}
+
+function isPlanManifestEntry(value: unknown): value is PlanManifestEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return record._type === 'plan' && typeof record.name === 'string' && (record.status === 'in-progress' || record.status === 'done') && typeof record.title === 'string' && typeof record.created_at === 'string' && (record.completed_at === null || typeof record.completed_at === 'string');
+}

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

@@ -0,0 +1,44 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isTaskMeta, isTaskRecord, type TaskMeta, type TaskRecord } from '../types.js';
+import { writeFileAtomic } from './atomic-write.js';
+
+const TASKS_FILE = 'tasks.jsonl';
+
+export interface TasksSnapshot { meta: TaskMeta; tasks: TaskRecord[] }
+
+export async function readTasksJsonl(planDir: string): Promise<TasksSnapshot | undefined> {
+  let text: string;
+  try { text = await readFile(join(planDir, TASKS_FILE), 'utf8'); } catch { return undefined; }
+  if (!text.trim()) throw new Error('tasks.jsonl is missing meta record');
+
+  let meta: TaskMeta | undefined;
+  const tasks: TaskRecord[] = [];
+  for (const [index, raw] of text.split(/\r?\n/).entries()) {
+    if (!raw.trim()) continue;
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch (error) { throw new Error(`Invalid JSONL at line ${index + 1}: ${(error as Error).message}`); }
+    if (isTaskMeta(parsed)) meta = parsed;
+    else if (isTaskRecord(parsed)) tasks.push(parsed);
+    else throw new Error(`Invalid tasks.jsonl record at line ${index + 1}`);
+  }
+  if (!meta) throw new Error('tasks.jsonl is missing meta record');
+  return { meta, tasks };
+}
+
+export async function writeTasksJsonl(planDir: string, meta: TaskMeta, tasks: TaskRecord[]): Promise<void> {
+  await mkdir(planDir, { recursive: true });
+  const content = [meta, ...tasks].map((record) => JSON.stringify(record)).join('\n') + '\n';
+  await writeFileAtomic(join(planDir, TASKS_FILE), content);
+}
+
+export async function updateTask(planDir: string, taskId: string, updates: Partial<Omit<TaskRecord, '_type' | 'id' | 'created_at'>>): Promise<TaskRecord> {
+  const snapshot = await readTasksJsonl(planDir);
+  if (!snapshot) throw new Error(`No tasks.jsonl found in ${planDir}`);
+  const index = snapshot.tasks.findIndex((task) => task.id === taskId);
+  if (index === -1) throw new Error(`Task not found: ${taskId}`);
+  const updated: TaskRecord = { ...snapshot.tasks[index], ...updates, updated_at: new Date().toISOString() };
+  snapshot.tasks[index] = updated;
+  await writeTasksJsonl(planDir, snapshot.meta, snapshot.tasks);
+  return updated;
+}