@dreki-gg/pi-plan-mode 0.15.0 → 0.16.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';
@@ -21,36 +20,52 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
   pi.registerTool({
     name: 'submit_plan',
     label: 'Submit Plan',
-    description: 'Finalize a conversational plan with task IDs, JSONL storage, HANDOFF.md, and generated plan.html.',
-    promptSnippet: 'Finalize the plan with title, handoff, tasks, dependencies, and optional prototype Pug',
+    description:
+      'Finalize a conversational plan with task IDs, JSONL storage, and HANDOFF.md.',
+    promptSnippet:
+      '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 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({ description: 'Short kebab-case name for the plan (e.g. "add-auth-middleware")' }),
+      name: Type.String({
+        description: 'Short kebab-case name for the plan (e.g. "add-auth-middleware")',
+      }),
       title: Type.String({ description: 'Human-readable plan title' }),
       handoff: Type.String({ description: 'Markdown content for HANDOFF.md' }),
       tasks: Type.Array(
         Type.Object({
           id: Type.String({ description: 'Stable task ID, e.g. t-001' }),
-          description: Type.String({ description: 'Short task label for progress display (≤60 chars)' }),
-          details: Type.Optional(Type.String({ description: 'Full implementation instructions for this task. Omit for lightweight checklist-style plans when you are executing yourself.' })),
+          description: Type.String({
+            description: 'Short task label for progress display (≤60 chars)',
+          }),
+          details: Type.Optional(
+            Type.String({
+              description:
+                'Full implementation instructions for this task. Omit for lightweight checklist-style plans when you are executing yourself.',
+            }),
+          ),
           depends_on: Type.Optional(Type.Array(Type.String({ description: 'Dependency task ID' }))),
         }),
         { minItems: 1 },
       ),
-      prototype: Type.Optional(Type.String({ description: 'Optional Pug markup for the prototype section in plan.html' })),
     }),
 
     async execute(_toolCallId, params) {
       const planName = toKebabCase(params.name);
       const planDir = `.plans/${planName}`;
       const now = new Date().toISOString();
-      const meta: TaskMeta = { _type: 'meta', title: params.title, plan_name: planName, created_at: now };
+      const meta: TaskMeta = {
+        _type: 'meta',
+        title: params.title,
+        plan_name: planName,
+        created_at: now,
+      };
       const tasks: TaskRecord[] = params.tasks.map((task) => ({
         _type: 'task',
         id: task.id,
@@ -66,13 +81,17 @@ 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);
 
       return {
-        content: [{ type: 'text' as const, text: `Plan "${params.title}" saved with ${tasks.length} tasks. Review ${planDir}/plan.html, then execute when ready.` }],
+        content: [
+          {
+            type: 'text' as const,
+            text: `Plan "${params.title}" saved with ${tasks.length} tasks in ${planDir}. Execute when ready.`,
+          },
+        ],
         details: { planDir, plan },
         terminate: true,
       };
@@ -91,7 +110,8 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
       const plan = (result.details as { plan?: PlanData } | undefined)?.plan;
       if (!plan) return new Text(theme.fg('success', '✓ Plan saved'), 0, 0);
       const lines = [theme.fg('success', '✓ ') + theme.fg('accent', theme.bold(plan.title)), ''];
-      for (const task of plan.tasks) lines.push(`  ${theme.fg('muted', task.id)} ${task.description}`);
+      for (const task of plan.tasks)
+        lines.push(`  ${theme.fg('muted', task.id)} ${task.description}`);
       return new Text(lines.join('\n'), 0, 0);
     },
   });

package/extensions/plan-mode/tools/update-task.ts

@@ -10,14 +10,19 @@ import type { PlanData, TaskStatus } from '../types.js';
 
 export interface UpdateTaskCallbacks {
   getPlan: () => PlanData | undefined;
-  onTaskUpdated: (taskId: string, status: Exclude<TaskStatus, 'pending'>, notes?: string) => void | Promise<void>;
+  onTaskUpdated: (
+    taskId: string,
+    status: Exclude<TaskStatus, 'pending'>,
+    notes?: string,
+  ) => void | Promise<void>;
 }
 
 export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCallbacks): void {
   pi.registerTool({
     name: 'update_task',
     label: 'Update Task',
-    description: 'Mark a plan task as done, skipped, or blocked. If blocked, execution pauses for user intervention.',
+    description:
+      'Mark a plan task as done, skipped, or blocked. If blocked, execution pauses for user intervention.',
     promptSnippet: 'Mark a plan task as done, skipped, or blocked',
     promptGuidelines: [
       'Call update_task after completing each plan task before moving to the next.',
@@ -27,7 +32,9 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
     parameters: Type.Object({
       task_id: Type.String({ description: 'Task ID (for example, t-001)' }),
       status: StringEnum(['done', 'skipped', 'blocked'] as const),
-      notes: Type.Optional(Type.String({ description: 'What was done, why skipped, or why blocked' })),
+      notes: Type.Optional(
+        Type.String({ description: 'What was done, why skipped, or why blocked' }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
@@ -37,15 +44,27 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       const task = plan.tasks.find((candidate) => candidate.id === params.task_id);
       if (!task) throw new Error(`Task not found: ${params.task_id}`);
       if (task.status !== 'pending') {
-        throw new Error(`Task ${params.task_id} is already "${task.status}". Only pending tasks can be updated.`);
+        throw new Error(
+          `Task ${params.task_id} is already "${task.status}". Only pending tasks can be updated.`,
+        );
       }
 
       await callbacks.onTaskUpdated(params.task_id, params.status, params.notes);
 
-      const details = { task_id: params.task_id, status: params.status, notes: params.notes, description: task.description };
+      const details = {
+        task_id: params.task_id,
+        status: params.status,
+        notes: params.notes,
+        description: task.description,
+      };
       if (params.status === 'blocked') {
         return {
-          content: [{ type: 'text' as const, text: `Task ${params.task_id} blocked. Execution paused — waiting for user input.` }],
+          content: [
+            {
+              type: 'text' as const,
+              text: `Task ${params.task_id} blocked. Execution paused — waiting for user input.`,
+            },
+          ],
           details,
           terminate: true,
         };
@@ -60,7 +79,12 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       if (params.notes) text += ` — ${params.notes}`;
       text += next ? `\n\nNext task ${next.id}: ${next.description}` : '\n\nAll tasks resolved!';
 
-      return { content: [{ type: 'text' as const, text }], details, terminate: !next };
+      // Do not terminate the turn just because the queue is empty: that would cut off
+      // the agent's final pass (closing summary, validation, follow-up) after the last
+      // task is marked done. Completion is handled out-of-band by the `agent_end`
+      // handler in index.ts. Only the `blocked` branch above terminates, to pause for
+      // user input.
+      return { content: [{ type: 'text' as const, text }], details };
     },
 
     renderCall(args, theme) {
@@ -68,15 +92,31 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       const status = (args as { status?: string }).status ?? '';
       let content = theme.fg('toolTitle', theme.bold('update_task '));
       content += theme.fg('muted', taskId);
-      if (status) content += ' ' + theme.fg(status === 'done' ? 'success' : status === 'skipped' ? 'warning' : 'error', status);
+      if (status)
+        content +=
+          ' ' +
+          theme.fg(
+            status === 'done' ? 'success' : status === 'skipped' ? 'warning' : 'error',
+            status,
+          );
       return new Text(content, 0, 0);
     },
 
     renderResult(result, _options, theme) {
-      const details = result.details as { task_id?: string; status?: string; description?: string } | undefined;
+      const details = result.details as
+        | { task_id?: string; status?: string; description?: string }
+        | undefined;
       if (!details) return new Text(theme.fg('dim', 'Updated'), 0, 0);
-      const statusMap: Record<string, string> = { done: theme.fg('success', '✓'), skipped: theme.fg('warning', '⊘'), blocked: theme.fg('error', '✗') };
-      return new Text(`${statusMap[details.status ?? ''] ?? ''} Task ${details.task_id}: ${details.description ?? ''}`, 0, 0);
+      const statusMap: Record<string, string> = {
+        done: theme.fg('success', '✓'),
+        skipped: theme.fg('warning', '⊘'),
+        blocked: theme.fg('error', '✗'),
+      };
+      return new Text(
+        `${statusMap[details.status ?? ''] ?? ''} Task ${details.task_id}: ${details.description ?? ''}`,
+        0,
+        0,
+      );
     },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.15.0",
+  "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