@dreki-gg/pi-subagent 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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
+
+- [`d133c3d`](https://github.com/dreki-gg/pi-extensions/commit/d133c3da917e7e5def568d27d6cde8ae8a6c00d2) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Mark pi peer dependencies as optional so npm does not auto-install pi internals when installing extension packages.
+
 ## 0.8.0
 
 ### Minor 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.0",
+  "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"
@@ -42,5 +42,22 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   }
 }

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