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

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.14.5
+
+### Patch Changes
+
+- Proper markdown rendering in plan.html — fenced code blocks, inline code, bold, italic, links, and all heading levels.
+
+## 0.14.4
+
+### Patch Changes
+
+- Remove task list widget entirely — plan.jsonl is the source of truth.
+
+## 0.14.3
+
+### Patch Changes
+
+- Only show task widget during active plan execution, not after exiting plan mode.
+
+## 0.14.2
+
+### Patch Changes
+
+- Remove post-plan submission menu and auto-hide task widget when all tasks are resolved.
+
+## 0.14.1
+
+### Patch Changes
+
+- Fix update_task failing after exiting plan mode; make task details optional for lightweight checklist-style plans.
+
+  - exitPlanMode now preserves plan data so update_task works outside execution mode
+  - submit_plan accepts tasks without details for self-execution workflows
+  - Plan widget shows in tracking mode after exiting plan mode
+  - Prompt guidance distinguishes delegation vs self-execution plan weights
+
 ## 0.14.0
 
 ### Minor Changes

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

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'bun:test';
+import { PlanModeState } from '../state.js';
+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',
+  };
+  return { title: 'Test Plan', planName: 'test-plan', handoff: '# Handoff', tasks: [task], ...overrides };
+}
+
+describe('PlanModeState', () => {
+  describe('exitPreservingPlan', () => {
+    test('clears mode flags but keeps plan data when a plan was submitted', () => {
+      const state = new PlanModeState();
+      state.planEnabled = true;
+      state.planDir = '.plans/test-plan';
+      state.plan = makePlan();
+
+      state.exitPreservingPlan();
+
+      expect(state.planEnabled).toBe(false);
+      expect(state.executing).toBe(false);
+      expect(state.plan).toBeDefined();
+      expect(state.planDir).toBe('.plans/test-plan');
+    });
+
+    test('fully resets when no plan was submitted', () => {
+      const state = new PlanModeState();
+      state.planEnabled = true;
+      state.planDir = undefined;
+      state.plan = undefined;
+
+      state.exitPreservingPlan();
+
+      expect(state.planEnabled).toBe(false);
+      expect(state.plan).toBeUndefined();
+      expect(state.planDir).toBeUndefined();
+    });
+  });
+});

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

@@ -1,6 +1,12 @@
 import { describe, expect, test } from 'bun:test';
-import { buildPlanModePrompt } from '../prompts.js';
+import { buildPlanModePrompt, buildExecutionPrompt } from '../prompts.js';
 import { PLAN_TOOLS } from '../constants.js';
+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 };
+}
 
 describe('buildPlanModePrompt', () => {
   const prompt = buildPlanModePrompt();
@@ -27,6 +33,38 @@ describe('buildPlanModePrompt', () => {
   });
 });
 
+describe('buildPlanModePrompt lightweight plan guidance', () => {
+  const prompt = buildPlanModePrompt();
+
+  test('mentions self-execution lightweight mode', () => {
+    expect(prompt).toMatch(/lightweight|checklist/i);
+  });
+
+  test('mentions delegation plans with full details', () => {
+    expect(prompt).toMatch(/delegation|different agent/i);
+  });
+});
+
+describe('buildExecutionPrompt', () => {
+  test('omits Details line when task has no details', () => {
+    const plan: PlanData = { title: 'Test', planName: 'test', handoff: '# H', tasks: [makeTask()] };
+    const prompt = buildExecutionPrompt(plan)!;
+    expect(prompt).not.toContain('Details:');
+    expect(prompt).toContain('t-001: Do work');
+  });
+
+  test('includes Details line when task has details', () => {
+    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' })] };
+    expect(buildExecutionPrompt(plan)).toBeUndefined();
+  });
+});
+
 describe('PLAN_TOOLS', () => {
   test('includes subagent for voting workflows', () => {
     expect(PLAN_TOOLS).toContain('subagent');

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

@@ -19,6 +19,14 @@ describe('tasks.jsonl storage', () => {
     await expect(readTasksJsonl(dir)).resolves.toEqual({ meta, tasks: [task] });
   });
 
+  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 };
+    await writeTasksJsonl(dir, meta, [lightweight]);
+    const result = await readTasksJsonl(dir);
+    expect(result?.tasks[0]?.id).toBe('t-002');
+    expect(result?.tasks[0]?.details).toBeUndefined();
+  });
+
   test('missing file returns undefined', async () => {
     await expect(readTasksJsonl(dir)).resolves.toBeUndefined();
   });

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

@@ -20,6 +20,19 @@ describe('task record type guards', () => {
     ).toBe(true);
   });
 
+  test('accepts task records without details (lightweight checklist)', () => {
+    expect(
+      isTaskRecord({
+        _type: 'task',
+        id: 't-001',
+        description: 'Do work',
+        status: 'pending',
+        created_at: now,
+        updated_at: now,
+      }),
+    ).toBe(true);
+  });
+
   test('rejects malformed task records', () => {
     expect(isTaskRecord({ _type: 'task', id: 't-001', status: 'pending' })).toBe(false);
     expect(

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

@@ -24,39 +24,83 @@ 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) {
-    if (line.startsWith('# ')) {
-      if (inList) {
-        html.push('</ul>');
-        inList = false;
+    // 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 = '';
       }
-      html.push(`<h1>${escapeHtml(line.slice(2))}</h1>`);
-    } else if (line.startsWith('## ')) {
-      if (inList) {
-        html.push('</ul>');
-        inList = false;
-      }
-      html.push(`<h2>${escapeHtml(line.slice(3))}</h2>`);
-    } else if (line.startsWith('- ')) {
-      if (!inList) {
-        html.push('<ul>');
-        inList = true;
-      }
-      html.push(`<li>${escapeHtml(line.slice(2))}</li>`);
-    } else if (line.trim()) {
-      if (inList) {
-        html.push('</ul>');
-        inList = false;
-      }
-      html.push(`<p>${escapeHtml(line)}</p>`);
+      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;')

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

@@ -17,6 +17,16 @@ html(lang="en")
       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; }
@@ -49,7 +59,8 @@ html(lang="en")
                 span.id= task.id
                 span.description= task.description
                 span.status= task.status
-              p.details= task.details
+              if task.details
+                p.details= task.details
               if task.depends_on && task.depends_on.length
                 .deps Depends on #{task.depends_on.join(', ')}
       if prototypeHtml

package/extensions/plan-mode/index.ts

@@ -271,34 +271,8 @@ export default function planMode(pi: ExtensionAPI): void {
       return;
     }
 
-    // ── After plan submission: show post-plan menu ──
-    if (!state.planEnabled || !ctx.hasUI) return;
-    if (!state.planDir || !state.plan) return;
-
-    const choice = await ctx.ui.select('Plan ready — what next?', [
-      'Execute Plan', 'Refine Plan', 'Follow up', 'Exit plan mode',
-    ]);
-
-    if (choice === 'Execute Plan') {
-      pi.sendUserMessage('/plan-exec', { deliverAs: 'followUp' });
-    } else if (choice === 'Refine Plan') {
-      pi.sendUserMessage(
-        `Review the plan you just created with an adversarial lens. Challenge assumptions, find gaps, identify risks, and look for:
-
-- Missing edge cases or error handling
-- Incorrect assumptions about the codebase
-- Tasks that are too vague or could be misinterpreted
-- Missing dependencies between tasks
-- Simpler alternatives that were overlooked
-
-After your review, call submit_plan again with the improved plan.`,
-        { deliverAs: 'followUp' },
-      );
-    } else if (choice === 'Follow up') {
-      // No-op: dismiss menu, let user type naturally
-    } else if (choice === 'Exit plan mode') {
-      await exitPlanMode(state, pi, ctx);
-    }
+    // 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.
   });
 
   // ── Event: session restore ────────────────────────────────────────────────

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

@@ -54,7 +54,7 @@ export async function exitPlanMode(
   ctx: ExtensionContext,
 ): Promise<void> {
   const { previousModel, previousThinking } = state;
-  state.reset();
+  state.exitPreservingPlan();
   pi.setActiveTools(EXEC_TOOLS);
   if (previousModel) {
     await switchModel(pi, ctx, previousModel);

package/extensions/plan-mode/prompts.ts

@@ -24,9 +24,13 @@ When you are ready to finalize the plan, call submit_plan with:
 - name: a short kebab-case name (e.g. "add-auth-middleware")
 - title: a human-readable plan title
 - handoff: a markdown document that explains what is changing, why it matters, approach, decisions, file paths, APIs, patterns, constraints, and gotchas
-- tasks: an array of tasks with id (e.g. "t-001"), description (≤60 chars), details, and optional depends_on task IDs
+- 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.
 
 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.`;
@@ -38,10 +42,16 @@ export function buildExecutionPrompt(plan: PlanData): string | undefined {
   if (remaining.length === 0) return undefined;
 
   const taskList = remaining
-    .map((task) => `${task.id}. ${task.description}\n   Details: ${task.details}`)
+    .map((task) => {
+      const line = `${task.id}. ${task.description}`;
+      return task.details ? `${line}\n   Details: ${task.details}` : line;
+    })
     .join('\n\n');
 
   const currentTask = remaining[0];
+  const currentDetails = currentTask.details
+    ? `\nDetails: ${currentTask.details}`
+    : '';
 
   return `[EXECUTING PLAN — FOLLOW THE PLAN EXACTLY]
 
@@ -55,8 +65,7 @@ Rules:
 - Do NOT deviate from the plan — if something seems wrong, call update_task with status "blocked"
 
 ## Current task
-${currentTask.id}: ${currentTask.description}
-Details: ${currentTask.details}
+${currentTask.id}: ${currentTask.description}${currentDetails}
 
 ## Handoff
 ${plan.handoff}

package/extensions/plan-mode/state.ts

@@ -44,4 +44,11 @@ export class PlanModeState {
     this.plan = undefined;
     this.executionStartIdx = undefined;
   }
+
+  /** Exit plan/execution mode but keep plan data for update_task tracking. */
+  exitPreservingPlan(): void {
+    this.planEnabled = false;
+    this.executing = false;
+    this.executionStartIdx = undefined;
+  }
 }

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

@@ -25,7 +25,9 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
     promptSnippet: 'Finalize the plan with title, handoff, tasks, dependencies, and optional prototype Pug',
     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, detailed implementation instructions, and optional depends_on task IDs.',
+      '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.',
     ],
     parameters: Type.Object({
@@ -36,7 +38,7 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
         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.String({ description: 'Full implementation instructions for this task' }),
+          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 },
@@ -53,7 +55,7 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
         _type: 'task',
         id: task.id,
         description: task.description.slice(0, 60),
-        details: task.details,
+        details: task.details ?? '',
         status: 'pending',
         depends_on: task.depends_on,
         created_at: now,

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

@@ -1,5 +1,5 @@
 /**
- * update_task tool — available during the execution phase.
+ * update_task tool — available during execution and after exiting plan mode with a submitted plan.
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';

package/extensions/plan-mode/types.ts

@@ -8,7 +8,7 @@ export interface TaskRecord {
   _type: 'task';
   id: string;
   description: string;
-  details: string;
+  details?: string;
   status: TaskStatus;
   depends_on?: string[];
   notes?: string;
@@ -62,7 +62,7 @@ export function isTaskRecord(value: unknown): value is TaskRecord {
     value._type === 'task' &&
     typeof value.id === 'string' &&
     typeof value.description === 'string' &&
-    typeof value.details === 'string' &&
+    (value.details === undefined || typeof value.details === 'string') &&
     typeof value.status === 'string' &&
     TASK_STATUSES.has(value.status as TaskStatus) &&
     (value.depends_on === undefined || isStringArray(value.depends_on)) &&

package/extensions/plan-mode/ui.ts

@@ -12,28 +12,16 @@ export function updateUI(state: PlanModeState, ctx: ExtensionContext): void {
     const done = state.plan.tasks.filter((task) => task.status === 'done').length;
     const total = state.plan.tasks.length;
     ctx.ui.setStatus('plan-mode', theme.fg('accent', `📋 exec ${done}/${total}`));
+  } else if (state.plan && !state.planEnabled) {
+    const done = state.plan.tasks.filter((task) => task.status === 'done').length;
+    const total = state.plan.tasks.length;
+    ctx.ui.setStatus('plan-mode', theme.fg('muted', `📋 ${done}/${total}`));
   } else if (state.planEnabled) {
     ctx.ui.setStatus('plan-mode', theme.fg('warning', '📝 plan'));
   } else {
     ctx.ui.setStatus('plan-mode', undefined);
   }
 
-  if (state.executing && state.plan) {
-    const lines = state.plan.tasks.map((task) => {
-      const label = `${task.id} ${task.description}`;
-      switch (task.status) {
-        case 'done':
-          return theme.fg('success', '✓ ') + theme.fg('muted', theme.strikethrough(label));
-        case 'skipped':
-          return theme.fg('warning', '⊘ ') + theme.fg('muted', theme.strikethrough(label));
-        case 'blocked':
-          return theme.fg('error', '✗ ') + theme.fg('error', label);
-        default:
-          return theme.fg('muted', '☐ ') + label;
-      }
-    });
-    ctx.ui.setWidget('plan-todos', lines);
-  } else {
-    ctx.ui.setWidget('plan-todos', undefined);
-  }
+  // Task list lives in plan.jsonl — no widget needed.
+  ctx.ui.setWidget('plan-todos', undefined);
 }

package/package.json

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