@dreki-gg/pi-plan-mode 0.20.1 → 0.23.0

package/extensions/plan-mode/commands/list-plans.ts

@@ -0,0 +1,229 @@
+/**
+ * /plans command — list, filter, and sort plans interactively.
+ *
+ * Reads from the plans manifest AND task snapshots to build a rich table
+ * with status, task counts, and dates. The user can filter by status and
+ * sort by different criteria via interactive selectors.
+ */
+
+import { Effect } from 'effect';
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { FileSystem } from '../effects/filesystem.js';
+import { readPlansManifest, type PlanManifestEntry } from '../storage/plans-manifest.js';
+import { readTasksJsonl } from '../storage/task-storage.js';
+import type { PlanStatus } from '../types.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type SortField = 'name' | 'date-asc' | 'date-desc' | 'tasks';
+export type StatusFilter = 'all' | PlanStatus;
+
+export interface PlanListItem {
+  name: string;
+  title: string;
+  status: PlanStatus;
+  created_at: string;
+  completed_at: string | null;
+  totalTasks: number;
+  doneTasks: number;
+  pendingTasks: number;
+}
+
+// ── Core logic (pure, testable) ──────────────────────────────────────────────
+
+export function filterPlans(plans: PlanListItem[], filter: StatusFilter): PlanListItem[] {
+  if (filter === 'all') return plans;
+  return plans.filter((p) => p.status === filter);
+}
+
+export function sortPlans(plans: PlanListItem[], sort: SortField): PlanListItem[] {
+  const sorted = [...plans];
+  switch (sort) {
+    case 'name':
+      sorted.sort((a, b) => a.name.localeCompare(b.name));
+      break;
+    case 'date-asc':
+      sorted.sort((a, b) => a.created_at.localeCompare(b.created_at));
+      break;
+    case 'date-desc':
+      sorted.sort((a, b) => b.created_at.localeCompare(a.created_at));
+      break;
+    case 'tasks':
+      sorted.sort((a, b) => b.totalTasks - a.totalTasks);
+      break;
+  }
+  return sorted;
+}
+
+const STATUS_ICON: Record<PlanStatus, string> = {
+  'in-progress': '🔵',
+  done: '✅',
+  superseded: '🔄',
+  abandoned: '❌',
+};
+
+export function formatPlanList(plans: PlanListItem[], filter: StatusFilter, sort: SortField): string {
+  if (plans.length === 0) {
+    return filter === 'all'
+      ? 'No plans found in .plans/plans.jsonl'
+      : `No plans with status "${filter}"`;
+  }
+
+  const sortLabel: Record<SortField, string> = {
+    name: 'name',
+    'date-asc': 'oldest first',
+    'date-desc': 'newest first',
+    tasks: 'most tasks first',
+  };
+
+  const header =
+    filter === 'all'
+      ? `All plans (${plans.length}) — sorted by ${sortLabel[sort]}`
+      : `Plans: ${filter} (${plans.length}) — sorted by ${sortLabel[sort]}`;
+
+  const lines = plans.map((p) => {
+    const icon = STATUS_ICON[p.status];
+    const progress =
+      p.totalTasks > 0 ? ` [${p.doneTasks}/${p.totalTasks} tasks]` : ' [no tasks]';
+    const date = p.created_at.slice(0, 10);
+    return `  ${icon} ${p.name} — ${p.title}${progress}  (${date})`;
+  });
+
+  return `${header}\n${lines.join('\n')}`;
+}
+
+// ── Data loading (Effect-based) ──────────────────────────────────────────────
+
+export function loadPlanListItems(): Effect.Effect<PlanListItem[], never, FileSystem> {
+  return Effect.gen(function* () {
+    const manifest = yield* Effect.orElseSucceed(readPlansManifest(), () => [] as PlanManifestEntry[]);
+    const items: PlanListItem[] = [];
+
+    for (const entry of manifest) {
+      const dir = `.plans/${entry.name}`;
+      const snapshot = yield* Effect.orElseSucceed(readTasksJsonl(dir), () => undefined);
+      const totalTasks = snapshot?.tasks.length ?? 0;
+      const doneTasks = snapshot?.tasks.filter(
+        (t) => t.status === 'done' || t.status === 'skipped',
+      ).length ?? 0;
+      const pendingTasks = snapshot?.tasks.filter((t) => t.status === 'pending').length ?? 0;
+
+      items.push({
+        name: entry.name,
+        title: entry.title,
+        status: entry.status,
+        created_at: entry.created_at,
+        completed_at: entry.completed_at,
+        totalTasks,
+        doneTasks,
+        pendingTasks,
+      });
+    }
+
+    return items;
+  });
+}
+
+// ── Interactive command handler ──────────────────────────────────────────────
+
+export async function handleListPlans(
+  ctx: ExtensionCommandContext,
+  runPlanIO: RunPlanIO,
+  args?: string,
+): Promise<void> {
+  const allItems = await runPlanIO(loadPlanListItems());
+
+  if (allItems.length === 0) {
+    ctx.ui.notify('No plans found in .plans/plans.jsonl', 'info');
+    return;
+  }
+
+  // Parse inline args: /plans [filter] [sort]
+  // e.g. /plans done tasks, /plans in-progress date-asc
+  let filter: StatusFilter = 'all';
+  let sort: SortField = 'date-desc';
+
+  if (args?.trim()) {
+    const parsed = parseArgs(args.trim());
+    filter = parsed.filter;
+    sort = parsed.sort;
+  } else {
+    // Interactive mode: ask the user
+    const filterChoice = await ctx.ui.select('Filter plans by status:', [
+      'All',
+      'In-progress',
+      'Done',
+      'Superseded',
+      'Abandoned',
+    ]);
+    if (!filterChoice) return;
+
+    const filterMap: Record<string, StatusFilter> = {
+      All: 'all',
+      'In-progress': 'in-progress',
+      Done: 'done',
+      Superseded: 'superseded',
+      Abandoned: 'abandoned',
+    };
+    filter = filterMap[filterChoice] ?? 'all';
+
+    const sortChoice = await ctx.ui.select('Sort by:', [
+      'Newest first',
+      'Oldest first',
+      'Most tasks',
+      'Name',
+    ]);
+    if (!sortChoice) return;
+
+    const sortMap: Record<string, SortField> = {
+      'Newest first': 'date-desc',
+      'Oldest first': 'date-asc',
+      'Most tasks': 'tasks',
+      Name: 'name',
+    };
+    sort = sortMap[sortChoice] ?? 'date-desc';
+  }
+
+  const filtered = filterPlans(allItems, filter);
+  const sorted = sortPlans(filtered, sort);
+  const output = formatPlanList(sorted, filter, sort);
+
+  ctx.ui.notify(output, 'info');
+}
+
+// ── Arg parsing ──────────────────────────────────────────────────────────────
+
+const FILTER_ALIASES: Record<string, StatusFilter> = {
+  all: 'all',
+  'in-progress': 'in-progress',
+  pending: 'in-progress',
+  active: 'in-progress',
+  done: 'done',
+  completed: 'done',
+  superseded: 'superseded',
+  abandoned: 'abandoned',
+};
+
+const SORT_ALIASES: Record<string, SortField> = {
+  name: 'name',
+  'date-asc': 'date-asc',
+  oldest: 'date-asc',
+  'date-desc': 'date-desc',
+  newest: 'date-desc',
+  tasks: 'tasks',
+  'task-count': 'tasks',
+};
+
+export function parseArgs(raw: string): { filter: StatusFilter; sort: SortField } {
+  const tokens = raw.toLowerCase().split(/\s+/);
+  let filter: StatusFilter = 'all';
+  let sort: SortField = 'date-desc';
+
+  for (const token of tokens) {
+    if (FILTER_ALIASES[token]) filter = FILTER_ALIASES[token];
+    else if (SORT_ALIASES[token]) sort = SORT_ALIASES[token];
+  }
+
+  return { filter, sort };
+}

package/extensions/plan-mode/constants.ts

@@ -10,12 +10,14 @@ export const PLAN_TOOLS = [
   'find',
   'ls',
   'submit_plan',
+  'revise_plan',
   'preview_prototype',
   'write',
   'questionnaire',
   'search_skills',
   'subagent',
   'plan_status',
+  'set_active_plan',
   'update_plan',
   'reconcile_plans',
 ];
@@ -29,6 +31,7 @@ export const EXEC_TOOLS = [
   'update_tasks',
   'add_task',
   'plan_status',
+  'set_active_plan',
   'update_plan',
   'reconcile_plans',
 ];

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

@@ -1,24 +1,47 @@
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import pug from 'pug';
+/**
+ * Prototype document builder.
+ *
+ * A prototype is a planning-phase visual aid the agent authors freely — there
+ * is no template engine and no imposed theme. Whatever HTML the agent (or a
+ * delegated ux-designer subagent) writes is what the user sees.
+ *
+ * The only thing this does is tolerate a bare fragment: if the agent passes
+ * body-only markup instead of a complete page, we drop it into a minimal,
+ * UNSTYLED shell so the browser still renders it. No fonts, colors, or layout
+ * are injected — the design is entirely the agent's.
+ */
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
 
-const templatePath = join(dirname(fileURLToPath(import.meta.url)), 'templates', 'prototype.pug');
+/** True when the markup is already a complete HTML page. */
+function isFullDocument(markup: string): boolean {
+  return /<!doctype\s+html|<html[\s>]/i.test(markup);
+}
 
 /**
- * Renders a standalone prototype preview: a minimal header (title + one-line
- * intent) wrapping the rendered Pug body. This is a planning-phase visual aid,
- * not a plan dump — no tasks, no handoff.
+ * Returns a standalone HTML document for the prototype. Full documents are
+ * passed through verbatim; fragments are wrapped in a barebones shell.
  */
-export function renderPrototypeHtml(title: string, intent: string, pugBody: string): string {
-  const template = readFileSync(templatePath, 'utf8');
-  const prototypeHtml = pugBody.trim() ? pug.render(pugBody) : '';
+export function buildPrototypeDocument(title: string, html: string): string {
+  const markup = html.trim();
+
+  if (isFullDocument(markup)) return markup;
 
-  return pug.render(template, {
-    filename: templatePath,
-    title,
-    intent,
-    prototypeHtml,
-    generatedAt: new Date().toISOString(),
-  });
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+</head>
+<body>
+${markup}
+</body>
+</html>`;
 }

package/extensions/plan-mode/index.ts

@@ -38,17 +38,20 @@ import { filterExecutionMessages, filterStalePlanMessages } from './context-filt
 import { activeTasksResolved, deferredTasks, isPlanFinalizable } from './task-status.js';
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
-import { resolveActivePlan } from './resolve-plan.js';
+import { resolveActivePlan, focusActivePlan } from './resolve-plan.js';
 import { collectPlanDrift } from './reconcile.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
+import { registerRevisePlanTool } from './tools/revise-plan.js';
 import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
 import { registerUpdateTasksTool } from './tools/update-tasks.js';
 import { registerAddTaskTool } from './tools/add-task.js';
 import { registerPlanStatusTool } from './tools/plan-status.js';
+import { registerSetActivePlanTool } from './tools/set-active-plan.js';
 import { registerUpdatePlanTool } from './tools/update-plan.js';
 import { registerReconcilePlansTool } from './tools/reconcile-plans.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
+import { handleListPlans } from './commands/list-plans.js';
 
 export default function planMode(pi: ExtensionAPI): void {
   const state = new PlanModeState();
@@ -71,6 +74,15 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerRevisePlanTool(pi, runPlanIO, {
+    resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
+    onPlanRevised: (dir, revisedPlan) => {
+      state.planDir = dir;
+      state.plan = revisedPlan;
+      state.persist(pi);
+    },
+  });
+
   registerPreviewPrototypeTool(pi, runPlanIO);
 
   // Shared task-write closure: mutate the in-memory task, persist tasks.jsonl,
@@ -169,6 +181,10 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerSetActivePlanTool(pi, {
+    setActivePlan: (name) => focusActivePlan(state, pi, runPlanIO, name),
+  });
+
   registerUpdatePlanTool(pi, runPlanIO);
   registerReconcilePlansTool(pi, runPlanIO);
 
@@ -220,10 +236,7 @@ export default function planMode(pi: ExtensionAPI): void {
           ctx.ui.notify('Usage: /plan focus <name>', 'info');
           return;
         }
-        // Clear any stale in-memory plan so the hint re-attaches from disk.
-        state.plan = undefined;
-        state.planDir = undefined;
-        const { plan, candidates } = await resolveActivePlan(state, pi, runPlanIO, { name });
+        const { plan, candidates } = await focusActivePlan(state, pi, runPlanIO, name);
         if (plan) {
           ctx.ui.notify(`Focused plan: ${plan.title} (${plan.planName})`, 'info');
         } else {
@@ -256,6 +269,14 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerCommand('plans', {
+    description:
+      'List all plans with filtering and sorting. Usage: /plans [filter] [sort]. Filters: all, in-progress, done, superseded, abandoned. Sorts: newest, oldest, tasks, name.',
+    handler: async (args, ctx) => {
+      await handleListPlans(ctx, runPlanIO, args);
+    },
+  });
+
   pi.registerCommand('todos', {
     description: 'Show current plan progress',
     handler: async (_args, ctx) => {

package/extensions/plan-mode/prompts.ts

@@ -33,7 +33,9 @@ Plan weight:
 
 submit_plan is finalization, not the starting point. It records tasks and the handoff — it does not generate HTML.
 
-For visual/UI/layout/style work, build a prototype with preview_prototype DURING planning, before submit_plan, so the user can react to the visual before the plan hardens. The visual-prototype skill covers when and how.
+If a plan with the same name already exists and the user asks for follow-up changes (e.g. you submitted prematurely), call revise_plan instead of submit_plan. It rewrites the existing plan in place — pass only the fields that change (title, handoff, and/or tasks); status and notes are preserved for tasks whose id is unchanged.
+
+For visual/UI/layout/style work, build a prototype with preview_prototype DURING planning, before submit_plan, so the user can react to the visual before the plan hardens. You author the HTML freely — no template engine, no imposed theme — and can delegate the markup to the ux-designer subagent for real design taste. The visual-prototype skill covers when and how.
 
 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.`;
 }

package/extensions/plan-mode/resolve-plan.ts

@@ -116,3 +116,21 @@ export async function resolveActivePlan(
 
   return { plan: undefined, candidates: inProgress.map((entry) => entry.name) };
 }
+
+/**
+ * Pin a plan as the active one (the tool/command form of `/plan focus`).
+ *
+ * Clears any stale in-memory plan first so the hint always re-attaches from
+ * disk, then resolves by name. Returns the same `ResolvedPlan` shape so callers
+ * can report success or surface in-progress candidates on a miss.
+ */
+export async function focusActivePlan(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  runPlanIO: RunPlanIO,
+  name: string,
+): Promise<ResolvedPlan> {
+  state.plan = undefined;
+  state.planDir = undefined;
+  return resolveActivePlan(state, pi, runPlanIO, { name });
+}

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

@@ -49,6 +49,7 @@ export function registerPlanStatusTool(pi: ExtensionAPI, callbacks: PlanStatusCa
     promptGuidelines: [
       'Call plan_status when unsure whether a plan is active or which task ids exist — it is read-only and never mutates state.',
       'Prefer it over guessing task ids; the returned ids are what update_task expects.',
+      'When it reports multiple in-progress plans, call set_active_plan to pin one before update_task / add_task.',
     ],
     parameters: Type.Object({
       plan: Type.Optional(
@@ -74,7 +75,7 @@ export function registerPlanStatusTool(pi: ExtensionAPI, callbacks: PlanStatusCa
             })
             .join('\n');
           const text =
-            `No single active plan — ${summaries.length} in-progress. Pass { plan: "<name>" } to target one.\n` +
+            `No single active plan — ${summaries.length} in-progress. Pass { plan: "<name>" } or call set_active_plan to target one.\n` +
             `Progress:\n${rows}`;
           return {
             content: [{ type: 'text' as const, text }],

package/extensions/plan-mode/tools/preview-prototype.ts

@@ -1,9 +1,9 @@
 /**
  * preview_prototype tool — available during the plan phase.
  *
- * Renders a Pug prototype to a standalone HTML visual aid, writes it under
- * .plans/_prototypes/, and best-effort opens it so the user can react to the
- * visual BEFORE the plan is finalized.
+ * Persists a freeform HTML prototype the agent authored (no template engine,
+ * no imposed theme), writes it under .plans/_prototypes/, and best-effort opens
+ * it so the user can react to the visual BEFORE the plan is finalized.
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
@@ -14,7 +14,7 @@ import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import { FileSystem } from '../effects/filesystem.js';
 import type { RunPlanIO } from '../effects/runtime.js';
-import { renderPrototypeHtml } from '../html/render.js';
+import { buildPrototypeDocument } from '../html/render.js';
 import { toKebabCase } from '../utils.js';
 
 const PREVIEW_DIR = '.plans/_prototypes';
@@ -41,25 +41,30 @@ export function registerPreviewPrototypeTool(pi: ExtensionAPI, runPlanIO: RunPla
     name: 'preview_prototype',
     label: 'Preview Prototype',
     description:
-      'Render a Pug prototype to a standalone HTML visual aid and open it for review during planning.',
-    promptSnippet: 'Render a Pug UI prototype to HTML and open it for the user to review',
+      'Open a freeform HTML prototype for review during planning. You write the HTML — any markup, styles, fonts, and scripts you want — and the tool just persists and opens it.',
+    promptSnippet: 'Open a freeform HTML prototype for the user to review',
     promptGuidelines: [
       'Use preview_prototype during planning for visual/UI/layout/style work, before submit_plan.',
       'The prototype is a convergence aid — show it so the user can react before the plan hardens.',
-      'Keep the Pug self-contained; inline any styles the prototype needs.',
+      'You have full freedom over the HTML: there is no template engine and no imposed theme. Avoid generic boilerplate — design something that fits the actual product.',
+      'For real design taste, consider delegating the markup to the ux-designer subagent and passing its HTML straight through.',
+      'Pass a complete, self-contained HTML document (doctype + html/head/body). Inline any styles or scripts; assume nothing about a host page.',
     ],
     parameters: Type.Object({
       title: Type.String({ description: 'Short title for the prototype' }),
       intent: Type.String({
         description: 'One-line description of what this prototype is showing',
       }),
-      pug: Type.String({ description: 'Pug markup for the prototype body' }),
+      html: Type.String({
+        description:
+          'Complete, self-contained HTML document for the prototype (your own markup, styles, and scripts). A bare fragment is also accepted and wrapped in a minimal unstyled shell.',
+      }),
     }),
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const slug = toKebabCase(params.title) || 'prototype';
       const filePath = join(PREVIEW_DIR, `${slug}.html`);
-      const html = renderPrototypeHtml(params.title, params.intent, params.pug);
+      const html = buildPrototypeDocument(params.title, params.html);
 
       await runPlanIO(
         Effect.gen(function* () {