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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.16.0
+
+### Minor Changes
+
+- 5c70b28: Reframe plan-mode HTML as a planning-phase visual aid instead of a finalization receipt.
+
+  - `submit_plan` no longer generates `plan.html`. It writes only `tasks.jsonl`, `HANDOFF.md`, and the manifest entry. The previous HTML duplicated the handoff and task list (already tracked elsewhere) and was never opened.
+  - Added a `preview_prototype` tool, available during planning. It renders self-contained Pug to a standalone HTML visual aid under `.plans/_prototypes/`, opens it, and notifies the path — so the user can react to a UI/component/style design _before_ the plan hardens.
+  - Added a bundled `visual-prototype` skill that routes UI/component/layout/style planning work to `preview_prototype` before `submit_plan`.
+  - Added a bundled `planning-context` skill that drives the living `context.md` deliberation discipline (intent, decisions, constraints, open questions, discarded options).
+
 ## 0.15.1
 
 ### Patch Changes

package/extensions/plan-mode/__tests__/html-render.test.ts

@@ -1,43 +1,34 @@
 import { describe, expect, test } from 'bun:test';
-import { renderPlanHtml } from '../html/render.js';
-import type { PlanData } from '../types.js';
-
-const plan: PlanData = {
-  title: 'Refactor Auth',
-  planName: 'refactor-auth',
-  handoff: '# Handoff\nShip carefully.',
-  tasks: [
-    {
-      _type: 'task',
-      id: 't-001',
-      description: 'Add auth middleware',
-      details: 'Implement the middleware.',
-      status: 'pending',
-      created_at: '2026-05-27T12:00:00.000Z',
-      updated_at: '2026-05-27T12:00:00.000Z',
-    },
-  ],
-};
-
-describe('renderPlanHtml', () => {
-  test('renders title, task count, handoff, and tasks', () => {
-    const html = renderPlanHtml(plan);
-
-    expect(html).toContain('Refactor Auth');
-    expect(html).toContain('1 task');
-    expect(html).toContain('Ship carefully.');
-    expect(html).toContain('t-001');
-    expect(html).toContain('Add auth middleware');
+import { renderPrototypeHtml } from '../html/render.js';
+
+describe('renderPrototypeHtml', () => {
+  test('renders title and intent in a minimal header', () => {
+    const html = renderPrototypeHtml('Sidebar redesign', 'Left-aligned nav with icons', '.nav Nav');
+
+    expect(html).toContain('Sidebar redesign');
+    expect(html).toContain('Left-aligned nav with icons');
+    expect(html).toContain('Prototype');
+  });
+
+  test('renders the Pug body markup', () => {
+    const html = renderPrototypeHtml('Card', 'A product card', '.card Product card');
+
+    expect(html).toContain('class="card"');
+    expect(html).toContain('Product card');
   });
 
-  test('omits prototypes section when no prototype is provided', () => {
-    expect(renderPlanHtml(plan)).not.toContain('Prototype');
+  test('does not render tasks or handoff sections', () => {
+    const html = renderPrototypeHtml('Card', 'A product card', '.card Hello');
+
+    expect(html).not.toContain('Handoff');
+    expect(html).not.toContain('Tasks');
+    expect(html).not.toContain('Depends on');
   });
 
-  test('renders optional prototype pug markup', () => {
-    const html = renderPlanHtml(plan, '.mockup Prototype card');
+  test('handles an empty prototype body without throwing', () => {
+    const html = renderPrototypeHtml('Empty', 'Nothing yet', '');
 
-    expect(html).toContain('Prototype');
-    expect(html).toContain('Prototype card');
+    expect(html).toContain('Empty');
+    expect(html).toContain('Nothing yet');
   });
 });

package/extensions/plan-mode/__tests__/package-skills.test.ts

@@ -45,3 +45,54 @@ describe('bundled technical-options skill', () => {
     expect(content).toMatch(/challenge.*framing|framing.*challenge/i);
   });
 });
+
+describe('bundled visual-prototype skill', () => {
+  const skillDir = join(PKG_ROOT, 'skills', 'visual-prototype');
+  const skillFile = join(skillDir, 'SKILL.md');
+
+  test('SKILL.md exists', () => {
+    expect(existsSync(skillFile)).toBe(true);
+  });
+
+  test('has valid frontmatter with name and description', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/^---\n/);
+    expect(content).toMatch(/name:\s*visual-prototype/);
+    expect(content).toMatch(/description:/);
+  });
+
+  test('routes on visual work, not backend-only', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/description:.*\b(UI|component|layout|style)\b/i);
+    expect(content).toMatch(/not for.*backend|backend-only/i);
+  });
+
+  test('directs use of preview_prototype before submit_plan', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toContain('preview_prototype');
+    expect(content).toContain('submit_plan');
+  });
+});
+
+describe('bundled planning-context skill', () => {
+  const skillDir = join(PKG_ROOT, 'skills', 'planning-context');
+  const skillFile = join(skillDir, 'SKILL.md');
+
+  test('SKILL.md exists', () => {
+    expect(existsSync(skillFile)).toBe(true);
+  });
+
+  test('has valid frontmatter with name and description', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/^---\n/);
+    expect(content).toMatch(/name:\s*planning-context/);
+    expect(content).toMatch(/description:/);
+  });
+
+  test('covers context.md deliberation sections', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toContain('context.md');
+    expect(content).toMatch(/discarded options/i);
+    expect(content).toMatch(/open questions/i);
+  });
+});

package/extensions/plan-mode/constants.ts

@@ -10,6 +10,7 @@ export const PLAN_TOOLS = [
   'find',
   'ls',
   'submit_plan',
+  'preview_prototype',
   'write',
   'questionnaire',
   'search_skills',

package/extensions/plan-mode/html/render.ts

@@ -2,127 +2,23 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import pug from 'pug';
-import type { PlanData } from '../types.js';
 
-const templatePath = join(dirname(fileURLToPath(import.meta.url)), 'templates', 'plan.pug');
+const templatePath = join(dirname(fileURLToPath(import.meta.url)), 'templates', 'prototype.pug');
 
-export function renderPlanHtml(plan: PlanData, prototype?: string): string {
+/**
+ * Renders a standalone prototype preview: a minimal header (title + one-line
+ * intent) wrapping the rendered Pug body. This is a planning-phase visual aid,
+ * not a plan dump — no tasks, no handoff.
+ */
+export function renderPrototypeHtml(title: string, intent: string, pugBody: string): string {
   const template = readFileSync(templatePath, 'utf8');
-  const prototypeHtml = prototype?.trim() ? pug.render(prototype) : undefined;
+  const prototypeHtml = pugBody.trim() ? pug.render(pugBody) : '';
 
   return pug.render(template, {
     filename: templatePath,
-    plan,
+    title,
+    intent,
     prototypeHtml,
-    handoffHtml: markdownToHtml(plan.handoff),
-    taskCountLabel: `${plan.tasks.length} ${plan.tasks.length === 1 ? 'task' : 'tasks'}`,
     generatedAt: new Date().toISOString(),
   });
 }
-
-function markdownToHtml(markdown: string): string {
-  const lines = markdown.split(/\r?\n/);
-  const html: string[] = [];
-  let inList = false;
-  let inCode = false;
-  let codeLang = '';
-  const codeLines: string[] = [];
-
-  for (const line of lines) {
-    // Fenced code blocks
-    if (line.startsWith('```')) {
-      if (!inCode) {
-        if (inList) {
-          html.push('</ul>');
-          inList = false;
-        }
-        inCode = true;
-        codeLang = line.slice(3).trim();
-        codeLines.length = 0;
-      } else {
-        const langAttr = codeLang ? ` class="language-${escapeHtml(codeLang)}"` : '';
-        html.push(`<pre><code${langAttr}>${codeLines.map(escapeHtml).join('\n')}</code></pre>`);
-        inCode = false;
-        codeLang = '';
-      }
-      continue;
-    }
-
-    if (inCode) {
-      codeLines.push(line);
-      continue;
-    }
-
-    // Headings
-    const headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
-    if (headingMatch) {
-      if (inList) {
-        html.push('</ul>');
-        inList = false;
-      }
-      const level = headingMatch[1].length;
-      html.push(`<h${level}>${inlineMarkdown(escapeHtml(headingMatch[2]))}</h${level}>`);
-      continue;
-    }
-
-    // List items (- or *)
-    const listMatch = line.match(/^\s*[-*]\s+(.*)$/);
-    if (listMatch) {
-      if (!inList) {
-        html.push('<ul>');
-        inList = true;
-      }
-      html.push(`<li>${inlineMarkdown(escapeHtml(listMatch[1]))}</li>`);
-      continue;
-    }
-
-    // Blank line
-    if (!line.trim()) {
-      if (inList) {
-        html.push('</ul>');
-        inList = false;
-      }
-      continue;
-    }
-
-    // Paragraph
-    if (inList) {
-      html.push('</ul>');
-      inList = false;
-    }
-    html.push(`<p>${inlineMarkdown(escapeHtml(line))}</p>`);
-  }
-
-  // Close unclosed blocks
-  if (inCode) {
-    html.push(`<pre><code>${codeLines.map(escapeHtml).join('\n')}</code></pre>`);
-  }
-  if (inList) html.push('</ul>');
-  return html.join('\n');
-}
-
-/** Converts inline markdown (bold, italic, inline code, links) in already-escaped HTML. */
-function inlineMarkdown(text: string): string {
-  return (
-    text
-      // Inline code: `code`
-      .replace(/`([^`]+)`/g, '<code>$1</code>')
-      // Bold: **text** or __text__
-      .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
-      .replace(/__(.+?)__/g, '<strong>$1</strong>')
-      // Italic: *text* or _text_
-      .replace(/\*(.+?)\*/g, '<em>$1</em>')
-      .replace(/_(.+?)_/g, '<em>$1</em>')
-      // Links: [text](url)
-      .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>')
-  );
-}
-
-function escapeHtml(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
-}

package/extensions/plan-mode/html/templates/prototype.pug

@@ -0,0 +1,25 @@
+doctype html
+html(lang="en")
+  head
+    meta(charset="utf-8")
+    meta(name="viewport" content="width=device-width, initial-scale=1")
+    title= title
+    style.
+      :root { color-scheme: dark; --bg:#0b0d12; --panel:#11141b; --muted:#8b93a7; --text:#eef1f7; --line:#242936; --accent:#8b5cf6; }
+      * { box-sizing: border-box; }
+      body { margin:0; background:radial-gradient(circle at top left,#1c1730,transparent 34rem),var(--bg); color:var(--text); font:14px/1.5 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      main { width:min(1040px, calc(100% - 48px)); margin:48px auto; }
+      header { margin-bottom:24px; }
+      h1 { font-size:30px; line-height:1.1; margin:0 0 8px; letter-spacing:-0.04em; }
+      .intent { color:var(--muted); margin:0; }
+      .badge { display:inline-block; border:1px solid var(--line); border-radius:999px; padding:5px 10px; background:rgba(255,255,255,0.03); color:var(--muted); font-size:12px; margin-bottom:14px; }
+      .prototype { background:rgba(17,20,27,0.82); border:1px solid var(--line); border-radius:18px; padding:22px; box-shadow:0 24px 80px rgba(0,0,0,0.24); }
+  body
+    main
+      header
+        span.badge Prototype · #{generatedAt}
+        h1= title
+        if intent
+          p.intent= intent
+      section.prototype
+        != prototypeHtml

package/extensions/plan-mode/index.ts

@@ -37,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';
 
@@ -59,6 +60,8 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerPreviewPrototypeTool(pi);
+
   registerUpdateTaskTool(pi, {
     getPlan: () => state.plan,
     onTaskUpdated: async (taskId, status, notes) => {
@@ -335,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 ────────────────────────────────────────────────

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.`;
 }

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);
+    },
+  });
+}

package/extensions/plan-mode/tools/submit-plan.ts

@@ -5,8 +5,7 @@
 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 { renderPlanHtml } from '../html/render.js';
+import { mkdir } from 'node:fs/promises';
 import { saveHandoff } from '../storage/plan-storage.js';
 import { writeTasksJsonl } from '../storage/task-storage.js';
 import { upsertPlanEntry } from '../storage/plans-manifest.js';
@@ -22,15 +21,16 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
     name: 'submit_plan',
     label: 'Submit Plan',
     description:
-      'Finalize a conversational plan with task IDs, JSONL storage, HANDOFF.md, and generated plan.html.',
+      'Finalize a conversational plan with task IDs, JSONL storage, and HANDOFF.md.',
     promptSnippet:
-      'Finalize the plan with title, handoff, tasks, dependencies, and optional prototype Pug',
+      'Finalize the plan with title, handoff, tasks, and dependencies',
     promptGuidelines: [
       'Only call submit_plan after shared understanding has been reached with the user.',
       'Each task needs an id like t-001, a short description, and optional depends_on task IDs.',
       "When a different agent or human will execute the plan, include detailed implementation instructions in each task's details field.",
       'When you are planning and executing yourself (same session), use lightweight checklist-style tasks: just id + description, omit details. Put the real context in the handoff document instead.',
       'The handoff must be thorough enough that both a human reviewer and executor agent with zero prior context can understand the plan.',
+      'For visual/UI work, preview a prototype with preview_prototype during planning — before submit_plan, not as part of it.',
     ],
     parameters: Type.Object({
       name: Type.String({
@@ -54,9 +54,6 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
         }),
         { minItems: 1 },
       ),
-      prototype: Type.Optional(
-        Type.String({ description: 'Optional Pug markup for the prototype section in plan.html' }),
-      ),
     }),
 
     async execute(_toolCallId, params) {
@@ -84,7 +81,6 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
       await mkdir(planDir, { recursive: true });
       await writeTasksJsonl(planDir, meta, tasks);
       await saveHandoff(planDir, params.handoff);
-      await writeFile(`${planDir}/plan.html`, renderPlanHtml(plan, params.prototype), 'utf-8');
       await upsertPlanEntry(planName, { status: 'in-progress', title: params.title });
 
       callbacks.onPlanSubmitted(planDir, plan);
@@ -93,7 +89,7 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
         content: [
           {
             type: 'text' as const,
-            text: `Plan "${params.title}" saved with ${tasks.length} tasks. Review ${planDir}/plan.html, then execute when ready.`,
+            text: `Plan "${params.title}" saved with ${tasks.length} tasks in ${planDir}. Execute when ready.`,
           },
         ],
         details: { planDir, plan },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Two-phase planning workflow for pi — plan with claude-opus-4-6:medium, execute with gpt-5.5:low, with .plans/ file-based handoff",
   "keywords": [
     "pi-package"

package/skills/planning-context/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: planning-context
+description: Maintain a living context.md during planning to capture intent, decisions, constraints, open questions, and discarded options before finalizing a plan. Use whenever you are in plan mode and converging on an approach, especially before calling submit_plan.
+---
+
+# Planning Context
+
+`context.md` is the living written record of a planning conversation. It exists to slow the jump from "read the codebase" to "submit the plan" — the moment where reasoning usually gets lost. Write it as you think, not as an afterthought.
+
+## When to use
+
+Use this throughout any planning session, from the first real decision onward. If you have read code and formed an opinion but have not written anything down, that is the signal to update `context.md`.
+
+## What it is
+
+`.plans/<plan-name>/context.md` — a deliberation document, not a plan. It captures the *why* and the *roads not taken*, which `HANDOFF.md` and the task list deliberately omit.
+
+## Process
+
+### 1. Create it early
+
+As soon as you understand the intent, write `.plans/<plan-name>/context.md` with the `write` tool. Do not wait until you are ready to submit.
+
+### 2. Keep these sections current
+
+- **Intent** — what the user actually wants, in their terms
+- **Decisions** — choices made and the reasoning behind each
+- **Constraints** — technical, product, or process limits that shape the work
+- **Open questions** — anything unresolved; do not submit a plan with silent unknowns
+- **Discarded options** — approaches considered and rejected, with why. This is the highest-value section and the one most often skipped.
+
+### 3. Style
+
+Caveman-lite: professional, tight, no filler. Bullet points over prose. Update in place as understanding shifts — do not append a changelog.
+
+### 4. Use it before submitting
+
+`context.md` is the input to `submit_plan`, not a duplicate of it. Before finalizing, re-read it: every open question resolved, every decision justified. The handoff is the distilled conclusion; `context.md` is the reasoning that earned it.
+
+## Relationship to prototypes
+
+For visual/UI work, a prototype is the visual sibling of `context.md` — see the `visual-prototype` skill. Both are deliberation artifacts. Written reasoning lives here; visual reasoning lives in the prototype.

package/skills/visual-prototype/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: visual-prototype
+description: Build a visual HTML prototype during planning for UI, component, layout, or style changes, so the user can react to the design before the plan is finalized. Use when a plan touches frontend appearance or interaction. Not for backend-only or non-visual work.
+---
+
+# Visual Prototype
+
+A prototype is a **convergence artifact**, not a deliverable. When a plan changes how something looks or behaves visually, a static markdown plan cannot show the user what they are agreeing to. Build the prototype while the plan is still soft, show it, and let the user redirect you before anything is committed to `submit_plan`.
+
+## When to use
+
+Use this when the plan involves any of:
+
+- New or restyled UI components
+- Layout, spacing, or visual hierarchy changes
+- Color, typography, or theming changes
+- Interaction states (hover, active, empty, loading, error)
+
+Do **not** use it for backend-only, refactor-only, or otherwise non-visual work.
+
+## Process
+
+### 1. Decide there is something to see
+
+If you cannot picture a screen or component changing, skip the prototype. A prototype for invisible work is noise.
+
+### 2. Build it with `preview_prototype`
+
+Call `preview_prototype` with:
+
+- `title` — short name for the prototype
+- `intent` — one line describing what it shows
+- `pug` — self-contained Pug markup for the prototype body. Inline any styles the prototype needs; assume nothing about the host page.
+
+The tool renders the Pug, writes `.plans/_prototypes/<slug>.html`, and opens it for review.
+
+### 3. Get a reaction before submitting
+
+Stop and ask the user what they think. Iterate on the prototype — call `preview_prototype` again with revisions — until the visual direction is agreed. Only then move toward `submit_plan`.
+
+`submit_plan` never generates HTML. The prototype lives entirely in the planning phase; its job is done once the user has reacted.
+
+## Relationship to context.md
+
+The prototype is the visual sibling of `context.md`. Both are deliberation artifacts that exist to slow the jump from "read the codebase" to "submit the plan." Keep `context.md` current as the living written record of intent, decisions, and open questions; use a prototype whenever the decision is visual. Resist the urge to skip straight to `submit_plan` on visual work.

package/extensions/plan-mode/html/templates/plan.pug

@@ -1,69 +0,0 @@
-doctype html
-html(lang="en")
-  head
-    meta(charset="utf-8")
-    meta(name="viewport" content="width=device-width, initial-scale=1")
-    title= plan.title
-    style.
-      :root { color-scheme: dark; --bg:#0b0d12; --panel:#11141b; --muted:#8b93a7; --text:#eef1f7; --line:#242936; --accent:#8b5cf6; --done:#33d69f; --blocked:#ff6b6b; }
-      * { box-sizing: border-box; }
-      body { margin:0; background:radial-gradient(circle at top left,#1c1730,transparent 34rem),var(--bg); color:var(--text); font:14px/1.5 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      main { width:min(1040px, calc(100% - 48px)); margin:48px auto; }
-      header { display:flex; justify-content:space-between; gap:24px; align-items:flex-start; margin-bottom:28px; }
-      h1 { font-size:34px; line-height:1.08; margin:0 0 10px; letter-spacing:-0.04em; }
-      h2 { font-size:15px; text-transform:uppercase; color:var(--muted); letter-spacing:0.14em; margin:0 0 14px; }
-      .meta { color:var(--muted); display:flex; gap:12px; flex-wrap:wrap; }
-      .pill { border:1px solid var(--line); border-radius:999px; padding:6px 10px; background:rgba(255,255,255,0.03); }
-      section { background:rgba(17,20,27,0.82); border:1px solid var(--line); border-radius:18px; padding:22px; margin:18px 0; box-shadow:0 24px 80px rgba(0,0,0,0.24); }
-      .handoff :first-child { margin-top:0; }
-      .handoff :last-child { margin-bottom:0; }
-      .handoff pre { background:#161922; border:1px solid var(--line); border-radius:10px; padding:14px 16px; overflow-x:auto; margin:12px 0; }
-      .handoff pre code { font-family:ui-monospace, SFMono-Regular, Menlo, monospace; font-size:13px; color:#c7ccda; background:none; padding:0; border:none; border-radius:0; }
-      .handoff code { font-family:ui-monospace, SFMono-Regular, Menlo, monospace; font-size:13px; background:rgba(139,92,246,0.12); color:var(--accent); padding:2px 6px; border-radius:5px; }
-      .handoff strong { font-weight:650; }
-      .handoff a { color:var(--accent); text-decoration:none; }
-      .handoff a:hover { text-decoration:underline; }
-      .handoff h1, .handoff h3, .handoff h4 { font-size:15px; text-transform:uppercase; color:var(--muted); letter-spacing:0.14em; margin:20px 0 10px; }
-      .handoff p { margin:8px 0; }
-      .handoff ul { margin:8px 0; padding-left:20px; }
-      .handoff li { margin:4px 0; }
-      .tasks { display:grid; gap:12px; }
-      .task { border:1px solid var(--line); border-radius:14px; padding:16px; background:#0f1218; }
-      .task-top { display:flex; gap:10px; align-items:center; margin-bottom:8px; }
-      .id { color:var(--accent); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
-      .status { margin-left:auto; color:var(--muted); }
-      .task.done .status { color:var(--done); }
-      .task.blocked .status { color:var(--blocked); }
-      .description { font-weight:650; }
-      .details { color:#c7ccda; margin:0; white-space:pre-wrap; }
-      .deps { color:var(--muted); margin-top:10px; font-size:12px; }
-  body
-    main
-      header
-        div
-          h1= plan.title
-          .meta
-            span.pill= plan.planName
-            span.pill= taskCountLabel
-        .meta
-          span.pill Generated #{generatedAt}
-      section.handoff
-        h2 Handoff
-        != handoffHtml
-      section
-        h2 Tasks
-        .tasks
-          each task in plan.tasks
-            article.task(class=task.status)
-              .task-top
-                span.id= task.id
-                span.description= task.description
-                span.status= task.status
-              if task.details
-                p.details= task.details
-              if task.depends_on && task.depends_on.length
-                .deps Depends on #{task.depends_on.join(', ')}
-      if prototypeHtml
-        section.prototype
-          h2 Prototype
-          != prototypeHtml