@henryqw/pi-subagent 15.0.2 → 15.1.0

package/README.md

@@ -12,11 +12,13 @@ pi install npm:@henryqw/pi-task-models
 pi install npm:@henryqw/pi-subagent
 ```
 
-Run `/task-models` and configure the `fast` profile before delegating.
+Run `/task-models` and configure the `fast` profile before delegating. Open `/task-models` again and verify that `fast` no longer says `not configured`.
 
 ## Works with
 
-**Required.** [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) supplies `fast`, `balanced`, `frontier`, and `fav` model routes.
+| Package | Relationship | Purpose |
+| --- | --- | --- |
+| [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) | Required | Supplies `fast`, `balanced`, `frontier`, and `fav` model routes. |
 
 Routes come from `~/.pi/agent/config/pi-task-models/config.json`. It stores explicit task overrides. Missing shared model config warns once because delegation needs a route.
 
@@ -76,7 +78,17 @@ See the [orchestration guide](./docs/orchestration.md) for full delegation, tran
 
 ### Skills
 
-The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill guides Main's planning and orchestration. It adds no runtime code, config, or Role installation. `delegate_flow` owns its Git mechanics and validation authority.
+The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill guides Main's planning and orchestration. It adds no runtime code, config, or Role installation.
+
+Its ordinary review loop is optional. Use it only when the caller or repository policy explicitly requires judgment review.
+
+- Call `delegate_task` with `role: "reviewer"` to select the effective `reviewer` Role.
+- Its task packet must state the read-only scope and exact `PASS` or findings contract. Include exact acceptance criteria and validation evidence.
+- The Reviewer must see exact candidate evidence from its working directory. Use `delegate_flow` for an isolated candidate, not an ordinary review from Main's unchanged checkout.
+- Fix initial findings together. Validate repaired inputs once before focused re-review. Include the original findings and acceptance criteria, exact repaired-candidate evidence, and validation evidence.
+- Only `PASS` completes the loop. Surface and block on re-review findings or empty output. Retry empty output only when explicit caller policy requires one. A second empty result blocks. Do not add another round.
+
+Flow is separate. It owns exact review evidence, exact `PASS` approval, validation replay, one repair continuation, and no automatic retry.
 
 ## Flow
 
@@ -94,6 +106,12 @@ A Flow has 1–8 units with unique non-empty IDs and allows one active Flow. It
 - Without `review`, Flow fast-forwards the exact validated tip.
 - With `review`, the Reviewer receives the exact `{base, tip, patchPath}` packet and must return exactly `PASS` before the same integration path. Use `review` only for stated judgment that validation cannot decide.
 
+A Role selects base tools, extensions, named Skills, instructions, and optional worktree isolation. Named Skills resolve from Main's effective Pi registry. Unavailable names warn and skip.
+
+Children disable ambient extension and Skill discovery. `tools: []` adds no base tools, but selected extension tools and caller tools still activate. `extensions: []` adds no Role extension bundle. `skills: []` adds no separately named Role Skills, but selected extension Skills still load.
+
+Parent-only delegation tools and `ask_question` are always excluded. Requested Role or caller tool names are checked after provider loading. Unavailable tools fail before the first model turn.
+
 An explicit unit `modelClass` overrides both frozen Roles. Without one, each Role uses its own `modelClass`, configured `pi-subagent/delegateTask` assignment, or declared default.
 
 One `delegate_flow_continue` can repair an Implementer, validation, or review block in the same worktree. Omitting its class keeps the unit's explicit class and frozen Role defaults. Supplying one replaces both Role defaults for that repair and its later Reviewer launch.
@@ -106,14 +124,12 @@ Flow has no dependency graph, saved recovery, automatic retry, aggregate review,
 
 pi-subagent owns `~/.pi/agent/config/pi-subagent/config.json`. It is optional. A missing file uses these defaults without a warning.
 
-| Field | Valid value | Default |
-| --- | --- | --- |
-| `maxSubagents` | Safe integer ≥ 1 | `5` |
-| `maxTurns` | Safe integer ≥ 1 | `50` |
-| `timeout.idleMinutes` | Positive minutes; minutes × 60,000 ≤ 2,147,483,647 ms | `10` |
-| `timeout.maxMinutes` | Positive minutes greater than `idleMinutes`; minutes × 60,000 ≤ 2,147,483,647 ms | `30` |
-
-`maxTurns` defaults to 50.
+| Name | Description | Values | Default |
+| --- | --- | --- | --- |
+| `maxSubagents` | Sets the maximum number of active child processes. | Safe integer of at least 1. | `5` |
+| `maxTurns` | Sets the hard provider-turn limit for each child. | Safe integer of at least 1. | `50` |
+| `timeout.idleMinutes` | Sets the idle timeout for a child. | Positive minutes. | `10` |
+| `timeout.maxMinutes` | Sets the maximum runtime for a child. | Positive minutes greater than `idleMinutes`. | `30` |
 
 Excess children wait FIFO without using a child timeout. A terminal response on turn 50 succeeds; an attempted continuation rejects with `turn_limit`.
 
@@ -164,7 +180,16 @@ Flow uses the effective Implementer and, only when requested, Reviewer. The Scou
 
 ## API
 
-The package root exports `loadRoles`, `resolveRoleSkills`, `resolveRoleLaunch`, `createRoleLaunch`, `createEphemeralSubagentExecutor`, and worktree helpers.
+The package root includes these main exports:
+
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `loadRoles` | function | Loads built-in and user Role definitions. |
+| `resolveRoleSkills` | function | Resolves a Role's named Skills from Pi's effective registry. |
+| `resolveRoleLaunch` | function | Resolves a Role, route, and launch resources. |
+| `createRoleLaunch` | function | Builds launch arguments from a resolved route. |
+| `createEphemeralSubagentExecutor` | function | Creates the bounded child-process executor. |
+| Worktree helpers | functions | Create, inspect, finalize, and report child worktrees. |
 
 The executor works only inside the active Pi process. It does not discover or start a standalone Node.js Pi installation.
 
@@ -172,22 +197,10 @@ The executor works only inside the active Pi process. It does not discover or st
 
 See the [public Role and executor API](./docs/orchestration.md#public-role-and-executor-api) for contracts and a `prepare` example. Pass `modelClass` to `resolveRoleLaunch` to override a Role default.
 
-## State and storage
-
-Flow state is memory-only.
-
-## Data, cost, and privacy
-
-A Role selects base tools, extensions, named Skills, instructions, and optional worktree isolation. Named Skills resolve from Main's effective Pi registry. Unavailable names warn and skip.
-
-Children disable ambient extension and Skill discovery. `tools: []` adds no base tools, but selected extension tools and caller tools still activate. `extensions: []` adds no Role extension bundle. `skills: []` adds no separately named Role Skills, but selected extension Skills still load.
+## Limits and recovery
 
 An explicitly selected extension is trusted, not sandboxed. Its tools, Skills, and executable behavior load together. Select fewer trusted extensions to reduce scope. pi-subagent does not guess or remove undocumented dependencies.
 
-Parent-only delegation tools and `ask_question` are always excluded. Requested Role or caller tool names are checked after provider loading. Unavailable tools fail before the first model turn.
-
-## Limits and recovery
-
 Flow never force-deletes recoverable work. Failed or uncertain units, and cleanup refusals after integration, retain their worktree path or branch for recovery.
 
 See [Flow mechanics and recovery](./docs/orchestration.md#delegate_flow) for retained-work recovery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "15.0.2",
+  "version": "15.1.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",

package/skills/pi-subagent-delegated-development/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pi-subagent-delegated-development
-description: Run bounded independent implementation through the runtime-managed Delegate Flow.
+description: Use Delegate Flow, or coordinate explicitly required judgment review for ordinary delegated implementation.
 ---
 
 # Delegated Development
 
-You are Main, the planner/orchestrator: slice work and call `delegate_flow`. Do not implement child work yourself or use external model tools, push, publish, or release.
+You are Main, the planner/orchestrator: slice work and choose `delegate_flow` or `delegate_task` as described below. Do not implement child work yourself or use external model tools, push, publish, or release.
 
 ## Slice
 
@@ -36,3 +36,24 @@ A cleanup warning does not undo successful integration. Report a cleanup warning
 ## Ordinary delegation
 
 Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Choose `modelClass` according to the delegation tool's guidance. A direct `model` replaces only the selected route's model. The route keeps its thinking level. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.
+
+### Optional evidence loop for implementation
+
+Use this caller-managed loop only when the caller or repository policy explicitly requires judgment review. It is not required for every ordinary implementation.
+
+After implementation and focused validation, launch `delegate_task` with `role: "reviewer"` to select the effective `reviewer` Role. A same-named user Role remains effective. The task packet must state:
+
+- the read-only scope;
+- the exact acceptance criteria;
+- exact candidate evidence visible from the Reviewer's working directory and the supplied validation evidence;
+- the exact output contract: return `PASS` alone on approval, or findings only.
+
+Do not launch the Reviewer unless it can see the actual candidate. For an isolated implementation candidate, use `delegate_flow` instead of composing an ordinary review against Main's unchanged checkout.
+
+Empty Reviewer output is a failure. Retry only when explicit caller policy requires one; otherwise surface the failure and block completion. If that retry is also empty, surface the second empty result and block completion.
+
+If the initial review returns findings, repair them together. Run one focused validation of the repaired inputs before one focused re-review. Its task packet must restate the read-only scope, exact output contract, original findings, original acceptance criteria, exact repaired-candidate evidence, and validation evidence.
+
+Only `PASS` completes the loop. Focused re-review findings block completion and must be surfaced. Do not start another repair/review round.
+
+Do not layer this loop onto `delegate_flow`. Flow already owns exact review evidence, exact `PASS` approval, validation replay, one repair continuation, and no automatic retry.