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

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.14.0
+
+### Minor Changes
+
+- Refactor plan-mode to conversational planning with JSONL task storage and HTML output. Replace steps with task records, add atomic writes, Pug-based plan.html generation, and migrate manifest to JSONL. Update subagent prompts.
+
+## 0.13.0
+
+### Minor Changes
+
+- Replace context+risks with HANDOFF.md and step summaries. submit_plan now writes a HANDOFF.md alongside plan.json. Completion message shows an actual summary of changes from step notes instead of just a checklist. Executor is prompted to always include notes summarizing what was done.
+
+## 0.12.1
+
+### Patch Changes
+
+- Include `skills/` directory in package files so the bundled technical-options skill is published.
+
+## 0.12.0
+
+### Minor Changes
+
+- Bundle `technical-options` skill inside the package (installable via `pi.skills`). The planner prompt now explicitly tells the agent to generate proposals itself and only delegate voting to subagents, keeping the planner visible as the main agent.
+
+## 0.11.0
+
+### Minor Changes
+
+- Integrate technical-options skill into plan mode: add `subagent` to plan-phase tools and nudge the planner to use structured proposal evaluation when facing significant design decisions with multiple viable approaches.
+
 ## 0.10.1
 
 ### Patch Changes

package/extensions/plan-mode/__tests__/atomic-write.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { writeFileAtomic } from '../storage/atomic-write.js';
+
+let dir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-atomic-'));
+});
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('writeFileAtomic', () => {
+  test('writes complete content to the target path', async () => {
+    const target = join(dir, 'data.txt');
+
+    await writeFileAtomic(target, 'hello world');
+
+    expect(await readFile(target, 'utf8')).toBe('hello world');
+  });
+
+  test('replaces existing content atomically from the caller perspective', async () => {
+    const target = join(dir, 'data.txt');
+    await writeFile(target, 'old');
+
+    await writeFileAtomic(target, 'new');
+
+    expect(await readFile(target, 'utf8')).toBe('new');
+  });
+
+  test('leaves target untouched when writing fails before rename', async () => {
+    const target = join(dir, 'data.txt');
+    await writeFile(target, 'original');
+
+    await expect(writeFileAtomic(target, 'next', { mode: 0o400 })).rejects.toThrow();
+
+    expect(await readFile(target, 'utf8')).toBe('original');
+  });
+});

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

@@ -0,0 +1,43 @@
+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');
+  });
+
+  test('omits prototypes section when no prototype is provided', () => {
+    expect(renderPlanHtml(plan)).not.toContain('Prototype');
+  });
+
+  test('renders optional prototype pug markup', () => {
+    const html = renderPlanHtml(plan, '.mockup Prototype card');
+
+    expect(html).toContain('Prototype');
+    expect(html).toContain('Prototype card');
+  });
+});

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

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PKG_ROOT = join(import.meta.dir, '..', '..', '..');
+const PKG_JSON = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8'));
+
+describe('package.json pi manifest', () => {
+  test('declares skills directory', () => {
+    expect(PKG_JSON.pi?.skills).toBeDefined();
+    expect(PKG_JSON.pi.skills).toContain('./skills');
+  });
+});
+
+describe('bundled technical-options skill', () => {
+  const skillDir = join(PKG_ROOT, 'skills', 'technical-options');
+  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*technical-options/);
+    expect(content).toMatch(/description:/);
+  });
+
+  test('description does not contain overly broad triggers', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    // These were flagged during review as too broad for routing
+    expect(content).not.toMatch(/description:.*help me decide/i);
+    expect(content).not.toMatch(/description:.*what are my options/i);
+  });
+
+  test('skill content mentions parallel voting agents', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toContain('voting');
+    expect(content).toContain('parallel');
+  });
+
+  test('skill content includes adversarial framing challenge step', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/challenge.*framing|framing.*challenge/i);
+  });
+});

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

@@ -0,0 +1,37 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+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';
+
+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 }); });
+
+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 };
+    await writePlansManifest([entry]);
+    await expect(readPlansManifest()).resolves.toEqual([entry]);
+  });
+
+  test('upserts new entries', async () => {
+    await upsertPlanEntry('new-plan', { status: 'in-progress', title: 'New Plan' });
+    const entries = await readPlansManifest();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.name).toBe('new-plan');
+    expect(entries[0]?.title).toBe('New Plan');
+  });
+
+  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 upsertPlanEntry('p', { status: 'done', title: 'New' });
+    const [entry] = await readPlansManifest();
+    expect(entry.created_at).toBe('created');
+    expect(entry.status).toBe('done');
+    expect(entry.completed_at).toBeString();
+  });
+});

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

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { buildPlanModePrompt } from '../prompts.js';
+import { PLAN_TOOLS } from '../constants.js';
+
+describe('buildPlanModePrompt', () => {
+  const prompt = buildPlanModePrompt();
+
+  test('mentions technical-options skill for significant decisions', () => {
+    expect(prompt).toContain('technical-options');
+  });
+
+  test('mentions handoff instead of context and risks', () => {
+    expect(prompt).toContain('handoff');
+    expect(prompt).not.toContain('- risks:');
+    expect(prompt).not.toContain('- context:');
+  });
+
+  test('tells planner to do proposal generation itself, not delegate', () => {
+    // The planner should generate proposals as the main agent, only using
+    // subagents for voting/evaluation — not delegating the entire workflow
+    expect(prompt).toMatch(/you.*generat|generat.*yourself|do this yourself/i);
+  });
+
+  test('mentions subagent is available for voting only', () => {
+    // Should clarify subagent is for evaluation, not for the whole workflow
+    expect(prompt).toMatch(/subagent|voting|evaluat/i);
+  });
+});
+
+describe('PLAN_TOOLS', () => {
+  test('includes subagent for voting workflows', () => {
+    expect(PLAN_TOOLS).toContain('subagent');
+  });
+
+  test('includes search_skills for skill discovery', () => {
+    expect(PLAN_TOOLS).toContain('search_skills');
+  });
+});

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

@@ -0,0 +1,44 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { readTasksJsonl, updateTask, writeTasksJsonl } from '../storage/task-storage.js';
+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 };
+
+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 () => {
+    await writeTasksJsonl(dir, meta, [task]);
+    await expect(readTasksJsonl(dir)).resolves.toEqual({ meta, tasks: [task] });
+  });
+
+  test('missing file returns undefined', async () => {
+    await expect(readTasksJsonl(dir)).resolves.toBeUndefined();
+  });
+
+  test('rejects corrupt lines', async () => {
+    await Bun.write(join(dir, 'tasks.jsonl'), `${JSON.stringify(meta)}\nnot-json\n`);
+    await expect(readTasksJsonl(dir)).rejects.toThrow(/Invalid JSONL/);
+  });
+
+  test('rejects empty files', async () => {
+    await Bun.write(join(dir, 'tasks.jsonl'), '');
+    await expect(readTasksJsonl(dir)).rejects.toThrow(/meta/);
+  });
+
+  test('updates a task by id and rewrites the snapshot', async () => {
+    await writeTasksJsonl(dir, meta, [task]);
+    const updated = await updateTask(dir, 't-001', { status: 'done', notes: 'finished' });
+
+    expect(updated.status).toBe('done');
+    expect(updated.notes).toBe('finished');
+    expect((await readTasksJsonl(dir))?.tasks[0]?.status).toBe('done');
+  });
+});

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

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test';
+import { isTaskMeta, isTaskRecord } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+describe('task record type guards', () => {
+  test('accepts valid task records', () => {
+    expect(
+      isTaskRecord({
+        _type: 'task',
+        id: 't-001',
+        description: 'Do work',
+        details: 'Full instructions',
+        status: 'pending',
+        depends_on: ['t-000'],
+        notes: 'note',
+        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(
+      isTaskRecord({
+        _type: 'task',
+        id: 't-001',
+        description: 'Do work',
+        details: 'Full instructions',
+        status: 'unknown',
+        created_at: now,
+        updated_at: now,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('task meta type guard', () => {
+  test('accepts valid meta records', () => {
+    expect(
+      isTaskMeta({
+        _type: 'meta',
+        title: 'Refactor',
+        plan_name: 'refactor',
+        created_at: now,
+      }),
+    ).toBe(true);
+  });
+
+  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);
+  });
+});

package/extensions/plan-mode/constants.ts

@@ -10,11 +10,13 @@ export const PLAN_TOOLS = [
   'find',
   'ls',
   'submit_plan',
+  'write',
   'questionnaire',
   'search_skills',
+  'subagent',
 ];
 
-export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_step'];
+export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_task'];
 
 // ── Model + thinking presets ─────────────────────────────────────────────────
 export const PLAN_MODEL = { provider: 'anthropic', id: 'claude-opus-4-6' } as const;

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

@@ -0,0 +1,67 @@
+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');
+
+export function renderPlanHtml(plan: PlanData, prototype?: string): string {
+  const template = readFileSync(templatePath, 'utf8');
+  const prototypeHtml = prototype?.trim() ? pug.render(prototype) : undefined;
+
+  return pug.render(template, {
+    filename: templatePath,
+    plan,
+    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;
+
+  for (const line of lines) {
+    if (line.startsWith('# ')) {
+      if (inList) {
+        html.push('</ul>');
+        inList = false;
+      }
+      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>`);
+    }
+  }
+
+  if (inList) html.push('</ul>');
+  return html.join('\n');
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}

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

@@ -0,0 +1,58 @@
+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; }
+      .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
+              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