@dreki-gg/pi-subagent 0.6.0 → 0.8.0

package/.fallowrc.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
+  "entry": [
+    "extensions/subagent/index.ts"
+  ]
+}

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @dreki-gg/pi-subagent
 
+## 0.8.0
+
+### Minor Changes
+
+- [`3a246f3`](https://github.com/dreki-gg/pi-extensions/commit/3a246f3fd55b900ebfcfbea2eff2a7ab9f9f94cf) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Refactor agent distribution from custom `pi.agents` to standard `pi.prompts`
+
+  - Rename `agents/` directory to `prompts/` to follow pi's standard resource type
+  - Use `pi.prompts` in package.json instead of non-standard `pi.agents`
+  - Remove legacy bundled-directory fallback — agent prompts are now resolved via pi's package manager
+  - Remove `/delegate-agents` command (unused; `/run-agent` and `subagent` tool cover all usage)
+  - Extract shared spawn logic into `spawn-utils.ts`, eliminating cross-file duplication between `agent-runner.ts` and `index.ts`
+  - Remove dead exports (`formatAgentList`, `buildSynthesisPrompt`, `SYNTHESIS_INSTRUCTION`)
+  - Clean up unused imports
+  - Maintainability score improved from 70.7 (moderate) to 90.6 (good)
+  - Model configuration (`model`, `thinking`, `tools` frontmatter) is unchanged
+
+## 0.7.0
+
+### Minor Changes
+
+- [`0be7b68`](https://github.com/dreki-gg/pi-extensions/commit/0be7b6877e9874b46c756b58c99d599db623ef11) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Remove the `/delegate` command from `@dreki-gg/pi-subagent`.
+
+  - keep the `subagent` tool as the primary orchestration surface
+  - keep `/run-agent` for direct named-agent runs
+  - keep `/delegate-agents` for agent management
+  - update docs and the `spawn-subagents` skill to point rigid multi-step flows toward prompt templates and direct `subagent` chain/parallel usage instead of `/delegate`
+
+### Patch Changes
+
+- [`0be7b68`](https://github.com/dreki-gg/pi-extensions/commit/0be7b6877e9874b46c756b58c99d599db623ef11) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Migrate TypeBox usage and session replacement flows for Pi 0.69 compatibility.
+
+  - switch extension imports from `@sinclair/typebox` to `typebox`
+  - update package peer dependencies to require `typebox`
+  - move subagent `/run-agent` fork-at follow-up work into `withSession` so post-fork operations use the replacement session safely
+  - add command argument completions for `/run-agent`, `/delegate-agents`, `/preset`, `/mode`, and `/plan`
+  - align local development dependencies with Pi 0.69 for typechecking and compatibility checks
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @dreki-gg/pi-subagent
 
-Subagent tool and delegate orchestration for pi — isolated agents, parallel scouts, planning gates, and workflow presets.
+Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled prompts.
 
 ## Install
 
@@ -18,99 +18,107 @@ The `subagent` tool supports three modes:
 | Parallel | `{ tasks: [...] }` — multiple agents concurrently |
 | Chain | `{ chain: [...] }` — sequential with `{previous}` placeholder |
 
+Optional overrides:
+- `model` — override the agent's default model for one run, or set a default for all tasks/steps in a call
+- `thinking` — override the agent's default reasoning level for one run, or set a default for all tasks/steps in a call
+
+Notes:
+- `/run-agent` provides autocomplete for `--model` and `--thinking`
+- the `subagent` tool supports the same fields in its schema, but this package does not currently add custom interactive autocomplete for tool-call JSON parameters
+
+## Opinionated Defaults
+
+This package is intentionally opinionated about orchestration:
+
+- Use **parallel mode for discovery, not competing edits**.
+- Prefer **one worker** and surround it with scouts, planners, and reviewers.
+- Use **chain mode** when work needs ordered handoffs.
+- Treat `reviewer` as a **verifier with fresh context**, not as a second writer.
+- Use `advisor` for **targeted second opinions** on tricky or high-risk cases, not as a default extra hop.
+- Only split implementation across multiple workers when file ownership is clearly partitioned.
+
+A good default mental model is: **parallel readers, single writer**.
+
+See [`docs/orchestration-principles.md`](./docs/orchestration-principles.md) for the fuller guidance.
+
 ## Recommended Usage
 
 In day-to-day use, the main agent should usually call the `subagent` tool from normal conversation.
 
-Examples:
+Safe defaults:
 - "spawn a scout for the auth code"
 - "run scout and docs-scout in parallel"
 - "have planner make a plan, then worker implement it"
 - "send this to reviewer"
+- "ask advisor whether this migration should be split before sending it to worker"
+- "use manager for this cross-package migration"
 
 For direct user-invoked single-agent runs, use:
 
 ```text
 /run-agent worker implement the auth flow we discussed
+/run-agent --model anthropic/claude-opus-4-6 --thinking high reviewer review the latest diff
 ```
 
-`/delegate` is optional. It exists for rigid gated workflows, plan approval, and explicit workflow control.
+Autocomplete notes:
+- `/run-agent --model` suggests available configured models plus models referenced by discovered agents
+- `/run-agent --thinking` suggests supported reasoning levels such as `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`
 
-## Optional Delegate Command
-
-After a design/grill session, or when you explicitly want a guided workflow:
-
-```
-/delegate
-```
-
-Or with an explicit task:
-
-```
-/delegate implement the auth flow we designed
-```
+For reusable multi-step workflows, prefer the main agent calling the `subagent` tool directly in `single` / `parallel` / `chain` mode rather than relying on canned slash workflows.
 
-Use project-local repo agents:
-
-```
-/delegate --scope project implement the subagent refactor
-```
-
-Pin a workflow and skip the project-agent confirmation prompt:
+Examples:
 
-```
-/delegate --scope project --workflow implement --yes-project-agents improve delegate execution
+```text
+spawn scout and docs-scout in parallel for auth session refresh
+have worker implement the questionnaire validation fix
+send this diff to reviewer, and if a claim needs proof use validator or bug-prover
+ask advisor whether this migration should be split before implementation
+use manager for this cross-package migration
 ```
 
-### How it works
+Recommended pattern in practice:
+- `parallel`: `scout` + `docs-scout` for repo and docs recon
+- `chain`: `scout` → `planner` → `worker` for coherent implementation
+- `chain`: `worker` → `reviewer`, then optionally `validator` / `bug-prover`, then `worker` for a prove-before-fix loop
+- `single`: `advisor` for a focused second opinion on a hard decision, failing test loop, or high-risk change
+- `single`: `manager` for multi-slice work that needs bounded delegation and synthesis
 
-1. **Synthesize** — extracts goal, decisions, constraints, architecture, intent from conversation
-2. **Confirm** — shows synthesis for approval
-3. **Pick workflow** — suggests one, you confirm or override
-4. **Execute** — runs phases sequentially with parallel scouts
-5. **Plan gate** — shows planner output for approval before worker runs
-6. **Summary** — full phase-by-phase report with usage totals
+`advisor` and `manager` are higher-level entry points built on the same `single` / `parallel` / `chain` primitives. `advisor` is for capability routing and second opinions; `manager` is for coherent delegation, not arbitrary peer-to-peer swarms. `validator` and `bug-prover` support evidence-driven review: validate a claim first, then build the smallest repro only when needed.
 
 ## Direct Agent Runs
 
 Run one agent directly from the current session:
 
 ```text
-/run-agent [--scope user|project|both] [--yes-project-agents] <agent> [task]
+/run-agent [--scope user|project|both] [--model <id>] [--thinking <level>] [--yes-project-agents] <agent> [task]
 ```
 
 Examples:
 
 ```text
 /run-agent scout trace how auth state is loaded
+/run-agent validator validate whether this suspected regression is real
+/run-agent bug-prover create a minimal failing repro for the auth refresh bug
+/run-agent advisor sanity-check whether this migration should be split
+/run-agent manager coordinate a multi-package migration plan
 /run-agent worker implement the refactor we just planned
 /run-agent --scope project reviewer review the latest changes
 ```
 
 If the chosen agent frontmatter sets `sessionStrategy: fork-at`, the command clones the current active path into a new session before running the agent. That keeps long implementation runs isolated in their own branch while preserving the original conversation.
 
-### Delegate Flags
+### `run-agent` Flags
 
 | Flag | Meaning |
 |------|---------|
 | `--scope user|project|both` | Which agent layers to use. Default: `user` |
-| `--workflow <id>` | Skip the picker and force a workflow |
+| `--model <id>` | Override the agent model for this run |
+| `--thinking <level>` | Override the default reasoning level for this run |
 | `--yes-project-agents` | Disable the confirmation prompt for project-local agents |
 
-### Workflows
-
-| Workflow | Phases |
-|----------|--------|
-| Scout only | scout ∥ docs-scout |
-| Scout and plan | scout ∥ docs-scout → planner |
-| Implement | scout ∥ docs-scout → planner → worker |
-| Implement and review | scout ∥ docs-scout → planner → worker → reviewer |
-| Quick fix | worker |
-| Review | reviewer |
-
 ## Agent Definitions
 
-Create agent files in `~/.pi/agent/agents/` or `.pi/agents/` as markdown with YAML frontmatter:
+Create agent prompt files in `~/.pi/agent/prompts/` or `.pi/prompts/` as markdown with YAML frontmatter:
 
 ```markdown
 ---
@@ -128,36 +136,40 @@ System prompt for the agent.
 
 The package ships with these agents out of the box:
 
-- `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
-
-Resolution order is: bundled → user (`~/.pi/agent/agents/`) → project (`.pi/agents/`). Project agents override user and bundled agents by name.
+| Agent | Purpose | Default model | Default reasoning level |
+|------|---------|---------------|-------------------------|
+| `scout` | Fast codebase recon | `openai/gpt-5.4-mini` | `medium` |
+| `docs-scout` | Context7-first documentation lookup | `openai/gpt-5.4-mini` | `medium` |
+| `planner` | Implementation planning | `openai/gpt-5.4` | `high` |
+| `worker` | General-purpose implementation | `openai/gpt-5.4` | `medium` |
+| `reviewer` | Code review | `openai/gpt-5.4` | `medium` |
+| `validator` | Validate or falsify a specific bug or behavior claim from code, tests, and commands | `openai/gpt-5.4` | `medium` |
+| `bug-prover` | Create the smallest failing repro for a suspected bug | `openai/gpt-5.4` | `medium` |
+| `advisor` | Focused second-opinion consult for tricky planning, implementation, or review decisions | `openai/gpt-5.4` | `medium` |
+| `manager` | Bounded orchestration for multi-slice work | `openai/gpt-5.4` | `high` |
+| `ux-designer` | Frontend UI design | `anthropic/claude-opus-4-6` | `medium` |
+
+Notes:
+- `worker`, `reviewer`, `bug-prover`, and `manager` default to `sessionStrategy: fork-at`.
+- "Default reasoning level" maps to the frontmatter field `thinking` and can be overridden per run.
+
+Resolution order is: bundled → user (`~/.pi/agent/prompts/`) → project (`.pi/prompts/`). Project agents override user and bundled agents by name.
 
 Optional frontmatter:
-- `thinking` — reasoning effort for the spawned pi process
+- `thinking` — default reasoning effort for the spawned pi process
 - `sessionStrategy: fork-at` — when used with `/run-agent`, clone the current active branch into a new session before running
 
-> Note: pi now supports package-shipped agents via `pi.agents` (or conventional `agents/` directories). This package publishes its bundled agents that way, while user agents in `~/.pi/agent/agents/` and project agents in `.pi/agents/` still override them by name.
-
-### Managing Agents
-
-```
-/delegate-agents              # list all agents with source
-/delegate-agents reset scout  # restore bundled version
-/delegate-agents reset --all  # restore all bundled versions
-/delegate-agents edit scout   # copy bundled to user dir for customization
-```
+> Note: pi supports package-shipped prompts via `pi.prompts` (or conventional `prompts/` directories). This package publishes its bundled agent prompts that way, while user prompts in `~/.pi/agent/prompts/` and project prompts in `.pi/prompts/` still override them by name.
 
 ## Bundled Resources
 
 ### Skill
 - `spawn-subagents` — guides the model on when/how to spawn specialized subagents conversationally
 
-### Prompt Templates
-- `/implement` — scout → planner → worker
-- `/scout-and-plan` — scout → planner
-- `/implement-and-review` — worker → reviewer → worker
+### No Prompt Templates by Design
+This package intentionally does **not** ship canned workflow prompts.
+
+Prefer:
+- normal conversation that leads the main agent to call `subagent`
+- direct `/run-agent <agent> ...` for explicit single-agent runs
+- examples in this README and `docs/orchestration-principles.md` for common orchestration shapes

package/docs/orchestration-principles.md

@@ -0,0 +1,132 @@
+# Orchestration Principles
+
+`@dreki-gg/pi-subagent` is an opinionated orchestration package.
+
+Its default operating model is simple: use extra agents to improve reconnaissance, planning, and review, while keeping implementation coherent under one writer unless ownership is clearly partitioned.
+
+## Default philosophy
+
+- Prefer **one writer, many thinkers**.
+- Use **parallel mode for discovery**, not for competing edits.
+- Use **chain mode for safe sequential handoffs** between scout, planner, worker, and reviewer.
+- Treat `reviewer` as a **fresh-context verifier**, not as a second implementation agent.
+- Reach for subagents to reduce context rot and sharpen conclusions, not to create an arbitrary swarm.
+
+## When to use each mode
+
+### `single`
+
+Use `single` when one specialist can do the job.
+
+Good fits:
+- `scout` tracing a code path
+- `docs-scout` checking framework or library docs
+- `planner` producing a focused implementation plan
+- `worker` implementing a bounded change
+- `reviewer` performing a focused review
+- `validator` confirming or falsifying a specific bug claim
+- `bug-prover` creating a minimal failing repro when proof needs a new artifact
+
+### `parallel`
+
+Use `parallel` when tasks are read-heavy, independent, and easy to synthesize.
+
+Good fits:
+- `scout` + `docs-scout` gathering code and docs context at the same time
+- two scouts inspecting different subsystems
+- multiple reviewers checking different bounded concerns
+
+Avoid `parallel` when two agents would edit the same files, make overlapping design decisions, or race to implement the same slice.
+
+### `chain`
+
+Use `chain` when a task benefits from ordered handoffs.
+
+Good fits:
+- discovery before planning
+- planning before implementation
+- implementation before review
+- review findings before a final fix pass
+
+Prefer compact handoffs and summaries over long transcript dumps.
+
+## Recommended workflows
+
+### Scout → planner → worker
+
+Use this when the task is unclear or spans multiple files.
+
+- `scout` identifies relevant code, constraints, and touched files
+- `planner` turns that into a concrete implementation path
+- `worker` executes with a coherent plan
+
+### Worker → reviewer → validator / bug-prover → worker
+
+Use this when you want fresh-context verification before returning a result and some review claims need proof.
+
+- `worker` makes the change
+- `reviewer` checks the diff and code with a fresh lens
+- `validator` confirms uncertain claims from commands, existing tests, and code
+- `bug-prover` creates the smallest failing repro only when proof needs a new artifact
+- `worker` applies concrete, scoped fixes after claims are evidenced
+
+### Scout + docs-scout in parallel
+
+Use this when both repository context and external documentation matter.
+
+- `scout` inspects the local codebase
+- `docs-scout` checks framework, library, or API docs
+- the main thread synthesizes both into one next action
+
+## Non-goals
+
+This package is not trying to optimize for:
+
+- arbitrary agent swarms
+- multi-writer editing without clear file ownership
+- speculative parallel implementations of the same task
+- using subagents as a substitute for coherent architecture decisions
+- pushing raw agent logs back into the main thread as the primary artifact
+
+## Examples
+
+### Single specialist
+
+```text
+/run-agent scout trace how auth state is loaded
+```
+
+### Parallel recon
+
+```ts
+subagent({
+  tasks: [
+    { agent: "scout", task: "Trace how auth state is loaded" },
+    { agent: "docs-scout", task: "Check the latest auth library session refresh docs" },
+  ],
+})
+```
+
+### Plan then implement
+
+```ts
+subagent({
+  chain: [
+    { agent: "scout", task: "Find all code relevant to auth session refresh" },
+    { agent: "planner", task: "Create an implementation plan for auth session refresh using {previous} as the handoff" },
+    { agent: "worker", task: "Implement the auth session refresh plan from {previous}" },
+  ],
+})
+```
+
+### Implement and review
+
+```ts
+subagent({
+  chain: [
+    { agent: "worker", task: "Implement questionnaire validation improvements" },
+    { agent: "reviewer", task: "Review the diff using {previous} as a compact handoff" },
+    { agent: "worker", task: "Address concrete findings from {previous}" },
+  ],
+})
+```