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

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,67 @@
+/**
+ * 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 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,67 @@
+/**
+ * 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
+- context: complete codebase context including relevant file paths, APIs, patterns, constraints, and gotchas — this must be thorough enough that an implementor with zero prior context can execute the plan
+- steps: an array of steps, each with a short description (≤60 chars for display) and detailed implementation instructions
+- risks: any open questions, assumptions, or concerns
+
+Do NOT attempt to make product code changes — only analyze and plan.
+Do NOT write files manually — use submit_plan to finalize the plan.`;
+}
+
+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
+- 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}
+
+## Codebase context
+${plan.context}
+
+## All remaining steps
+${stepList}
+
+Start with step ${currentStep.num} NOW. When done, call update_step(step=${currentStep.num}, status="done").`;
+}

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/update-step.ts

@@ -103,6 +103,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

@@ -16,6 +16,13 @@ export interface PlanData {
   risks: string;
 }
 
+export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+
+export interface ExecPendingConfig {
+  model: { provider: string; id: string };
+  thinking: string;
+}
+
 export interface PersistedState {
   planEnabled: boolean;
   executing: boolean;

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.10.1",
   "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"
@@ -27,7 +27,8 @@
     "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": [