pi-subagents 0.81.0 → 0.82.1

package/skills/pi-subagents/references/orchestration.md

@@ -0,0 +1,124 @@
+# Orchestration
+
+Use this when several tasks need coordinated children, worktrees, or
+repositories, or when a change goes through write, review, and fix rounds.
+Create lanes only after delegation is operator-authorized and each lane
+materially improves evidence, independent review, specialization, useful
+parallelism, or isolated execution. Keep dependent work serial.
+
+## Recipes
+
+Recipes select a shape; they do not authorize delegation. Pick the smallest:
+
+- **Recon then implement:** one focused `scout`, then one `worker` that gets its findings.
+- **Implementation:** settle scope and acceptance first, then use a scout, writer, or fresh reviewer only where that stage earns its overhead. Split large work into serial milestones, not a writer swarm.
+- **Parallel analysis:** fan out only independent read, review, or validation work, or give each writer its own worktree.
+
+## Seams before writers
+
+Before launching a writer for substantial mutation work, classify it as
+**single-seam** or **multi-seam**. Two or more independently testable
+contracts or source boundaries make it multi-seam. One PR does not imply one
+writer.
+
+- **Multi-seam:** give each component writer exclusive file or contract
+  ownership, a focused gate, and a committed or otherwise durable handoff.
+  Start one integration-only owner after those handoffs are ready. Repartition
+  any writer brief that owns all major outcomes across independent boundaries.
+- **Single-seam:** one writer is right when the work is one coupled seam, or
+  when splitting would create overlapping ownership or artificial handoffs.
+  Record that evidence. Do not split coupled work to raise the lane count.
+
+## Lane board
+
+Before more than one mutation-capable lane starts, record in the parent:
+
+`Lane | repo/cwd | decision | owned files or contract | isolation path | authority | next gate | handoff | why independent`
+
+One source seam or decision is one lane. Record each lane's delivery target,
+allowed actions, validation, and review rigor. For cross-repository work,
+name the shared contract and which repository changes first. A blocked
+decision is a lane state: owner, options, recommended default, and the
+evidence needed to continue.
+
+Mutation lanes need distinct isolation paths and explicit `cwd` values.
+`worktree: true` branches from `HEAD` (or `baseRef`) and refuses a dirty
+checkout; in a shared or dirty checkout, commit first or give each lane a
+worktree you created. Use one async workflow for a coordinated wave:
+`runs.all` for independent lanes, `runs.run` for dependent stages, repo slug
+or lane key in every child key and output path.
+
+While one lane waits, run safe independent preparation, validation, or
+read-only review. When only async lanes remain, record what reopens work and
+yield; completion wakes the parent.
+
+## Review loop
+
+1. Inspect the source, diff, issue, or plan directly.
+2. One writer implements inside its boundary and runs focused validation that can fail for the changed behavior.
+3. When the delegation contract calls for independent review, fresh-context read-only reviewers inspect the actual worktree. Otherwise parent inspection is enough; skip review for trivial wording, renames, or local probes.
+4. The parent classifies findings (below) and sends accepted fixes to one writer: resume the original worker with its latest run id, or launch one forked `worker` as `/review-loop` does.
+5. Re-run affected validation and review only the changed blast radius.
+6. Stop when no blocker or fix worth doing now remains, an unapproved product, scope, or architecture decision appears, or the round cap is reached (default 3). Do not loop for polish. Children never decide the loop outcome.
+
+An async writer's handoff is an intermediate state, not completion, unless the
+user asked for writer-only work.
+
+| Situation | Review shape |
+| --- | --- |
+| One coherent diff or risk | one reviewer |
+| Independent risks (correctness, tests, security, UI) | parallel reviewers with distinct contracts |
+| Possible over-scope | same-writer challenge before fresh review |
+| Material design tradeoff | council mode |
+
+### Staged fixes
+
+When reviews have produced findings across several clusters:
+
+1. Run a read-only planning fanout, one reviewer per cluster or angle, each returning exact files, lines, fixes, and validation.
+2. Classify the accepted fixes as single-seam or multi-seam (above) on the lane board before any writer starts.
+3. Give a writer only its assigned stage. Pass each earlier result into the later task by variable or by its declared `output` path, not as a whole aggregate blob. With `runs.lanes`, keep stages narrow: red test, helper change, one render seam, validation, review.
+4. Validate the integrated result with fresh read-only reviewers on distinct angles.
+
+When a child returns a target list, validate it in JavaScript and map bounded
+entries into `runs.all`.
+
+## Finding disposition
+
+Classify each finding against the current head:
+
+- **Valid blocker:** concrete failure, repro, security issue, contract mismatch, or source-proven regression. Fix now.
+- **Valid non-blocker:** real but outside the slice. Record or defer.
+- **Stale:** already fixed or absent. Cite current evidence.
+- **Invalid:** contradicted by source, tests, docs, or approved scope. Cite it.
+- **Out of scope or policy:** needs an unapproved product, architecture, authority, or release decision. Escalate.
+- **Speculative:** no contract, repro, or reachable failure. Do not block.
+
+Classify bot comments the same way before assigning severity.
+
+## Gate failures
+
+1. Confirm the run belongs to the exact head under judgment.
+2. Read the focused failing log; name the failing test, assertion, or contract.
+3. Classify: current diff, stale test, environment, or existing flake.
+4. Reproduce with the narrowest command when practical.
+5. Patch forward when the diff caused it. For a stale or flaky failure, collect proof before one rerun.
+6. Re-run the affected command or exact-head gate after every fix.
+
+## Handoff and cleanup
+
+A handoff states lane status, repository and worktree, changed files,
+validation, open decisions, next action, and artifact or receipt paths. Copy
+only final evidence to memory, a mission, a PR, or an approved docs path, then
+remove scratch reports from the worktree.
+
+Keep a worktree until its handoff is durable, no run owns it, and no later
+gate needs it. If a run stops or needs attention, preserve its worktree and
+artifacts, then resume that run or start one replacement lane from the
+handoff. Never start a second writer while worktree ownership is unclear.
+
+Before reporting done, check the board: every lane terminal or blocked with a
+named next action; one writer per worktree; required validation and fresh
+review done; accepted findings fixed and revalidated; publication authority
+present before any push, comment, merge, or release; residual risks and
+skipped checks stated.

package/skills/pi-subagents/references/prompting-and-roles.md

@@ -1,297 +1,98 @@
-# Pi Subagents: Prompting And Roles
-
-This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
-
-## Capability ceilings
-
-Parent extensions may register a session-scoped, out-of-band ceiling through `pi-subagents/capability-ceiling`. Child tools and eligible canonical agent names are intersected with every active registration and inherited snapshot; `denyExtensions` removes ambient/provider extension loading while retaining package protocol runtime. `{ action: "list" }` marks non-allowlisted agents as restricted, and launch rejects them before spawn. Do not add a model-visible ceiling field or rely on unrestricted role selection for enforcement. Restricted schedules are rejected until their ceiling can be persisted safely.
-
-## When to Use
+# Prompting and Roles
 
 All launch guidance below assumes delegation was requested by the operator in
-the current request or applicable user/project instructions. Complexity,
-workflow fit, and potential quality gains help choose a shape after that gate;
-they do not authorize a launch.
-
-- **Complex work orchestration**: after delegation is authorized, keep the parent on its ordinary strong default model and launch only when a bounded child materially improves evidence, independent review, specialization, useful parallelism, or isolated execution. For hard orchestration or root-cause questions, use a top-reasoning model only as a bounded read-only critic/oracle escalation, never as an autonomous root. Lightweight one-off delegation can stay lightweight.
-- **Advisory review**: use fresh-context `reviewer` agents for adversarial code review; fork to `oracle` only for rare escalation where inherited decisions, drift, model routing, root cause, or hard tradeoffs matter
-- **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction
-- **Recon and planning**: use `scout`, then write a plan when needed
-- **Parallel exploration**: run multiple non-conflicting tasks concurrently
-- **Regular skill specialists**: when authorized delegation names or benefits from a relevant specialization, discovery suggestions may help select a small fresh-context fanout
-- **Long-running work**: launch async/background runs and inspect them later. For mutation-capable work, bound the delivery slice and elapsed runtime, then request checkpoints after active tool work returns. Reserve hard tool-call caps for explicitly read-only children.
-- **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
-- **Agent authoring**: create, update, or override project agents. Treat saved chain records as legacy inspection or migration inputs, not as a current authoring target.
-
-## Tool vs Slash Commands
-
-Agents use the `subagent(...)` tool for execution, management, status, and control. Direct `{ agent, task }` execution is enough for one bounded child task; use a workflow script (one ```` ```js workflow ```` block in the reply plus `subagent({ workflow: true })`) when the parent needs JavaScript control flow or data-dependent branching, keyed, parallel, sequential, retry, retained-resume, aggregate, or explicit staged-lane behavior (`runs.lanes`). Humans often use the slash-command layer instead:
-
-- `/run` — launch a single agent
-- `subagent({ workflow: ... })` — the workflow-script surface for sequence, parallelism, branching, retries, and aggregation; with `disabledFeatures: ["workflow-scripts"]`, top-level `chain` and `tasks` replace it (see [configuration](../../../docs/configuration.md#chain-and-tasks-without-workflow-scripts))
-- `/subagents` — interactive admin for inspecting agents and editing model, thinking, or system prompt
-- `/subagents-stop [run-id]` — stop a current-session top-level async run; opens a selector when no id is given
-- `/subagents-detach [run-id]` — detach an active foreground single-subagent run without terminating its child
-- `/subagents-steer <run-id> [--child <child-id>] <message>` — steer a live async run (or one child of it) from non-TUI sessions and RPC hosts
-- `/subagent-cost` — show parent plus child token usage and cost for the session
-- `/subagents-fleet` — open the live fleet inspector with per-child controls; `↑↓`/`jk` selects children, `PgUp`/`PgDn` scrolls transcript detail, `s` steers the selected live async child, and `D` stops its top-level async run after confirmation
-- `/subagents-watchdog` — inspect or configure the opt-in adversarial change watchdog (model, on/off, recommend-model, check)
-- `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
-- `/subagents-models [agent]` — show the live runtime-loaded builtin model mapping
-- `/subagents-profiles`, `/subagents-load-profile`, `/subagents-refresh-provider-models`, `/subagents-generate-profiles`, `/subagents-check-profile` — manage model profiles and provider catalogs
-- `/prompt-workflow` — run a prompt template as a native workflow script
-
-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. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, apply the same pattern directly with `subagent(...)` and other tools:
-- `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
-- `/review-loop` — parent-orchestrated worker, fresh-reviewer, and fix-worker cycles until clean or capped
-- `/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`
-- `/parallel-cleanup` — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff
-- `/council` — bounded advisor council for material decisions, plan critique, cross-exam, and parent-written decision memos
-
-## Applying Prompt Techniques Without Slash Commands
-
-The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. For targets outside the parent cwd, include the exact repository, explicit `cwd`, authority boundary, and expected output path in each child task. Do not depend on the parent conversation history when the recipe calls for fresh context.
-
-### Commission-risk and cold-start packets
-
-After the operator-authority gate above, delegate only when the child materially improves evidence, independent review, specialization, useful parallelism, or isolated execution; do not manufacture parallelism. Every child packet must be cold-start complete: state the goal, exact target/cwd/ref, authority and edit boundary, relevant context/evidence, success criteria, validation, output, and stop/escalation rules. For an orchestration audit by the critic tier, make the child read-only and request at most three omissions, each cited to a file, line, or decision; high thinking is an explicit escalation, not a default.
-
-### Council Mode technique
-
-Use Council Mode when the user asks to convene advisors, debate a material decision, cross-examine recommendations, or critique and improve a plan with several model perspectives. This includes requests such as “run a council on this architecture,” “have the configured advisors critique this plan,” or “get multiple oracles to debate the tradeoffs.” Read `../council-mode/SKILL.md` and follow its bounded parent-supervised protocol instead of launching ad hoc parallel oracle calls.
-
-Council advisors are read-only. User or project `council-*` profiles choose allowed models and define any persistent stance in the profile body. A top-reasoning advisor remains bounded and read-only; it does not become the root. Package advisors such as Surf's `gpt-pro` can join the roster only when the `surf-cli` Pi extension is installed and its `surf-oracle` provider is registered; treat them as external runners, omit child `async` for attached results, and do not pass `outputSchema` to them. The council question and scope provide the decision frame; do not invent per-advisor role labels. The parent collects independent reports, optionally sends curated cross-exam packets, and writes the final memo. Do not treat the council as agent-to-agent chat, implementation authority, or a writer swarm.
-
-### Parallel review technique
-
-Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. Filter on evidence, not severity: report concrete current issues within the named review target, with source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Label findings P0/P1/P2 and end with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. Use `blockers only` only for final pre-merge re-checks after P1/P2 findings are already captured, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred. For targeted follow-up, ask only whether the named finding was resolved, whether the fix introduced a new defect in the fix blast radius, and whether prior P1/P2 notes still stand. For bot or PR-comment triage, classify each comment as VALID, STALE, INVALID, or OUT-OF-POLICY against current HEAD, then assign P0/P1/P2 only to VALID comments. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
-
-### Proactive skill-specialist technique
-
-Use this only within operator-authorized delegation when `{ action: "list" }` reports skill subagent suggestions relevant to the requested handoff. Availability is a selection hint, not authority or a command to fan out.
-
-Default guardrails:
-- Keep the fanout small: usually one or two skill-specialist children, never more than the listed recommendations or configured cap.
-- Prefer `context: "fresh"` and include only the files, diff, plan, URL, or request details each child needs. Use forked context only when private/session history is essential and appropriate to share.
-- Use read-only agents for analysis/review unless implementation was explicitly requested; do not create several writers in the same worktree.
-- Skip proactive skill subagents for tiny questions, direct commands, highly private requests, or when the user asks not to delegate.
-- Make cost and concurrency visible by using an ordinary `subagent(...)` call rather than hidden/background automation.
-
-Example shape:
-
-```js workflow
-const results = await runs.all([
-  { key: "deslop", agent: "reviewer", task: "Apply the available 'deslop' skill to review the current diff for concrete cleanup findings only. Do not modify files.", skill: "deslop" },
-  { key: "accessibility", agent: "reviewer", task: "Apply the available 'accessibility' skill to review the UI changes for concrete issues only. Do not modify files.", skill: "accessibility" }
-]);
-return results.map(result => result.output);
-```
-
-```typescript
-subagent({ workflow: true, options: { context: "fresh" } })
-```
-
-### Review-loop technique
-
-Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `worker` applies them. The parent can express the sequence up front as an async/background workflow script when the workflow is known, or continue with explicit follow-up workflow script runs after each async completion. For an initial workflow, pass `async: true` so the main chat is unblocked. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no P0 blockers or P1 fixes worth doing now, remaining P2 feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
-
-As a conservative orchestration policy, do not pass a hard `toolBudget` to an implementation worker, fix worker, reviewer with edit authority, or other mutation-capable child. The default tool budget blocks read/search tools rather than mutation tools, but count limits still do not measure delivery safety. Use a narrow task plus an outer elapsed deadline with enough margin, then request a checkpoint after the current tool returns. The checkpoint should report changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be used as the checkpoint trigger.
-
-### Parallel research technique
-
-Use this when the question needs both external evidence and local implications. Combine `researcher` for official docs, specs, ecosystem behavior, recent changes, benchmarks, and primary sources with `scout` for repository files, patterns, constraints, tests, and likely integration points. Give each child a distinct angle: external evidence, local code context, and practical tradeoffs. Ask for source links or file ranges, confidence level, gaps, and decision implications. Do not ask these children to edit unless implementation was explicitly requested.
-
-
-
-### Gather-context-and-clarify technique
-
-Use this when the operator requests delegated context gathering. Launch `scout` for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
-
-### Parallel cleanup technique
-
-Use this after implementation when the user or applicable instructions request delegated cleanup review. Launch two fresh-context `reviewer` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
-
-### Staged fix orchestration technique
-
-Use this when a broad diff has known reviewer findings across several items and the user wants the parent to “orchestrate subagents like a boss.” Keep mutation ownership explicit in the workflow script:
-
-When staged seams are available, a low-tier writer should not receive the
-end-to-end issue. Use `runs.lanes` inside the workflow script to keep stages narrow:
-a scout/red test, helper-only change, one render seam, validation, minimality
-challenge, or fresh review. Give the writer only its assigned implementation
-stage; keep sequencing and synthesis with the parent.
-
-1. A parallel read-only planning fanout, one reviewer per issue cluster or review angle. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit.
-2. Classify the accepted fixes on the lane board before writer launch. If issue clusters are independently testable source or contract boundaries, use isolated component writers with exclusive file/contract ownership and focused gates. Each component must commit or produce another durable handoff; only after those handoffs are ready, start one integration-only owner.
-3. Use one writer for the complete fix only when the accepted fixes are one tightly coupled existing diff/seam and the lane board records evidence that splitting would create overlapping ownership or artificial handoffs. Give that writer the planning summaries, accepted scope, stop rules, and verification contract.
-4. Run fresh-context, read-only validation against the integrated or single-seam result. Validators use distinct angles and report pass/fail, remaining blockers, and missing verification.
-
-Prefer `async: true`, `context: "fresh"` for reviewers/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Use stable `runs` keys plus `phase` and `label` on each launch item to make async status readable, and hold each awaited result in an ordinary JavaScript variable when a later step needs that specific result — interpolate it (or the durable output path you declared for that child) into the later task text instead of passing a whole aggregate blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
-
-When one child returns a structured target list, use ordinary JavaScript to validate/filter it and map bounded entries into `runs.all`; do not use the removed chain fanout DSL.
-
-Single-seam example shape (the lane board records that these are review angles on one tightly coupled deployment-lifecycle diff, not independent implementation contracts):
-
-```js workflow
-// Stage 1: parallel read-only review angles on one recorded single seam
-const plans = await runs.all([
-  { key: "correctness-plan", agent: "reviewer", phase: "Planning", label: "Review lifecycle correctness", task: "Plan correctness fixes for the same deployment-lifecycle diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/correctness.md", outputMode: "file-only" },
-  { key: "regression-plan", agent: "reviewer", phase: "Planning", label: "Review lifecycle regressions", task: "Plan regression coverage for the same deployment-lifecycle diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/regressions.md", outputMode: "file-only" },
-  { key: "minimality-plan", agent: "reviewer", phase: "Planning", label: "Review lifecycle minimality", task: "Plan minimality fixes for the same deployment-lifecycle diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/minimality.md", outputMode: "file-only" }
-]);
-
-// Stage 2: one writer for this lane-board-recorded single seam.
-// Under outputMode "file-only" the awaited .output is the saved-output
-// reference, so pass those managed artifact references to the writer.
-const worker = await runs.run("apply-fixes", {
-  agent: "worker",
-  phase: "Implementation",
-  label: "Apply accepted fixes",
-  task: "Apply only the accepted fixes to the one deployment-lifecycle seam. The lane board records that splitting this existing diff would create overlapping ownership. You are the sole writer for this seam. Run focused validation and report changed files, commands, failures, and remaining issues.\n\nCorrectness plan: " + plans[0].output + "\n\nRegression plan: " + plans[1].output + "\n\nMinimality plan: " + plans[2].output,
-  output: "worker/fixes.md",
-  outputMode: "file-only"
-});
-
-// Stage 3: parallel read-only validation fanout
-const validations = await runs.all([
-  { key: "validate-behavior", agent: "reviewer", phase: "Validation", label: "Validate lifecycle behavior", task: "Validate behavior in the post-worker deployment-lifecycle diff. Start from the worker result: " + worker.output + ". Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/behavior.md", outputMode: "file-only" },
-  { key: "validate-minimality", agent: "reviewer", phase: "Validation", label: "Validate lifecycle minimality", task: "Validate minimality in the same post-worker deployment-lifecycle diff. Start from the worker result: " + worker.output + ". Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/minimality.md", outputMode: "file-only" }
-]);
-
-return { worker: worker.output, validations: validations.map(v => v.output) };
-```
-
-```typescript
-subagent({ workflow: true, async: true, options: { context: "fresh" } })
-```
-
-## Builtin Agents
-
-Builtin agents load at the lowest priority. Project agents override user agents,
-and user/project agents override builtins with the same name.
-
-| Agent | Purpose | Recommended tier | Typical output / role |
-|-------|---------|-------|------------------------|
-| `scout` | Fast codebase recon | fast worker/scout tier | Writes `context.md` handoff material |
-| `worker` | Implementation and approved oracle handoffs | capable worker tier | Single-writer implementation with decision escalation |
-| `reviewer` | Review specialist | strong reviewer tier; high thinking for serious reviews | Default recipes are review-only; tools include edit/write when a fix pass is explicit |
-| `researcher` | Web research brief generator | inherits configured default | Writes `research.md` |
-| `delegate` | Lightweight generic delegate | inherits configured default | No fixed output; generic delegated work |
-| `oracle` | Rare hard-decision/root-cause escalation | top-reasoning critic tier, bounded read-only; high thinking escalation only | Advisory trajectory review, not routine code review |
-| `advisor` | Compatibility alias for `oracle` | top-reasoning critic tier, bounded read-only; high thinking escalation only | Same advisory escalation role as `oracle` |
-
-Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Agents without the corresponding field follow `subagents.defaultExtensions` or the ambient-preserving `subagents.defaultSubagentOnlyExtensions` when set.
-
-Builtin agents inherit the current Pi default model unless a run, user setting, project setting, or `subagents.defaultModel` overrides `model`. The table records recommended tier routing, not shipped hard defaults; explicit run, user, or project settings still win. Keep the parent/orchestrator on the ordinary strong default model unless parent/user policy says otherwise. Override builtin defaults before copying full agent files when a small tweak is enough.
-
-Set `subagents.defaultThinking` to apply a shared thinking level to builtin, package, user, and project agents whose frontmatter leaves `thinking` unset. Project settings win over user settings; matching `agentOverrides.<name>.thinking` and per-run overrides replace frontmatter, while an explicit frontmatter value remains in effect when no matching override is set. This setting affects child agents only and does not change the parent session's default thinking level.
-
-```json
-{
-  "subagents": {
-    "defaultThinking": "medium"
-  }
-}
-```
-
-For one run, use inline config:
-
-```text
-/run reviewer[model=provider/review-model] "Review this diff"
-```
-
-For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides. Use `/subagents-models` or `subagent({ action: "models" })` to inspect the live mapping after settings and overrides load.
-
-Provider-scoped entries can layer on top of the default override for the active parent session provider. The provider is selected once from the parent model. Within each settings file, the provider entry wins per field; project settings still win over user settings.
-
-```json
-{
-  "subagents": {
-    "agentOverrides": {
-      "worker": { "thinking": "medium" }
-    },
-    "agentOverridesByProvider": {
-      "provider-a": {
-        "worker": { "model": "provider-a/fast-worker-model" }
-      },
-      "provider-b": {
-        "worker": { "model": "provider-b/fast-worker-model" }
-      }
-    }
-  }
-}
-```
-
-Model ids do not have to be exact. Separator variations (`fast.worker-v1` vs `fast-worker-v1`), case (`Strong-Review-Model`), and optional trailing date stamps all resolve to the same registry model. Exact `provider/id` wins; a qualified `provider/model` never switches providers. To constrain subagents to a budget or compliance profile, set `subagents.modelScope: { enforce: true, allow: ["approved-provider/*", "second-provider/approved-*"] }` in user or project settings. Out-of-scope models you pass explicitly error and abort; models inherited from frontmatter, `subagents.defaultModel`, agent frontmatter, or the parent session only warn.
-
-For model fleets, use the profile commands instead of hand-editing repeated overrides: `/subagents-refresh-provider-models <provider>`, `/subagents-generate-profiles <provider>`, `/subagents-load-profile <name>`, and `/subagents-check-profile <name>`. Profiles live under `~/.pi/agent/profiles/pi-subagents/` and replace only `settings.subagents` when loaded.
-
-## Prompting role subagents
-
-Builtin role agents inherit the current Pi default model unless you override them. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path.
-
-A strong subagent prompt usually includes:
-- **Goal**: the concrete outcome the child should produce.
-- **Target**: repository, explicit `cwd`, branch/ref/head, and source seam when the target is not the parent cwd.
-- **Authority boundary**: whether the child may read, edit, commit, push, comment, close, merge, publish, or release. Omit or forbid actions that are not approved.
-- **Context/evidence**: relevant plan paths, files, diffs, decisions, or user constraints already approved.
-- **Success criteria**: what must be true before the child can finish.
-- **Hard constraints**: true invariants only, such as no edits for review-only tasks, one writer thread, child must not run subagents unless it is explicitly authorized through `tools: subagent` or `allowNestedSubagents: true`, or escalation for unapproved decisions.
-- **Validation**: targeted checks to run, or the next-best check when validation is impossible.
-- **Output**: the expected summary shape, artifact path, or finding format. Use managed artifact paths for scratch reports; reserve repo-qualified absolute paths for durable handoffs that the user approved.
-- **Stop rules**: when to ask via `intercom` or `contact_supervisor`, when to stop after enough evidence, and when not to keep searching.
-
-Give each role useful discovery anchors. Name source roots, filenames, symbols, types, methods, and paths for scouts. Give workers context files, plans, task paths, and named source seams before asking them to search. Give reviewers changed files, contracts, and any exhaustive-verification target. Tell oracle whether current source behavior, product/policy documents, plans, or inherited decisions are the evidence that matters.
-
-Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell a reviewer to inspect the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell a researcher the retrieval budget: start with broad targeted searches, fetch only the strongest sources, search again only when a required fact is missing, then stop.
-
-For implementation handoffs, name the approved scope and success criteria more clearly than the process. Good prompts say what to change, what not to change, where the evidence lives, how to validate, and when to escalate. They should not ask the child to create another subagent plan or continue the parent conversation.
-
-Settings locations:
-- User scope: `~/.pi/agent/settings.json`
-- Project scope: `.pi/settings.json`
-
-Direct settings example:
-
-```json
-{
-  "subagents": {
-    "agentOverrides": {
-      "reviewer": {
-        "model": "provider/strong-review-model",
-        "thinking": "high",
-        "acceptanceRole": "read-only"
-      }
-    }
-  }
-}
-```
-
-Useful override fields: `description`, `model`, `thinking`,
-`systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`,
-`acceptanceRole`, `disabled`, `skills`, `tools`, `extensions`, and `systemPrompt`.
-`description` replaces the discovered description for builtin and custom agents
-in `list` output, which is useful for deployment-specific routing notes.
-Use `acceptanceRole: false` to clear an override. Create a user or project
-agent with the same name only when you want a substantially different agent.
-
-### Recommended model tiering (optional)
-
-Keep the parent/orchestrator on the ordinary strong default model because omission failures are cheaper than unnecessary commissions. Route workers and scouts to a fast, capable worker tier, and keep serious reviews on the strong reviewer tier at high thinking. Do not use `oracle` or a top-reasoning model as the routine fresh-review default. Use that tier only for bounded, read-only critic/oracle/root-cause audits after ordinary review, CI, bot, or source evidence is insufficient; critic-tier high thinking is escalation-only and never an autonomous root. Explicit parent/user model policy wins over these recommendations.
-
-Examples are illustrative, not requirements. Map these tiers to concrete models in user/project settings or a profile. A non-OpenAI setup should choose comparable available models by capability.
-
-Each child launch uses one resolved model exactly once. If quota or availability fails, surface that failure and let the parent or operator explicitly launch a later attempt with another model. Forked children keep their requested thinking level even when provider-specific reasoning blocks are stripped from the inherited transcript.
-
-If a provider rejects model IDs with thinking suffixes, use
-`subagents.disableThinking: true` in user or project settings to clear bundled
-builtin thinking defaults globally. A higher-precedence per-agent `thinking`
-override can opt one builtin back in or replace custom-agent frontmatter thinking.
-
-Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Set `subagents.defaultSubagentOnlyExtensions` to add shared child-only paths without disabling ambient discovery. For either field, explicit frontmatter suppresses the default and a matching override replaces or false-clears it; lists are not combined.
-
-Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses a short tool description plus an active `promptSnippet`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.
+the current request or applicable user/project instructions. Complexity and
+workflow fit choose a shape after that; they do not authorize a launch.
+
+## Roles
+
+| Agent | Use for | Default context | Tier |
+| --- | --- | --- | --- |
+| `scout` | Codebase recon | fresh | fast |
+| `worker` | Implementation, the single writer | fresh | fast capable |
+| `reviewer` | Code and plan review; read-only (send fixes to `worker`) | fresh | strong, high thinking for serious reviews |
+| `researcher` | Web and primary-source research | fresh | default |
+| `delegate` | Generic bounded task | fresh | default |
+| `oracle` | Rare escalation on direction, drift, root cause, or hard tradeoffs | fork (fresh if the parent session is not persisted yet) | top reasoning, read-only |
+
+Run `subagent({ action: "list" })` for project, user, and package agents;
+project agents override user agents, which override builtins. `worker` and
+`delegate` get only their listed tools; to give a child an extension tool,
+name it in `tools` and load its extension (guide
+`agents/tool-and-extension-selection`). Each launch uses one resolved model;
+on a quota or availability failure, report it rather than picking another
+model.
+
+## Writing the brief
+
+The SKILL.md brief checklist says what goes in. To make it work:
+
+- Write a contract, not a script. Name the destination and let the role pick the path.
+- Give discovery anchors: source roots, files, symbols, and paths for scouts; plans, task paths, and named seams for workers; changed files, contracts, and the verification target for reviewers; which evidence matters (source, policy docs, inherited decisions) for oracle.
+- Use `must`, `always`, and `never` only for real invariants. For judgment calls, give a decision rule.
+- Give researchers a retrieval budget: broad targeted searches, fetch only the strongest sources, search again only for a missing required fact, then stop.
+- For implementation, state what to change, what not to change, where the evidence is, how to validate, and when to escalate. Never ask a child to plan more subagents or continue the parent conversation.
+- When the user gives a URL, issue, PR, plan, or file, read it first and name it explicitly in every child task; fresh children cannot see the parent's history.
+- Review-only children: "Do not modify project/source files; returning findings through the configured output artifact is allowed."
+
+## Techniques
+
+Packaged prompt shortcuts (`/parallel-review`, `/review-loop`,
+`/parallel-research`, `/gather-context-and-clarify`, `/parallel-cleanup`,
+`/council`) encode these. When the user describes one in words, run the same
+shape directly with `subagent(...)`.
+
+**Parallel review.** Fresh-context `reviewer` children, each with a distinct
+angle drawn from the target (correctness and regressions, tests, simplicity;
+adapt for security, UI, TypeScript, docs). Report only concrete current issues
+with source proof, a test or repro, or a contract contradiction; for a diff,
+the diff must cause or expose the issue. Label findings P0/P1/P2 and end with
+`Merge verdict: BLOCK`, `OK`, or `OK with notes`. A follow-up review asks only
+whether the named finding is fixed, whether the fix broke something nearby,
+and whether earlier notes still stand. Bot comments are first classified
+VALID, STALE, INVALID, or OUT-OF-POLICY against the current head.
+
+**Review loop.** Writer, fresh reviewers, accepted fixes to one writer,
+capped at 3 rounds. Details in [orchestration.md](orchestration.md#review-loop).
+
+**Parallel research.** `researcher` for docs, specs, recent changes, and
+primary sources, plus `scout` for local files, patterns, and integration
+points. Ask for links or file ranges, confidence, gaps, and what the evidence
+means for the decision.
+
+**Gather context and clarify.** `scout` for local context, `researcher` only
+when outside sources would change the answer. Then synthesize and ask the user
+the open questions with `interview` before planning.
+
+**Parallel cleanup.** After implementation, two fresh reviewers with
+`output: false`: one deslop pass, one verbosity pass, using the `deslop` and
+`verbosity-cleaner` skills when available. They flag issues with file and line
+and the smallest fix; the parent decides what to apply.
+
+**Skill specialists.** When `list` suggests skill subagents relevant to the
+requested handoff, launch at most one or two, fresh context, read-only unless
+implementation was requested, passing `skill: "<name>"` on a direct call or a
+`runs.run` / `runs.all` item (`workflow: "parallel"` items do not take it). A suggestion is a hint,
+not authority to fan out.
+
+**Oracle consultation.** For "ask/consult the oracle" on a plan or design, run
+one forked `oracle`. If its answer challenges the direction or leaves a
+material tradeoff, resume that same child once with a focused question, then
+decide. Skip the second round for one-shot requests or settled answers. Oracle
+advice approves nothing; `worker` implements only after the parent approves a
+direction. Never use oracle or a top-reasoning model for routine reviews; use
+`reviewer`, and escalate only when review, CI, or source evidence leaves an
+invariant, root-cause, routing, or product question open.
+
+**Council.** For several advisors debating a material decision, follow
+[../../council-mode/SKILL.md](../../council-mode/SKILL.md) instead of ad hoc
+parallel oracle calls.
+
+## Model tiers
+
+Keep the parent on its ordinary strong model. Workers and scouts use a fast
+capable tier; serious reviews use a strong tier at high thinking; a
+top-reasoning model is only a bounded read-only critic after ordinary evidence
+falls short, never an autonomous root. Map tiers to real models in user or
+project settings or a profile (guide `models/setting-defaults-and-overrides`,
+`models/profiles-and-provider-model-catalogs`). Explicit user policy wins.

package/src/agents/agent-management.js

@@ -5,7 +5,7 @@ import { serializeAgent } from "./agent-serializer.js";
 import { mergeAgentsForScope } from "./agent-selection.js";
 import { discoverAvailableSkills, resolveSkills } from "./skills.js";
 import { buildProactiveSkillSubagentRecommendationLines, } from "./proactive-skills.js";
-import { parseFrontmatter, parseFrontmatterList } from "./frontmatter.js";
+import { parseFrontmatter, parseUnquotedList } from "./frontmatter.js";
 import { resolveEffectiveThinking, toModelInfo } from "../shared/model-info.js";
 import { resolveSubagentModelOverride } from "../runs/shared/model-resolution.js";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.js";
@@ -175,9 +175,9 @@ function withDeclaredExtensionPaths(config, filePath) {
     const { extensions: _extensions, subagentOnlyExtensions: _subagentOnlyExtensions, ...withoutResolvedExtensions } = config;
     return {
         ...withoutResolvedExtensions,
-        ...(frontmatter.extensions !== undefined ? { extensions: parseFrontmatterList(frontmatter.extensions) } : {}),
+        ...(frontmatter.extensions !== undefined ? { extensions: parseUnquotedList(frontmatter.extensions) } : {}),
         ...(frontmatter.subagentOnlyExtensions !== undefined
-            ? { subagentOnlyExtensions: parseFrontmatterList(frontmatter.subagentOnlyExtensions) }
+            ? { subagentOnlyExtensions: parseUnquotedList(frontmatter.subagentOnlyExtensions) }
             : {}),
     };
 }

package/src/agents/agent-memory.js

@@ -236,7 +236,9 @@ export function readMemoryFile(memoryDir) {
     let fd;
     try {
         const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
-        fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+        // A FIFO must not block the launch before fstat can reject non-files.
+        const nonBlock = typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0;
+        fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow | nonBlock);
     }
     catch (error) {
         const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";