@dreki-gg/pi-subagent 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @dreki-gg/pi-subagent
 
+## 0.8.3
+
+### Patch Changes
+
+- [`6f0b219`](https://github.com/dreki-gg/pi-extensions/commit/6f0b219ac357ce1607a7a8211fd1c66bd35c62f1) Thanks [@jalbarrang](https://github.com/jalbarrang)! - fix(subagent): resolve TDZ crash when onMessage/onToolResult callbacks fire before spawnResult is assigned
+
+  Previously, `runSingleAgent` declared `const spawnResult = await spawnPiAgent({...})` and referenced `spawnResult` inside the `onMessage`/`onToolResult` callbacks. Since callbacks fire during the await (before the const is assigned), this caused a `ReferenceError: Cannot access 'spawnResult' before initialization`. Now uses `let` with a guard to safely accumulate messages when the result is not yet available.
+
+## 0.8.2
+
+### Patch Changes
+
+- [`32797ff`](https://github.com/dreki-gg/pi-extensions/commit/32797ff18d968e22c6c44e95c46e3393d8928cef) Thanks [@jalbarrang](https://github.com/jalbarrang)! - feat(plan-mode): add Windows compatibility — replace Unix shell commands with cross-platform Bun/Node APIs
+
+  Plan-mode no longer shells out to `cat`, `bash`, or `mkdir` via `pi.exec()`. File I/O now uses `Bun.file()` / `Bun.write()` and `node:fs/promises` `mkdir`, making the extension fully cross-platform. Destructive and safe command pattern lists now include Windows equivalents (`del`, `rd`, `copy`, `move`, `powershell`, `dir`, `where`, `tasklist`, etc.).
+
+  Also fixes Windows compatibility in three other packages:
+
+  - **browser-tools**: `spawn` now uses `shell: true` on Windows so `.cmd` wrappers resolve correctly; `shellEscape` uses double-quote style on Windows; install guidance is platform-aware (Homebrew shown only on macOS).
+  - **subagent**: `spawn` uses `shell: true` on Windows when the command is bare `pi`, allowing `pi.cmd` resolution.
+  - **lsp**: `globalConfigPath()` now uses `os.homedir()` on Windows instead of the unreliable `process.env.HOME`.
+
 ## 0.8.1
 
 ### Patch Changes

package/extensions/subagent/index.ts

@@ -27,14 +27,16 @@ import {
   SettingsManager,
 } from '@earendil-works/pi-coding-agent';
 import type { ResolvedPaths } from '@earendil-works/pi-coding-agent';
-import { Box, Container, Markdown, Spacer, Text, type AutocompleteItem } from '@earendil-works/pi-tui';
-import { Type } from 'typebox';
 import {
-  type AgentConfig,
-  type AgentScope,
-  type AgentSource,
-  discoverAgents,
-} from './agents.js';
+  Box,
+  Container,
+  Markdown,
+  Spacer,
+  Text,
+  type AutocompleteItem,
+} from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { type AgentConfig, type AgentScope, type AgentSource, discoverAgents } from './agents.js';
 import { formatRunAgentUsage, parseRunAgentArgs } from './run-agent-args.js';
 import { runAgent } from './agent-runner.js';
 import { extractRecentConversation } from './synthesis.js';
@@ -247,7 +249,6 @@ async function mapWithConcurrencyLimit<TIn, TOut>(
   return results;
 }
 
-
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
 async function runSingleAgent(
@@ -303,7 +304,8 @@ async function runSingleAgent(
     }
   };
 
-  const spawnResult = await spawnPiAgent({
+  let spawnResult: Awaited<ReturnType<typeof spawnPiAgent>> | undefined;
+  spawnResult = await spawnPiAgent({
     cwd: cwd ?? defaultCwd,
     agentName: agent.name,
     task,
@@ -313,15 +315,23 @@ async function runSingleAgent(
     tools: agent.tools,
     signal,
     onMessage: (msg) => {
-      currentResult.messages = spawnResult.messages;
-      currentResult.usage = spawnResult.usage;
-      currentResult.model = spawnResult.model ?? currentResult.model;
-      currentResult.stopReason = spawnResult.stopReason;
-      currentResult.errorMessage = spawnResult.errorMessage;
+      if (!spawnResult) {
+        currentResult.messages = [...currentResult.messages, msg];
+      } else {
+        currentResult.messages = spawnResult.messages;
+        currentResult.usage = spawnResult.usage;
+        currentResult.model = spawnResult.model ?? currentResult.model;
+        currentResult.stopReason = spawnResult.stopReason;
+        currentResult.errorMessage = spawnResult.errorMessage;
+      }
       emitUpdate();
     },
-    onToolResult: () => {
-      currentResult.messages = spawnResult.messages;
+    onToolResult: (msg) => {
+      if (!spawnResult) {
+        currentResult.messages = [...currentResult.messages, msg];
+      } else {
+        currentResult.messages = spawnResult.messages;
+      }
       emitUpdate();
     },
   });
@@ -373,13 +383,19 @@ const SubagentParams = Type.Object({
     Type.String({ description: 'Optional default model override for the run or all steps/tasks' }),
   ),
   thinking: Type.Optional(
-    Type.String({ description: 'Optional default reasoning level override for the run or all steps/tasks' }),
+    Type.String({
+      description: 'Optional default reasoning level override for the run or all steps/tasks',
+    }),
   ),
   tasks: Type.Optional(
-    Type.Array(TaskItem, { description: 'Array of {agent, task, model?, thinking?} for parallel execution' }),
+    Type.Array(TaskItem, {
+      description: 'Array of {agent, task, model?, thinking?} for parallel execution',
+    }),
   ),
   chain: Type.Optional(
-    Type.Array(ChainItem, { description: 'Array of {agent, task, model?, thinking?} for sequential execution' }),
+    Type.Array(ChainItem, {
+      description: 'Array of {agent, task, model?, thinking?} for sequential execution',
+    }),
   ),
   agentScope: Type.Optional(AgentScopeSchema),
   confirmProjectAgents: Type.Optional(
@@ -424,9 +440,7 @@ export default function (pi: ExtensionAPI) {
     if (!trimmedEnd) return replacement;
     if (/\s$/.test(argumentText)) return `${trimmedEnd} ${replacement}`;
     const lastSpace = trimmedEnd.lastIndexOf(' ');
-    return lastSpace === -1
-      ? replacement
-      : `${trimmedEnd.slice(0, lastSpace + 1)}${replacement}`;
+    return lastSpace === -1 ? replacement : `${trimmedEnd.slice(0, lastSpace + 1)}${replacement}`;
   }
 
   function buildArgumentCompletions(
@@ -456,9 +470,9 @@ export default function (pi: ExtensionAPI) {
     return discoverAgents(autocompleteCwd, scope, resolvedPaths).agents;
   }
 
-  async function getAutocompleteModels(scope: AgentScope): Promise<
-    Array<{ value: string; label?: string; description?: string }>
-  > {
+  async function getAutocompleteModels(
+    scope: AgentScope,
+  ): Promise<Array<{ value: string; label?: string; description?: string }>> {
     const items = new Map<string, { value: string; label?: string; description?: string }>();
 
     try {
@@ -1238,7 +1252,9 @@ export default function (pi: ExtensionAPI) {
         title,
         modeLine,
         theme.fg('muted', `Task: ${details.task}`),
-        failed && details.errorMessage ? theme.fg('error', `Error: ${details.errorMessage}`) : previewLines,
+        failed && details.errorMessage
+          ? theme.fg('error', `Error: ${details.errorMessage}`)
+          : previewLines,
         usageLine ? theme.fg('dim', usageLine) : undefined,
         theme.fg('muted', '(Ctrl+O to expand)'),
       ]
@@ -1347,7 +1363,10 @@ export default function (pi: ExtensionAPI) {
         { value: '--model', description: 'Override the agent model for this run' },
         { value: '--thinking', description: 'Override the reasoning level for this run' },
         { value: '--reasoning-level', description: 'Alias for --thinking' },
-        { value: '--yes-project-agents', description: 'Skip the project-agent trust confirmation prompt' },
+        {
+          value: '--yes-project-agents',
+          description: 'Skip the project-agent trust confirmation prompt',
+        },
         ...agents.map((agent) => ({
           value: agent.name,
           label: agent.name,
@@ -1363,7 +1382,8 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      const { agentName, explicitTask, agentScope, confirmProjectAgents, model, thinking } = parsed.options;
+      const { agentName, explicitTask, agentScope, confirmProjectAgents, model, thinking } =
+        parsed.options;
       if (!agentName) {
         ctx.ui.notify(formatRunAgentUsage(), 'warning');
         return;
@@ -1394,7 +1414,10 @@ export default function (pi: ExtensionAPI) {
       const conversation = extractRecentConversation(ctx);
       const task = buildRunAgentTask(conversation, explicitTask);
       if (!task) {
-        ctx.ui.notify(`No conversation context and no task specified.\n\n${formatRunAgentUsage()}`, 'warning');
+        ctx.ui.notify(
+          `No conversation context and no task specified.\n\n${formatRunAgentUsage()}`,
+          'warning',
+        );
         return;
       }
 
@@ -1486,5 +1509,4 @@ export default function (pi: ExtensionAPI) {
       await runAndReport(ctx.cwd, ctx.ui, (message) => pi.sendMessage(message), false);
     },
   });
-
 }

package/extensions/subagent/spawn-utils.ts

@@ -114,9 +114,10 @@ export async function spawnPiAgent(options: SpawnPiAgentOptions): Promise<SpawnP
 
     const exitCode = await new Promise<number>((resolve) => {
       const invocation = getPiInvocation(args);
+      const needsShell = process.platform === 'win32' && invocation.command === 'pi';
       const proc = spawn(invocation.command, invocation.args, {
         cwd: options.cwd,
-        shell: false,
+        shell: needsShell,
         stdio: ['ignore', 'pipe', 'pipe'],
       });
       let buffer = '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled prompts",
   "keywords": [
     "pi-package"

package/docs/plans/01_structured-handoffs-and-synthesis.plan.md

@@ -1,376 +0,0 @@
----
-name: "Structured handoffs + synthesis for chain workflows"
-overview: "Introduce a first-class handoff format for `@dreki-gg/pi-subagent` so chained agents pass compact, decision-rich context instead of raw `{previous}` markdown blobs. This slice should improve coherence across isolated agents without changing the core single/parallel/chain execution model."
-todo:
-  - id: "structured-handoffs-1"
-    task: "Add a handoff module that normalizes agent output into a compact envelope with goal, decisions, constraints, files, symbols, and raw output"
-    status: pending
-  - id: "structured-handoffs-2"
-    task: "Thread the structured handoff through chain execution in `extensions/subagent/index.ts` while preserving `{previous}` compatibility"
-    status: pending
-  - id: "structured-handoffs-3"
-    task: "Tighten bundled prompts so scout/planner/worker/docs-scout emit sections the handoff module can reliably summarize"
-    status: pending
----
-
-# Goal
-
-Make chained subagent workflows in `packages/subagent` pass structured, compact handoffs instead of blindly injecting the previous agent’s final markdown blob into the next task.
-
-# Context
-
-- Parent rationale: apply the “single writer, many thinkers” / “context engineering over prompt gimmicks” learnings we discussed for `@dreki-gg/pi-subagent`.
-- Module root: `packages/subagent`
-- This slice is infrastructure. Later slices like clean-context review, manager orchestration, and advisor routing should be able to reuse the same handoff format, but this plan must **not** assume those slices already exist.
-- Existing repo convention for package-local planning docs lives under `packages/<pkg>/docs/plans/` (see `packages/browser-tools/docs/plans/`).
-
-## What exists
-
-Current relevant file tree on disk:
-
-- `packages/subagent/package.json`
-- `packages/subagent/tsconfig.json`
-- `packages/subagent/README.md`
-- `packages/subagent/CHANGELOG.md`
-- `packages/subagent/extensions/subagent/index.ts`
-- `packages/subagent/extensions/subagent/agents.ts`
-- `packages/subagent/extensions/subagent/agent-runner.ts`
-- `packages/subagent/extensions/subagent/agent-runner-types.ts`
-- `packages/subagent/extensions/subagent/agent-result-utils.ts`
-- `packages/subagent/extensions/subagent/run-agent-args.ts`
-- `packages/subagent/extensions/subagent/synthesis.ts`
-- `packages/subagent/prompts/docs-scout.md`
-- `packages/subagent/prompts/planner.md`
-- `packages/subagent/prompts/reviewer.md`
-- `packages/subagent/prompts/scout.md`
-- `packages/subagent/prompts/ux-designer.md`
-- `packages/subagent/prompts/worker.md`
-- `packages/subagent/prompts/implement.md`
-- `packages/subagent/prompts/implement-and-review.md`
-- `packages/subagent/prompts/scout-and-plan.md`
-- `packages/subagent/skills/spawn-subagents/SKILL.md`
-- `packages/subagent/skills/write-an-agent/SKILL.md`
-
-Actual current behavior on disk:
-
-- Chain mode is still raw text plumbing. In `packages/subagent/extensions/subagent/index.ts:658-716`, each step computes `taskWithContext = step.task.replace(/\{previous\}/g, previousOutput)` and then updates `previousOutput = getFinalOutput(result.messages)`. There is no typed handoff object, parser, or summarizer.
-- `getFinalOutput()` in `packages/subagent/extensions/subagent/index.ts:204-214` returns only the last assistant text block, so any rich structure from tool calls or earlier assistant messages is discarded before handoff.
-- `run-agent` synthesizes main-conversation context via `extractRecentConversation()` and `buildRunAgentTask()` (`index.ts:1215-1229`, `index.ts:1557-1559`), but that synthesis is only used for direct `/run-agent` entry and not for agent-to-agent handoff.
-- `packages/subagent/extensions/subagent/synthesis.ts:5-38` already defines a strong section-oriented synthesis instruction (`Goal`, `Decisions`, `Constraints`, `Architecture`, `Open Questions`, `Intent`), but those sections are not reused anywhere in chain orchestration.
-- Bundled prompt templates still explicitly rely on `{previous}` text substitution:
-  - `packages/subagent/prompts/implement.md:6-10`
-  - `packages/subagent/prompts/scout-and-plan.md:6-9`
-  - `packages/subagent/prompts/implement-and-review.md:6-10`
-- The `spawn-subagents` skill already hints at the desired future shape: it says to “return a compact synthesis to the main thread” and to pass previous outputs “verbatim or as a tight structured summary” (`packages/subagent/skills/spawn-subagents/SKILL.md:31-35`, `:49-54`). That guidance is not enforced in code.
-- Bundled agents already emit semi-structured markdown, but the section names are inconsistent across roles:
-  - `scout` => `Files Retrieved`, `Key Code`, `Architecture`, `Start Here`
-  - `docs-scout` => `Libraries`, `Key Documentation`, `Integration Notes`, `Recommended Next Step`
-  - `planner` => `Goal`, `Plan`, `Files to Modify`, `New Files`, `Risks`
-  - `worker` => `Completed`, `Files Changed`, `Notes`
-- There is no test directory in `packages/subagent`; current validation is package typechecking (`packages/subagent/package.json`, `packages/subagent/tsconfig.json`).
-
-# API inventory
-
-## Existing public types and helpers the implementation will touch
-
-From `packages/subagent/extensions/subagent/agents.ts`:
-
-```ts
-export type AgentScope = 'user' | 'project' | 'both';
-export type AgentSource = 'bundled' | 'user' | 'project' | 'package';
-export type AgentSessionStrategy = 'inline' | 'fork-at';
-
-export interface AgentConfig {
-  name: string;
-  description: string;
-  tools?: string[];
-  model?: string;
-  thinking?: string;
-  sessionStrategy?: AgentSessionStrategy;
-  systemPrompt: string;
-  source: AgentSource;
-  filePath: string;
-}
-
-export interface AgentDiscoveryResult {
-  agents: AgentConfig[];
-  projectAgentsDir: string | null;
-}
-```
-
-From `packages/subagent/extensions/subagent/agent-runner-types.ts`:
-
-```ts
-export interface UsageStats {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  cost: number;
-  contextTokens: number;
-  turns: number;
-}
-
-export interface AgentResult {
-  agent: string;
-  task: string;
-  exitCode: number;
-  messages: Message[];
-  stderr: string;
-  usage: UsageStats;
-  model?: string;
-  stopReason?: string;
-  errorMessage?: string;
-}
-```
-
-From `packages/subagent/extensions/subagent/agent-runner.ts`:
-
-```ts
-export type OnPhaseUpdate = (
-  phaseName: string,
-  agentName: string,
-  result: AgentResult,
-) => void;
-
-export interface RunAgentOptions {
-  agentScope?: AgentScope;
-  cwd?: string;
-  onUpdate?: OnPhaseUpdate;
-  phaseName?: string;
-  signal?: AbortSignal;
-  resolvedPaths?: ResolvedPaths;
-}
-
-export async function runAgent(
-  cwd: string,
-  agentName: string,
-  task: string,
-  options: RunAgentOptions = {},
-): Promise<AgentResult>
-```
-
-From `packages/subagent/extensions/subagent/synthesis.ts`:
-
-```ts
-export function extractRecentConversation(
-  ctx: ExtensionCommandContext,
-): string
-
-export function buildSynthesisPrompt(
-  conversation: string,
-  explicitTask?: string,
-): string
-```
-
-## Existing internal chain data shape in `index.ts`
-
-```ts
-interface SingleResult {
-  agent: string;
-  agentSource: AgentSource | 'unknown';
-  task: string;
-  exitCode: number;
-  messages: Message[];
-  stderr: string;
-  usage: UsageStats;
-  model?: string;
-  stopReason?: string;
-  errorMessage?: string;
-  step?: number;
-}
-
-interface SubagentDetails {
-  mode: 'single' | 'parallel' | 'chain';
-  agentScope: AgentScope;
-  projectAgentsDir: string | null;
-  results: SingleResult[];
-}
-```
-
-These are currently private to `index.ts`, but the new handoff helper can either:
-- accept a narrow `Pick<SingleResult, ...>` shape, or
-- define its own exported `HandoffSource` input type to avoid importing internal UI state.
-
-## Proposed new handoff shape for this slice
-
-Create a dedicated module for this instead of baking ad hoc string munging into `index.ts`:
-
-```ts
-export interface HandoffFileRef {
-  path: string;
-  notes?: string;
-}
-
-export interface HandoffEnvelope {
-  version: 'subagent-handoff/v1';
-  sourceAgent: string;
-  sourceStep?: number;
-  task: string;
-  summary: string;
-  goal?: string;
-  decisions: string[];
-  constraints: string[];
-  files: HandoffFileRef[];
-  symbols: string[];
-  openQuestions: string[];
-  rawOutput: string;
-}
-
-export interface RenderHandoffOptions {
-  includeRawOutput?: boolean;
-  maxRawChars?: number;
-}
-
-export function buildHandoffFromResult(input: {
-  agent: string;
-  step?: number;
-  task: string;
-  output: string;
-}): HandoffEnvelope
-
-export function renderHandoffForPrompt(
-  handoff: HandoffEnvelope,
-  options?: RenderHandoffOptions,
-): string
-```
-
-The parser can be heuristic and markdown-based. It does **not** need to become a full AST parser. The goal is reliable compaction, not perfect semantic extraction.
-
-# Tasks
-
-## 1. Add a handoff module that normalizes agent output into a compact envelope
-
-### Files
-- Create `packages/subagent/extensions/subagent/handoffs.ts`
-
-### What to add
-- Export a small, typed handoff model (see `Proposed new handoff shape` above).
-- Implement markdown-section extraction that recognizes the current bundled agent contracts:
-  - `## Goal`
-  - `## Decisions`
-  - `## Constraints`
-  - `## Architecture`
-  - `## Open Questions`
-  - `## Plan`
-  - `## Files Retrieved`
-  - `## Files to Modify`
-  - `## New Files`
-  - `## Files Changed`
-  - `## Notes`
-  - `## Risks`
-  - `## Recommended Next Step`
-- Build a compact summary by prioritizing the most useful sections instead of returning the entire raw output.
-- Extract file paths by scanning markdown bullets/code spans for repo-looking paths (e.g. `` `packages/subagent/...` ``).
-- Extract symbols conservatively from code fences or bullets when they are clearly named functions/types; do not overfit.
-- Always keep `rawOutput` so callers can still include the source text when needed.
-
-### Code sketch
-
-```ts
-const SECTION_RE = /^##\s+(.+)$/gm;
-
-function splitMarkdownSections(markdown: string): Map<string, string> {
-  // return section title -> body
-}
-
-export function buildHandoffFromResult(input: {
-  agent: string;
-  step?: number;
-  task: string;
-  output: string;
-}): HandoffEnvelope {
-  const sections = splitMarkdownSections(input.output);
-  return {
-    version: 'subagent-handoff/v1',
-    sourceAgent: input.agent,
-    sourceStep: input.step,
-    task: input.task,
-    summary: ..., 
-    goal: ..., 
-    decisions: ..., 
-    constraints: ..., 
-    files: ..., 
-    symbols: ..., 
-    openQuestions: ..., 
-    rawOutput: input.output,
-  };
-}
-```
-
-### Notes
-- Keep this module dependency-free.
-- Do not move UI rendering logic into this file.
-- The formatter should emit readable markdown because existing prompt templates still use string substitution.
-
-## 2. Thread the structured handoff through chain execution in `extensions/subagent/index.ts`
-
-### Files
-- Modify `packages/subagent/extensions/subagent/index.ts`
-
-### What to change
-- Import the new handoff helper.
-- In the chain path (`index.ts:658-716`), replace the raw `previousOutput` update with a rendered handoff string built from the prior step’s final output.
-- Preserve the existing `{previous}` placeholder contract so current prompt templates still work, but change what gets injected:
-  - before: raw final assistant text
-  - after: a compact structured markdown summary plus optional truncated raw output
-- Keep error handling behavior unchanged.
-- Keep streaming UI behavior unchanged.
-
-### Implementation rules
-- Do **not** change single-mode or parallel-mode semantics in this slice.
-- Do **not** add a new tool mode; keep `single`, `parallel`, and `chain` only.
-- Avoid coupling the handoff module to `Message[]`; extract final text in `index.ts` and pass plain strings into the helper.
-- If the previous step returned no final text, fall back to `'(no output)'` exactly as current code does.
-
-## 3. Tighten bundled prompts so handoffs have stable sections to summarize
-
-### Files
-- Modify `packages/subagent/prompts/scout.md`
-- Modify `packages/subagent/prompts/docs-scout.md`
-- Modify `packages/subagent/prompts/planner.md`
-- Modify `packages/subagent/prompts/worker.md`
-- Modify `packages/subagent/prompts/implement.md`
-- Modify `packages/subagent/prompts/scout-and-plan.md`
-
-### What to change
-- Keep the roles the same, but make their output contracts easier to summarize reliably.
-- Prefer stable section names over freeform prose.
-- Add a small “Handoff” / “Next step” section where helpful instead of forcing the summarizer to infer everything from generic notes.
-
-### Recommended section adjustments
-- `scout.md`: keep `Files Retrieved` / `Key Code` / `Architecture`, and add `## Constraints or Unknowns`
-- `docs-scout.md`: keep `Libraries` / `Key Documentation` / `Integration Notes`, and make `Recommended Next Step` mandatory
-- `planner.md`: keep `Goal` / `Plan` / `Files to Modify` / `New Files` / `Risks`; optionally add `## Constraints`
-- `worker.md`: keep `Completed` / `Files Changed` / `Notes`, but require a short bullet list of decisions made and unresolved concerns
-- Prompt templates should mention that `{previous}` now contains a structured handoff, not an unbounded transcript dump
-
-# Files to create
-
-- `packages/subagent/extensions/subagent/handoffs.ts`
-
-# Files to modify
-
-- `packages/subagent/extensions/subagent/index.ts` — switch chain substitution from raw final text to rendered structured handoff
-- `packages/subagent/prompts/scout.md` — make scout output easier to summarize deterministically
-- `packages/subagent/prompts/docs-scout.md` — make docs handoff more consistent
-- `packages/subagent/prompts/planner.md` — preserve plan structure but expose constraints explicitly
-- `packages/subagent/prompts/worker.md` — add explicit decision / unresolved sections for downstream agents
-- `packages/subagent/prompts/implement.md` — document structured `{previous}` expectations
-- `packages/subagent/prompts/scout-and-plan.md` — document structured `{previous}` expectations
-
-# Testing notes
-
-- Run `bun run --filter '@dreki-gg/pi-subagent' typecheck` after adding `handoffs.ts` and updating imports.
-- Manually inspect the rendered handoff string by running a small local chain (for example, a trivial `scout -> planner` task) and confirm that the second step receives a compact summary instead of a huge raw blob.
-- Verify that existing prompt templates still work without changing the user-facing `{previous}` placeholder name.
-- Do not add runtime-only assumptions about sibling plans. This slice must provide value on its own.
-
-# Patterns to follow
-
-- `packages/subagent/extensions/subagent/synthesis.ts:5-38` — section-oriented synthesis prompt structure worth mirroring in handoffs
-- `packages/subagent/extensions/subagent/index.ts:658-716` — existing chain control flow to preserve
-- `packages/subagent/extensions/subagent/index.ts:204-214` — current final-output extraction behavior to wrap, not duplicate all over the package
-- `packages/subagent/skills/spawn-subagents/SKILL.md:31-35` — “compact synthesis” guidance already present in the skill
-- `packages/subagent/skills/spawn-subagents/SKILL.md:49-54` — existing advice about structured summaries
-- `packages/subagent/skills/write-an-agent/SKILL.md:15-20` and `:62-67` — output contracts should stay sharp and structured