pi-subagents 0.19.1 → 0.19.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/prompts/gather-context-and-clarify.md

@@ -0,0 +1,13 @@
+---
+description: Use subagents to gather context, then ask clarifying questions
+---
+
+Based on our discussion and my intent, launch focused context-gathering subagents before planning or implementing.
+
+Use `scout` to inspect the relevant local files, existing patterns, constraints, tests, and likely integration points. Use `researcher` when external docs, recent sources, ecosystem context, or primary evidence would improve the answer.
+
+Give each subagent a specific meta prompt. Ask them to return concise findings plus the remaining clarification questions that matter for implementation confidence.
+
+After they return, synthesize what we know and use the `interview` tool to ask me the unresolved questions needed to reach a shared understanding.
+
+$@

package/prompts/oracle-executor.md

@@ -0,0 +1,9 @@
+---
+description: Send an explicitly approved task to oracle-executor with full inherited context.
+subagent: oracle-executor
+inheritContext: true
+---
+
+Launch the oracle-executor subagent with a strict implementation meta prompt that points it at the plan and asks it to execute:
+
+$@

package/prompts/parallel-research.md

@@ -0,0 +1,50 @@
+---
+description: Parallel subagents research
+---
+
+Launch parallel research subagents to build a grounded answer to the current question or decision.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Researchers and scouts should inspect sources directly instead of relying on the main conversation history.
+
+Use a combination of `researcher` and `scout` subagents:
+- Use `researcher` for web, docs, standards, ecosystem, recent changes, benchmarks, and primary-source evidence.
+- Use `scout` for local codebase context, existing implementation patterns, repo constraints, and files that would be affected.
+
+Give each subagent a distinct angle. Unless I specify angles, use these three:
+
+1. External evidence
+   Use `researcher` to find current, authoritative sources: official docs, specs, release notes, benchmarks, issue threads, or primary explanations.
+
+2. Local code context
+   Use `scout` to inspect the repository for relevant files, existing patterns, constraints, tests, and likely integration points.
+
+3. Practical tradeoffs
+   Use `researcher` or `scout`, whichever fits the question, to compare options, risks, edge cases, maintenance cost, and what would be easiest to validate.
+
+Adapt the angles when the question calls for it:
+- Library/API questions: include official docs and recent examples.
+- Architecture decisions: include local module boundaries, dependency direction, and migration cost.
+- Debugging questions: include likely failure modes, local call paths, and exact error evidence.
+- UI/product questions: include user flow, accessibility, design precedent, and implementation constraints.
+- Time-sensitive topics: include a recent-developments angle and prefer 2026/2025 sources.
+
+Prefer two or three strong subagents over many vague ones. The parent agent should frame the question and assign angles; the child agents should research or scout, not invent broad plans.
+
+Ask each subagent to return concise findings with evidence:
+- file paths and line ranges for local findings
+- source links for external findings
+- confidence level and gaps
+- recommended next step or decision implication
+
+Do not ask subagents to edit files. This is a research pass only unless I explicitly ask for implementation.
+
+After the subagents return, synthesize the answer into:
+- what we know
+- what the local codebase implies
+- tradeoffs and risks
+- gaps or assumptions
+- the recommended next move
+
+If findings disagree, call out the disagreement instead of smoothing it over.
+
+$@

package/prompts/parallel-review.md

@@ -1,8 +1,40 @@
 ---
 description: Parallel subagents review
 ---
-Great. Now let's launch parallel reviewers to conduct an adversarial review.
 
-Important: launch reviewers with fresh context, not forked context. Reviewers should inspect the repository and current diff directly from files and commands, without inheriting the main agent chat. Use forked context only if I explicitly ask for it.
+Launch parallel reviewers for an adversarial review of the current work.
+
+Use fresh context, not forked context, unless I explicitly ask for forked context. Reviewers should inspect the repository, relevant instructions, and current diff directly from files and commands. Do not rely on the main conversation history.
+
+Give each reviewer a distinct angle. Generate the angles dynamically from the user's intent, the plan, the implemented code, and the current diff. If I specify angles, use mine. Otherwise, choose the highest-value review angles for this specific work.
+
+These are examples, not fixed defaults:
+
+1. Correctness and regressions
+   Check whether the change satisfies the request, preserves existing behavior, handles edge cases, and avoids hidden runtime failures.
+
+2. Tests and validation
+   Check whether tests or validation were added at the right layer, whether assertions are meaningful, and whether the chosen verification commands are enough.
+
+3. Simplicity and maintainability
+   Check for unnecessary complexity, duplicate structure, single-use wrappers, brittle abstractions, confusing names, verbosity, and cleanup that is clearly worth doing.
+
+Choose or adapt angles when the work calls for it:
+- TypeScript-heavy changes: include type safety, source-of-truth types, casts, and error-boundary discipline.
+- UI-heavy changes: include UX, accessibility, copy, and visual quality.
+- Security-sensitive changes: include unsafe input/output handling, auth boundaries, privacy, and data exposure.
+- Docs-heavy changes: include clarity, accuracy, completeness, reader flow, and non-robotic prose.
+- Large multi-file changes: consider a fourth reviewer for structural friction, module boundaries, and testability.
+
+Prefer three strong reviewers over many vague reviewers.
+
+Give every reviewer a specific task prompt naming its angle. Ask reviewers to return concise, evidence-backed findings with file/line references and suggested fixes. The response should be review feedback, not a context summary. Reviewers must not edit files unless I explicitly ask for a writer pass.
+
+While reviewers run, do your own narrow inspection if useful. After they return, synthesize the feedback into:
+- fixes worth doing now
+- optional improvements
+- feedback to ignore or defer, with a short reason
+
+Do not blindly apply every reviewer suggestion. Ask before applying fixes unless I already told you to address review feedback.
 
 $@

package/skills/pi-subagents/SKILL.md

@@ -15,8 +15,8 @@ agents into a workflow, or create/edit agents and chains on demand.
 
 ## When to Use
 
-- **Advisory review**: fork to `oracle` or `reviewer` for a branched review thread
-- **Implementation handoff**: have `oracle` advise, then `oracle-executor` or `worker` implement
+- **Advisory review**: use fresh-context `reviewer` agents for adversarial code review, or fork to `oracle` when inherited decisions and drift matter
+- **Implementation handoff**: have `oracle` advise, then `oracle-executor` or `worker` implement only after an approved direction
 - **Recon and planning**: use `scout` or `context-builder`, then `planner`
 - **Parallel exploration**: run multiple non-conflicting tasks concurrently
 - **Long-running work**: launch async/background runs and inspect them later
@@ -32,11 +32,19 @@ Humans often use the slash-command layer instead:
 - `/chain` — launch a chain of steps
 - `/parallel` — launch top-level parallel tasks
 - `/agents` — open the agents manager TUI
+- `/run-chain` — launch a saved `.chain.md` workflow
 - `/subagents-status` — inspect active/recent async runs
+- `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
 
 Prefer the tool when you are writing agent logic. Prefer the slash commands when
 you are guiding a human through an interactive flow.
 
+Packaged prompt shortcuts are also available for repeatable workflows:
+- `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
+- `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
+- `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
+- `/oracle-executor` — send an explicitly approved implementation task to `oracle-executor`
+
 ## Builtin Agents
 
 Builtin agents load at the lowest priority. Project agents override user agents,
@@ -54,16 +62,40 @@ and user/project agents override builtins with the same name.
 | `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.5` | Advisory review, intercom coordination |
 | `oracle-executor` | Implementation after approval | `openai-codex/gpt-5.5` | Single-writer implementation after approval |
 
-Override builtin defaults via settings before copying full agent files when a
-small tweak is enough.
+Override builtin defaults before copying full agent files when a small tweak is enough.
+
+For one run, use inline config:
+
+```text
+/run reviewer[model=anthropic/claude-sonnet-4] "Review this diff"
+```
+
+For persistent tweaks, prefer `/agents`: choose the builtin, press `e`, change the model or other fields, then save a user or project override. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides.
 
 Settings locations:
 - User scope: `~/.pi/agent/settings.json`
 - Project scope: `.pi/settings.json`
 
+Direct settings example:
+
+```json
+{
+  "subagents": {
+    "agentOverrides": {
+      "reviewer": {
+        "model": "anthropic/claude-sonnet-4",
+        "thinking": "high",
+        "fallbackModels": ["openai/gpt-5-mini"]
+      }
+    }
+  }
+}
+```
+
 Useful override fields: `model`, `fallbackModels`, `thinking`,
 `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `disabled`,
-`skills`, `tools`, and `systemPrompt`.
+`skills`, `tools`, and `systemPrompt`. Create a user or project agent with the
+same name only when you want a substantially different agent.
 
 ## Discovery and Scope Rules
 
@@ -119,6 +151,21 @@ subagent({
 })
 ```
 
+Top-level parallel tasks can override per-task behavior:
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "scout", task: "Map auth", output: "auth-context.md", progress: true },
+    { agent: "researcher", task: "Research OAuth best practices", output: "oauth-research.md" },
+    { agent: "reviewer", task: "Review auth tests", model: "anthropic/claude-sonnet-4" }
+  ],
+  concurrency: 3
+})
+```
+
+Avoid duplicate output paths in parallel tasks. Concurrent children should not write to the same file.
+
 ### Chain execution
 
 ```typescript
@@ -147,6 +194,14 @@ subagent({
 
 Inspect async runs with `subagent({ action: "status", id: "..." })`, `subagent({ action: "status" })` for active runs, or the `/subagents-status` slash command.
 
+Use diagnostics when setup or child startup looks wrong:
+
+```typescript
+subagent({ action: "doctor" })
+```
+
+Humans can use `/subagents-doctor` for the same read-only report. It checks runtime paths, discovery counts, async support, current session context, and intercom bridge state.
+
 ### Subagent control
 
 Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, or `failed`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck.
@@ -198,6 +253,8 @@ subagent({
 Chains default to clarify mode unless you explicitly set `clarify: false`.
 For programmatic background launches, use `clarify: false, async: true`.
 
+The `/agents` manager also has launch toggles for forked context, background execution, and worktree-isolated parallel runs. Use it when guiding a human who wants to inspect or edit the launch before starting.
+
 ## Worktree Isolation
 
 When multiple agents might write concurrently, use worktrees instead of letting
@@ -249,35 +306,44 @@ history as a baseline contract.
 
 ## Subagent + Intercom Coordination
 
-When `pi-intercom` is installed and enabled, delegated runs can coordinate with
-the orchestrator through the intercom bridge.
+`pi-subagents` works without `pi-intercom`. When `pi-intercom` is installed and enabled, the intercom bridge can automatically give child agents a private coordination channel back to the parent session.
 
-### Subagent asks the orchestrator
+Most agents should not call `intercom` directly unless bridge instructions provide a target. Do not invent a target. Use the target from the injected bridge instructions or from a visible needs-attention notice.
+
+Use `intercom` when:
+- a subagent is blocked on a decision
+- a child needs clarification instead of guessing
+- a detached or async child needs to coordinate without waiting for normal tool return flow
+- an advisory agent was explicitly asked to send a concise progress update
+
+Message conventions:
+- `ask` means the child needs a decision or clarification from the parent session.
+- `send` means a short blocked/progress update, only when blocked or explicitly asked.
+- Routine completion does not go through intercom. The normal subagent result still returns through `pi-subagents`.
+
+If a bridge target is available, a child can ask:
 
 ```typescript
 intercom({
   action: "ask",
-  to: "orchestrator",
+  to: "<bridge-provided-target>",
   message: "Should I optimize for readability or performance here?"
 })
 ```
 
-### Orchestrator replies
+The parent replies with:
 
 ```typescript
 intercom({ action: "reply", message: "Optimize for readability." })
 ```
 
-Or inspect unresolved asks first:
+Or inspects unresolved asks first:
 
 ```typescript
 intercom({ action: "pending" })
 ```
 
-Use `intercom` when:
-- a subagent is blocked on a decision
-- an advisory agent wants to send a concise handoff mid-flight
-- a detached or async child needs to coordinate without waiting for normal tool return flow
+If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/subagents-doctor`.
 
 ## Management Mode
 
@@ -326,6 +392,8 @@ subagent({ action: "delete", agent: "my-agent" })
 Use management actions when the system needs to create or edit subagents on
 demand without dropping into raw file editing.
 
+Management actions create or update user/project agent files. For small builtin changes such as a model swap, prefer `/agents` builtin overrides or `subagents.agentOverrides` in settings.
+
 ## Creating and Editing Agents by File
 
 A minimal agent file looks like this:
@@ -357,7 +425,12 @@ copying a full builtin file.
 
 ## Prompt Template Integration
 
-If `pi-prompt-template-model` is installed, prompt templates can delegate into
+The package includes prompt shortcuts for common workflows: `/parallel-review`,
+`/parallel-research`, `/gather-context-and-clarify`, and `/oracle-executor`.
+Use them when the user wants repeatable review, research, clarification, or
+approved execution patterns.
+
+If `pi-prompt-template-model` is installed, additional user prompt templates can delegate into
 `pi-subagents`. This is useful when a slash command should always run through a
 particular agent or with forked context.
 
@@ -366,7 +439,7 @@ particular agent or with forked context.
 - **Forking requires a persisted parent session.** If the current session does not
   have a persisted session file, forked runs fail.
 - **Forked runs inherit parent history.** They are branched threads, not fresh
-  filtered contexts.
+  filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
 - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
   unless configured otherwise.
 - **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`.
@@ -386,7 +459,10 @@ for the actual write path.
 ### Use fork for branched advisory or execution threads
 
 Forked runs are useful when the child should reason in a separate thread while
-still inheriting the parent’s accumulated context.
+still inheriting the parent’s accumulated context. They are especially useful for
+`oracle`, which audits inherited decisions and drift. For adversarial code review,
+prefer fresh-context reviewers that inspect the repo and diff directly unless the
+user explicitly requests forked context.
 
 ### Prefer narrow tasks
 
@@ -426,8 +502,7 @@ subagent({
 subagent({ agent: "worker", task: "Add retry logic to the API client." })
 subagent({
   agent: "reviewer",
-  task: "Review the retry logic implementation. Look for edge cases and race conditions.",
-  context: "fork"
+  task: "Review the retry logic implementation. Inspect the repo and current diff directly. Look for edge cases and race conditions."
 })
 ```
 
@@ -442,6 +517,14 @@ subagent({
 })
 ```
 
+### Saved chain
+
+```text
+/run-chain review-chain -- review this branch
+```
+
+Use saved `.chain.md` workflows when the user wants a repeatable multi-agent flow without rewriting the chain each time.
+
 ## Error Handling
 
 **"Unknown agent"**
@@ -450,6 +533,12 @@ subagent({ action: "list" })
 // Check available agents and chains, then confirm scope/precedence.
 ```
 
+**Setup, discovery, or intercom confusion**
+```typescript
+subagent({ action: "doctor" })
+// Check runtime paths, async support, discovery counts, current session, and intercom bridge state.
+```
+
 **"Max subagent depth exceeded"**
 ```typescript
 // Flatten the workflow or raise maxSubagentDepth in config.
@@ -464,3 +553,18 @@ subagent({ action: "list" })
 ```typescript
 // Resolve the current outbound ask before starting another one.
 ```
+
+**Parallel output-path conflict**
+```typescript
+// Give each parallel task a distinct output path, or disable output for tasks that do not need it.
+```
+
+**Worktree launch fails**
+```typescript
+// Ensure the git working tree is clean and task cwd overrides match the shared cwd.
+```
+
+**Child fails before starting**
+```typescript
+// Inspect /subagents-status detail, artifact metadata/output logs, and run doctor. Extension loader errors usually appear in child output logs.
+```