@dreki-gg/pi-subagent 0.6.0 → 0.8.0

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

@@ -0,0 +1,376 @@
+---
+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

@@ -0,0 +1,240 @@
+---
+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