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

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @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
+
+- Fix execution stopping after the final task is marked done. `update_task` no longer terminates the turn merely because the task queue is empty, so the agent can run its closing summary / validation pass before the `agent_end` completion handler takes over. The `blocked` branch still terminates to pause for user input.
+
 ## 0.15.0
 
 ### Minor Changes

package/extensions/plan-mode/__tests__/agent-end-safety.test.ts

@@ -102,9 +102,9 @@ describe('agent_end handler safety', () => {
     if (violations.length > 0) {
       throw new Error(
         `Found sendUserMessage calls inside agent_end without deliverAs.\n` +
-        `The agent is still "processing" during agent_end, so deliverAs is required.\n\n` +
-        `Violations:\n${violations.map((v) => `  - ${v}`).join('\n')}\n\n` +
-        `Fix: add { deliverAs: 'followUp' } to each call.`,
+          `The agent is still "processing" during agent_end, so deliverAs is required.\n\n` +
+          `Violations:\n${violations.map((v) => `  - ${v}`).join('\n')}\n\n` +
+          `Fix: add { deliverAs: 'followUp' } to each call.`,
       );
     }
   });

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/__tests__/phase-transitions.test.ts

@@ -4,10 +4,21 @@ import type { PlanData, TaskRecord } from '../types.js';
 
 function makePlan(overrides?: Partial<PlanData>): PlanData {
   const task: TaskRecord = {
-    _type: 'task', id: 't-001', description: 'Do work', details: 'Details',
-    status: 'pending', created_at: '2026-01-01T00:00:00Z', updated_at: '2026-01-01T00:00:00Z',
+    _type: 'task',
+    id: 't-001',
+    description: 'Do work',
+    details: 'Details',
+    status: 'pending',
+    created_at: '2026-01-01T00:00:00Z',
+    updated_at: '2026-01-01T00:00:00Z',
+  };
+  return {
+    title: 'Test Plan',
+    planName: 'test-plan',
+    handoff: '# Handoff',
+    tasks: [task],
+    ...overrides,
   };
-  return { title: 'Test Plan', planName: 'test-plan', handoff: '# Handoff', tasks: [task], ...overrides };
 }
 
 describe('PlanModeState', () => {

package/extensions/plan-mode/__tests__/plans-manifest.test.ts

@@ -3,17 +3,34 @@ import { chdir } from 'node:process';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { readPlansManifest, upsertPlanEntry, writePlansManifest } from '../storage/plans-manifest.js';
+import {
+  readPlansManifest,
+  upsertPlanEntry,
+  writePlansManifest,
+} from '../storage/plans-manifest.js';
 
 const originalCwd = process.cwd();
 let dir: string;
 
-beforeEach(async () => { dir = await mkdtemp(join(tmpdir(), 'plan-mode-manifest-')); chdir(dir); });
-afterEach(async () => { chdir(originalCwd); await rm(dir, { recursive: true, force: true }); });
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-manifest-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
 
 describe('plans.jsonl manifest', () => {
   test('round trips entries', async () => {
-    const entry = { _type: 'plan' as const, name: 'refactor', status: 'in-progress' as const, title: 'Refactor', created_at: 'now', completed_at: null };
+    const entry = {
+      _type: 'plan' as const,
+      name: 'refactor',
+      status: 'in-progress' as const,
+      title: 'Refactor',
+      created_at: 'now',
+      completed_at: null,
+    };
     await writePlansManifest([entry]);
     await expect(readPlansManifest()).resolves.toEqual([entry]);
   });
@@ -27,7 +44,16 @@ describe('plans.jsonl manifest', () => {
   });
 
   test('upserts existing entries without changing created_at', async () => {
-    await writePlansManifest([{ _type: 'plan', name: 'p', status: 'in-progress', title: 'Old', created_at: 'created', completed_at: null }]);
+    await writePlansManifest([
+      {
+        _type: 'plan',
+        name: 'p',
+        status: 'in-progress',
+        title: 'Old',
+        created_at: 'created',
+        completed_at: null,
+      },
+    ]);
     await upsertPlanEntry('p', { status: 'done', title: 'New' });
     const [entry] = await readPlansManifest();
     expect(entry.created_at).toBe('created');

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

@@ -5,7 +5,15 @@ import type { PlanData, TaskRecord } from '../types.js';
 
 const now = '2026-01-01T00:00:00Z';
 function makeTask(overrides?: Partial<TaskRecord>): TaskRecord {
-  return { _type: 'task', id: 't-001', description: 'Do work', status: 'pending', created_at: now, updated_at: now, ...overrides };
+  return {
+    _type: 'task',
+    id: 't-001',
+    description: 'Do work',
+    status: 'pending',
+    created_at: now,
+    updated_at: now,
+    ...overrides,
+  };
 }
 
 describe('buildPlanModePrompt', () => {
@@ -54,13 +62,23 @@ describe('buildExecutionPrompt', () => {
   });
 
   test('includes Details line when task has details', () => {
-    const plan: PlanData = { title: 'Test', planName: 'test', handoff: '# H', tasks: [makeTask({ details: 'Full instructions here' })] };
+    const plan: PlanData = {
+      title: 'Test',
+      planName: 'test',
+      handoff: '# H',
+      tasks: [makeTask({ details: 'Full instructions here' })],
+    };
     const prompt = buildExecutionPrompt(plan)!;
     expect(prompt).toContain('Details: Full instructions here');
   });
 
   test('returns undefined when no pending tasks', () => {
-    const plan: PlanData = { title: 'Test', planName: 'test', handoff: '# H', tasks: [makeTask({ status: 'done' })] };
+    const plan: PlanData = {
+      title: 'Test',
+      planName: 'test',
+      handoff: '# H',
+      tasks: [makeTask({ status: 'done' })],
+    };
     expect(buildExecutionPrompt(plan)).toBeUndefined();
   });
 });

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

@@ -8,10 +8,22 @@ import type { TaskMeta, TaskRecord } from '../types.js';
 let dir: string;
 const now = '2026-05-27T12:00:00.000Z';
 const meta: TaskMeta = { _type: 'meta', title: 'Plan', plan_name: 'plan', created_at: now };
-const task: TaskRecord = { _type: 'task', id: 't-001', description: 'Do work', details: 'Details', status: 'pending', created_at: now, updated_at: now };
+const task: TaskRecord = {
+  _type: 'task',
+  id: 't-001',
+  description: 'Do work',
+  details: 'Details',
+  status: 'pending',
+  created_at: now,
+  updated_at: now,
+};
 
-beforeEach(async () => { dir = await mkdtemp(join(tmpdir(), 'plan-mode-tasks-')); });
-afterEach(async () => { await rm(dir, { recursive: true, force: true }); });
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-tasks-'));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
 
 describe('tasks.jsonl storage', () => {
   test('round trips meta and tasks', async () => {
@@ -20,7 +32,14 @@ describe('tasks.jsonl storage', () => {
   });
 
   test('round trips tasks without details (lightweight checklist)', async () => {
-    const lightweight: TaskRecord = { _type: 'task', id: 't-002', description: 'Quick fix', status: 'pending', created_at: now, updated_at: now };
+    const lightweight: TaskRecord = {
+      _type: 'task',
+      id: 't-002',
+      description: 'Quick fix',
+      status: 'pending',
+      created_at: now,
+      updated_at: now,
+    };
     await writeTasksJsonl(dir, meta, [lightweight]);
     const result = await readTasksJsonl(dir);
     expect(result?.tasks[0]?.id).toBe('t-002');

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

@@ -63,6 +63,8 @@ describe('task meta type guard', () => {
 
   test('rejects malformed meta records', () => {
     expect(isTaskMeta({ _type: 'meta', title: 'Refactor' })).toBe(false);
-    expect(isTaskMeta({ _type: 'task', title: 'Refactor', plan_name: 'refactor', created_at: now })).toBe(false);
+    expect(
+      isTaskMeta({ _type: 'task', title: 'Refactor', plan_name: 'refactor', created_at: now }),
+    ).toBe(false);
   });
 });

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

@@ -14,7 +14,9 @@ describe('isSafeCommand', () => {
 
     test('command with 2>/dev/null stderr redirect', () => {
       expect(
-        isSafeCommand('cat .release-please-manifest.json 2>/dev/null; echo "---"; cat release-please-config.json 2>/dev/null'),
+        isSafeCommand(
+          'cat .release-please-manifest.json 2>/dev/null; echo "---"; cat release-please-config.json 2>/dev/null',
+        ),
       ).toBe(true);
     });
 

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/context-filter.ts

@@ -4,10 +4,7 @@
  */
 
 /** Drop everything before the execution start index. */
-export function filterExecutionMessages<T>(
-  messages: T[],
-  executionStartIdx: number,
-): T[] {
+export function filterExecutionMessages<T>(messages: T[], executionStartIdx: number): T[] {
   return messages.filter((_m, i) => i >= executionStartIdx);
 }
 

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

@@ -2,110 +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