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

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

@@ -1,18 +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 { saveHandoff } from '../plan-storage.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;
@@ -22,80 +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, handoff document, and numbered steps. ' +
-      'Each step has a short description (for progress display) and detailed implementation instructions. ' +
-      'This finalizes the plan, writes .plans/<name>/plan.json and .plans/<name>/HANDOFF.md.',
-    promptSnippet:
-      'Submit a structured plan with title, handoff (what/why/context), and steps',
+    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 handoff field is a markdown document explaining what change is being made, why it matters, and all relevant codebase context (file paths, APIs, patterns, constraints). It must be thorough enough that both a human reviewer and an executor agent with zero prior context can understand 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' }),
-      handoff: Type.String({
-        description:
-          'Markdown content for HANDOFF.md — explains what change is being made, why, and includes relevant codebase context for the executor',
-      }),
-      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 },
       ),
+      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,
-        handoff: params.handoff,
-        steps,
-      };
-
-      // Write plan.json and HANDOFF.md
       await mkdir(planDir, { recursive: true });
-      await writeFile(`${planDir}/plan.json`, JSON.stringify(plan, null, 2) + '\n', 'utf-8');
+      await writeTasksJsonl(planDir, meta, tasks);
       await saveHandoff(planDir, params.handoff);
-
-      // 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 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,32 +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}`);
-      }
-
+      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,17 +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;
+  planName: string;
   handoff: string;
-  steps: PlanStep[];
+  tasks: TaskRecord[];
 }
 
 export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
@@ -29,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.13.0",
+  "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"
@@ -40,7 +40,8 @@
     ]
   },
   "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/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`;
-}
-
-

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

@@ -1,146 +0,0 @@
-/**
- * update_step tool — available during the execution phase.
- *
- * The executor calls this to mark a plan step as done, skipped, or blocked.
- * On "blocked", returns a stop signal so the executor pauses for user intervention.
- */
-
-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 } from '../types.js';
-
-export interface UpdateStepCallbacks {
-  getPlan: () => PlanData | undefined;
-  onStepUpdated: (step: number, status: 'done' | 'skipped' | 'blocked', notes?: string) => void;
-}
-
-export function registerUpdateStepTool(pi: ExtensionAPI, callbacks: UpdateStepCallbacks): void {
-  pi.registerTool({
-    name: 'update_step',
-    label: 'Update Step',
-    description:
-      'Mark a plan step as done, skipped, or blocked. ' +
-      'Call this after completing each step. ' +
-      'If a step is blocked, execution will pause for user intervention.',
-    promptSnippet: 'Mark a plan step as done, skipped, or blocked',
-    promptGuidelines: [
-      'Call update_step after completing each plan step to mark it done before moving to the next.',
-      'Always include notes when calling update_step — summarize what was done (files changed, key decisions made) for done steps, why it was unnecessary for skipped steps, or what went wrong for blocked steps.',
-      'Use update_step with status "skipped" if a step is unnecessary after inspecting the code.',
-      'Use update_step with status "blocked" and explain the reason in notes if a step cannot be completed — execution will pause for user input.',
-    ],
-    parameters: Type.Object({
-      step: Type.Number({ description: 'Step number (1-indexed)' }),
-      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 step.');
-      }
-
-      const stepIdx = params.step - 1;
-      if (stepIdx < 0 || stepIdx >= plan.steps.length) {
-        throw new Error(
-          `Invalid step number ${params.step}. Plan has ${plan.steps.length} steps.`,
-        );
-      }
-
-      const step = plan.steps[stepIdx];
-      if (step.status !== 'pending') {
-        throw new Error(
-          `Step ${params.step} is already "${step.status}". Only pending steps can be updated.`,
-        );
-      }
-
-      callbacks.onStepUpdated(params.step, params.status, params.notes);
-
-      const details = {
-        step: params.step,
-        status: params.status,
-        notes: params.notes,
-        description: step.description,
-      };
-
-      if (params.status === 'blocked') {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `Step ${params.step} blocked. Execution paused — waiting for user input.`,
-            },
-          ],
-          details,
-          terminate: true,
-        };
-      }
-
-      // Build progress info
-      const done = plan.steps.filter((s) => s.status === 'done').length;
-      const skipped = plan.steps.filter((s) => s.status === 'skipped').length;
-      const resolved = done + skipped;
-
-      const statusEmoji = params.status === 'done' ? '✓' : '⊘';
-      let text = `${statusEmoji} Step ${params.step} ${params.status}. Progress: ${resolved}/${plan.steps.length}`;
-      if (params.notes) {
-        text += ` — ${params.notes}`;
-      }
-
-      // Find next pending step
-      const next = plan.steps.find((s) => s.status === 'pending');
-      if (next) {
-        const nextIdx = plan.steps.indexOf(next) + 1;
-        text += `\n\nNext step ${nextIdx}: ${next.description}`;
-      } else {
-        text += '\n\nAll steps resolved!';
-      }
-
-      return {
-        content: [{ type: 'text' as const, text }],
-        details,
-        // Stop the agent when all steps are done so agent_end fires immediately
-        terminate: !next,
-      };
-    },
-
-    renderCall(args, theme) {
-      const step = (args as { step?: number }).step ?? '?';
-      const status = (args as { status?: string }).status ?? '';
-      let content = theme.fg('toolTitle', theme.bold('update_step '));
-      content += theme.fg('muted', `#${step}`);
-      if (status) {
-        const color = status === 'done' ? 'success' : status === 'skipped' ? 'warning' : 'error';
-        content += ' ' + theme.fg(color, status);
-      }
-      return new Text(content, 0, 0);
-    },
-
-    renderResult(result, _options, theme) {
-      const details = result.details as {
-        step?: number;
-        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', '✗'),
-      };
-
-      const icon = statusMap[details.status ?? ''] ?? '';
-      const desc = details.description ?? '';
-      return new Text(`${icon} Step ${details.step}: ${desc}`, 0, 0);
-    },
-  });
-}