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

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.13.0
+
+### Minor Changes
+
+- Replace context+risks with HANDOFF.md and step summaries. submit_plan now writes a HANDOFF.md alongside plan.json. Completion message shows an actual summary of changes from step notes instead of just a checklist. Executor is prompted to always include notes summarizing what was done.
+
+## 0.12.1
+
+### Patch Changes
+
+- Include `skills/` directory in package files so the bundled technical-options skill is published.
+
+## 0.12.0
+
+### Minor Changes
+
+- Bundle `technical-options` skill inside the package (installable via `pi.skills`). The planner prompt now explicitly tells the agent to generate proposals itself and only delegate voting to subagents, keeping the planner visible as the main agent.
+
+## 0.11.0
+
+### Minor Changes
+
+- Integrate technical-options skill into plan mode: add `subagent` to plan-phase tools and nudge the planner to use structured proposal evaluation when facing significant design decisions with multiple viable approaches.
+
+## 0.10.1
+
+### Patch Changes
+
+- Fix "Execute Plan" menu option crashing with "Agent is already processing" error. The `sendUserMessage('/plan-exec')` call inside the `agent_end` handler was missing `deliverAs: 'followUp'`. Added regression test that scans all `sendUserMessage` calls inside `agent_end` handlers to ensure they always include `deliverAs`.
+
+## 0.10.0
+
+### Minor Changes
+
+- Refactor: extract plan-mode god module into domain-driven modules. index.ts goes from ~780 to ~308 lines.
+
+  New files:
+
+  - `constants.ts` — tool sets, model presets, thinking levels, model picker options
+  - `state.ts` — PlanModeState class encapsulating all mutable state with persist/restore
+  - `plan-storage.ts` — disk I/O: save/load plans, exec-pending markers, manifest updates
+  - `ui.ts` — status bar and step widget rendering
+  - `prompts.ts` — plan phase and execution phase prompt builders
+  - `context-filter.ts` — message filtering for context event
+  - `phase-transitions.ts` — enter/exit plan mode, start execution, model switching
+  - `resume.ts` — resume flow, model picker, new session handoff
+
+  No functional changes — pure structural refactor.
+
+## 0.9.2
+
+### Patch Changes
+
+- Fix plan completion not triggering immediately: update_step now returns `terminate: true` when all steps are resolved, so the agent stops and agent_end fires right away with the completion message.
+
+## 0.9.1
+
+### Patch Changes
+
+- Simplify execution model picker to just two preset options: gpt-5.5 and claude-opus-4-6. No more nested registry browsing.
+
+## 0.9.0
+
+### Minor Changes
+
+- Plan execution now launches in a clean session via `ctx.newSession()` for true context isolation. The executor gets a fresh context window with zero planning history, no skill references, and no system prompt pollution — fixing the root cause of rogue executor behavior.
+
+  New features:
+
+  - Model picker before execution: choose Default, Previous, or any model from registry
+  - `/plan-exec` command for direct execution handoff
+  - Removed `search_skills` from execution tools (executor follows the plan, not skills)
+
+  Breaking: Execution always creates a new session. The planning session is preserved and linked via parentSession.
+
+## 0.8.1
+
+### Patch Changes
+
+- Strengthen execution context injection to prevent the agent from going rogue. The prompt now explicitly forbids running diagnostics/skills/linters unless a step asks for it, highlights the current step front and center, and demands immediate update_step calls.
+
+## 0.8.0
+
+### Minor Changes
+
+- Add `/plan resume` command to pick up in-progress plans from disk. Shows a list of in-progress plans from `.plans/plans.json`, lets the user select one, and resumes execution from where it left off. Also supports re-planning from scratch.
+
+## 0.7.4
+
+### Patch Changes
+
+- Simplify "Follow up" menu option: just dismiss the menu and let the user type naturally instead of opening an editor. The planner remains active with submit_plan available.
+
+## 0.7.3
+
+### Patch Changes
+
+- Fix "Follow up" menu option to wrap user message with planner context, instructing the agent to revise and resubmit the plan via submit_plan.
+
 ## 0.7.2
 
 ### Patch Changes

package/extensions/plan-mode/__tests__/agent-end-safety.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Regression tests for plan-mode extension wiring.
+ *
+ * These are static analysis tests that scan source code for common mistakes
+ * that cause runtime errors in the pi extension lifecycle.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const INDEX_PATH = join(import.meta.dir, '..', 'index.ts');
+const indexSource = readFileSync(INDEX_PATH, 'utf-8');
+
+/**
+ * Extract all `pi.on('agent_end', ...)` handler bodies from the source.
+ *
+ * The agent_end handler runs while the agent is still technically "processing",
+ * so every sendUserMessage call inside it MUST include deliverAs to avoid:
+ *   "Agent is already processing. Specify streamingBehavior..."
+ */
+function extractAgentEndBodies(source: string): string[] {
+  const bodies: string[] = [];
+  // Match pi.on('agent_end', ...) and extract everything until the matching });
+  const pattern = /pi\.on\(\s*'agent_end'/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    const startIdx = match.index;
+    // Find the handler body by counting braces
+    let braceCount = 0;
+    let inHandler = false;
+    let bodyStart = startIdx;
+    let bodyEnd = startIdx;
+
+    for (let i = startIdx; i < source.length; i++) {
+      if (source[i] === '{') {
+        if (!inHandler) {
+          inHandler = true;
+          bodyStart = i;
+        }
+        braceCount++;
+      } else if (source[i] === '}') {
+        braceCount--;
+        if (inHandler && braceCount === 0) {
+          bodyEnd = i + 1;
+          break;
+        }
+      }
+    }
+
+    bodies.push(source.slice(bodyStart, bodyEnd));
+  }
+  return bodies;
+}
+
+/**
+ * Find all sendUserMessage calls in a code block, returning each call
+ * with its line content and whether it has deliverAs.
+ */
+function findSendUserMessageCalls(code: string): Array<{
+  line: string;
+  hasDeliverAs: boolean;
+  isCommand: boolean;
+}> {
+  const results: Array<{ line: string; hasDeliverAs: boolean; isCommand: boolean }> = [];
+  const lines = code.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line.includes('sendUserMessage')) continue;
+    if (line.startsWith('//') || line.startsWith('*')) continue;
+
+    // Look ahead generously — multi-line template literals can push deliverAs 12+ lines away
+    const context = lines.slice(i, Math.min(i + 15, lines.length)).join(' ');
+    const hasDeliverAs = context.includes('deliverAs');
+
+    // Check if this is sending a slash command (e.g., '/plan-exec')
+    const isCommand = /sendUserMessage\s*\(\s*['"`]\//.test(context);
+
+    results.push({ line, hasDeliverAs, isCommand });
+  }
+
+  return results;
+}
+
+describe('agent_end handler safety', () => {
+  test('all sendUserMessage calls inside agent_end must include deliverAs', () => {
+    const bodies = extractAgentEndBodies(indexSource);
+    expect(bodies.length).toBeGreaterThan(0);
+
+    const violations: string[] = [];
+
+    for (const body of bodies) {
+      const calls = findSendUserMessageCalls(body);
+      for (const call of calls) {
+        if (!call.hasDeliverAs) {
+          violations.push(call.line);
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      throw new Error(
+        `Found sendUserMessage calls inside agent_end without deliverAs.\n` +
+        `The agent is still "processing" during agent_end, so deliverAs is required.\n\n` +
+        `Violations:\n${violations.map((v) => `  - ${v}`).join('\n')}\n\n` +
+        `Fix: add { deliverAs: 'followUp' } to each call.`,
+      );
+    }
+  });
+
+  test('sendUserMessage calls sending slash commands must include deliverAs', () => {
+    // Slash commands sent via sendUserMessage still go through the input pipeline
+    // and need deliverAs when called during agent processing
+    const bodies = extractAgentEndBodies(indexSource);
+
+    for (const body of bodies) {
+      const calls = findSendUserMessageCalls(body);
+      const commandCalls = calls.filter((c) => c.isCommand);
+      for (const call of commandCalls) {
+        expect(call.hasDeliverAs).toBe(true);
+      }
+    }
+  });
+});

package/extensions/plan-mode/__tests__/package-skills.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PKG_ROOT = join(import.meta.dir, '..', '..', '..');
+const PKG_JSON = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8'));
+
+describe('package.json pi manifest', () => {
+  test('declares skills directory', () => {
+    expect(PKG_JSON.pi?.skills).toBeDefined();
+    expect(PKG_JSON.pi.skills).toContain('./skills');
+  });
+});
+
+describe('bundled technical-options skill', () => {
+  const skillDir = join(PKG_ROOT, 'skills', 'technical-options');
+  const skillFile = join(skillDir, 'SKILL.md');
+
+  test('SKILL.md exists', () => {
+    expect(existsSync(skillFile)).toBe(true);
+  });
+
+  test('has valid frontmatter with name and description', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/^---\n/);
+    expect(content).toMatch(/name:\s*technical-options/);
+    expect(content).toMatch(/description:/);
+  });
+
+  test('description does not contain overly broad triggers', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    // These were flagged during review as too broad for routing
+    expect(content).not.toMatch(/description:.*help me decide/i);
+    expect(content).not.toMatch(/description:.*what are my options/i);
+  });
+
+  test('skill content mentions parallel voting agents', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toContain('voting');
+    expect(content).toContain('parallel');
+  });
+
+  test('skill content includes adversarial framing challenge step', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/challenge.*framing|framing.*challenge/i);
+  });
+});

package/extensions/plan-mode/__tests__/prompts.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { buildPlanModePrompt } from '../prompts.js';
+import { PLAN_TOOLS } from '../constants.js';
+
+describe('buildPlanModePrompt', () => {
+  const prompt = buildPlanModePrompt();
+
+  test('mentions technical-options skill for significant decisions', () => {
+    expect(prompt).toContain('technical-options');
+  });
+
+  test('mentions handoff instead of context and risks', () => {
+    expect(prompt).toContain('handoff');
+    expect(prompt).not.toContain('- risks:');
+    expect(prompt).not.toContain('- context:');
+  });
+
+  test('tells planner to do proposal generation itself, not delegate', () => {
+    // The planner should generate proposals as the main agent, only using
+    // subagents for voting/evaluation — not delegating the entire workflow
+    expect(prompt).toMatch(/you.*generat|generat.*yourself|do this yourself/i);
+  });
+
+  test('mentions subagent is available for voting only', () => {
+    // Should clarify subagent is for evaluation, not for the whole workflow
+    expect(prompt).toMatch(/subagent|voting|evaluat/i);
+  });
+});
+
+describe('PLAN_TOOLS', () => {
+  test('includes subagent for voting workflows', () => {
+    expect(PLAN_TOOLS).toContain('subagent');
+  });
+
+  test('includes search_skills for skill discovery', () => {
+    expect(PLAN_TOOLS).toContain('search_skills');
+  });
+});

package/extensions/plan-mode/{utils.test.ts → __tests__/utils.test.ts}

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { isSafeCommand } from './utils.js';
+import { isSafeCommand } from '../utils.js';
 
 describe('isSafeCommand', () => {
   // ── Commands that SHOULD be allowed ──────────────────────────────────────

package/extensions/plan-mode/constants.ts

@@ -0,0 +1,34 @@
+/**
+ * Plan mode constants — tool sets, model presets, thinking levels, and execution model options.
+ */
+
+// ── Tool sets ────────────────────────────────────────────────────────────────
+export const PLAN_TOOLS = [
+  'read',
+  'bash',
+  'grep',
+  'find',
+  'ls',
+  'submit_plan',
+  'questionnaire',
+  'search_skills',
+  'subagent',
+];
+
+export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_step'];
+
+// ── Model + thinking presets ─────────────────────────────────────────────────
+export const PLAN_MODEL = { provider: 'anthropic', id: 'claude-opus-4-6' } as const;
+export const PLAN_THINKING = 'medium' as const;
+
+export const EXEC_MODEL = { provider: 'openai', id: 'gpt-5.5' } as const;
+export const EXEC_THINKING = 'low' as const;
+
+// ── Exec-pending marker file name ────────────────────────────────────────────
+export const EXEC_PENDING_FILE = '.exec-pending.json';
+
+// ── Execution model picker options ───────────────────────────────────────────
+export const EXEC_MODEL_OPTIONS: { label: string; model: { provider: string; id: string } }[] = [
+  { label: 'gpt-5.5', model: { provider: 'openai', id: 'gpt-5.5' } },
+  { label: 'claude-opus-4-6', model: { provider: 'anthropic', id: 'claude-opus-4-6' } },
+];

package/extensions/plan-mode/context-filter.ts

@@ -0,0 +1,32 @@
+/**
+ * Message filtering for the context event — strips planning artifacts during execution
+ * and removes stale plan-mode injections when not in plan mode.
+ */
+
+/** Drop everything before the execution start index. */
+export function filterExecutionMessages<T>(
+  messages: T[],
+  executionStartIdx: number,
+): T[] {
+  return messages.filter((_m, i) => i >= executionStartIdx);
+}
+
+/** Strip stale plan-mode injected messages when not in plan mode. */
+export function filterStalePlanMessages<T>(messages: T[]): T[] {
+  return messages.filter((m) => {
+    const msg = m as { customType?: string; role?: string; content?: unknown };
+    if (msg.customType === 'plan-mode-context') return false;
+    if (msg.role !== 'user') return true;
+    const content = msg.content;
+    if (typeof content === 'string') {
+      return !content.includes('[PLAN MODE ACTIVE]');
+    }
+    if (Array.isArray(content)) {
+      return !content.some(
+        (c: { type?: string; text?: string }) =>
+          c.type === 'text' && c.text?.includes('[PLAN MODE ACTIVE]'),
+      );
+    }
+    return true;
+  });
+}