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

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

@@ -0,0 +1,87 @@
+/**
+ * Phase transitions — enter/exit plan mode, start execution, switch models.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { PlanModeState } from './state.js';
+import type { ThinkingLevel } from './types.js';
+import { PLAN_TOOLS, EXEC_TOOLS, PLAN_MODEL, PLAN_THINKING, EXEC_MODEL, EXEC_THINKING } from './constants.js';
+import { updateUI } from './ui.js';
+
+export async function switchModel(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  preset: { provider: string; id: string },
+): Promise<boolean> {
+  const model = ctx.modelRegistry.find(preset.provider, preset.id);
+  if (!model) {
+    ctx.ui.notify(`Model ${preset.provider}/${preset.id} not found`, 'error');
+    return false;
+  }
+  const ok = await pi.setModel(model);
+  if (!ok) {
+    ctx.ui.notify(`No API key for ${preset.provider}/${preset.id}`, 'error');
+    return false;
+  }
+  return true;
+}
+
+export async function enterPlanMode(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  state.planEnabled = true;
+  state.executing = false;
+  state.planDir = undefined;
+  state.plan = undefined;
+  state.previousThinking = pi.getThinkingLevel() as ThinkingLevel;
+  state.previousModel = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined;
+  pi.setActiveTools(PLAN_TOOLS);
+  await switchModel(pi, ctx, PLAN_MODEL);
+  pi.setThinkingLevel(PLAN_THINKING);
+  ctx.ui.notify(
+    `Plan mode ON — ${PLAN_MODEL.provider}/${PLAN_MODEL.id}:${PLAN_THINKING}`,
+    'info',
+  );
+  updateUI(state, ctx);
+  state.persist(pi);
+}
+
+export async function exitPlanMode(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const { previousModel, previousThinking } = state;
+  state.reset();
+  pi.setActiveTools(EXEC_TOOLS);
+  if (previousModel) {
+    await switchModel(pi, ctx, previousModel);
+  }
+  if (previousThinking) {
+    pi.setThinkingLevel(previousThinking);
+  }
+  ctx.ui.notify('Plan mode OFF — original model restored', 'info');
+  updateUI(state, ctx);
+  state.persist(pi);
+}
+
+export async function startExecution(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  state.planEnabled = false;
+  state.executing = true;
+  state.executionStartIdx = ctx.sessionManager.getEntries().length;
+  pi.setActiveTools(EXEC_TOOLS);
+  await switchModel(pi, ctx, EXEC_MODEL);
+  pi.setThinkingLevel(EXEC_THINKING);
+  ctx.ui.notify(
+    `Executing plan — ${EXEC_MODEL.provider}/${EXEC_MODEL.id}:${EXEC_THINKING}`,
+    'info',
+  );
+  updateUI(state, ctx);
+  state.persist(pi);
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Plan disk I/O — save/load plans, exec-pending markers, and manifest updates.
+ */
+
+import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import { readPlansJson, serializePlansJson } from './plans-json.js';
+import type { PlanData, ExecPendingConfig } from './types.js';
+import { EXEC_PENDING_FILE } from './constants.js';
+
+export async function savePlanToDisk(planDir: string, plan: PlanData): Promise<void> {
+  await mkdir(planDir, { recursive: true });
+  await writeFile(`${planDir}/plan.json`, JSON.stringify(plan, null, 2) + '\n', 'utf-8');
+}
+
+export async function loadPlanFromDisk(dir: string): Promise<PlanData | undefined> {
+  try {
+    const text = await readFile(`${dir}/plan.json`, 'utf-8');
+    return JSON.parse(text) as PlanData;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeExecPending(dir: string, config: ExecPendingConfig): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  await writeFile(`${dir}/${EXEC_PENDING_FILE}`, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+export async function readAndClearExecPending(): Promise<{ planDir: string; config: ExecPendingConfig } | undefined> {
+  try {
+    const entries = await readdir('.plans', { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dir = `.plans/${entry.name}`;
+      const markerPath = `${dir}/${EXEC_PENDING_FILE}`;
+      try {
+        const text = await readFile(markerPath, 'utf-8');
+        const config = JSON.parse(text) as ExecPendingConfig;
+        await unlink(markerPath);
+        return { planDir: dir, config };
+      } catch {
+        // No marker in this directory
+      }
+    }
+  } catch {
+    // .plans/ doesn't exist
+  }
+  return undefined;
+}
+
+export async function saveHandoff(planDir: string, content: string): Promise<void> {
+  await mkdir(planDir, { recursive: true });
+  await writeFile(`${planDir}/HANDOFF.md`, content, 'utf-8');
+}
+
+export async function loadHandoff(planDir: string): Promise<string | undefined> {
+  try {
+    return await readFile(`${planDir}/HANDOFF.md`, 'utf-8');
+  } catch {
+    return undefined;
+  }
+}
+
+export async function updatePlansManifest(
+  planName: string,
+  status: 'in-progress' | 'done',
+  title?: string,
+): Promise<void> {
+  const manifest = await readPlansJson();
+  const existing = manifest[planName];
+  const now = new Date().toISOString();
+  manifest[planName] = {
+    status,
+    title: title ?? existing?.title ?? 'Untitled plan',
+    created: existing?.created ?? now,
+    completed: status === 'done' ? now : null,
+  };
+  await mkdir('.plans', { recursive: true });
+  await writeFile('.plans/plans.json', serializePlansJson(manifest), 'utf-8');
+}

package/extensions/plan-mode/prompts.ts

@@ -0,0 +1,72 @@
+/**
+ * Prompt builders for plan and execution phases.
+ */
+
+import type { PlanData } from './types.js';
+import { PLAN_TOOLS } from './constants.js';
+
+export function buildPlanModePrompt(): string {
+  return `[PLAN MODE ACTIVE]
+You are in plan mode — a planning phase with strict bash restrictions.
+
+Restrictions:
+- Available tools: ${PLAN_TOOLS.join(', ')}
+- Bash is restricted to read-only commands (ls, grep, git status, etc.)
+
+Your task:
+1. Analyze the codebase thoroughly using the available read-only tools
+2. Ask clarifying questions if needed (use the questionnaire tool)
+3. Produce a detailed, concrete plan
+
+When you are ready to finalize the plan, call the submit_plan tool with:
+- name: a short kebab-case name (e.g. "add-auth-middleware")
+- title: a human-readable plan title
+- handoff: a markdown document that explains:
+  1. **What** change is being made and **why** it matters
+  2. The approach and key design decisions
+  3. Relevant codebase context: file paths, APIs, patterns, constraints, and gotchas
+  This document is saved as HANDOFF.md and must be clear to both human reviewers and executor agents.
+- steps: an array of steps, each with a short description (≤60 chars for display) and detailed implementation instructions
+
+Do NOT attempt to make product code changes — only analyze and plan.
+Do NOT write files manually — use submit_plan to finalize the plan.
+
+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.`;
+}
+
+export function buildExecutionPrompt(plan: PlanData): string | undefined {
+  const remaining = plan.steps
+    .map((s, i) => ({ ...s, num: i + 1 }))
+    .filter((s) => s.status === 'pending');
+
+  if (remaining.length === 0) return undefined;
+
+  const stepList = remaining
+    .map((s) => `${s.num}. ${s.description}\n   Details: ${s.details}`)
+    .join('\n\n');
+
+  const currentStep = remaining[0];
+
+  return `[EXECUTING PLAN — FOLLOW THE PLAN EXACTLY]
+
+You are executing a structured plan. Your ONLY job is to implement the plan steps below, one at a time.
+
+Rules:
+- Work on ONE step at a time, starting with step ${currentStep.num}
+- After completing each step, IMMEDIATELY call update_step to mark it done with notes summarizing what you changed (files modified, key decisions)
+- Do NOT run diagnostics, linters, test suites, or skills unless a step explicitly asks for it
+- Do NOT explore the codebase beyond what the current step requires
+- Do NOT deviate from the plan — if something seems wrong, call update_step with status "blocked"
+
+## Current step
+Step ${currentStep.num}: ${currentStep.description}
+Details: ${currentStep.details}
+
+## Handoff
+${plan.handoff}
+
+## All remaining steps
+${stepList}
+
+Start with step ${currentStep.num} NOW. When done, call update_step(step=${currentStep.num}, status="done", notes="<brief summary of what you did>").`;
+}

package/extensions/plan-mode/resume.ts

@@ -0,0 +1,121 @@
+/**
+ * Resume and execution handoff — pick up in-progress plans, model picker, new session handoff.
+ */
+
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { PlanModeState } from './state.js';
+import type { PlanData } from './types.js';
+import { EXEC_THINKING, EXEC_MODEL_OPTIONS } from './constants.js';
+import { readPlansJson } from './plans-json.js';
+import { loadPlanFromDisk, writeExecPending, savePlanToDisk } from './plan-storage.js';
+import { enterPlanMode } from './phase-transitions.js';
+
+export async function pickExecutionModel(
+  ctx: ExtensionContext,
+): Promise<{ provider: string; id: string } | undefined> {
+  const labels = EXEC_MODEL_OPTIONS.map((o) => o.label);
+  const choice = await ctx.ui.select('Execute with:', labels);
+  if (!choice) return undefined;
+  return EXEC_MODEL_OPTIONS.find((o) => o.label === choice)?.model;
+}
+
+export async function executeInNewSession(
+  ctx: ExtensionCommandContext,
+  dir: string,
+  _planData: PlanData,
+  kickoff: string,
+): Promise<void> {
+  const selectedModel = await pickExecutionModel(ctx);
+  if (!selectedModel) return;
+
+  await writeExecPending(dir, { model: selectedModel, thinking: EXEC_THINKING });
+  const parentSession = ctx.sessionManager.getSessionFile();
+
+  await ctx.newSession({
+    parentSession,
+    withSession: async (newCtx) => {
+      await newCtx.sendUserMessage(kickoff);
+    },
+  });
+}
+
+export async function resumePlan(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const manifest = await readPlansJson();
+  const inProgress = Object.entries(manifest).filter(([, e]) => e.status === 'in-progress');
+
+  if (inProgress.length === 0) {
+    ctx.ui.notify('No in-progress plans found in .plans/plans.json', 'info');
+    return;
+  }
+
+  const options = inProgress.map(([name, entry]) => `${name} — ${entry.title}`);
+  options.push('Cancel');
+
+  const choice = await ctx.ui.select('Resume which plan?', options);
+  if (!choice || choice === 'Cancel') return;
+
+  const planName = choice.split(' — ')[0];
+  const dir = `.plans/${planName}`;
+  const loaded = await loadPlanFromDisk(dir);
+
+  if (!loaded) {
+    ctx.ui.notify(`Could not load ${dir}/plan.json`, 'error');
+    return;
+  }
+
+  state.planDir = dir;
+  state.plan = loaded;
+
+  const doneCount = state.plan.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+  const pendingCount = state.plan.steps.filter((s) => s.status === 'pending').length;
+  const blockedCount = state.plan.steps.filter((s) => s.status === 'blocked').length;
+
+  if (pendingCount === 0 && blockedCount === 0) {
+    ctx.ui.notify(`Plan "${state.plan.title}" is already complete (${doneCount}/${state.plan.steps.length} done).`, 'info');
+    state.plan = undefined;
+    state.planDir = undefined;
+    return;
+  }
+
+  const summary = `${doneCount}/${state.plan.steps.length} done, ${pendingCount} pending${blockedCount ? `, ${blockedCount} blocked` : ''}`;
+  const action = await ctx.ui.select(
+    `Resume "${state.plan.title}" (${summary}) — what next?`,
+    ['Continue execution', 'Re-plan from scratch', 'Cancel'],
+  );
+
+  if (!action || action === 'Cancel') {
+    state.plan = undefined;
+    state.planDir = undefined;
+    return;
+  }
+
+  if (action === 'Re-plan from scratch') {
+    const planTitle = state.plan.title;
+    const planDirPath = state.planDir;
+    await enterPlanMode(state, pi, ctx);
+    pi.sendUserMessage(
+      `There is an existing plan "${planTitle}" at ${planDirPath}/plan.json. Review it and create a revised plan using submit_plan. Keep the same plan name ("${planName}").`,
+    );
+    return;
+  }
+
+  // Unblock any blocked steps
+  if (blockedCount > 0) {
+    for (const step of state.plan.steps) {
+      if (step.status === 'blocked') step.status = 'pending';
+    }
+    await savePlanToDisk(dir, state.plan);
+  }
+
+  const remaining = state.plan.steps
+    .map((s, i) => ({ ...s, num: i + 1 }))
+    .filter((s) => s.status === 'pending');
+  const stepList = remaining.map((s) => `${s.num}. ${s.description}`).join('\n');
+  const kickoff = `Resuming plan: "${state.plan.title}"\n\nCompleted: ${doneCount}/${state.plan.steps.length} steps\n\nRemaining steps:\n${stepList}\n\nContinue from step ${remaining[0].num}. Call update_step after completing each step.`;
+
+  await executeInNewSession(ctx, dir, state.plan, kickoff);
+}

package/extensions/plan-mode/state.ts

@@ -0,0 +1,47 @@
+/**
+ * Encapsulates all mutable plan-mode state with persistence helpers.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { PlanData, PersistedState, ThinkingLevel } from './types.js';
+
+export class PlanModeState {
+  planEnabled = false;
+  executing = false;
+  planDir: string | undefined;
+  plan: PlanData | undefined;
+  executionStartIdx: number | undefined;
+  previousThinking: ThinkingLevel | undefined;
+  previousModel: { provider: string; id: string } | undefined;
+
+  persist(pi: ExtensionAPI): void {
+    pi.appendEntry<PersistedState>('plan-mode', {
+      planEnabled: this.planEnabled,
+      executing: this.executing,
+      planDir: this.planDir,
+      plan: this.plan,
+      executionStartIdx: this.executionStartIdx,
+    });
+  }
+
+  restore(entries: Array<{ type: string; customType?: string; data?: PersistedState }>): void {
+    const saved = entries
+      .filter((e) => e.type === 'custom' && e.customType === 'plan-mode')
+      .pop();
+    if (saved?.data) {
+      this.planEnabled = saved.data.planEnabled ?? this.planEnabled;
+      this.executing = saved.data.executing ?? this.executing;
+      this.planDir = saved.data.planDir ?? this.planDir;
+      this.plan = saved.data.plan ?? this.plan;
+      this.executionStartIdx = saved.data.executionStartIdx ?? this.executionStartIdx;
+    }
+  }
+
+  reset(): void {
+    this.planEnabled = false;
+    this.executing = false;
+    this.planDir = undefined;
+    this.plan = undefined;
+    this.executionStartIdx = undefined;
+  }
+}

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

@@ -10,6 +10,7 @@ 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 { toKebabCase } from '../utils.js';
 import type { PlanData, PlanStep } from '../types.js';
 
@@ -22,24 +23,24 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
     name: 'submit_plan',
     label: 'Submit Plan',
     description:
-      'Submit a structured plan with a title, context, numbered steps, and risks. ' +
+      '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 and writes it to .plans/<name>/plan.json.',
+      'This finalizes the plan, writes .plans/<name>/plan.json and .plans/<name>/HANDOFF.md.',
     promptSnippet:
-      'Submit a structured plan with title, context, steps (description + details), and risks',
+      'Submit a structured plan with title, handoff (what/why/context), and steps',
     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.',
+      '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.',
     ],
     parameters: Type.Object({
       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({
+      handoff: Type.String({
         description:
-          'Complete codebase context: relevant file paths, APIs, patterns, constraints, and gotchas',
+          'Markdown content for HANDOFF.md — explains what change is being made, why, and includes relevant codebase context for the executor',
       }),
       steps: Type.Array(
         Type.Object({
@@ -52,7 +53,6 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
         }),
         { minItems: 1 },
       ),
-      risks: Type.String({ description: 'Open questions, assumptions, and risks' }),
     }),
 
     async execute(_toolCallId, params) {
@@ -67,14 +67,14 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
 
       const plan: PlanData = {
         title: params.title,
-        context: params.context,
+        handoff: params.handoff,
         steps,
-        risks: params.risks,
       };
 
-      // Write plan.json
+      // 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 saveHandoff(planDir, params.handoff);
 
       // Update plans.json manifest
       const manifest = await readPlansJson();
@@ -132,12 +132,6 @@ export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCa
         lines.push(`  ${num} ${step.description}`);
       }
 
-      // Risks
-      if (plan.risks) {
-        lines.push('');
-        lines.push(theme.fg('warning', '⚠ Risks: ') + theme.fg('dim', plan.risks));
-      }
-
       return new Text(lines.join('\n'), 0, 0);
     },
   });

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

@@ -27,6 +27,7 @@ export function registerUpdateStepTool(pi: ExtensionAPI, callbacks: UpdateStepCa
     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.',
     ],
@@ -103,6 +104,8 @@ export function registerUpdateStepTool(pi: ExtensionAPI, callbacks: UpdateStepCa
       return {
         content: [{ type: 'text' as const, text }],
         details,
+        // Stop the agent when all steps are done so agent_end fires immediately
+        terminate: !next,
       };
     },
 

package/extensions/plan-mode/types.ts

@@ -11,9 +11,15 @@ export interface PlanStep {
 
 export interface PlanData {
   title: string;
-  context: string;
+  handoff: string;
   steps: PlanStep[];
-  risks: string;
+}
+
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+
+export interface ExecPendingConfig {
+  model: { provider: string; id: string };
+  thinking: string;
 }
 
 export interface PersistedState {

package/extensions/plan-mode/ui.ts

@@ -0,0 +1,39 @@
+/**
+ * Plan mode UI — status bar and step widget rendering.
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { PlanModeState } from './state.js';
+
+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;
+    ctx.ui.setStatus('plan-mode', theme.fg('accent', `📋 exec ${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.steps.map((step, i) => {
+      const num = `${i + 1}. `;
+      switch (step.status) {
+        case 'done':
+          return theme.fg('success', '✓ ') + theme.fg('muted', theme.strikethrough(num + step.description));
+        case 'skipped':
+          return theme.fg('warning', '⊘ ') + theme.fg('muted', theme.strikethrough(num + step.description));
+        case 'blocked':
+          return theme.fg('error', '✗ ') + theme.fg('error', num + step.description);
+        default:
+          return theme.fg('muted', '☐ ') + (num + step.description);
+      }
+    });
+    ctx.ui.setWidget('plan-todos', lines);
+  } else {
+    ctx.ui.setWidget('plan-todos', undefined);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.7.2",
+  "version": "0.13.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",
@@ -27,11 +28,15 @@
     "typecheck": "tsc --noEmit",
     "lint": "oxlint extensions bin",
     "format": "oxfmt --write extensions bin",
-    "format:check": "oxfmt --check extensions bin"
+    "format:check": "oxfmt --check extensions bin",
+    "test": "bun test extensions/plan-mode/__tests__"
   },
   "pi": {
     "extensions": [
       "./extensions/plan-mode"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "dependencies": {