pi-subagents 0.82.0 → 0.82.1

package/skills/pi-subagents/references/management-authoring-rpc.md

@@ -1,165 +0,0 @@
-# Pi Subagents: Management Authoring Rpc
-
-This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
-
-## Management Mode
-
-The `subagent(...)` tool also supports management actions.
-
-### List available agents and legacy chain records
-
-```typescript
-subagent({ action: "list" })
-```
-
-### List retained children
-
-```typescript
-subagent({ action: "children.list" })
-```
-
-Lists up to the last 10 retained workflow children from this parent session with explicit `resumable` or `not resumable` rows. This workflow-only roster is not an exhaustive list of direct native children. Resume only rows reported `resumable`. When the exact run id of an intended direct child is known, inspect it with `subagent({ action: "status", id: "<run-id>" })`; if status identifies the candidate, attempt `subagent({ action: "resume", id: "<run-id>", message: "..." })`. Resume performs the authoritative eligibility check and may reject the attempt. Continue one inside a workflow with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`; each workflow key identifies one result lane, so use a new stable workflow key for every distinct retained resume pass. Same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected. The revived child keeps its stored agent, model, and tool contract. Start a same-role fallback challenge, labeled as fallback, only when no known candidate exists or resume rejects eligibility. `steer` with `mode: "follow_up"` only queues text for the next `resume` when the child has already completed.
-
-### Refinement overlays
-
-```typescript
-subagent({ action: "refine", agent: "reviewer" })
-subagent({ action: "refine.show", agent: "reviewer" })
-subagent({ action: "refine.rollback", agent: "reviewer" })
-```
-
-`refine` builds a bounded project-local guidance overlay for one agent from recent run evidence, using a fresh read-only proposal child; validated guidance is stored under `.pi/subagents/refinements/<agent>.md` with revision snapshots and is injected into that agent's child system prompt for this project. `refine.show` prints the current overlay and history; `refine.rollback` restores the previous revision. Guidance that tries to override safety, policy, tool, output, acceptance, developer, or system instructions is rejected. `/subagents-refine <agent>` is the slash equivalent.
-
-### Create an agent
-
-```typescript
-subagent({
-  action: "create",
-  options: {
-    config: {
-      name: "my-agent",
-      package: "code-analysis",
-      description: "Project-specific implementation helper",
-      systemPrompt: "Your system prompt here.",
-      systemPromptMode: "replace",
-      model: "provider/model-id",
-      tools: "read,grep,find,ls,bash"
-    }
-  }
-})
-```
-
-### Update an agent
-
-```typescript
-subagent({
-  action: "update",
-  agent: "code-analysis.my-agent",
-  options: {
-    config: {
-      thinking: "high"
-    }
-  }
-})
-```
-
-### Delete an agent
-
-```typescript
-subagent({ action: "delete", agent: "code-analysis.my-agent" })
-```
-
-### Eject, disable, enable, and reset
-
-```typescript
-// Copy a bundled builtin/package agent to user scope as an editable custom file.
-subagent({ action: "eject", agent: "reviewer" })
-subagent({ action: "eject", agent: "reviewer", options: { agentScope: "project" } })
-
-// Hide an agent from runtime discovery without deleting it (reversible).
-subagent({ action: "disable", agent: "reviewer" })
-subagent({ action: "enable", agent: "reviewer", options: { agentScope: "project" } })
-
-// Delete the scope's custom agent file and/or settings override, restoring the bundled default.
-subagent({ action: "reset", agent: "reviewer" })
-```
-
-`eject` copies a builtin or package agent verbatim into the user (default) or project agent dir so it can be customized without hunting package files; the copy shadows the original by runtime name. `disable` writes a reversible `agentOverrides.<name>.disabled: true` entry to the user or project settings file. `enable` removes that `disabled` field while keeping any other override fields. `reset` removes the scope's custom file and settings override to restore the bundled default, and refuses if no bundled default exists (use `delete` for purely custom agents). All four take optional `agentScope: "user" | "project"`; project overrides win over user ones, so target the project scope to undo a project-scope disable.
-
-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. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and scripted workflow steps. For small agent changes such as a model swap, prefer `subagents.agentOverrides` in settings. Durable `.chain.md` definitions are legacy records, not a current authoring target; use a workflow script file (`workflow: "./path.js"`) or `/prompt-workflow` for repeatable orchestration.
-
-## Creating and Editing Agents by File
-
-A minimal agent file looks like this:
-
-```markdown
----
-name: my-agent
-package: code-analysis
-description: What this agent does
-advertise: true
-aliases: developer, coder
-model: provider/model-id
-thinking: high
-tools: read, grep, find, ls, bash
-systemPromptMode: replace
-inheritProjectContext: true
-inheritGlobalContext: false
-inheritSkills: false
-skills: safe-bash, review-checklist
-skillPath: ./skills, ../shared-skills
----
-
-Your system prompt here.
-```
-
-That is only a starting point. Omit `package` for the traditional unqualified runtime name. Set `advertise: true` only when the parent should receive this agent's name and description before deciding whether to delegate; advertisement is off by default. Common optional fields include:
-- `defaultProgress`
-- `defaultReads`
-- `output`
-- `aliases`
-- `subagentOnlyExtensions`
-- `skills`
-- `skillPath`
-- `memory`
-- `maxSubagentDepth`
-- `acceptance`
-- `acceptanceRole`
-- `async` — single-agent default for background launch (`true`/`false`); explicit tool-call `async` wins
-- `timeoutMs` — single-agent default run-level max runtime in ms; foreground calls use a 30-minute package default only when neither the call nor agent provides one (tool alias `maxRuntimeMs` is also accepted)
-
-`aliases` is an optional comma-separated or block-list set of alternate names for selecting an agent. Aliases resolve to the canonical `name` for execution, status, persistence, and config. Exact canonical names take precedence over aliases, and alias collisions between distinct canonical agents fail as ambiguous. Management create/update accepts a comma-separated string, string array, or `false`/empty string to clear aliases.
-
-`acceptance` is a single-agent launch default. Use a scalar level such as `checked` or an inline/block YAML map such as `{ level: "none", reason: "lightweight lookup" }`. An explicit tool-call value wins; scripted workflow child acceptance remains configured on the `runs.run` or `runs.all` item. Management create/update accepts the same policy object, and `acceptance: ""` clears the frontmatter default (`false` remains the deprecated disabled-policy shorthand).
-
-`acceptanceRole` is `read-only` or `writer` and controls automatic acceptance inference only. The structured role is authoritative; task wording and agent names do not escalate acceptance. Omission uses lightweight attestation. The field does not grant or revoke tools. Management accepts `false` or an empty string to clear it.
-
-`tools` is a strict child allowlist, not an extension loader. For a named extension tool, keep its registered name in `tools` and load its provider through normal Pi discovery, `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. For example, pair `tools: read, fixture_search` with `subagentOnlyExtensions: ./tools/fixture-search.ts` when the provider should exist only in that agent's child sessions. The child now fails with the unavailable names and provider-loading guidance instead of silently continuing when a requested tool is absent; internal `structured_output` is allowed automatically when an output schema requires it.
-
-`skillPath` adds invocation-private skill files or discovery directories relative to the agent file; it does not select them, so list the desired names under `skills`. Local matches win, unresolved or unreadable matches use normal discovery, and local candidates never enter the parent/global catalog. Use `memory: { scope: "project" | "user", path: "<name>" }` for opt-in role-specific durable memory under the dedicated `agent-memory/` namespace; it is separate from parent/session project memory.
-
-For many customizations, builtin overrides in settings are lower-friction than
-copying a full builtin file.
-
-## Prompt Template Integration
-
-The package includes prompt shortcuts for common workflows: `/parallel-review`,
-`/review-loop`, `/parallel-research`, `/gather-context-and-clarify`, and
-`/parallel-cleanup`. Use them when the user wants repeatable review,
-review/fix loops, research, context handoff, implementation handoff,
-clarification, or cleanup-review patterns. `/parallel-review autofix` and
-`/parallel-cleanup autofix` synthesize reviewer feedback and then apply only the
-fixes worth doing now. Parent agents can also apply the same recipes directly
-with `subagent(...)` when the user describes the workflow in natural language
-instead of invoking a slash command.
-
-Additional user prompt templates can delegate into `pi-subagents` through the native `/prompt-workflow` command. This is useful when a slash command should always run through a particular agent or with forked context. Prompt frontmatter can set `subagent`, `model`, `skill`, `cwd`, `fresh`, `fork`, or `inheritContext` for the native adapter.
-
-## Extension RPC
-
-Other Pi extensions can call `pi-subagents` through the in-process event bus. The RPC channels are `subagents:rpc:v1:ready`, `subagents:rpc:v1:request`, and per-request replies at `subagents:rpc:v1:reply:<requestId>`. Envelopes use `{ version: 1, requestId, method, params }`, and replies use `{ version: 1, requestId, success, data | error }`. `ping` advertises the exact process-local async completion event as `events.asyncComplete` for RPC-spawn consumers.
-
-Methods: `ping`, `status`, `manage`, `spawn`, `steer`, `interrupt`, `resume`, `stop`, and `cost`. `ping` capability metadata advertises optional projections: `capabilities.fleetStatus: { version: 1 }` adds bounded current-session `data.fleet` records (opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, `startedAt`, split `{ input, output, total }` tokens, plus `totalActive`/`omitted` overflow counts) to successful `status` replies; `capabilities.launchResolvedExtensions` advertises parent-resolved opaque launch-extension identifiers in status details; `capabilities.runtimeAcknowledgedExtensions` advertises the best-effort child-runtime acknowledgement projection fed by cooperating extensions emitting `subagent:acknowledge-extension`; `capabilities.cost: { version: 1 }` advertises parent-plus-child accounting as data. Foreground `details.results[]` rows carry a stable numeric `index`; correlate children by `(runId, index)` rather than row position. Consumers should read status/result artifacts and RPC projections instead of scraping terminal output and must ignore unknown fields. `spawn` accepts either `{ agent, task? }`, inline script text as `script`, or `workflow` with a script path (containing `/`) or a named workflow resource; `workflow: true` is rejected because RPC has no assistant reply to read. It is async-only and rejects management actions, `async: false`, or `clarify: true`. It reuses the normal executor, so discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status are shared with the `subagent` tool. `manage` accepts only the schedule actions advertised by `ping.capabilities.managementActions`. `status`, acknowledged async `steer`, and `interrupt` map to the normal control actions. RPC steer disables pause-and-revive recovery and advertises `capabilities.nonRecoveringSteer`, preserving the caller's authority over the exact spawned child. `resume` requires a target plus non-empty message and delegates to the package-owned revival path; it may set a caller-owned `file-only` output path but cannot override the persisted child model, tools, budgets, session ownership, or exclusive session lease. For retained-child workflows, resume only roster rows reported `resumable`; because that workflow-only roster is not exhaustive, inspect the exact status of a known direct-run candidate and attempt the authoritative resume when status identifies it. Start a labeled same-role fallback only when there is no known candidate or resume rejects eligibility. `stop` targets running async runs through the existing timeout control channel. `pi.events` is process-local, so separate Pi processes and child subagents need lifecycle artifact files or `pi-intercom` instead.

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

@@ -1,61 +0,0 @@
-# Multi-Lane Orchestration
-
-Use this reference when several independent tasks need coordinated workers, worktrees, or repositories. It defines lane ownership; use the other pi-subagents references for run controls, prompts, and mission details. The parent remains the final decision-maker.
-
-Create lanes only after delegation is operator-authorized and each lane materially improves evidence, independent review, specialization, useful parallelism, or isolated execution. Do not manufacture parallelism: keep dependent work serial, and only split work when each lane has a distinct decision and useful output.
-
-## Mandatory implementation-topology preflight
-
-Before launching a writer for substantial mutation work, classify the implementation 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, and the one-writer-per-worktree rule prevents concurrent ownership conflicts; it does not authorize an issue-wide commission.
-
-Record the classification and evidence on a lane board before writer launch. For multi-seam work, give each isolated component writer exclusive file or contract ownership and focused validation gates. Require every component to produce a committed or otherwise durable handoff, then start a separate integration-only owner after the component handoffs are ready. Mechanically reject and repartition a writer prompt if it owns all major outcomes across multiple independent boundaries.
-
-A single complete writer remains valid only when the board records evidence that the work is genuinely one seam or that splitting it would create overlapping ownership or artificial handoffs. This preflight must not manufacture parallelism: do not split tightly coupled work merely to increase the lane count.
-
-## Lane board and authority
-
-Before multiple mutation-capable lanes start, record this board in the parent context:
-
-`Lane | repo/cwd | exact decision | claimed files or contract | isolation path | authority | next gate | handoff | why independent`
-
-Record the isolation path before the first mutation. Do not split one source seam or decision into duplicate lanes. Make overlapping work one lane with one source of truth.
-
-For every lane, record the delivery target, allowed actions, required validation, and review rigor. For cross-repository work, name the shared contract and which repository changes first. A blocked decision is a lane state: record the owner, options, recommended default, and evidence needed to continue.
-
-## Partitioned runs
-
-Use one writer per repo/cwd or worktree. Mutation lanes need distinct isolation paths and explicit `cwd` values. Set `worktree: true` when a run needs managed worktree isolation within one repository. Each managed worktree branches from `HEAD` unless `baseRef` names another ref, and launch fails with "worktree isolation requires a clean git working tree" while the source checkout has modified, staged, or untracked files outside `.pi/subagents/`. In a shared or dirty checkout, commit your own changes before launching, give each lane an explicit `cwd` in a worktree you created, or run without isolation. Read-only runs can share a checkout only when they cannot change state or create generated files.
-
-For Pi extension repositories, keep lane worktrees outside auto-discovered extension directories such as `~/.pi/agent/extensions`. A stale extension worktree there can auto-load duplicate tools and shortcuts. Remove or move it only after its handoff is durable, the worktree is clean, and no run owns it.
-
-Partition fanout by repository, source seam, decision, or review angle. Each run needs a stable key, lane-specific task, and a managed output path when a file is needed. Do not launch prompts that differ only by item name or broad file glob.
-
-### Cold-start packets and bounded orchestration audits
-
-Every child packet must stand alone: include the goal, exact repository/cwd/ref, authority and edit boundary, relevant context/evidence, success criteria, validation, expected output, and stop/escalation rules. Do not rely on parent history, an issue number, or a broad glob alone. An orchestration audit by a top-reasoning critic model is read-only and returns at most three cited omissions; use high thinking only as an explicit parent/user escalation, never as an autonomous root or a parallel placeholder.
-
-Use one async workflow script (`subagent({ workflow: true, async: true })` after a ```` ```js workflow ```` block) for a coordinated wave. Use `runs.all` for independent lanes and `runs.run` for dependent lane stages. Give cross-repository runs explicit `cwd` values and lane-qualified outputs. Use `outputMode: "file-only"` when a report must survive the run or feed a later stage. Keep scratch outputs relative so they live under subagent artifacts; use absolute paths only for durable memory, approved docs paths, or final handoff files.
-
-## Keep independent work moving
-
-While one lane waits, run safe independent preparation, validation, or fresh read-only review lanes. Do not block the parent just because a run is active. If no safe lane remains, record the blocker and the event that will reopen work.
-
-In an ordinary interactive session, completion wakes the parent; after useful
-async lanes are launched or triaged, yield rather than use
-`bg_wait({ all: true })` as a barrier. “Continue/orchestrate/work until
-done” means keep the board moving while safe immediate work remains. If only
-async lanes are running, record the revisit trigger and yield.
-
-An ordinary coordinated workflow has one mission. Use its durable state, artifacts, run records, and receipts for recovery. Treat a receipt as evidence, not as authority or acceptance.
-
-After a writer produces a candidate, run the required fresh-context, read-only reviewer. The reviewer inspects the exact worktree and returns evidence-backed findings. The parent decides which findings are in scope and whether the lane is ready. Use `review-and-validation.md` for finding disposition, validation, and gate-failure triage. Send accepted fixes to that lane's sole writer, then rerun only the affected gate.
-
-## Handoff, cleanup, and recovery
-
-Use stable lane-qualified artifact paths for reports and review output. A handoff states the lane status, repository and worktree, changed files, validation, open decisions, next action, and artifact or receipt paths. Copy only the final evidence to memory, a mission record, or a PR/comment, then remove scratch files from the active worktree before closing the lane.
-
-For backlog lanes and other subagent-governed workflows, a setup/runtime/tooling failure remains an infrastructure blocker. Preserve the exact failure, run/status, and repository/cwd/worktree/branch/ref state; verify a clean worktree or capture any partial diff before a same-protocol retry or asking the owner. Do not start another writer or switch to an external, foreground, or CLI execution mode without explicit owner approval.
-
-Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
-
-Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.

package/skills/pi-subagents/references/review-and-validation.md

@@ -1,73 +0,0 @@
-# Pi Subagents: Review And Validation
-
-Generic review and delivery guidance for operator-authorized delegated work. This file does not encode private backlog, merge, or release policy.
-
-## Delivery loop
-
-Use the smallest loop that proves the change:
-
-1. Inspect the source, diff, issue, or plan directly.
-2. Keep one writer for each cwd or worktree.
-3. Run focused validation that can fail for the changed behavior.
-4. When the operator/project delegation contract calls for independent review, use a fresh-context read-only reviewer; otherwise parent inspection is valid.
-5. Apply only accepted findings inside the same writer boundary.
-6. Re-run affected validation and review only the changed blast radius.
-7. Inspect the final diff and evidence before parent acceptance.
-
-Skip review ceremony for trivial wording, renames, or local-only probes when direct parent inspection is enough.
-
-## Review shape
-
-| Situation | Shape |
-| --- | --- |
-| One coherent diff or one risk | one reviewer |
-| Independent risks, such as correctness, tests, security, or UI | parallel reviewers with distinct contracts |
-| Possible over-scope or needless complexity | same-writer challenge before fresh review |
-| Material design tradeoff | council mode |
-
-Reviewers are fresh-context by default. Use the ordinary `reviewer` role for routine code review. Forked oracle/advisor runs are escalation-only for parent-history, drift, root-cause, model-routing, or hard tradeoff evidence.
-
-## Finding disposition
-
-The parent classifies each finding against current HEAD:
-
-- **Valid blocker:** concrete failure, repro, security issue, contract mismatch, or source-proven regression. Fix now.
-- **Valid non-blocker:** real but outside the delivery slice. Record or defer.
-- **Stale:** fixed or absent at the reviewed head. Cite current evidence.
-- **Invalid:** contradicted by source, tests, docs, or user-approved scope. Cite the contradiction.
-- **Out of policy/scope:** needs unapproved product, architecture, authority, release, or public-repo action. Escalate.
-- **Speculative:** no contract, repro, or reachable failure. Do not block.
-
-A clean reviewer result is evidence, not publication authority.
-
-## Gate-failure triage
-
-When validation fails:
-
-1. Confirm the run belongs to the exact head/ref under judgment.
-2. Read the focused failing logs first.
-3. Name the failing test, assertion, contract, or thread.
-4. Classify cause: current diff, stale test, environment/setup, or existing flake.
-5. Reproduce locally when practical with the narrowest command.
-6. Patch forward when the current diff caused it.
-7. For stale/flaky failures, collect proof before one rerun or residual-risk note.
-8. Re-run the affected command or exact-head gate after every fix.
-
-For bot comments, classify each thread as valid, stale, invalid, or out of policy before assigning severity.
-
-## Final checklist
-
-Before reporting delegated work as done, verify the relevant subset:
-
-- final diff contains only intended files
-- focused validation covers changed behavior
-- required independent review has fresh-review evidence
-- accepted findings are fixed and revalidated
-- publication authority exists before push, comment, close, merge, deploy, or release
-- external checks are exact-head when used as evidence
-- handoff is durable before cleanup
-- residual risks, skipped validation, and blocked decisions are explicit
-
-## Public/private boundary
-
-For issue/PR backlogs, releases, merge queues, contributor credit, or repo-specific policy, load the matching user/project skill when available. Keep those rules out of this public package until intentionally released.