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

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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

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/constants.ts

@@ -12,6 +12,7 @@ export const PLAN_TOOLS = [
   'submit_plan',
   'questionnaire',
   'search_skills',
+  'subagent',
 ];
 
 export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_step'];

package/extensions/plan-mode/index.ts

@@ -217,11 +217,34 @@ export default function planMode(pi: ExtensionAPI): void {
           await updatePlansManifest(state.planDir.replace(/^\.plans\//, ''), 'done', state.plan.title);
           await savePlanToDisk(state.planDir, state.plan);
         }
-        const list = state.plan.steps
-          .map((s) => s.status === 'done' ? `~~${s.description}~~` : `⊘ ~~${s.description}~~`)
+        const done = state.plan.steps.filter((s) => s.status === 'done').length;
+        const skipped = state.plan.steps.filter((s) => s.status === 'skipped').length;
+        const total = state.plan.steps.length;
+        const stats = skipped > 0
+          ? `${done}/${total} done, ${skipped} skipped`
+          : `${done}/${total} done`;
+
+        // Build a summary of what was actually done from step notes
+        const changeSummary = state.plan.steps
+          .map((s, i) => {
+            const icon = s.status === 'done' ? '✓' : '⊘';
+            const label = `${i + 1}. ${icon} ${s.description}`;
+            return s.notes ? `${label}\n   ${s.notes}` : label;
+          })
           .join('\n');
+
+        const summary = [
+          `**Plan Complete!** ✓ — ${state.plan.title}`,
+          '',
+          `> ${stats}`,
+          '',
+          '## Summary',
+          '',
+          changeSummary,
+        ].join('\n');
+
         pi.sendMessage(
-          { customType: 'plan-complete', content: `**Plan Complete!** ✓\n\n${list}`, display: true },
+          { customType: 'plan-complete', content: summary, display: true },
           { triggerTurn: false },
         );
 

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

@@ -48,6 +48,19 @@ export async function readAndClearExecPending(): Promise<{ planDir: string; conf
   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',

package/extensions/plan-mode/prompts.ts

@@ -21,12 +21,17 @@ Your task:
 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
+- 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
-- 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.`;
+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 {
@@ -48,7 +53,7 @@ You are executing a structured plan. Your ONLY job is to implement the plan step
 
 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
+- 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"
@@ -57,11 +62,11 @@ Rules:
 Step ${currentStep.num}: ${currentStep.description}
 Details: ${currentStep.details}
 
-## Codebase context
-${plan.context}
+## Handoff
+${plan.handoff}
 
 ## All remaining steps
 ${stepList}
 
-Start with step ${currentStep.num} NOW. When done, call update_step(step=${currentStep.num}, status="done").`;
+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/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.',
     ],

package/extensions/plan-mode/types.ts

@@ -11,9 +11,8 @@ 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.10.1",
+  "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",
@@ -33,6 +34,9 @@
   "pi": {
     "extensions": [
       "./extensions/plan-mode"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "dependencies": {

package/skills/technical-options/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: technical-options
+description: Generate and rank competing options for a technical decision using parallel evaluators. Use when the user wants a structured comparison of implementation approaches, architecture alternatives, or engineering tradeoffs before choosing one. Not for binary yes/no or pure preference decisions.
+---
+
+# Technical Options
+
+Generate competing proposals for a technical decision, challenge the framing, then fan out to parallel voting agents for ranking.
+
+## Process
+
+### 1. Understand the problem
+
+- Read relevant code and context
+- Identify the core constraint or failure mode driving the decision
+- Note available APIs, tools, and integration points
+
+### 2. Research (optional)
+
+Use `web_search` + `web_visit` if external patterns would help. Skip for purely internal decisions. If those tools are unavailable, proceed from repo context only.
+
+### 3. Generate 3–5 proposals
+
+Each proposal needs:
+- **Letter** (A–E) and a short memorable name
+- **One-paragraph description** with the key mechanism
+- **Pros and cons** — honest tradeoffs, not sales pitches
+
+Rules:
+- Span the solution space — don't cluster around one idea
+- Include a simplest-possible option and a most-robust option
+- Include an unconventional or contrarian option when possible
+- 3 proposals for small choices, 4–5 for architectural decisions
+
+### 4. Challenge the framing
+
+Before voting, spawn one `advisor` agent (or equivalent) with this task:
+
+> "Here are N proposals for [problem]. What important constraint, framing assumption, or missing approach is absent? If you find a materially distinct option the proposals don't cover, describe it. If the slate is well-shaped, say so."
+
+Only amend the proposal slate if the challenger surfaces a genuinely distinct option. Do not add variations of existing proposals.
+
+### 5. Fan out to 3 voting agents
+
+Use `subagent` in parallel mode with 3 tasks. Each voter gets identical proposals but a different evaluation preamble. The lenses are the contract; agent names are flexible — use `advisor`, `reviewer`, or whatever is available:
+
+**Lens 1 — Pragmatic engineer:**
+> "You value shipping speed and simplicity. You penalize over-engineering. A complex solution must justify its complexity with concrete failure modes the simple one can't handle."
+
+**Lens 2 — Reliability engineer:**
+> "You value robustness, crash recovery, and correctness over speed. You penalize approaches that work in happy paths but have edge-case blind spots. If two are equally correct, prefer the one that fails louder."
+
+**Lens 3 — Maintainability reviewer:**
+> "You value clean abstractions, testability, and long-term ownership cost. You penalize approaches that fight the framework or create implicit coupling. The best solution is one a new team member understands in 5 minutes."
+
+Each voter must output a strict ranking:
+```
+1st: [Letter] — [reason]
+2nd: [Letter] — [reason]
+...
+```
+
+Scale to 5 voters only for high-stakes decisions (new system boundaries, irreversible migrations, public API design).
+
+### 6. Tally and present
+
+**Scoring**: Borda count — 1st = N points, 2nd = N-1, ..., last = 1.
+
+**Tiebreaker**: Most 1st-place votes. If still tied, present the split to the user honestly and let them decide — do NOT force a winner.
+
+Present in this order:
+1. **Problem framing** (one sentence)
+2. **Proposals** (A–E with names)
+3. **Vote table** with per-voter rankings and scores
+4. **Winner** with consensus reasoning
+5. **Dissent** — where voters disagreed and why
+6. **Recommendation** — winner, plus any elements worth borrowing from runner-up
+7. **Question to user** — proceed, combine, or reconsider?
+
+### 7. Confirm with user
+
+Do NOT auto-implement. Ask whether to proceed with the winner, combine elements, or reconsider.
+
+## When NOT to use this
+
+- Binary yes/no decisions — just discuss pros/cons
+- Decisions with an obviously correct answer — just do it
+- Pure preference decisions with no technical tradeoffs — ask the user
+- Reversible decisions where trying the simplest option first is cheap