@dreki-gg/pi-plan-mode 0.15.0 → 0.16.0

package/extensions/plan-mode/index.ts

@@ -18,7 +18,14 @@
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Key } from '@earendil-works/pi-tui';
-import { PLAN_TOOLS, EXEC_TOOLS, PLAN_MODEL, PLAN_THINKING, EXEC_MODEL, EXEC_THINKING } from './constants.js';
+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 { loadHandoff, readAndClearExecPending } from './storage/plan-storage.js';
@@ -30,6 +37,7 @@ import { filterExecutionMessages, filterStalePlanMessages } from './context-filt
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
+import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
 
@@ -52,6 +60,8 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerPreviewPrototypeTool(pi);
+
   registerUpdateTaskTool(pi, {
     getPlan: () => state.plan,
     onTaskUpdated: async (taskId, status, notes) => {
@@ -63,7 +73,12 @@ export default function planMode(pi: ExtensionAPI): void {
       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 },
+        {
+          _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);
@@ -72,7 +87,8 @@ export default function planMode(pi: ExtensionAPI): void {
 
   // ── Commands ──────────────────────────────────────────────────────────────
   pi.registerCommand('plan', {
-    description: 'Enter plan mode, optionally with a starting prompt. Use "/plan resume" to pick up an existing plan.',
+    description:
+      'Enter plan mode, optionally with a starting prompt. Use "/plan resume" to pick up an existing plan.',
     handler: async (args, ctx) => {
       const trimmed = args?.trim();
       if (trimmed === 'resume') {
@@ -96,7 +112,8 @@ export default function planMode(pi: ExtensionAPI): void {
         return;
       }
       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 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);
     },
@@ -168,7 +185,11 @@ export default function planMode(pi: ExtensionAPI): void {
   pi.on('before_agent_start', async () => {
     if (state.planEnabled) {
       return {
-        message: { customType: 'plan-mode-context', content: buildPlanModePrompt(), display: false },
+        message: {
+          customType: 'plan-mode-context',
+          content: buildPlanModePrompt(),
+          display: false,
+        },
       };
     }
     if (state.executing && state.plan) {
@@ -194,17 +215,31 @@ export default function planMode(pi: ExtensionAPI): void {
           : `Task ${bs.id}: ${bs.description}`;
 
         const choice = await ctx.ui.select(`Task blocked — ${info}\n\nWhat next?`, [
-          'Skip this task', 'Provide instructions', 'Re-plan', 'Abort execution',
+          'Skip this task',
+          'Provide instructions',
+          'Re-plan',
+          'Abort execution',
         ]);
 
         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);
+          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.tasks.some((s) => s.status === 'pending')) {
-            pi.sendUserMessage('The blocked task has been skipped. Continue with the next task.', { deliverAs: 'followUp' });
+            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 task:', '');
@@ -212,7 +247,16 @@ export default function planMode(pi: ExtensionAPI): void {
             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);
+            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(
@@ -235,18 +279,28 @@ export default function planMode(pi: ExtensionAPI): void {
       }
 
       // Check completion
-      const allResolved = state.plan.tasks.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 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);
+          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 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`;
+        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
@@ -284,8 +338,8 @@ export default function planMode(pi: ExtensionAPI): void {
       return;
     }
 
-    // Plan submitted — user can review plan.html then /plan-exec or type naturally.
-    // No menu needed: plan.jsonl + plan.html are the source of truth.
+    // Plan submitted — user can /plan-exec or type naturally.
+    // No menu needed: plan.jsonl + HANDOFF.md are the source of truth.
   });
 
   // ── Event: session restore ────────────────────────────────────────────────
@@ -302,7 +356,14 @@ export default function planMode(pi: ExtensionAPI): void {
       state.planDir = 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;
+        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;

package/extensions/plan-mode/phase-transitions.ts

@@ -5,7 +5,14 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import type { PlanModeState } from './state.js';
 import type { ThinkingLevel } from './types.js';
-import { PLAN_TOOLS, EXEC_TOOLS, PLAN_MODEL, PLAN_THINKING, EXEC_MODEL, EXEC_THINKING } from './constants.js';
+import {
+  PLAN_TOOLS,
+  EXEC_TOOLS,
+  PLAN_MODEL,
+  PLAN_THINKING,
+  EXEC_MODEL,
+  EXEC_THINKING,
+} from './constants.js';
 import { updateUI } from './ui.js';
 
 export async function switchModel(
@@ -40,10 +47,7 @@ export async function enterPlanMode(
   pi.setActiveTools(PLAN_TOOLS);
   await switchModel(pi, ctx, PLAN_MODEL);
   pi.setThinkingLevel(PLAN_THINKING);
-  ctx.ui.notify(
-    `Plan mode ON — ${PLAN_MODEL.provider}/${PLAN_MODEL.id}:${PLAN_THINKING}`,
-    'info',
-  );
+  ctx.ui.notify(`Plan mode ON — ${PLAN_MODEL.provider}/${PLAN_MODEL.id}:${PLAN_THINKING}`, 'info');
   updateUI(state, ctx);
   state.persist(pi);
 }

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

@@ -1 +1,6 @@
-export { loadHandoff, readAndClearExecPending, saveHandoff, writeExecPending } from './storage/plan-storage.js';
+export {
+  loadHandoff,
+  readAndClearExecPending,
+  saveHandoff,
+  writeExecPending,
+} from './storage/plan-storage.js';

package/extensions/plan-mode/prompts.ts

@@ -18,7 +18,7 @@ Restrictions:
 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.
+3. Maintain a living .plans/<plan-name>/context.md as you converge — the planning-context skill covers what to capture and how.
 4. Only call submit_plan after the user and agent have converged on the approach.
 
 When you are ready to finalize the plan, call submit_plan with:
@@ -26,13 +26,14 @@ When you are ready to finalize the plan, call submit_plan with:
 - title: a human-readable plan title
 - 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), optional details, and optional depends_on task IDs
-- prototype: optional Pug markup for a creative prototype section in the generated plan.html
 
 Plan weight:
 - **Delegation plans** (different agent/human executes): include full details in each task so an executor with zero context can follow them.
 - **Self-execution plans** (you plan and execute in the same session): use lightweight checklist-style tasks — just id + description, skip details. The handoff doc carries the real context.
 
-submit_plan is finalization, not the starting point. The generated plan.html is written but not opened automatically.
+submit_plan is finalization, not the starting point. It records tasks and the handoff — it does not generate HTML.
+
+For visual/UI/layout/style work, build a prototype with preview_prototype DURING planning, before submit_plan, so the user can react to the visual before the plan hardens. The visual-prototype skill covers when and how.
 
 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.`;
 }
@@ -50,9 +51,7 @@ export function buildExecutionPrompt(plan: PlanData): string | undefined {
     .join('\n\n');
 
   const currentTask = remaining[0];
-  const currentDetails = currentTask.details
-    ? `\nDetails: ${currentTask.details}`
-    : '';
+  const currentDetails = currentTask.details ? `\nDetails: ${currentTask.details}` : '';
 
   return `[EXECUTING PLAN — FOLLOW THE PLAN EXACTLY]
 

package/extensions/plan-mode/resume.ts

@@ -2,7 +2,11 @@
  * Resume and execution handoff — pick up in-progress plans, model picker, new session handoff.
  */
 
-import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionCommandContext,
+} from '@earendil-works/pi-coding-agent';
 import type { PlanModeState } from './state.js';
 import type { PlanData } from './types.js';
 import { EXEC_THINKING, EXEC_MODEL_OPTIONS } from './constants.js';
@@ -11,7 +15,9 @@ 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;
@@ -38,7 +44,11 @@ export async function executeInNewSession(
   });
 }
 
-export async function resumePlan(state: PlanModeState, pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+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');
 
@@ -70,12 +80,17 @@ export async function resumePlan(state: PlanModeState, pi: ExtensionAPI, ctx: Ex
     tasks: snapshot.tasks,
   };
 
-  const doneCount = state.plan.tasks.filter((task) => task.status === 'done' || task.status === 'skipped').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.tasks.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;

package/extensions/plan-mode/state.ts

@@ -25,9 +25,7 @@ export class PlanModeState {
   }
 
   restore(entries: Array<{ type: string; customType?: string; data?: PersistedState }>): void {
-    const saved = entries
-      .filter((e) => e.type === 'custom' && e.customType === 'plan-mode')
-      .pop();
+    const saved = entries.filter((e) => e.type === 'custom' && e.customType === 'plan-mode').pop();
     if (saved?.data) {
       this.planEnabled = saved.data.planEnabled ?? this.planEnabled;
       this.executing = saved.data.executing ?? this.executing;

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

@@ -8,7 +8,11 @@ export interface AtomicWriteOptions {
   mode?: number;
 }
 
-export async function writeFileAtomic(path: string, data: string | Buffer, options: AtomicWriteOptions = {}): Promise<void> {
+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;

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

@@ -11,7 +11,9 @@ export async function writeExecPending(dir: string, config: ExecPendingConfig):
   await writeFile(`${dir}/${EXEC_PENDING_FILE}`, JSON.stringify(config, null, 2) + '\n', 'utf-8');
 }
 
-export async function readAndClearExecPending(): Promise<{ planDir: string; config: ExecPendingConfig } | undefined> {
+export async function readAndClearExecPending(): Promise<
+  { planDir: string; config: ExecPendingConfig } | undefined
+> {
   try {
     const entries = await readdir('.plans', { withFileTypes: true });
     for (const entry of entries) {

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

@@ -14,13 +14,22 @@ export interface PlanManifestEntry {
 
 export async function readPlansManifest(): Promise<PlanManifestEntry[]> {
   let text: string;
-  try { text = await readFile(MANIFEST_PATH, 'utf8'); } catch { return []; }
+  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}`);
+    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;
@@ -28,11 +37,15 @@ export async function readPlansManifest(): Promise<PlanManifestEntry[]> {
 
 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' : '');
+  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> {
+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);
@@ -53,5 +66,12 @@ export async function upsertPlanEntry(name: string, updates: { status: 'in-progr
 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');
+  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

@@ -5,11 +5,18 @@ import { writeFileAtomic } from './atomic-write.js';
 
 const TASKS_FILE = 'tasks.jsonl';
 
-export interface TasksSnapshot { meta: TaskMeta; tasks: TaskRecord[] }
+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; }
+  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;
@@ -17,7 +24,11 @@ export async function readTasksJsonl(planDir: string): Promise<TasksSnapshot | u
   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}`); }
+    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}`);
@@ -26,18 +37,30 @@ export async function readTasksJsonl(planDir: string): Promise<TasksSnapshot | u
   return { meta, tasks };
 }
 
-export async function writeTasksJsonl(planDir: string, meta: TaskMeta, tasks: TaskRecord[]): Promise<void> {
+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> {
+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() };
+  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;

package/extensions/plan-mode/tools/preview-prototype.ts

@@ -0,0 +1,91 @@
+/**
+ * preview_prototype tool — available during the plan phase.
+ *
+ * Renders a Pug prototype to a standalone HTML visual aid, writes it under
+ * .plans/_prototypes/, and best-effort opens it so the user can react to the
+ * visual BEFORE the plan is finalized.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { renderPrototypeHtml } from '../html/render.js';
+import { toKebabCase } from '../utils.js';
+
+const PREVIEW_DIR = '.plans/_prototypes';
+
+/** Best-effort open of a file in the OS default app. Never throws. */
+function openInBrowser(filePath: string): void {
+  const command =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    const child = spawn(command, [filePath], {
+      detached: true,
+      stdio: 'ignore',
+      shell: process.platform === 'win32',
+    });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    // Opening is a convenience — ignore failures (headless, sandbox, etc.).
+  }
+}
+
+export function registerPreviewPrototypeTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: 'preview_prototype',
+    label: 'Preview Prototype',
+    description:
+      'Render a Pug prototype to a standalone HTML visual aid and open it for review during planning.',
+    promptSnippet: 'Render a Pug UI prototype to HTML and open it for the user to review',
+    promptGuidelines: [
+      'Use preview_prototype during planning for visual/UI/layout/style work, before submit_plan.',
+      'The prototype is a convergence aid — show it so the user can react before the plan hardens.',
+      'Keep the Pug self-contained; inline any styles the prototype needs.',
+    ],
+    parameters: Type.Object({
+      title: Type.String({ description: 'Short title for the prototype' }),
+      intent: Type.String({
+        description: 'One-line description of what this prototype is showing',
+      }),
+      pug: Type.String({ description: 'Pug markup for the prototype body' }),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const slug = toKebabCase(params.title) || 'prototype';
+      const filePath = join(PREVIEW_DIR, `${slug}.html`);
+      const html = renderPrototypeHtml(params.title, params.intent, params.pug);
+
+      await mkdir(PREVIEW_DIR, { recursive: true });
+      await writeFile(filePath, html, 'utf-8');
+      openInBrowser(filePath);
+      ctx?.ui?.notify(`Prototype written to ${filePath} — opening for review.`, 'info');
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Prototype "${params.title}" rendered to ${filePath} and opened. Ask the user for feedback before submitting the plan.`,
+          },
+        ],
+        details: { filePath, title: params.title },
+      };
+    },
+
+    renderCall(args, theme) {
+      const title = (args as { title?: string }).title ?? 'prototype';
+      let content = theme.fg('toolTitle', theme.bold('preview_prototype '));
+      content += theme.fg('accent', title);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const filePath = (result.details as { filePath?: string } | undefined)?.filePath;
+      const label = filePath ? `✓ Prototype → ${filePath}` : '✓ Prototype rendered';
+      return new Text(theme.fg('success', label), 0, 0);
+    },
+  });
+}