@henryqw/pi-subagent 4.0.1 → 4.1.0

package/CONTEXT.md

@@ -2,13 +2,13 @@
 
 ## Purpose
 
-Provide validated user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, and a `delegate_task` extension that runs one selected bounded workflow in one or more ephemeral child processes.
+Provide validated built-in and user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, a `delegate_task` extension that runs one selected bounded workflow in one or more ephemeral child processes, and a bundled Main-side `pi-subagent-delegated-development` policy Skill. The Skill requires a clean committed Git `HEAD`, exact clean committed-diff review through a private byte-verified patch file reference, and post-validation recovery cleanup; it adds no runtime behavior or changes generic fallback.
 
 ## Domain glossary
 
 - **Main**: Pi session delegating work.
 - **Subagent**: isolated Pi child process handling one task.
-- **Role**: user-owned Markdown definition of a reusable responsibility, with a name, description, system instructions, optional base tool allowlist, extensions, and Skill names.
+- **Role**: package-shipped built-in or user-owned Markdown definition of a reusable responsibility, with a name, description, system instructions, optional base tool allowlist, extensions, and Skill names.
 - **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, assigned in shared task-model settings or overridden by Main from task complexity.
 - **Route**: configured model and thinking-level pair selected from a shared Model Class profile; the primary route precedes its optional fallback.
 - **Delegated Task**: one bounded work request sent from Main to one Role.
@@ -27,6 +27,6 @@ Provide validated user Roles, shared task-model Pi launch policy, generic manage
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation.
 - Main selects Role and may override Model Class and thinking level per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.
 - The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.
-- Role Markdown files and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`; repository roles do not execute.
+- User Role Markdown files and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`. Package-shipped built-in Roles (`implementer`, `reviewer`) resolve from the package's own `examples/roles/` Markdown through the same parser; a same-named user file explicitly overrides a built-in.
 - Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.
 - Generic Herdr host functions validate workspace ownership and provisioning identity while callers retain domain state, prompts, and lifecycle decisions.

package/README.md

@@ -49,41 +49,71 @@ Parallel mode starts entries concurrently, waits for every entry, and reports th
 
 Background workflows are session-scoped. Session shutdown or reload aborts them and may deliver only recoverable-work evidence or no follow-up message.
 
-Each delegation resolves its own user Role, resources, route, and optional worktree request. When available, `isolation: worktree` gives each entry a deterministic separate worktree; non-Git or unborn-`HEAD` contexts may use Main's cwd. Siblings and chain steps never implicitly share one created worktree.
+Each delegation resolves its own Role, resources, route, and optional worktree request. When available, `isolation: worktree` gives each entry a deterministic separate worktree; non-Git or unborn-`HEAD` contexts may use Main's cwd. Siblings and chain steps never implicitly share one created worktree.
 
 See [Orchestration, isolation, and the public API](./docs/orchestration.md) for the complete contract and JavaScript composition examples.
 
 ## Config
 
-`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the ephemeral child pool and timeouts:
+pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-subagent/`, which holds two kinds of user-owned configuration: one Markdown file per Role (see [Roles](#roles)) and its own optional JSON file below. Model routing is *not* configured here; children resolve routes through the shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models.json`.
 
-```json
-{
-  "maxSubagents": 5,
-  "timeout": { "idleMinutes": 10, "maxMinutes": 30 }
-}
-```
+`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the ephemeral child pool and timeouts. All fields are optional; a missing file uses defaults.
+
+| Field | Required | Possible values | Default |
+| --- | --- | --- | --- |
+| `maxSubagents` | No | Safe integer ≥ 1 | `5` |
+| `timeout.idleMinutes` | No | Positive number of minutes where minutes × 60 000 ms ≤ 2,147,483,647 | `10` |
+| `timeout.maxMinutes` | No | Positive number within the same ms cap that must be greater than `timeout.idleMinutes`, otherwise the whole `timeout` object falls back to defaults | `30` |
+
+Excess children wait FIFO without consuming child timeout. `PI_SUBAGENT_MAX_SUBAGENTS` overrides `maxSubagents` for the session (positive integer; an invalid value prevents the extension from loading, leaving `delegate_task` unavailable).
+
+This JSON is read leniently: malformed JSON, a non-object root, unknown keys, or invalid values are collected into one warning and the affected settings fall back to defaults; the file is never rewritten.
+
+### Role frontmatter
+
+Each Role `.md` file in the same directory accepts these frontmatter fields:
 
-Excess children wait FIFO without consuming child timeout. `PI_SUBAGENT_MAX_SUBAGENTS` overrides the configured concurrency for the session.
+| Field | Required | Possible values | Default |
+| --- | --- | --- | --- |
+| `name` | Yes | Non-empty text; unique across roles | — |
+| `description` | Yes | Non-empty text | — |
+| `tools` | No | Array or comma-separated string of tool names | Omitted: caller tools win, else Pi defaults apply |
+| `isolation` | No | `worktree` | None |
+| `extensions` | No | Absolute paths, `~/…`, `file://`, or package sources (`npm:`, `git:`, `github:`, `https?:`, `ssh:`) | None |
+| `skills` | No | Array or comma-separated string of skill names | None; unavailable names warn and skip |
+| body | Yes | System-prompt Markdown after the frontmatter | — |
+
+An unreadable or invalid Role file fails role loading fast; duplicate role names are rejected.
 
 ## Roles
 
-Roles are user-owned Markdown files in `~/.pi/agent/config/pi-subagent/`. This repository includes inert samples:
+The package ships two working built-in Roles, always available without any configuration:
+
+- `implementer`: focused edits requesting worktree isolation; commits completed scoped changes locally and never pushes or opens PRs without authorization
+- `reviewer`: read-only correctness review from a supplied exact patch file reference (path, bytes, SHA-256) and referenced files; never edits or commits
+
+A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default.
+
+The repository also includes optional inert samples:
 
 - [`scout`](./examples/roles/scout.md): read-only discovery
-- [`implementer`](./examples/roles/implementer.md): focused edits requesting worktree isolation
-- [`reviewer`](./examples/roles/reviewer.md): read-only correctness review
 - [`synthesizer`](./examples/roles/synthesizer.md): reconcile supplied reports
 
-Copy them manually from the repository root:
+Copy them manually from your installed `@henryqw/pi-subagent` package (npm installs ship the `examples/roles/` directory) if you want them as a starting point:
 
 ```bash
 mkdir -p ~/.pi/agent/config/pi-subagent
-cp packages/pi-subagent/examples/roles/*.md ~/.pi/agent/config/pi-subagent/
+cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
 ```
 
+Locate the install directory with `npm root` inside your project, or via Pi's package installation path.
+
 The package never installs or writes Role configuration. Sample names are not built-ins; after copying, edit or replace them as your own Roles.
 
+## Skill
+
+The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill is opinionated orchestration policy for Main. It fails before delegation unless Main's cwd is a clean Git working tree with a committed `HEAD`; then it requires a clean retained implementer worktree, a verified base/branch/tip committed diff, and review from a privately generated, byte-verified exact patch file reference (path, bytes, SHA-256) plus referenced files—not inline patch text. It re-checks Main before integrating the reviewed commit, preserves artifacts on integration or validation failure, and removes eligible retained worktrees, task branches, and temporary patch files only after focused validation passes. Dirty or incomplete work goes to a fresh repair delegation. This leaves the generic `delegate_task` non-Git/unborn-`HEAD` fallback unchanged. All model and agent work stays in Pi via `delegate_task`; deterministic developer tools remain allowed. It is guidance only — it adds no runtime code, config, or Role installation, and preserves the [composition-outside-the-executor](./docs/adr/001-composable-ephemeral-execution.md) boundary.
+
 A Role owns its base tools, extensions, named Skills, instructions, and optional `isolation: worktree`. Ambient extension and Skill discovery is disabled in children. With neither Role tools nor caller tools, Pi defaults remain; caller tools with omitted Role tools snapshot Main's effective active built-ins and install the child policy. Loaded Role/caller extension tools still activate, parent-only tools stay excluded, and unavailable named Skills warn and skip.
 
 ## Library API
@@ -91,17 +121,3 @@ A Role owns its base tools, extensions, named Skills, instructions, and optional
 The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers. The ephemeral executor is for code already running inside active Pi; it does not provide standalone Node.js Pi discovery or launch support.
 
 Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior and a post-permit `prepare` example using `resolveRoleLaunch` against the latest Pi context.
-
-## Remove
-
-```bash
-pi remove npm:@henryqw/pi-subagent
-```
-
-## Development
-
-```bash
-npm test --workspace @henryqw/pi-subagent
-npm run typecheck --workspace @henryqw/pi-subagent
-npm run pack:check --workspace @henryqw/pi-subagent
-```

package/dist/index.d.ts

@@ -38,6 +38,12 @@ export interface ResolvedRoleSkills {
     paths: string[];
     missing: string[];
 }
+/**
+ * Validated built-in implementer/reviewer Roles plus valid user roles from
+ * `config/pi-subagent`. A user role with a built-in name overrides the default;
+ * duplicate names among user files are an error. Missing user directory returns
+ * the built-ins.
+ */
 export declare function loadRoles(agentDir?: string): Role[];
 export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string, thinking?: ThinkingLevel): ResolvedTaskRoute;
 export declare function resolveRoleSkills(pi: Pick<ExtensionAPI, "getCommands">, role: Role): ResolvedRoleSkills;

package/dist/index.js

@@ -42,7 +42,53 @@ function validateExtension(extension, source) {
 function extensionList(value, source) {
     return stringList(value, "extensions", source).map((extension) => validateExtension(extension, source));
 }
+// Built-in Roles required by the bundled pi-subagent-delegated-development Skill;
+// resolved from the package-shipped Markdown relative to this module.
+const BUILTIN_ROLE_FILES = ["implementer.md", "reviewer.md"];
+/** Single-file Role parser shared by built-in and user roles. */
+function parseRoleFile(file, raw) {
+    let parsed;
+    try {
+        parsed = parseFrontmatter(raw);
+    }
+    catch (error) {
+        throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const frontmatter = parsed.frontmatter;
+    const isolation = frontmatter.isolation === undefined ? undefined : cleanText(frontmatter.isolation, "isolation", file);
+    if (isolation !== undefined && isolation !== "worktree")
+        throw new Error(`${file}: isolation must be "worktree".`);
+    return {
+        name: cleanText(frontmatter.name, "name", file),
+        description: cleanText(frontmatter.description, "description", file),
+        tools: frontmatter.tools === undefined ? undefined : stringList(frontmatter.tools, "tools", file, true),
+        isolation,
+        extensions: extensionList(frontmatter.extensions, file),
+        skills: stringList(frontmatter.skills, "skills", file),
+        systemPrompt: cleanText(parsed.body, "system prompt", file),
+    };
+}
+function readRoleFile(file) {
+    try {
+        return parseRoleFile(file, readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith(`${file}: `))
+            throw error;
+        throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function builtinRoles() {
+    return BUILTIN_ROLE_FILES.map((name) => readRoleFile(fileURLToPath(new URL(`../examples/roles/${name}`, import.meta.url))));
+}
+/**
+ * Validated built-in implementer/reviewer Roles plus valid user roles from
+ * `config/pi-subagent`. A user role with a built-in name overrides the default;
+ * duplicate names among user files are an error. Missing user directory returns
+ * the built-ins.
+ */
 export function loadRoles(agentDir = getAgentDir()) {
+    const byName = new Map(builtinRoles().map((role) => [role.name, role]));
     const dir = join(agentDir, "config", "pi-subagent");
     let entries;
     try {
@@ -50,42 +96,21 @@ export function loadRoles(agentDir = getAgentDir()) {
     }
     catch (error) {
         if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
-            return [];
+            return [...byName.values()];
         throw error;
     }
-    const roles = entries
+    const userRoles = entries
         .filter((entry) => entry.name.endsWith(".md") && (entry.isFile() || entry.isSymbolicLink()))
         .sort((a, b) => a.name.localeCompare(b.name))
-        .map((entry) => {
-        const file = join(dir, entry.name);
-        let parsed;
-        try {
-            parsed = parseFrontmatter(readFileSync(file, "utf8"));
-        }
-        catch (error) {
-            throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        const frontmatter = parsed.frontmatter;
-        const isolation = frontmatter.isolation === undefined ? undefined : cleanText(frontmatter.isolation, "isolation", file);
-        if (isolation !== undefined && isolation !== "worktree")
-            throw new Error(`${file}: isolation must be "worktree".`);
-        return {
-            name: cleanText(frontmatter.name, "name", file),
-            description: cleanText(frontmatter.description, "description", file),
-            tools: frontmatter.tools === undefined ? undefined : stringList(frontmatter.tools, "tools", file, true),
-            isolation,
-            extensions: extensionList(frontmatter.extensions, file),
-            skills: stringList(frontmatter.skills, "skills", file),
-            systemPrompt: cleanText(parsed.body, "system prompt", file),
-        };
-    });
+        .map((entry) => readRoleFile(join(dir, entry.name)));
     const names = new Set();
-    for (const role of roles) {
+    for (const role of userRoles) {
         if (names.has(role.name))
             throw new Error(`Duplicate Subagent role: ${role.name}.`);
         names.add(role.name);
+        byName.set(role.name, role);
     }
-    return roles;
+    return [...byName.values()];
 }
 export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir(), thinking) {
     let config;

package/docs/adr/001-composable-ephemeral-execution.md

@@ -12,7 +12,7 @@ Resource Policy is split at launch preparation:
 - Caller may add explicit tools, extensions, and environment through `createRoleLaunch`.
 - The executor receives the resulting Pi Launch and does not discover resources.
 
-Repository Role samples are inert and user-owned only after manual copying to `~/.pi/agent/config/pi-subagent/`. This package does not install, copy, or write user configuration; copy instructions belong in downstream user documentation.
+Built-in `implementer` and `reviewer` Roles ship with the package as Markdown in `examples/roles/` and resolve through the same single-file parser at load time; a same-named user file in `~/.pi/agent/config/pi-subagent/` explicitly overrides a built-in. Other repository samples are inert and user-owned only after manual copying to `~/.pi/agent/config/pi-subagent/`. This package does not install, copy, or write user configuration; copy instructions belong in downstream user documentation.
 
 ## Consequences
 

package/docs/orchestration.md

@@ -3,7 +3,7 @@
 `pi-subagent` separates tool policy from execution mechanism:
 
 ```text
-user Role + latest Pi registries ── resolveRoleLaunch ──> PiLaunch
+Role (built-in or user override) + latest Pi registries ── resolveRoleLaunch ──> PiLaunch
                                                         │
 caller-owned task, cwd, signal ─────────────────────────┤
                                                         v
@@ -63,7 +63,7 @@ Single mode puts one delegation's fields at the top level.
 
 | Field | Required | Contract |
 | --- | --- | --- |
-| `role` | yes | Name of a Role in the user's effective `config/pi-subagent` directory. There are no package-owned Role names. |
+| `role` | yes | Name of a Role in the user's effective `config/pi-subagent` directory or a package-shipped built-in (`implementer`, `reviewer`); a same-named user file overrides the built-in. |
 | `task` | yes | Non-empty bounded task packet. |
 | `model` | no | Designated `provider/modelId`; takes precedence over `modelClass`. |
 | `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; omission uses shared task assignment. |
@@ -83,14 +83,14 @@ All Main-visible text for one tool call shares one aggregate 50 KiB UTF-8 transp
 
 Every single entry, parallel sibling, and chain step independently:
 
-1. loads its selected user Role;
+1. loads its selected Role;
 2. resolves its route and named Skills from the latest effective Pi context after receiving an executor permit;
 3. creates its Role launch policy; and
 4. when the Role requests `isolation: worktree`, creates a worktree identified by the tool call, mode, and input index.
 
 Separate deterministic identities produce separate hashed worktree paths and branches. Parallel siblings cannot collide, and a chain does not base one step's worktree on the preceding step's branch. `{previous}` passes text only. There is no implicit shared worktree or hidden workflow state.
 
-A worktree starts from Main's current `HEAD`. Clean worktrees with no child commits are pruned; committed, dirty, switched, unmeasurable, or otherwise recoverable work is preserved and reported. Non-git directories and repositories with an unborn `HEAD` use Main's working directory. Git submodules reject worktree isolation, and setup failure in a real repository throws rather than silently sharing Main's checkout.
+A worktree starts from Main's current `HEAD`. Clean worktrees with no child commits are pruned; committed, dirty, switched, unmeasurable, or otherwise recoverable work is preserved and reported. Non-git directories and repositories with an unborn `HEAD` use Main's working directory. Git submodules reject worktree isolation, and setup failure in a real repository throws rather than silently sharing Main's checkout. This generic fallback remains unchanged: the bundled delegated-development Skill separately refuses to begin without a committed Git `HEAD`.
 
 If steps must share files, make that an explicit caller decision: use an intentionally shared workspace, merge preserved child commits, or pass state through a caller-owned store. Do not rely on chain order to imply filesystem sharing.
 
@@ -116,7 +116,7 @@ The package root exports the following mechanism-level APIs:
 
 | API | Responsibility |
 | --- | --- |
-| `loadRoles(agentDir?)` | Validate and load user Role Markdown. |
+| `loadRoles(agentDir?)` | Validate and load package-shipped built-in and user Role Markdown. |
 | `resolveRoleSkills(pi, role)` | Resolve Role Skill names from Pi's effective registry. |
 | `resolveRoleLaunch(pi, ctx, input)` | Resolve a shared task route and produce `ResolvedRoleLaunch`. |
 | `createRoleLaunch(pi, ctx, input)` | Produce the same launch from a caller-supplied resolved route. |
@@ -319,24 +319,33 @@ if (!approved) throw new Error(`Review did not pass after ${maxReviewRounds} rou
 
 The verdict schema, parser, round state, shared workspace, and terminal decision all belong to the caller. Add a richer protocol only when the workflow requires one; do not encode it as a recursive package workflow definition.
 
-## Role samples
+## Built-in Roles and samples
 
-Repository samples are documentation, not installed configuration:
+The package ships two working built-in Roles, validated by the same parser as user roles and always present even with no `config/pi-subagent` directory:
+
+| Built-in | Behavior |
+| --- | --- |
+| `implementer` | Focused implementation requesting `isolation: worktree`; commits scoped changes locally, never pushes or opens PRs without authorization. Non-Git or unborn-`HEAD` contexts may use Main's cwd. |
+| `reviewer` | Read-only correctness review from a supplied exact patch file reference (path, bytes, SHA-256) and referenced files; never edits or commits. |
+
+A same-named Markdown file in `config/pi-subagent/` explicitly overrides the built-in default.
+
+Additional repository samples are inert starting points, not installed configuration:
 
 | Sample | Intended starting point |
 | --- | --- |
 | [`scout`](../examples/roles/scout.md) | Read-only code/evidence mapping. |
-| [`implementer`](../examples/roles/implementer.md) | Focused implementation requesting `isolation: worktree`; non-Git or unborn-`HEAD` contexts may use Main's cwd. |
-| [`reviewer`](../examples/roles/reviewer.md) | Read-only correctness review. |
 | [`synthesizer`](../examples/roles/synthesizer.md) | Reconcile supplied reports without broad discovery. |
 
-From the repository root, opt in explicitly:
+Copy the package-shipped samples from your installed `@henryqw/pi-subagent` package (npm installs include `examples/roles/`) if you want them:
 
 ```bash
 mkdir -p ~/.pi/agent/config/pi-subagent
-cp packages/pi-subagent/examples/roles/*.md ~/.pi/agent/config/pi-subagent/
+cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
 ```
 
 The package never creates, copies, updates, or removes files in `~/.pi/agent/config/pi-subagent/`. Once copied, the files and their names are entirely user-owned.
 
+The bundled [`pi-subagent-delegated-development`](../skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side orchestration policy only. It prescribes an implement → review → merge loop over the built-in `implementer` and `reviewer` Roles, with private byte-verified exact-patch file references rather than inline patch text and cleanup only after integration validation. It defines no workflow AST, runtime code, or configuration; `delegate_task` remains the flat single/parallel/chain mechanism.
+
 See the architectural decision: [Compose workflows outside the ephemeral executor](./adr/001-composable-ephemeral-execution.md).

package/examples/roles/implementer.md

@@ -1,7 +1,14 @@
 ---
 name: implementer
 description: Implements and validates one bounded change, requesting worktree isolation
-tools: [read, bash, edit, write, grep, find, ls]
+tools:
+  - read
+  - bash
+  - edit
+  - write
+  - grep
+  - find
+  - ls
 isolation: worktree
 ---
 
@@ -9,6 +16,8 @@ Implement one bounded task.
 
 Read applicable repository instructions and domain context first. Inspect the existing flow and its callers before editing. Work only in explicitly assigned files and preserve unrelated changes. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies.
 
-Run focused validation that would fail if the change were wrong. Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it.
+Run focused validation that would fail if the change were wrong. Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs; deterministic developer tools remain allowed.
 
-Return changed files, validation results, and remaining risks.
+Commit completed scoped changes locally unless the task forbids it. Never push or open pull requests without explicit authorization.
+
+Return the retained worktree path, branch, base commit, tip commit, changed files from the base-to-tip committed diff, clean `git status --porcelain=v1 --untracked-files=all` result, validation results, and remaining risks. Do not remove the retained worktree or task branch; Main cleans them only after successful integration and validation.

package/examples/roles/reviewer.md

@@ -1,11 +1,19 @@
 ---
 name: reviewer
 description: Reviews one bounded change for correctness without changing files
-tools: [read, grep, find, ls]
+tools:
+  - read
+  - grep
+  - find
+  - ls
 ---
 
 Perform a read-only correctness review of one bounded change.
 
-Review only the requirements and changed files named in the task, plus directly relevant callers, contracts, and tests. Check correctness, regressions, trust-boundary validation, error handling, and missing high-value tests. Do not edit files, run shell commands, or propose unrelated refactors.
+Refuse review unless the task supplies the base commit, tip commit, complete exact base-to-tip patch file reference (path, byte count, SHA-256), and explicit review context: `{type:'child_branch', branch}` or `{type:'integration_head'}`. Review from that supplied file and the files it references only; do not infer a diff from a branch or worktree. Read the patch in bounded chunks when needed and use only `read`, `grep`, `find`, or `ls` for referenced files.
+
+Review only the supplied requirements, exact patch file, and explicitly referenced files, including any relevant callers, contracts, and tests. Check correctness, regressions, trust-boundary validation, error handling, and missing high-value tests. Do not run commands or tests. Never edit files, commit, push, or otherwise modify state.
+
+Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
 Return findings first, ordered by severity. Every finding must include file and line evidence, impact, and the smallest valid fix. If there are no findings, say so and list any unvalidated risk.

package/extensions/subagent.ts

@@ -178,8 +178,7 @@ function failedToolPatch(error: WorkflowFailureError | WorkflowAbortedError) {
 
 const roleSummary = (): string => {
 	try {
-		const roles = loadRoles();
-		return roles.length ? roles.map((role) => `${role.name}: ${role.description}`).join("; ") : "none configured";
+		return loadRoles().map((role) => `${role.name}: ${role.description}`).join("; ");
 	} catch (error) {
 		return `configuration error: ${error instanceof Error ? error.message : String(error)}`;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -18,6 +18,7 @@
     "extensions",
     "docs",
     "examples",
+    "skills",
     "README.md",
     "CONTEXT.md",
     "LICENSE"
@@ -57,6 +58,9 @@
   "pi": {
     "extensions": [
       "./extensions/subagent.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "dependencies": {

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

@@ -0,0 +1,54 @@
+---
+name: pi-subagent-delegated-development
+description: Orchestrate delegated development with pi-subagent delegate_task. Use when splitting implementation work into bounded units for isolated implementer children reviewed by a read-only reviewer before merging.
+---
+
+# Delegated Development
+
+You are Main. Decompose work into bounded units and coordinate; never edit files yourself.
+
+All model and agent work in this workflow goes through Pi's `delegate_task` and Pi-managed children. Do not invoke external LLM APIs, SDKs, agent harnesses, or model CLIs; ordinary deterministic developer tools such as `git`, npm, test runners, and compilers remain allowed.
+
+## Required preflight
+
+Before any delegation, require that Main's cwd is a Git working tree with a committed `HEAD`:
+
+```bash
+test "$(git rev-parse --is-inside-work-tree)" = true &&
+git rev-parse --verify -q HEAD^{commit} >/dev/null
+```
+
+If this fails, stop before delegation and report that this Skill requires a Git repository with a committed `HEAD`; do not rely on the generic worktree fallback to Main's cwd.
+
+Before recording each unit's `base=$(git rev-parse HEAD)`, and again immediately before integration and validation, require `git status --porcelain=v1 --untracked-files=all` to be empty. If Git cannot inspect status or any tracked or untracked change is present, stop and ask the user to preserve the changes; never stash, discard, hide, or work around them.
+
+## Roles
+
+The package-shipped built-in Roles `implementer` (`isolation: worktree`) and `reviewer` (read-only patch-and-file review) are always available; no installation step is required. A same-name user override replaces the built-in entirely. Before using this workflow, Main must verify that each override preserves implementer worktree isolation and reviewer read-only patch-and-file constraints; fail clearly if it does not. Do not invent substitute Roles.
+
+## Per-unit loop
+
+For each bounded unit:
+
+1. **Implement** — one `delegate_task` single call to `implementer`. The packet states the objective, touched scope, required validation, and recorded base commit. Require its output to identify the retained worktree path, branch, base commit, tip commit, changed files from the base-to-tip committed diff, and clean `git status --porcelain=v1 --untracked-files=all` result.
+2. **Verify and review** — refuse review or merge unless Main independently verifies that the worktree was retained and is clean (including untracked files), the reported base/branch/tip identities are complete and match Git, the tip is descended from the recorded base, and the reported changed files equal `git diff --name-only "$base" "$tip"`. All intended changes must be in that committed base-to-tip diff. If any evidence is missing or any check fails, send the work to a fresh implementer repair; never review dirty or uncommitted work.
+
+   Create a private temporary exact-patch artifact outside the repository from `git diff --no-textconv --no-ext-diff --ignore-submodules=none --binary "$base" "$tip"`. Independently regenerate that same diff and byte-compare it with the artifact, then record its path, byte count, and SHA-256. If creation, regeneration, comparison, byte count, or checksum fails, stop and report the artifact failure clearly; do not review or merge. Do not put any complete patch content in `delegate_task` text or argv.
+
+   Make one `delegate_task` single call to `reviewer` with only a bounded metadata packet: base, tip, review context `{type:'child_branch', branch}`, the verified complete patch file reference (`path`, `bytes`, `sha256`), and the verified changed paths. If that complete metadata cannot fit the task transport bound, stop and report it rather than truncating or inlining patch content. Chain entries do not share files: `{previous}` passes text only.
+3. **Merge** — only after an approving review, re-check Main's clean status, verify the branch tip still equals the reviewed tip commit, then merge that exact commit (not the branch name) into Main's current worktree and run focused validation there. Never merge on unresolved findings.
+4. **Clean up after success** — only after the exact reviewed tip is integrated and focused validation passes, remove each reported retained worktree, then safely delete its task branch. Include a superseded repair-round worktree only when its exact tip is an ancestor of integrated `HEAD`. For each candidate, verify ancestry first, use non-forced worktree removal followed by `git branch -d`, and stop/report cleanup failure without deleting later evidence. On any integration or validation failure, preserve every temporary patch artifact, retained worktree, and task branch for recovery. After integration and validation succeed, remove the temporary reviewer patch artifacts.
+
+## Findings
+
+Any reviewer finding goes back as a **fresh** `implementer` delegation containing the findings plus the reviewed base/branch/tip identities and complete exact patch file reference, followed by a fresh review of the new state. A fresh repair implementer starts in a new worktree from Main HEAD and does not contain the prior unit commit: the repair packet must first bring the whole reviewed `$base..$tip` range into its fresh worktree by merging the exact `$tip`, or cherry-picking every range commit in order. Cherry-pick `$tip` alone only after `git rev-list --count "$base..$tip"` verifies the range is exactly one commit; then address the findings. Dirty or uncommitted work also goes only to this fresh repair path. Bound the loop (e.g. three rounds); past the bound, stop and report to the user instead of merging.
+
+## Parallelism
+
+Independent units may run concurrently via one `delegate_task` parallel call (max 8 entries) or concurrent single calls, each still following its own implement → review cycle. Never parallelize a unit's review ahead of its implementation. Each child gets its own deterministic worktree; they never share files implicitly.
+
+## Boundaries
+
+- Never bypass review, edit inside a child's worktree, or re-implement a child's work yourself.
+- On child failure, recover from the reported preserved-worktree evidence; retry at most once per unit before escalating to the user.
+- Do not push, publish, release, or open PRs without explicit user authorization.