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

package/extensions/plan-mode/storage/plans-manifest.ts

@@ -0,0 +1,57 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { writeFileAtomic } from './atomic-write.js';
+
+const MANIFEST_PATH = '.plans/plans.jsonl';
+
+export interface PlanManifestEntry {
+  _type: 'plan';
+  name: string;
+  status: 'in-progress' | 'done';
+  title: string;
+  created_at: string;
+  completed_at: string | null;
+}
+
+export async function readPlansManifest(): Promise<PlanManifestEntry[]> {
+  let text: string;
+  try { text = await readFile(MANIFEST_PATH, 'utf8'); } catch { return []; }
+  const entries: PlanManifestEntry[] = [];
+  for (const [index, raw] of text.split(/\r?\n/).entries()) {
+    if (!raw.trim()) continue;
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch (error) { throw new Error(`Invalid plans.jsonl at line ${index + 1}: ${(error as Error).message}`); }
+    if (!isPlanManifestEntry(parsed)) throw new Error(`Invalid plans.jsonl record at line ${index + 1}`);
+    entries.push(parsed);
+  }
+  return entries;
+}
+
+export async function writePlansManifest(entries: PlanManifestEntry[]): Promise<void> {
+  await mkdir('.plans', { recursive: true });
+  const content = entries.map((entry) => JSON.stringify(entry)).join('\n') + (entries.length ? '\n' : '');
+  await writeFileAtomic(MANIFEST_PATH, content);
+}
+
+export async function upsertPlanEntry(name: string, updates: { status: 'in-progress' | 'done'; title?: string }): Promise<void> {
+  const entries = await readPlansManifest();
+  const now = new Date().toISOString();
+  const index = entries.findIndex((entry) => entry.name === name);
+  const existing = index === -1 ? undefined : entries[index];
+  const entry: PlanManifestEntry = {
+    _type: 'plan',
+    name,
+    status: updates.status,
+    title: updates.title ?? existing?.title ?? 'Untitled plan',
+    created_at: existing?.created_at ?? now,
+    completed_at: updates.status === 'done' ? now : null,
+  };
+  if (index === -1) entries.push(entry);
+  else entries[index] = entry;
+  await writePlansManifest(entries);
+}
+
+function isPlanManifestEntry(value: unknown): value is PlanManifestEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return record._type === 'plan' && typeof record.name === 'string' && (record.status === 'in-progress' || record.status === 'done') && typeof record.title === 'string' && typeof record.created_at === 'string' && (record.completed_at === null || typeof record.completed_at === 'string');
+}

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

@@ -0,0 +1,44 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isTaskMeta, isTaskRecord, type TaskMeta, type TaskRecord } from '../types.js';
+import { writeFileAtomic } from './atomic-write.js';
+
+const TASKS_FILE = 'tasks.jsonl';
+
+export interface TasksSnapshot { meta: TaskMeta; tasks: TaskRecord[] }
+
+export async function readTasksJsonl(planDir: string): Promise<TasksSnapshot | undefined> {
+  let text: string;
+  try { text = await readFile(join(planDir, TASKS_FILE), 'utf8'); } catch { return undefined; }
+  if (!text.trim()) throw new Error('tasks.jsonl is missing meta record');
+
+  let meta: TaskMeta | undefined;
+  const tasks: TaskRecord[] = [];
+  for (const [index, raw] of text.split(/\r?\n/).entries()) {
+    if (!raw.trim()) continue;
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch (error) { throw new Error(`Invalid JSONL at line ${index + 1}: ${(error as Error).message}`); }
+    if (isTaskMeta(parsed)) meta = parsed;
+    else if (isTaskRecord(parsed)) tasks.push(parsed);
+    else throw new Error(`Invalid tasks.jsonl record at line ${index + 1}`);
+  }
+  if (!meta) throw new Error('tasks.jsonl is missing meta record');
+  return { meta, tasks };
+}
+
+export async function writeTasksJsonl(planDir: string, meta: TaskMeta, tasks: TaskRecord[]): Promise<void> {
+  await mkdir(planDir, { recursive: true });
+  const content = [meta, ...tasks].map((record) => JSON.stringify(record)).join('\n') + '\n';
+  await writeFileAtomic(join(planDir, TASKS_FILE), content);
+}
+
+export async function updateTask(planDir: string, taskId: string, updates: Partial<Omit<TaskRecord, '_type' | 'id' | 'created_at'>>): Promise<TaskRecord> {
+  const snapshot = await readTasksJsonl(planDir);
+  if (!snapshot) throw new Error(`No tasks.jsonl found in ${planDir}`);
+  const index = snapshot.tasks.findIndex((task) => task.id === taskId);
+  if (index === -1) throw new Error(`Task not found: ${taskId}`);
+  const updated: TaskRecord = { ...snapshot.tasks[index], ...updates, updated_at: new Date().toISOString() };
+  snapshot.tasks[index] = updated;
+  await writeTasksJsonl(planDir, snapshot.meta, snapshot.tasks);
+  return updated;
+}

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

@@ -1,17 +1,17 @@
 /**
  * submit_plan tool — available during the plan phase.
- *
- * The planner calls this to submit a structured plan with typed steps.
- * Writes `.plans/<name>/plan.json` and updates the plans.json manifest.
  */
 
 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 { readPlansJson, serializePlansJson } from '../plans-json.js';
+import { renderPlanHtml } from '../html/render.js';
+import { saveHandoff } from '../storage/plan-storage.js';
+import { writeTasksJsonl } from '../storage/task-storage.js';
+import { upsertPlanEntry } from '../storage/plans-manifest.js';
 import { toKebabCase } from '../utils.js';
-import type { PlanData, PlanStep } from '../types.js';
+import type { PlanData, TaskMeta, TaskRecord } from '../types.js';
 
 export interface SubmitPlanCallbacks {
   onPlanSubmitted: (planDir: string, plan: PlanData) => void;
@@ -21,81 +21,56 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
   pi.registerTool({
     name: 'submit_plan',
     label: 'Submit Plan',
-    description:
-      'Submit a structured plan with a title, context, numbered steps, and risks. ' +
-      'Each step has a short description (for progress display) and detailed implementation instructions. ' +
-      'This finalizes the plan and writes it to .plans/<name>/plan.json.',
-    promptSnippet:
-      'Submit a structured plan with title, context, steps (description + details), and risks',
+    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',
     promptGuidelines: [
-      'Call submit_plan once when you have finished analyzing the codebase and are ready to finalize your plan.',
-      'Each submit_plan step description should be a short label (≤60 chars). Put full implementation instructions in the details field.',
-      'The submit_plan context field must include all codebase findings, relevant file paths, APIs, patterns, and constraints so an executor with zero prior context can implement the plan.',
+      '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.',
+      '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({
-      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' }),
-      context: Type.String({
-        description:
-          'Complete codebase context: relevant file paths, APIs, patterns, constraints, and gotchas',
-      }),
-      steps: Type.Array(
+      handoff: Type.String({ description: 'Markdown content for HANDOFF.md' }),
+      tasks: Type.Array(
         Type.Object({
-          description: Type.String({
-            description: 'Short step label for progress display (≤60 chars)',
-          }),
-          details: Type.String({
-            description: 'Full implementation instructions for this step',
-          }),
+          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' }),
+          depends_on: Type.Optional(Type.Array(Type.String({ description: 'Dependency task ID' }))),
         }),
         { minItems: 1 },
       ),
-      risks: Type.String({ description: 'Open questions, assumptions, and risks' }),
+      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 steps: PlanStep[] = params.steps.map((s) => ({
-        description: s.description.slice(0, 60),
-        details: s.details,
-        status: 'pending' as const,
+      const now = new Date().toISOString();
+      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,
+        description: task.description.slice(0, 60),
+        details: task.details,
+        status: 'pending',
+        depends_on: task.depends_on,
+        created_at: now,
+        updated_at: now,
       }));
+      const plan: PlanData = { title: params.title, planName, handoff: params.handoff, tasks };
 
-      const plan: PlanData = {
-        title: params.title,
-        context: params.context,
-        steps,
-        risks: params.risks,
-      };
-
-      // Write plan.json
       await mkdir(planDir, { recursive: true });
-      await writeFile(`${planDir}/plan.json`, JSON.stringify(plan, null, 2) + '\n', 'utf-8');
-
-      // Update plans.json manifest
-      const manifest = await readPlansJson();
-      const now = new Date().toISOString();
-      manifest[planName] = {
-        status: 'in-progress',
-        title: params.title,
-        created: manifest[planName]?.created ?? now,
-        completed: null,
-      };
-      await writeFile('.plans/plans.json', serializePlansJson(manifest), 'utf-8');
+      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 ${steps.length} steps. Waiting for user to review and execute.`,
-          },
-        ],
+        content: [{ type: 'text' as const, text: `Plan "${params.title}" saved with ${tasks.length} tasks. Review ${planDir}/plan.html, then execute when ready.` }],
         details: { planDir, plan },
         terminate: true,
       };
@@ -106,38 +81,15 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
       const title = (args as { title?: string }).title ?? '';
       let content = theme.fg('toolTitle', theme.bold('submit_plan '));
       content += theme.fg('accent', name);
-      if (title) {
-        content += ' ' + theme.fg('dim', `"${title}"`);
-      }
+      if (title) content += ' ' + theme.fg('dim', `"${title}"`);
       return new Text(content, 0, 0);
     },
 
     renderResult(result, _options, theme) {
-      const details = result.details as { plan?: PlanData } | undefined;
-      const plan = details?.plan;
-      if (!plan) {
-        return new Text(theme.fg('success', '✓ Plan saved'), 0, 0);
-      }
-
-      const lines: string[] = [];
-
-      // Title
-      lines.push(theme.fg('success', '✓ ') + theme.fg('accent', theme.bold(plan.title)));
-      lines.push('');
-
-      // Steps
-      for (let i = 0; i < plan.steps.length; i++) {
-        const step = plan.steps[i];
-        const num = theme.fg('muted', `${i + 1}.`);
-        lines.push(`  ${num} ${step.description}`);
-      }
-
-      // Risks
-      if (plan.risks) {
-        lines.push('');
-        lines.push(theme.fg('warning', '⚠ Risks: ') + theme.fg('dim', plan.risks));
-      }
-
+      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}`);
       return new Text(lines.join('\n'), 0, 0);
     },
   });

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

@@ -0,0 +1,82 @@
+/**
+ * update_task tool — available during the execution phase.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { StringEnum } from '@earendil-works/pi-ai';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+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>;
+}
+
+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.',
+    promptSnippet: 'Mark a plan task as done, skipped, or blocked',
+    promptGuidelines: [
+      'Call update_task after completing each plan task before moving to the next.',
+      'Always include notes summarizing what was done, why skipped, or why blocked.',
+      'Use update_task with status "blocked" and explain the reason in notes if a task cannot be completed.',
+    ],
+    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' })),
+    }),
+
+    async execute(_toolCallId, params) {
+      const plan = callbacks.getPlan();
+      if (!plan) throw new Error('No active plan. Cannot update task.');
+
+      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.`);
+      }
+
+      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 };
+      if (params.status === 'blocked') {
+        return {
+          content: [{ type: 'text' as const, text: `Task ${params.task_id} blocked. Execution paused — waiting for user input.` }],
+          details,
+          terminate: true,
+        };
+      }
+
+      const done = plan.tasks.filter((candidate) => candidate.status === 'done').length;
+      const skipped = plan.tasks.filter((candidate) => candidate.status === 'skipped').length;
+      const resolved = done + skipped;
+      const next = plan.tasks.find((candidate) => candidate.status === 'pending');
+      const statusEmoji = params.status === 'done' ? '✓' : '⊘';
+      let text = `${statusEmoji} Task ${params.task_id} ${params.status}. Progress: ${resolved}/${plan.tasks.length}`;
+      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 };
+    },
+
+    renderCall(args, theme) {
+      const taskId = (args as { task_id?: string }).task_id ?? '?';
+      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);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      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);
+    },
+  });
+}

package/extensions/plan-mode/types.ts

@@ -2,18 +2,32 @@
  * Shared types for plan mode.
  */
 
-export interface PlanStep {
+export type TaskStatus = 'pending' | 'done' | 'skipped' | 'blocked';
+
+export interface TaskRecord {
+  _type: 'task';
+  id: string;
   description: string;
   details: string;
-  status: 'pending' | 'done' | 'skipped' | 'blocked';
+  status: TaskStatus;
+  depends_on?: string[];
   notes?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface TaskMeta {
+  _type: 'meta';
+  title: string;
+  plan_name: string;
+  created_at: string;
 }
 
 export interface PlanData {
   title: string;
-  context: string;
-  steps: PlanStep[];
-  risks: string;
+  planName: string;
+  handoff: string;
+  tasks: TaskRecord[];
 }
 
 export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
@@ -30,3 +44,41 @@ export interface PersistedState {
   plan: PlanData | undefined;
   executionStartIdx: number | undefined;
 }
+
+const TASK_STATUSES = new Set<TaskStatus>(['pending', 'done', 'skipped', 'blocked']);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+export function isTaskRecord(value: unknown): value is TaskRecord {
+  if (!isRecord(value)) return false;
+
+  return (
+    value._type === 'task' &&
+    typeof value.id === 'string' &&
+    typeof value.description === 'string' &&
+    typeof value.details === 'string' &&
+    typeof value.status === 'string' &&
+    TASK_STATUSES.has(value.status as TaskStatus) &&
+    (value.depends_on === undefined || isStringArray(value.depends_on)) &&
+    (value.notes === undefined || typeof value.notes === 'string') &&
+    typeof value.created_at === 'string' &&
+    typeof value.updated_at === 'string'
+  );
+}
+
+export function isTaskMeta(value: unknown): value is TaskMeta {
+  if (!isRecord(value)) return false;
+
+  return (
+    value._type === 'meta' &&
+    typeof value.title === 'string' &&
+    typeof value.plan_name === 'string' &&
+    typeof value.created_at === 'string'
+  );
+}

package/extensions/plan-mode/ui.ts

@@ -1,5 +1,5 @@
 /**
- * Plan mode UI — status bar and step widget rendering.
+ * Plan mode UI — status bar and task widget rendering.
  */
 
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
@@ -9,8 +9,8 @@ export function updateUI(state: PlanModeState, ctx: ExtensionContext): void {
   const { theme } = ctx.ui;
 
   if (state.executing && state.plan) {
-    const done = state.plan.steps.filter((s) => s.status === 'done').length;
-    const total = state.plan.steps.length;
+    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.planEnabled) {
     ctx.ui.setStatus('plan-mode', theme.fg('warning', '📝 plan'));
@@ -19,17 +19,17 @@ export function updateUI(state: PlanModeState, ctx: ExtensionContext): void {
   }
 
   if (state.executing && state.plan) {
-    const lines = state.plan.steps.map((step, i) => {
-      const num = `${i + 1}. `;
-      switch (step.status) {
+    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(num + step.description));
+          return theme.fg('success', '✓ ') + theme.fg('muted', theme.strikethrough(label));
         case 'skipped':
-          return theme.fg('warning', '⊘ ') + theme.fg('muted', theme.strikethrough(num + step.description));
+          return theme.fg('warning', '⊘ ') + theme.fg('muted', theme.strikethrough(label));
         case 'blocked':
-          return theme.fg('error', '✗ ') + theme.fg('error', num + step.description);
+          return theme.fg('error', '✗ ') + theme.fg('error', label);
         default:
-          return theme.fg('muted', '☐ ') + (num + step.description);
+          return theme.fg('muted', '☐ ') + label;
       }
     });
     ctx.ui.setWidget('plan-todos', lines);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.10.1",
+  "version": "0.14.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"
@@ -18,6 +18,7 @@
   },
   "files": [
     "extensions",
+    "skills",
     "bin",
     "README.md",
     "CHANGELOG.md",
@@ -33,10 +34,14 @@
   "pi": {
     "extensions": [
       "./extensions/plan-mode"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "dependencies": {
-    "@dreki-gg/pi-command-sandbox": "^0.2.0"
+    "@dreki-gg/pi-command-sandbox": "^0.2.0",
+    "pug": "^3.0.3"
   },
   "devDependencies": {
     "@types/node": "24",

package/skills/technical-options/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: technical-options
+description: Generate and rank competing options for a technical decision using parallel evaluators. Use when the user wants a structured comparison of implementation approaches, architecture alternatives, or engineering tradeoffs before choosing one. Not for binary yes/no or pure preference decisions.
+---
+
+# Technical Options
+
+Generate competing proposals for a technical decision, challenge the framing, then fan out to parallel voting agents for ranking.
+
+## Process
+
+### 1. Understand the problem
+
+- Read relevant code and context
+- Identify the core constraint or failure mode driving the decision
+- Note available APIs, tools, and integration points
+
+### 2. Research (optional)
+
+Use `web_search` + `web_visit` if external patterns would help. Skip for purely internal decisions. If those tools are unavailable, proceed from repo context only.
+
+### 3. Generate 3–5 proposals
+
+Each proposal needs:
+- **Letter** (A–E) and a short memorable name
+- **One-paragraph description** with the key mechanism
+- **Pros and cons** — honest tradeoffs, not sales pitches
+
+Rules:
+- Span the solution space — don't cluster around one idea
+- Include a simplest-possible option and a most-robust option
+- Include an unconventional or contrarian option when possible
+- 3 proposals for small choices, 4–5 for architectural decisions
+
+### 4. Challenge the framing
+
+Before voting, spawn one `advisor` agent (or equivalent) with this task:
+
+> "Here are N proposals for [problem]. What important constraint, framing assumption, or missing approach is absent? If you find a materially distinct option the proposals don't cover, describe it. If the slate is well-shaped, say so."
+
+Only amend the proposal slate if the challenger surfaces a genuinely distinct option. Do not add variations of existing proposals.
+
+### 5. Fan out to 3 voting agents
+
+Use `subagent` in parallel mode with 3 tasks. Each voter gets identical proposals but a different evaluation preamble. The lenses are the contract; agent names are flexible — use `advisor`, `reviewer`, or whatever is available:
+
+**Lens 1 — Pragmatic engineer:**
+> "You value shipping speed and simplicity. You penalize over-engineering. A complex solution must justify its complexity with concrete failure modes the simple one can't handle."
+
+**Lens 2 — Reliability engineer:**
+> "You value robustness, crash recovery, and correctness over speed. You penalize approaches that work in happy paths but have edge-case blind spots. If two are equally correct, prefer the one that fails louder."
+
+**Lens 3 — Maintainability reviewer:**
+> "You value clean abstractions, testability, and long-term ownership cost. You penalize approaches that fight the framework or create implicit coupling. The best solution is one a new team member understands in 5 minutes."
+
+Each voter must output a strict ranking:
+```
+1st: [Letter] — [reason]
+2nd: [Letter] — [reason]
+...
+```
+
+Scale to 5 voters only for high-stakes decisions (new system boundaries, irreversible migrations, public API design).
+
+### 6. Tally and present
+
+**Scoring**: Borda count — 1st = N points, 2nd = N-1, ..., last = 1.
+
+**Tiebreaker**: Most 1st-place votes. If still tied, present the split to the user honestly and let them decide — do NOT force a winner.
+
+Present in this order:
+1. **Problem framing** (one sentence)
+2. **Proposals** (A–E with names)
+3. **Vote table** with per-voter rankings and scores
+4. **Winner** with consensus reasoning
+5. **Dissent** — where voters disagreed and why
+6. **Recommendation** — winner, plus any elements worth borrowing from runner-up
+7. **Question to user** — proceed, combine, or reconsider?
+
+### 7. Confirm with user
+
+Do NOT auto-implement. Ask whether to proceed with the winner, combine elements, or reconsider.
+
+## When NOT to use this
+
+- Binary yes/no decisions — just discuss pros/cons
+- Decisions with an obviously correct answer — just do it
+- Pure preference decisions with no technical tradeoffs — ask the user
+- Reversible decisions where trying the simplest option first is cheap

package/extensions/plan-mode/plans-json.ts

@@ -1,48 +0,0 @@
-/**
- * Reads and writes `.plans/plans.json` — the tracking manifest for plan lifecycle.
- *
- * Schema:
- * ```json
- * {
- *   "<plan-name>": {
- *     "status": "in-progress" | "done",
- *     "title": "Human-readable plan title",
- *     "created": "2026-05-08T12:00:00.000Z",
- *     "completed": "2026-05-08T13:00:00.000Z" | null
- *   }
- * }
- * ```
- */
-
-export interface PlanEntry {
-  status: 'in-progress' | 'done';
-  title: string;
-  created: string;
-  completed: string | null;
-}
-
-export type PlansManifest = Record<string, PlanEntry>;
-
-import { readFile } from 'node:fs/promises';
-
-const PLANS_JSON = '.plans/plans.json';
-
-/** Read plans.json, returning current manifest (empty object if missing). */
-export async function readPlansJson(): Promise<PlansManifest> {
-  try {
-    const text = await readFile(PLANS_JSON, 'utf-8');
-    if (text.trim()) {
-      return JSON.parse(text) as PlansManifest;
-    }
-  } catch {
-    // File doesn't exist or isn't valid JSON
-  }
-  return {};
-}
-
-/** Serialize the manifest to a formatted JSON string. */
-export function serializePlansJson(manifest: PlansManifest): string {
-  return `${JSON.stringify(manifest, null, 2)}\n`;
-}
-
-