@dreki-gg/pi-subagent 0.5.0 → 0.7.0

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/agents/reviewer.md`
+- `packages/subagent/agents/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/agents/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/agents/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/agents/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/agents/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/agents/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/agents/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/agents/reviewer.md` — make clean-context review an explicit prompt rule
+- `packages/subagent/agents/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/agents/reviewer.md:12-18` — existing diff-first reviewer stance to strengthen, not replace
+- `packages/subagent/agents/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

@@ -0,0 +1,199 @@
+---
+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/agents/scout.md`
+- `packages/subagent/agents/planner.md`
+- `packages/subagent/agents/reviewer.md`
+- `packages/subagent/agents/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

@@ -0,0 +1,248 @@
+---
+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/agents/scout.md`
+- `packages/subagent/agents/docs-scout.md`
+- `packages/subagent/agents/planner.md`
+- `packages/subagent/agents/worker.md`
+- `packages/subagent/agents/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/agents/*.md` manager override in this repo right now; `.pi/agents/` 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/agents/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/agents/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/agents/planner.md:9-38` — good example of a narrow role with a clear output contract
+- `packages/subagent/agents/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