@dreki-gg/pi-subagent 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @dreki-gg/pi-subagent
 
+## 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/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.2",
   "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

package/docs/plans/02_clean-context-review-loop.plan.md

@@ -1,240 +0,0 @@
----
-name: "Clean-context review loop"
-overview: "Refactor the existing implement→review→fix workflow so the reviewer starts from the diff and a minimal handoff instead of inheriting the worker’s full narrative. This slice should preserve the current single-writer loop while making review less correlated with generation."
-todo:
-  - id: "clean-review-1"
-    task: "Tighten the reviewer prompt so review starts from `git diff` and re-discovered code context, not from the worker’s rationale"
-    status: pending
-  - id: "clean-review-2"
-    task: "Change the worker output contract so implementation handoff exposes exact files, symbols, validation, and unresolved risks in a compact review packet"
-    status: pending
-  - id: "clean-review-3"
-    task: "Rewrite `/implement-and-review` to pass only the minimal review packet and findings needed for the next step"
-    status: pending
----
-
-# Goal
-
-Improve the bundled review loop so the reviewer reasons from a fresh, diff-first context and the worker only receives actionable findings back.
-
-# Context
-
-- Parent rationale: we want the reviewer to act as a clean-context verifier rather than a second pass over the worker’s self-explanation.
-- Module root: `packages/subagent`
-- This slice must work against the current package even if the structured-handoff plan has not landed yet.
-- Keep the package philosophy intact: one writer (`worker`) plus verifier intelligence (`reviewer`), not competing writers.
-
-## What exists
-
-Current relevant file tree on disk:
-
-- `packages/subagent/prompts/reviewer.md`
-- `packages/subagent/prompts/worker.md`
-- `packages/subagent/prompts/implement-and-review.md`
-- `packages/subagent/skills/spawn-subagents/SKILL.md`
-- `packages/subagent/extensions/subagent/index.ts`
-- `packages/subagent/README.md`
-
-Actual current behavior on disk:
-
-- The bundled review workflow is a plain chain prompt. `packages/subagent/prompts/implement-and-review.md:4-10` tells the main agent to:
-  1. run `worker` to implement `$@`
-  2. run `reviewer` “to review the implementation from the previous step (use {previous} placeholder)”
-  3. run `worker` again to apply review feedback from `{previous}`
-- Chain execution in `packages/subagent/extensions/subagent/index.ts:658-716` performs raw `{previous}` replacement with the previous step’s final assistant text. There is no review-specific minimization layer in code today.
-- The current reviewer prompt already points in the right direction:
-  - `packages/subagent/prompts/reviewer.md:12-18` restricts bash to read-only commands and tells the agent to start with `git diff`, then read modified files.
-  - But the prompt does **not** explicitly tell the reviewer to distrust or deprioritize the worker’s implementation narrative when that narrative is also passed through `{previous}`.
-- The current worker prompt includes a helpful but minimal handoff hint:
-  - `packages/subagent/prompts/worker.md:13-26` asks for `Completed`, `Files Changed`, and `Notes`, and says that if handing off to another agent it should include exact file paths changed and key functions/types touched.
-  - There is no required section for validation run, constraints, or unresolved risk, so the review handoff is underspecified.
-- The `spawn-subagents` skill currently recommends a `reviewer` loop after implementation and says the main agent may apply fixes directly or send a focused follow-up to `worker` (`packages/subagent/skills/spawn-subagents/SKILL.md:44-58`). It does not yet describe “clean context” review explicitly.
-- There is no additional workflow prompt for “clean review”; the current `/implement-and-review` prompt is the only bundled implementation review loop.
-
-# API inventory
-
-## Existing reviewer and worker contracts
-
-From `packages/subagent/prompts/reviewer.md`:
-
-```md
-Strategy:
-1. Run `git diff` to see recent changes (if applicable)
-2. Read the modified files
-3. Check for bugs, security issues, code smells
-
-Output format:
-## Files Reviewed
-- `path/to/file.ts` (lines X-Y)
-
-## Critical (must fix)
-- `file.ts:42` - Issue description
-
-## Warnings (should fix)
-- `file.ts:100` - Issue description
-
-## Suggestions (consider)
-- `file.ts:150` - Improvement idea
-
-## Summary
-Overall assessment in 2-3 sentences.
-```
-
-From `packages/subagent/prompts/worker.md`:
-
-```md
-Output format when finished:
-
-## Completed
-What was done.
-
-## Files Changed
-- `path/to/file.ts` - what changed
-
-## Notes (if any)
-Anything the main agent should know.
-
-If handing off to another agent (e.g. reviewer), include:
-- Exact file paths changed
-- Key functions/types touched (short list)
-```
-
-## Existing workflow prompt shape
-
-From `packages/subagent/prompts/implement-and-review.md`:
-
-```md
-1. First, use the "worker" agent to implement: $@
-2. Then, use the "reviewer" agent to review the implementation from the previous step (use {previous} placeholder)
-3. Finally, use the "worker" agent to apply the feedback from the review (use {previous} placeholder)
-```
-
-## Existing chain plumbing in code
-
-From `packages/subagent/extensions/subagent/index.ts`:
-
-```ts
-const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
-...
-previousOutput = getFinalOutput(result.messages);
-```
-
-This means the review workflow can be improved significantly even with prompt-only changes, because the thing being substituted is whatever the worker chose to emit as final text.
-
-# Tasks
-
-## 1. Tighten the reviewer prompt so review starts from `git diff` and re-discovered code context
-
-### Files
-- Modify `packages/subagent/prompts/reviewer.md`
-
-### What to change
-- Keep the reviewer read-only.
-- Make “diff first, repo second, worker narrative last” an explicit rule.
-- Tell the reviewer to use the incoming handoff only for:
-  - the original goal
-  - exact file paths / symbols to inspect first
-  - any explicit constraints that must not be violated
-- Tell the reviewer to challenge assumptions openly when the diff suggests a bug, insecure pattern, or scope creep.
-- Add a rule that the reviewer should request more investigation rather than hallucinate missing repo context.
-
-### Recommended prompt additions
-- Add a short “Rules” section such as:
-  1. Start with `git diff` / `git show`; do not trust the generator’s explanation over the code.
-  2. Use the incoming handoff only as a pointer to files, constraints, and touched symbols.
-  3. Re-discover missing context from the repo yourself.
-  4. If a claim cannot be verified from diff or code, say so explicitly.
-- Keep the current output sections, but add a mandatory “No findings” bullet format when the diff looks good.
-
-## 2. Change the worker output contract so implementation handoff becomes a compact review packet
-
-### Files
-- Modify `packages/subagent/prompts/worker.md`
-
-### What to change
-- Keep the worker autonomous and implementation-focused.
-- Expand the finish contract so a downstream reviewer gets a compact, machine-readable packet.
-
-### Required output structure
-
-```md
-## Completed
-- concise implementation summary
-
-## Files Changed
-- `path/to/file.ts` - what changed
-
-## Key Symbols Touched
-- `functionName`
-- `TypeName`
-
-## Validation
-- command run / not run
-- result
-
-## Constraints Followed
-- user constraints that shaped the implementation
-
-## Open Risks or Unknowns
-- anything the reviewer should pressure-test
-```
-
-### Notes
-- Do not ask the worker to justify every design choice in prose; that would reintroduce context bloat.
-- The goal is a review packet, not a diary.
-
-## 3. Rewrite `/implement-and-review` to pass only the minimal review packet and findings needed for the next step
-
-### Files
-- Modify `packages/subagent/prompts/implement-and-review.md`
-
-### What to change
-- Replace the vague “review the implementation from the previous step” language with explicit review behavior.
-- The prompt should instruct the main agent to pass a **minimal** handoff to `reviewer`:
-  - goal
-  - exact files changed
-  - touched symbols
-  - constraints followed
-  - open risks / unknowns
-- The prompt should instruct the reviewer to start from `git diff`, not from the packet itself.
-- The prompt should instruct the final `worker` step to apply only concrete review findings, not to rewrite code based on generic commentary.
-
-### Suggested prompt shape
-
-```md
-1. Use `worker` to implement: $@
-2. Use `reviewer` to perform a diff-first review. Treat the previous step only as a compact review packet (goal, files changed, key symbols, constraints, open risks). Re-discover repo context from the diff and files as needed.
-3. Use `worker` to address concrete Critical and Warning findings from the review. Ignore Suggestions unless they clearly fit scope.
-```
-
-### Optional follow-up
-- If, during implementation, you find the package benefits from a second prompt template instead of changing the default one, create `packages/subagent/prompts/implement-and-clean-review.md` and keep `/implement-and-review` as a thin wrapper or conservative alias.
-- If you choose that route, document the reason in the plan output and README follow-up notes.
-
-# Files to create
-
-- None required for the first iteration
-
-# Files to modify
-
-- `packages/subagent/prompts/reviewer.md` — make clean-context review an explicit prompt rule
-- `packages/subagent/prompts/worker.md` — emit a compact review packet instead of only freeform notes
-- `packages/subagent/prompts/implement-and-review.md` — encode diff-first review semantics in the bundled workflow
-
-# Testing notes
-
-- No TypeScript changes are required unless you choose to add a helper module, so package validation is primarily manual.
-- Run a small local `/implement-and-review` workflow and verify:
-  - the reviewer starts from `git diff`
-  - the reviewer output references concrete files/lines
-  - the worker’s second pass applies Critical/Warning items rather than rewriting everything
-- If you add any TS helper to support review packet rendering, run `bun run --filter '@dreki-gg/pi-subagent' typecheck`.
-- Do not assume the structured-handoff slice already exists. This prompt-level refactor should still improve behavior on its own.
-
-# Patterns to follow
-
-- `packages/subagent/prompts/reviewer.md:12-18` — existing diff-first reviewer stance to strengthen, not replace
-- `packages/subagent/prompts/worker.md:24-26` — current handoff hints to make mandatory and more compact
-- `packages/subagent/prompts/implement-and-review.md:4-10` — current workflow entry point to refine
-- `packages/subagent/skills/spawn-subagents/SKILL.md:44-58` — current review-loop guidance
-- `packages/subagent/skills/write-an-agent/SKILL.md:15-20` and `:62-67` — keep prompt files sharp, minimal, and output-contract-driven

package/docs/plans/03_parallel-recon-single-writer-docs.plan.md

@@ -1,199 +0,0 @@
----
-name: "Parallel recon, single-writer docs refresh"
-overview: "Document `@dreki-gg/pi-subagent` as an opinionated orchestration tool for parallel reconnaissance, planning, and review around a single writer. This slice updates the package docs and skill guidance without introducing new runtime behavior."
-todo:
-  - id: "docs-refresh-1"
-    task: "Add a package-local orchestration principles doc that explains when to use single, parallel, and chain modes—and when not to"
-    status: done
-  - id: "docs-refresh-2"
-    task: "Update the package README so one-writer guidance appears near the top instead of being implied"
-    status: done
-  - id: "docs-refresh-3"
-    task: "Tighten the spawn-subagents skill and bundled prompt descriptions so they consistently recommend parallel recon, not parallel conflicting edits"
-    status: done
----
-
-# Goal
-
-Make the package documentation explicitly teach the operating model we want users and orchestrating agents to follow: parallelize discovery and verification, keep writes coherent, and use fresh-context reviewers instead of swarms of editors.
-
-# Context
-
-- Parent rationale: the current package direction is already mostly right; the docs should make that philosophy unmistakable.
-- Module root: `packages/subagent`
-- This is a docs-and-guidance slice. It should not depend on runtime changes landing first.
-- Prefer package-local docs because the repo already stores package-specific plans under package-local `docs/` trees (for example `packages/browser-tools/docs/plans/`).
-
-## What exists
-
-Current relevant file tree on disk:
-
-- `packages/subagent/README.md`
-- `packages/subagent/skills/spawn-subagents/SKILL.md`
-- `packages/subagent/prompts/implement.md`
-- `packages/subagent/prompts/scout-and-plan.md`
-- `packages/subagent/prompts/implement-and-review.md`
-- `packages/subagent/prompts/scout.md`
-- `packages/subagent/prompts/planner.md`
-- `packages/subagent/prompts/reviewer.md`
-- `packages/subagent/prompts/worker.md`
-- `packages/subagent/package.json`
-- `packages/subagent/CHANGELOG.md`
-
-Actual current state on disk:
-
-- `packages/subagent/README.md` explains the three tool modes and the bundled agents, but it does not prominently state a philosophy like “parallel readers, single writer” or “use review loops over swarms.” The first sections are mode descriptions and examples (`README.md:11-45`).
-- The README does list examples that already imply sensible usage—scout, planner, worker, reviewer—but it stops short of explicitly warning against conflicting parallel edits (`README.md:21-45`).
-- The `spawn-subagents` skill is already the clearest articulation of current best practice:
-  - `Single specialist` (`SKILL.md:23-29`)
-  - `Parallel recon` (`SKILL.md:31-35`)
-  - `Plan then implement` (`SKILL.md:37-42`)
-  - `Review loop` (`SKILL.md:44-47`)
-  - execution rules that say “Parallelize reconnaissance, not conflicting edits” and “Prefer one worker unless file ownership is clearly partitioned” (`SKILL.md:49-53`)
-- The prompt templates are short and functional, but their descriptions do not advertise the package’s opinionated orchestration stance:
-  - `/implement` is “Full implementation workflow” (`packages/subagent/prompts/implement.md:1-10`)
-  - `/scout-and-plan` is “Scout gathers context, planner creates implementation plan” (`packages/subagent/prompts/scout-and-plan.md:1-9`)
-  - `/implement-and-review` is “Worker implements, reviewer reviews, worker applies feedback” (`packages/subagent/prompts/implement-and-review.md:1-10`)
-- There is currently no `packages/subagent/docs/` directory other than the plans we are now adding.
-
-# API inventory
-
-## User-facing package surface documented today
-
-From `packages/subagent/README.md`:
-
-```md
-## Subagent Tool
-
-The `subagent` tool supports three modes:
-
-| Mode | Description |
-| Single | `{ agent, task }` — one agent, one task |
-| Parallel | `{ tasks: [...] }` — multiple agents concurrently |
-| Chain | `{ chain: [...] }` — sequential with `{previous}` placeholder |
-```
-
-```md
-### Bundled Agents
-- `scout` — fast codebase recon
-- `docs-scout` — Context7-first documentation lookup
-- `planner` — implementation planning
-- `worker` — general-purpose implementation (`sessionStrategy: fork-at` by default)
-- `reviewer` — code review (`sessionStrategy: fork-at` by default)
-- `ux-designer` — frontend UI design
-```
-
-## Current skill guidance to preserve and elevate
-
-From `packages/subagent/skills/spawn-subagents/SKILL.md`:
-
-```md
-## 2. Parallel recon
-- Run `scout` + `docs-scout` in parallel when both code and docs matter.
-- Keep parallel tasks non-overlapping.
-- Return a compact synthesis to the main thread.
-
-Execution rules:
-- Parallelize reconnaissance, not conflicting edits.
-- Prefer one `worker` unless file ownership is clearly partitioned.
-- Use `docs-scout` when external library/framework details matter.
-- Pass previous outputs verbatim or as a tight structured summary.
-```
-
-These lines are the core behavioral contract the docs refresh should reinforce.
-
-# Tasks
-
-## 1. Add a package-local orchestration principles doc
-
-### Files
-- Create `packages/subagent/docs/orchestration-principles.md`
-
-### What to add
-Create a short, high-signal doc that explains the intended operating model of `@dreki-gg/pi-subagent`.
-
-### Required sections
-- `## Default philosophy`
-  - single writer, many thinkers
-  - parallel recon yes / conflicting edits no
-- `## When to use each mode`
-  - `single`
-  - `parallel`
-  - `chain`
-- `## Recommended workflows`
-  - scout → planner → worker
-  - worker → reviewer → worker
-  - scout + docs-scout in parallel
-- `## Non-goals`
-  - arbitrary swarms
-  - multi-writer editing without clear ownership
-  - using subagents as a substitute for coherent architecture decisions
-- `## Examples`
-  - concise examples mirroring current prompt templates and skill guidance
-
-### Notes
-- Keep it grounded in features that exist today.
-- Do not document manager/advisor agents here unless they actually ship before this slice lands.
-
-## 2. Update the package README so one-writer guidance appears near the top
-
-### Files
-- Modify `packages/subagent/README.md`
-
-### What to change
-- Add an “Opinionated defaults” or “How to think about this package” section immediately after the mode table.
-- Make these points explicit:
-  - `parallel` is best for scouts and other read-only discovery agents
-  - `chain` is best when a single writer needs planned, sequential help
-  - `reviewer` is a verifier, not a second writer
-  - default safe pattern is one writer unless file ownership is clearly partitioned
-- Keep existing install/use examples, but rewrite at least one example block to show the philosophy in practice.
-
-### Suggested wording targets
-- “Use parallel mode for discovery, not competing edits.”
-- “Prefer one worker and surround it with scouts, planners, and reviewers.”
-- “Use review loops to inject fresh context before a human or main agent reads the result.”
-
-## 3. Tighten the `spawn-subagents` skill and prompt descriptions
-
-### Files
-- Modify `packages/subagent/skills/spawn-subagents/SKILL.md`
-- Modify `packages/subagent/prompts/implement.md`
-- Modify `packages/subagent/prompts/scout-and-plan.md`
-- Modify `packages/subagent/prompts/implement-and-review.md`
-
-### What to change
-- Keep the skill concise, but move the “parallel recon, not conflicting edits” principle earlier or phrase it more strongly.
-- Make the prompt descriptions more self-explanatory:
-  - `/implement` should read as a safe sequential workflow around one implementing agent.
-  - `/scout-and-plan` should read as a recon + planning workflow, not a half-implemented swarm.
-  - `/implement-and-review` should read as a generator-verifier loop.
-- If any prompt template still implies that `{previous}` is just an unbounded transcript, rewrite the wording to say “handoff” / “summary” instead.
-
-# Files to create
-
-- `packages/subagent/docs/orchestration-principles.md`
-
-# Files to modify
-
-- `packages/subagent/README.md` — make package philosophy explicit near the top
-- `packages/subagent/skills/spawn-subagents/SKILL.md` — strengthen the opinionated orchestration guidance
-- `packages/subagent/prompts/implement.md` — clarify this is a sequential one-writer workflow
-- `packages/subagent/prompts/scout-and-plan.md` — clarify this is recon + planning, not implementation
-- `packages/subagent/prompts/implement-and-review.md` — describe the workflow as a generator-verifier loop
-
-# Testing notes
-
-- This slice is markdown-only unless you also tweak package metadata, so there is no TypeScript typecheck requirement.
-- Manually read the final README and skill files in one pass to make sure they do not contradict each other.
-- Keep examples aligned with currently shipped agents and prompts.
-- If a later feature slice adds manager/advisor agents before this one lands, update the new principles doc in the same branch rather than documenting speculative agents now.
-
-# Patterns to follow
-
-- `packages/subagent/skills/spawn-subagents/SKILL.md:21-58` — current best articulation of package operating rules
-- `packages/subagent/README.md:11-45` — current package intro to improve, not replace wholesale
-- `packages/subagent/prompts/implement.md:1-10` — terse prompt-template style to preserve
-- `packages/subagent/prompts/scout-and-plan.md:1-9` — terse prompt-template style to preserve
-- `packages/subagent/prompts/implement-and-review.md:1-10` — terse prompt-template style to preserve
-- `packages/browser-tools/docs/plans/*.plan.md` — package-local docs/plans organization pattern already used elsewhere in the repo

package/docs/plans/04_manager-workflow.plan.md

@@ -1,248 +0,0 @@
----
-name: "Manager workflow for multi-slice delegation"
-overview: "Add a bundled `manager` role and a reusable manager workflow so `@dreki-gg/pi-subagent` can coordinate larger, multi-slice tasks without turning into an unstructured swarm. The manager should split work, delegate bounded child tasks, synthesize discoveries, and keep writes coherent."
-todo:
-  - id: "manager-workflow-1"
-    task: "Add a bundled `manager` agent with a narrow orchestration role, explicit child-report contract, and no multi-writer default"
-    status: pending
-  - id: "manager-workflow-2"
-    task: "Add a bundled prompt template that invokes the manager for larger features or migrations"
-    status: pending
-  - id: "manager-workflow-3"
-    task: "Expose the new manager role in package docs and examples without overpromising unstructured swarm behavior"
-    status: pending
----
-
-# Goal
-
-Introduce a first-class manager workflow that can decompose larger tasks into bounded child-agent workstreams, synthesize the results, and keep decision-making coherent.
-
-# Context
-
-- Parent rationale: the package already has strong primitives (`single`, `parallel`, `chain`), but not a clear higher-level delegation pattern for “a feature spanning several slices” or “a migration with multiple child tasks.”
-- Module root: `packages/subagent`
-- This slice should stay opinionated: map / reduce / manage, not arbitrary peer-to-peer swarms.
-- The manager should be useful even if no new runtime code is added. Prefer prompt + workflow packaging first.
-
-## What exists
-
-Current relevant file tree on disk:
-
-- `packages/subagent/prompts/scout.md`
-- `packages/subagent/prompts/docs-scout.md`
-- `packages/subagent/prompts/planner.md`
-- `packages/subagent/prompts/worker.md`
-- `packages/subagent/prompts/reviewer.md`
-- `packages/subagent/prompts/implement.md`
-- `packages/subagent/prompts/scout-and-plan.md`
-- `packages/subagent/prompts/implement-and-review.md`
-- `packages/subagent/README.md`
-- `packages/subagent/extensions/subagent/index.ts`
-- `packages/subagent/extensions/subagent/agent-runner.ts`
-- `packages/subagent/extensions/subagent/agents.ts`
-- `packages/subagent/skills/spawn-subagents/SKILL.md`
-- `packages/subagent/skills/write-an-agent/SKILL.md`
-
-Actual current state on disk:
-
-- The package ships six bundled agents today: `scout`, `docs-scout`, `planner`, `worker`, `reviewer`, and `ux-designer` (`packages/subagent/README.md:88-105`). There is no `manager` agent.
-- The package ships three prompt templates today: `/implement`, `/scout-and-plan`, and `/implement-and-review` (`README.md:121-124`). There is no manager-oriented workflow prompt.
-- The `subagent` tool supports only three orchestration modes:
-  - single
-  - parallel
-  - chain
-  (`packages/subagent/extensions/subagent/index.ts:584-595` and `README.md:13-20`)
-- Parallel mode is already bounded and intentionally limited:
-  - max 8 tasks (`index.ts:50`, `:728-738`)
-  - max concurrency 4 (`index.ts:51`, `:780-805`)
-- The `spawn-subagents` skill already encodes the package’s desired shape:
-  - parallel recon
-  - plan then implement
-  - review loop
-  - “Parallelize reconnaissance, not conflicting edits” (`SKILL.md:31-58`)
-  But there is no equivalent section for higher-level “manager delegates to children, then synthesizes.”
-- The current agent runner logic is already compatible with a manager-style agent:
-  - `runSingleAgent()` in `index.ts:325-328` only passes `--tools` when the agent frontmatter declares a tool list.
-  - `runAgent()` in `agent-runner.ts:73-76` behaves the same way.
-  - This means a new `manager` agent can omit `tools:` in frontmatter if it needs access to the full tool set, including the `subagent` tool itself.
-- There is no project-local `.pi/prompts/*.md` manager override in this repo right now; `.pi/prompts/` exists but is empty.
-
-# API inventory
-
-## Existing agent frontmatter model
-
-From `packages/subagent/extensions/subagent/agents.ts`:
-
-```ts
-export interface AgentConfig {
-  name: string;
-  description: string;
-  tools?: string[];
-  model?: string;
-  thinking?: string;
-  sessionStrategy?: 'inline' | 'fork-at';
-  systemPrompt: string;
-  source: 'bundled' | 'user' | 'project' | 'package';
-  filePath: string;
-}
-```
-
-From `packages/subagent/README.md`:
-
-```md
----
-name: my-agent
-description: What this agent does
-tools: read, grep, find, ls
-model: anthropic/claude-haiku-4-5
-sessionStrategy: fork-at
----
-```
-
-## Existing subagent tool modes the manager will likely use
-
-From `packages/subagent/README.md` and `packages/subagent/extensions/subagent/index.ts`:
-
-```ts
-// Single
-{ agent, task }
-
-// Parallel
-{ tasks: [{ agent, task }, ...] }
-
-// Chain
-{ chain: [{ agent, task }, ...] }
-```
-
-## Existing agent roles the manager should compose, not replace
-
-- `scout` — repo reconnaissance
-- `docs-scout` — docs lookup
-- `planner` — implementation planning
-- `worker` — implementation
-- `reviewer` — verification
-
-The manager should orchestrate these roles, not absorb them.
-
-## Proposed manager output contract
-
-Create a prompt contract that is directly usable by the main agent or a human:
-
-```md
-## Goal
-- one-sentence statement of the parent task
-
-## Workstreams
-1. Workstream name — owner agent, scope, expected output
-2. ...
-
-## Shared Decisions
-- constraints all children must follow
-
-## Child Reports
-### <workstream>
-- what was learned / produced
-- files implicated
-- blockers or open questions
-
-## Recommended Next Action
-- whether to run worker, reviewer, or ask the human
-```
-
-# Tasks
-
-## 1. Add a bundled `manager` agent with a narrow orchestration role
-
-### Files
-- Create `packages/subagent/prompts/manager.md`
-
-### What to add
-Author a concise bundled agent prompt that:
-- decomposes a larger task into bounded child workstreams
-- delegates to child agents via the `subagent` tool when beneficial
-- prefers read-only discovery or planning in parallel
-- keeps implementation coherent by limiting writing to one `worker` at a time unless file ownership is truly partitioned
-- synthesizes child output into a structured manager report
-
-### Frontmatter guidance
-- Omit `tools:` in the first implementation unless you confirm that explicitly listing `subagent` is supported end-to-end in spawned agent tool selection.
-- Use an existing strong model already present in the package (for example `openai/gpt-5.4`) rather than introducing a new provider requirement in this slice.
-- Keep the file under ~100 lines, following `packages/subagent/skills/write-an-agent/SKILL.md`.
-
-### Required prompt rules
-1. Split work by scope, not by arbitrary agent count.
-2. Prefer `scout` / `docs-scout` / `planner` in parallel for discovery.
-3. Prefer a single `worker` for edits unless file ownership is obviously isolated.
-4. Synthesize child findings before asking for more work.
-5. Escalate open product or architecture decisions back to the main agent / user instead of hallucinating consensus.
-
-## 2. Add a bundled prompt template that invokes the manager for larger tasks
-
-### Files
-- Create `packages/subagent/prompts/manage.md`
-
-### What to add
-Add a prompt template for larger tasks such as migrations, multi-package refactors, or features that need several child investigations.
-
-### Suggested prompt shape
-
-```md
-Use the subagent tool to run the `manager` agent on: $@
-
-The manager should:
-1. break the work into bounded child workstreams
-2. use parallel scouts/planners where helpful
-3. keep implementation single-writer by default
-4. return a synthesized report with recommended next steps
-```
-
-### Notes
-- Do not build an unbounded recursive swarm prompt.
-- The manager prompt should feel like a higher-level entry point, not a new runtime mode.
-
-## 3. Expose the new manager role in docs and examples
-
-### Files
-- Modify `packages/subagent/README.md`
-- Modify `packages/subagent/skills/spawn-subagents/SKILL.md`
-
-### What to change
-- Add `manager` to the bundled agent list in the README.
-- Add one example showing when to use it, such as a multi-package migration or a feature spanning several child tasks.
-- Extend the `spawn-subagents` skill with a new “Manager pattern” section that explains:
-  - when to use a manager
-  - how it should delegate
-  - why this is different from a generic swarm
-
-### Suggested skill wording targets
-- “Use `manager` when the task is too large for one prompt but still needs coherent decisions.”
-- “Managers split work, children investigate or implement bounded slices, the manager synthesizes.”
-- “Do not create arbitrary peer-to-peer negotiation loops.”
-
-# Files to create
-
-- `packages/subagent/prompts/manager.md`
-- `packages/subagent/prompts/manage.md`
-
-# Files to modify
-
-- `packages/subagent/README.md` — add manager to bundled agents and prompt templates, plus one usage example
-- `packages/subagent/skills/spawn-subagents/SKILL.md` — add manager orchestration guidance
-
-# Testing notes
-
-- If the manager prompt remains markdown-only, there is no package typecheck requirement.
-- Manually run a small `/run-agent manager ...` or equivalent `subagent` call and confirm the manager:
-  - breaks work into bounded tasks
-  - uses parallel recon rather than parallel conflicting edits
-  - returns a synthesized report instead of dumping raw child logs
-- If you decide to add any helper TS module to support manager summaries, run `bun run --filter '@dreki-gg/pi-subagent' typecheck`.
-- Keep the manager role useful without assuming any future advisor/handoff feature exists.
-
-# Patterns to follow
-
-- `packages/subagent/skills/spawn-subagents/SKILL.md:31-58` — existing orchestration philosophy to extend upward
-- `packages/subagent/skills/write-an-agent/SKILL.md:15-20` and `:46-67` — agent-authoring constraints for concise, high-signal prompts
-- `packages/subagent/prompts/planner.md:9-38` — good example of a narrow role with a clear output contract
-- `packages/subagent/prompts/worker.md:9-26` — example of a task-focused executor the manager should call, not replace
-- `packages/subagent/README.md:88-124` — bundled-agent and bundled-prompt sections to update

package/docs/plans/05_advisor-routing.plan.md

@@ -1,244 +0,0 @@
----
-name: "Advisor / smart-friend routing"
-overview: "Add a bundled `advisor` role and lightweight escalation guidance so strong primary agents in `@dreki-gg/pi-subagent` can ask for focused second opinions on tricky cases without turning every task into a swarm. This slice is about capability routing, not replacing the main worker."
-todo:
-  - id: "advisor-routing-1"
-    task: "Add a bundled `advisor` agent with a focused consultative contract: diagnose, suggest next investigation, and surface risks without taking ownership of implementation"
-    status: done
-  - id: "advisor-routing-2"
-    task: "Teach bundled worker/planner/reviewer prompts when to call the advisor and what context to send"
-    status: done
-  - id: "advisor-routing-3"
-    task: "Add a reusable prompt entry point and docs examples for advisor-assisted workflows"
-    status: done
----
-
-# Goal
-
-Introduce a lightweight advisor pattern so primary agents can consult a strong second opinion for hard cases while keeping a single primary owner of the work.
-
-# Context
-
-- Parent rationale: we want capability routing and targeted escalation, not a default “everyone talks to everyone” swarm.
-- Module root: `packages/subagent`
-- This slice should work with the current package architecture and should not depend on a new runtime mode.
-- Keep the advisor narrowly scoped: diagnose, redirect, highlight risk, or suggest the next question. The advisor should not silently become another worker.
-
-## What exists
-
-Current relevant file tree on disk:
-
-- `packages/subagent/prompts/planner.md`
-- `packages/subagent/prompts/reviewer.md`
-- `packages/subagent/prompts/worker.md`
-- `packages/subagent/prompts/docs-scout.md`
-- `packages/subagent/prompts/implement.md`
-- `packages/subagent/prompts/implement-and-review.md`
-- `packages/subagent/README.md`
-- `packages/subagent/extensions/subagent/index.ts`
-- `packages/subagent/extensions/subagent/agent-runner.ts`
-- `packages/subagent/skills/spawn-subagents/SKILL.md`
-- `packages/subagent/skills/write-an-agent/SKILL.md`
-
-Actual current state on disk:
-
-- There is no bundled `advisor` agent in `packages/subagent/prompts/`.
-- There is no advisor-oriented prompt template in `packages/subagent/prompts/`.
-- The current bundled roles are:
-  - `planner` for planning (`packages/subagent/prompts/planner.md`)
-  - `worker` for implementation (`packages/subagent/prompts/worker.md`)
-  - `reviewer` for verification (`packages/subagent/prompts/reviewer.md`)
-  - plus `scout`, `docs-scout`, and `ux-designer`
-- The package runner already supports spawned agents consulting tools as needed:
-  - in `packages/subagent/extensions/subagent/index.ts:325-328`, `runSingleAgent()` passes `--tools` only when frontmatter declares them
-  - in `packages/subagent/extensions/subagent/agent-runner.ts:73-76`, `runAgent()` behaves the same way
-  - therefore bundled agents with omitted `tools:` can keep access to the broader tool surface, including `subagent`
-- The current prompt contracts do **not** teach any role when to escalate:
-  - `planner.md` only says to produce a concrete plan
-  - `worker.md` only says to complete the task autonomously
-  - `reviewer.md` only says to review the diff / files
-- The `spawn-subagents` skill recommends specialists and review loops, but does not mention an advisor or “consult when tricky” routing rule.
-
-# API inventory
-
-## Existing agent prompt contracts that may invoke advisor
-
-From `packages/subagent/prompts/planner.md`:
-
-```md
-You are a planning specialist.
-You must NOT make any changes. Only read, analyze, and plan.
-```
-
-From `packages/subagent/prompts/worker.md`:
-
-```md
-You are a worker agent with full capabilities.
-Work autonomously to complete the assigned task. Use all available tools as needed.
-```
-
-From `packages/subagent/prompts/reviewer.md`:
-
-```md
-You are a senior code reviewer.
-Analyze code for quality, security, and maintainability.
-```
-
-## Existing subagent entry shapes available to an advisor pattern
-
-From the `subagent` tool surface:
-
-```ts
-// single consult
-{ agent: 'advisor', task: '...' }
-
-// consult inside a chain
-{ chain: [{ agent: 'worker', task: '...' }, { agent: 'advisor', task: '... {previous} ...' }] }
-
-// focused parallel consults
-{ tasks: [{ agent: 'advisor', task: '...' }, { agent: 'docs-scout', task: '...' }] }
-```
-
-## Proposed advisor contract
-
-The advisor should return guidance the caller can act on immediately:
-
-```md
-## Assessment
-- what looks tricky / risky / ambiguous
-
-## What to inspect next
-- concrete files, commands, or questions
-
-## Recommendation
-- best next action for the caller
-
-## Risks
-- what could still go wrong
-```
-
-The advisor should not claim to have implemented or verified anything it did not actually inspect.
-
-# Tasks
-
-## 1. Add a bundled `advisor` agent with a focused consultative contract
-
-### Files
-- Create `packages/subagent/prompts/advisor.md`
-
-### What to add
-Create a concise bundled agent whose sole job is to provide focused second-opinion guidance.
-
-### Required behavior
-- Work from the caller’s question plus any provided handoff.
-- Ask the caller to investigate specific files / commands when the answer depends on context the advisor has not yet inspected.
-- Surface hidden risks or better approaches.
-- Avoid taking over implementation.
-- Prefer decisive recommendations over brainstorming lists.
-
-### Frontmatter guidance
-- Use an existing strong model already in package conventions (default to `openai/gpt-5.4` unless there is a strong reason to diversify).
-- Keep the prompt under ~100 lines per `packages/subagent/skills/write-an-agent/SKILL.md`.
-- Omit `tools:` only if you want the advisor to have broad access; otherwise keep the tool list minimal and read-oriented.
-
-### Suggested prompt rules
-1. Diagnose the hard part, not the whole task from scratch.
-2. If more repo context is needed, say exactly what to inspect next.
-3. Return a recommendation the caller can act on immediately.
-4. Do not implement code or rewrite plans unless explicitly asked.
-
-## 2. Teach bundled prompts when to call the advisor and what context to send
-
-### Files
-- Modify `packages/subagent/prompts/worker.md`
-- Modify `packages/subagent/prompts/planner.md`
-- Modify `packages/subagent/prompts/reviewer.md`
-
-### What to change
-Add small, explicit escalation rules to the existing bundled roles.
-
-### Recommended escalation triggers
-- `worker`
-  - ambiguous architecture tradeoff
-  - persistent failing tests or unexplained errors
-  - merge conflicts / tangled diffs
-  - security-sensitive or migration-heavy changes
-- `planner`
-  - multiple viable designs with materially different blast radius
-  - unclear ownership boundaries across packages
-  - need for sharper decomposition before implementation
-- `reviewer`
-  - uncertainty whether an issue is real vs. intended
-  - suspected deeper architectural problem beyond the current diff
-  - need for a second opinion on severity
-
-### Required context to send when consulting advisor
-Keep the consult lightweight:
-- current role (`worker` / `planner` / `reviewer`)
-- the exact question
-- touched files / symbols if known
-- the smallest relevant task summary
-- what has already been tried or observed
-
-### Notes
-- Do not tell every role to always call the advisor. This is an escalation path, not a mandatory step.
-- Keep the primary role in charge; the advisor should inform decisions, not replace ownership.
-
-## 3. Add a reusable prompt entry point and docs examples for advisor-assisted workflows
-
-### Files
-- Create `packages/subagent/prompts/consult-advisor.md`
-- Modify `packages/subagent/README.md`
-- Modify `packages/subagent/skills/spawn-subagents/SKILL.md`
-
-### What to add
-Create a simple prompt template that encourages focused advisor consultation without changing core workflow semantics.
-
-### Suggested prompt shape
-
-```md
-Use the subagent tool to consult the `advisor` agent about: $@
-
-The advisor should:
-1. identify the hard part
-2. suggest the next investigation or decision
-3. surface concrete risks
-4. return a recommendation, not a full implementation
-```
-
-### README / skill updates
-- Add `advisor` to the bundled agent list once shipped.
-- Add one example such as:
-  - “ask advisor whether this migration should be split before sending it to worker”
-  - “have worker consult advisor on the failing test loop”
-- In `spawn-subagents`, add guidance that advisor use is optional and should be reserved for tricky or high-risk cases.
-
-# Files to create
-
-- `packages/subagent/prompts/advisor.md`
-- `packages/subagent/prompts/consult-advisor.md`
-
-# Files to modify
-
-- `packages/subagent/prompts/worker.md` — add narrow escalation guidance
-- `packages/subagent/prompts/planner.md` — add narrow escalation guidance
-- `packages/subagent/prompts/reviewer.md` — add narrow escalation guidance
-- `packages/subagent/README.md` — document the new advisor role and one or two examples
-- `packages/subagent/skills/spawn-subagents/SKILL.md` — explain when to use advisor vs. planner/reviewer
-
-# Testing notes
-
-- If this remains markdown-only, there is no TypeScript validation requirement.
-- Manually test one focused consult, such as a planner or worker asking advisor a hard question, and verify:
-  - the advisor returns a recommendation rather than trying to own the full task
-  - the caller stays in charge of implementation or review
-  - the exchange is shorter and more targeted than a full additional workflow
-- If you introduce any helper TS module later to render consult packets, run `bun run --filter '@dreki-gg/pi-subagent' typecheck`.
-
-# Patterns to follow
-
-- `packages/subagent/skills/write-an-agent/SKILL.md:15-20` and `:46-67` — keep the new agent narrow, concise, and output-contract-driven
-- `packages/subagent/prompts/planner.md:9-38` — example of a specialist planner role that the advisor should complement, not replace
-- `packages/subagent/prompts/reviewer.md:10-37` — example of a verifier role that may occasionally need escalation
-- `packages/subagent/prompts/worker.md:9-26` — example of a primary owner role that should remain in charge after consulting advisor
-- `packages/subagent/skills/spawn-subagents/SKILL.md:23-58` — existing specialist-selection guidance to extend with optional escalation