@tianhai/pi-workflow-kit 1.4.0 → 1.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 AI coding agents tend to skip design and jump straight into implementation, producing over-engineered or misaligned code. **pi-workflow-kit** solves this by hard-blocking write operations during brainstorm and planning phases — the agent *literally cannot modify your source files* until you approve the design.
 
-[pi](https://github.com/badlogic/pi-mono) package. Zero configuration required.
+[pi](https://github.com/badlogic/pi-mono) package. Skills are portable; the workflow guard and `/pwk-setup` command are Pi integrations.
 
 ## Install
 
@@ -12,7 +12,13 @@ AI coding agents tend to skip design and jump straight into implementation, prod
 pi install npm:@tianhai/pi-workflow-kit
 ```
 
-No setup needed — skills and guards activate automatically after install.
+For Pi delegation providers that discover project agents, install the canonical PWK roles before starting a gated workflow:
+
+```text
+/pwk-setup
+```
+
+This creates the five role definitions under `.agents/agents/`. It does not install or configure a provider. Existing customized files are preserved; use `/pwk-setup --force` only when you explicitly want to replace differing role files. Run setup before `/skill:pwk-brainstorming`; the command is refused during brainstorm and plan phases.
 
 **Want to try before committing?**
 
@@ -20,13 +26,19 @@ No setup needed — skills and guards activate automatically after install.
 pi -e npm:@tianhai/pi-workflow-kit
 ```
 
-**Optional — parallel code review.** The feature-level review can run four specialized reviewers in parallel over the whole feature diff via the `subagent` tool. Install [`pi-subagents`](https://pi.dev/packages/pi-subagents) to enable it:
+**Optional — delegated recon and review.** The skills request logical capabilities rather than a specific agent tool. If the host has no safe compatible provider, they perform recon and review inline. In Pi, [`@tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) is one compatible provider:
 
 ```bash
-pi install npm:pi-subagents
+pi install npm:@tintinweb/pi-subagents
 ```
 
-The four reviewers (`pwk-spec-reviewer`, `pwk-tracing-reviewer`, `pwk-smell-reviewer`, `pwk-hazard-reviewer`) ship with this kit as **package agents** — `pi-subagents` discovers them automatically, no extra setup. Without `pi-subagents`, `pwk-executing-tasks` falls back to inline `/skill:pwk-code-review`.
+After `/pwk-setup`, Tintinweb can discover the five named roles from `.agents/agents/`; recon can also use its built-in read-only `Explore` agent. No running subagents need to be pre-created. Other Pi extensions require the documented capabilities or a separate adapter; arbitrary extensions are not automatically compatible.
+
+### Using the roles on other hosts
+
+The five role files define portable logical roles, not a required provider API. Claude Code can map them to its native read-only task/subagent mechanism, but must enforce its own permissions or hooks because the Pi workflow guard does not transfer outside Pi. A different Pi extension can use the same roles when it provides the documented capabilities or an adapter; otherwise PWK performs recon and review inline.
+
+See [`docs/provider-delegation-contract.md`](docs/provider-delegation-contract.md) for the normalized capability and outcome contract. The core kit does not install a provider, require `@tintinweb/pi-subagents`, or provide automatic compatibility with every Pi subagent extension.
 
 ## What You Get
 
@@ -58,10 +70,10 @@ A **design doc is one PR**; a **requirement is one testable slice within it**. A
 
 | Phase | Trigger | What Happens |
 |-------|---------|--------------|
-| **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list. On non-trivial topics, dispatches the `pwk-recon-scout` agent (read-only) to map the codebase before design. |
+| **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list. On non-trivial topics, requests the logical `codebase-recon` capability; if unavailable or unsafe, performs the `pwk-recon-scout` role inline. |
 | **Plan** | `/skill:pwk-writing-plans` | Turn each requirement into **acceptance criteria + integration tests** — a behavioral spec (no implementation code) |
 | **Execute** | `/skill:pwk-executing-tasks` | Write the feature E2E (red) → **checkpoint: feature-spec** → implement requirements → **checkpoint: feature-complete** → feature review |
-| **Code review** | `/skill:pwk-code-review` | Feature-level (default) or per-requirement: code tracing, spec alignment, code smells (applies fixes), production hazard check |
+| **Code review** | `/skill:pwk-code-review` | Feature-level (default) or per-requirement: code tracing, spec alignment, code smells (applies fixes), production hazard check. Delegated review uses four logical roles when a safe provider is available; otherwise it runs inline. |
 | **Finalize** | `/skill:pwk-finalizing` | Delete consumed plan docs, update README/CHANGELOG, create PR |
 | **Diagnose** | `/skill:pwk-diagnose` | Debugging loop: reproduce → hypothesise → instrument → fix → cleanup. **Exits the gated phase** (debugging writes tests/instrumentation) |
 | **Status** | `/skill:pwk-status` | Read-only overview of all active design topics — phase + progress. Use when resuming or juggling several designs in parallel worktrees. Not a pipeline phase; **does not exit the gated phase**. |
@@ -177,11 +189,12 @@ pi-workflow-kit/
 │   ├── pwk-finalizing/SKILL.md
 │   ├── pwk-status/SKILL.md
 │   └── pwk-diagnose/SKILL.md
-├── agents/                   # package agents for parallel code-review + recon scout (discovered by pi-subagents)
+├── agents/                   # canonical role contracts; /pwk-setup copies them to .agents/agents/
 ├── docs/
 │   ├── developer-usage-guide.md
 │   ├── workflow-phases.md
 │   ├── oversight-model.md
+│   ├── provider-delegation-contract.md
 │   ├── lessons.md
 │   ├── adr/                  # permanent architectural decisions (never archived)
 │   └── plans/                # active design/plan/progress docs (deleted after finalization)

package/agents/pwk-hazard-reviewer.md

@@ -7,7 +7,11 @@ systemPromptMode: replace
 
 # PWK Hazard Reviewer
 
-You are a production-hazards reviewer. Execute the task instructions below faithfully using read-only tools (`read`, `grep`, `find`, `bash`). **Report findings only — do NOT modify files.** Flag hazards and non-trivial issues for the main agent / human to decide.
+You are a production-hazards reviewer. Execute the task instructions below faithfully using the host’s read-only tools. **Report findings only — do not modify files.** Flag hazards and non-trivial issues for the main agent or human to decide.
+
+## Authority boundary
+
+The host must enforce read-only execution. Do not create, modify, delete, move, or copy files, and do not run commands that mutate system or repository state.
 
 ## Checklist — audit each changed file
 
@@ -21,4 +25,6 @@ For each item below, write `[SAFE]` (1-line justification) or `[TRIGGERED]` (con
 6. **Unrestricted uploads / temp flooding** — uploads to local temp without limits or `finally` cleanup
 7. **Silent swallowing loops** — background workers catching/suppressing exceptions without logging/back-off
 
-Also check the design doc's `## Production-risk areas`, if any.
+Also check the design doc’s `## Production-risk areas`, if any.
+
+Include file and line evidence for each finding. If there are no findings, report `No findings` explicitly.

package/agents/pwk-recon-scout.md

@@ -7,21 +7,21 @@ systemPromptMode: replace
 
 # PWK Recon Scout
 
-You are a codebase recon scout dispatched by `pwk-brainstorming` before design work. Your job is to map how a repository handles a topic today so the main agent can design against prior art instead of loading the relevant files into its own context.
+You are a codebase recon scout requested during brainstorming before design work. Your job is to map how a repository handles a topic today so the main agent can design against prior art instead of loading the relevant files into its own context.
 
 **You are observations only.** No design recommendations, no preferred-approach opinion, no code beyond one-line excerpts. Every claim must cite a `file:line` so the main agent can drill in if it needs to.
 
-## Tools
+## Authority boundary
 
-You inherit the read-only set the workflow-guard already enforces on the brainstorm session: `read, grep, find, ls, bash`. Do not attempt writes or edits — they will be blocked.
+You are a read-only reporter. The host must enforce the requested read-only boundary; do not create, modify, delete, move, or copy files, and do not run commands that mutate system or repository state.
 
 ## Inputs
 
-The main agent dispatches you with three things in the task string:
+The host provides three things:
 
 - a `<topic>` (one short phrase, the new feature or change)
 - a one-line `<intent>` (what the new thing does, in plain words)
-- the repo root
+- the repository root
 
 If any of these is missing, ask for it before proceeding.
 
@@ -47,7 +47,9 @@ Where similar tests live, what harness they use (vitest, jest, go test, etc.), a
 
 ### Gotchas
 
-Anything that bit a previous change, in this layer of the code or in the topic area specifically. A migrations folder that must run in order, a feature flag that gates the new path, a known deadlock with another subsystem, an environment variable that has to be set, a CI hook that runs before tests. The point is to surface landmines before the main agent commits to a design.
+Anything that bit a previous change, in this layer of the code or in the topic area specifically. A migrations folder that must run in order, a feature flag that gates the new path, a known deadlock with another subsystem, an environment variable that has to be set, a CI hook that runs before tests. The point is to surface landmines before the planning phase.
+
+End with `Scout: complete` when the five sections are present. If the host cannot complete the report, return `Scout: unavailable` with the reason instead of inventing observations.
 
 ## Hard rules
 
@@ -59,10 +61,9 @@ Anything that bit a previous change, in this layer of the code or in the topic a
 
 ## When you finish
 
-Return the report as your final message. The main agent reads it into its context and uses it as the grounding for the next two brainstorm steps (Explore approaches, Present the design).
+Return the report as your final message. The main agent reads it into its context and uses it as the grounding context for approach exploration and design presentation.
 
 ## Failure modes
 
-- Subagent tool unavailable: the main agent will fall back to inline recon and you will not be invoked. You do not need to handle this case.
-- You return empty: the main agent will treat it as greenfield and proceed with no-prior-art assumptions. Returning a short, honest report is better than padding it.
-- You return a wrong-shaped report: the main agent will downweight the findings but still proceed. Better to ship the 5-section shape than to improvise.
+- If no compatible read-only delegation worker is available, the main agent performs this role inline.
+- If the role cannot complete, return `Scout: unavailable` with the reason rather than returning an empty or invented report.

package/agents/pwk-smell-reviewer.md

@@ -7,11 +7,21 @@ systemPromptMode: replace
 
 # PWK Smell Reviewer
 
-You are a code-smell reviewer. Execute the task instructions below faithfully using read-only tools (`read`, `grep`, `find`, `bash`). **Report findings only — do NOT modify files.** Flag only: smells that require large refactors risky to the requirement; everything else is for the main agent to fix.
+You are a code-smell reviewer. Execute the task instructions below faithfully using the host’s read-only tools. **Report findings only — do not modify files.** Flag only smells that require large refactors risky to the requirement; everything else is for the main agent to fix.
+
+## Authority boundary
+
+The host must enforce read-only execution. Do not create, modify, delete, move, or copy files, and do not run commands that mutate system or repository state.
+
+## Review scope
+
+Review the changed code and affected files against the assigned requirement and feature scope.
 
 ## Checklist — report what you find
 
 - Shallow modules (interface nearly as complex as implementation)
 - Duplication
-- Missing seams / premature abstraction
-- Poor naming, magic values, dead code
+- Missing seams or premature abstraction
+- Poor naming, magic values, dead code
+
+Include file and line evidence for each finding. If there are no findings, report `No findings` explicitly.

package/agents/pwk-spec-reviewer.md

@@ -7,8 +7,12 @@ systemPromptMode: replace
 
 # PWK Spec Reviewer
 
-You are a spec-alignment reviewer. Execute the task instructions below faithfully using read-only tools (`read`, `grep`, `find`, `bash`). **Report findings only — do NOT modify files.**
+You are a spec-alignment reviewer. Execute the task instructions below faithfully using the host’s read-only tools. **Report findings only — do not modify files.**
+
+## Authority boundary
+
+The host must enforce read-only execution. Do not create, modify, delete, move, or copy files, and do not run commands that mutate system or repository state.
 
 ## Checklist
 
-For each acceptance criterion, point to the code and the test that satisfy it. A criterion with no covering code or no test is a **gap**. Code that does more than the criteria specify is **scope creep** — flag it.
+For each acceptance criterion, point to the code and the test that satisfy it. A criterion with no covering code or no test is a **gap**. Code that does more than the criteria specify is **scope creep** — flag it. Include the relevant file and line for each finding. If there are no findings, report `No findings` explicitly.

package/agents/pwk-tracing-reviewer.md

@@ -7,8 +7,12 @@ systemPromptMode: replace
 
 # PWK Trace Reviewer
 
-You are a code-tracing reviewer. Execute the task instructions below faithfully using read-only tools (`read`, `grep`, `find`, `bash`). **Report findings only — do NOT modify files.**
+You are a code-tracing reviewer. Execute the task instructions below faithfully using the host’s read-only tools. **Report findings only — do not modify files.**
+
+## Authority boundary
+
+The host must enforce read-only execution. Do not create, modify, delete, move, or copy files, and do not run commands that mutate system or repository state.
 
 ## Checklist
 
-Trace the new/changed code paths end-to-end against the integration tests. For each path: does data flow correctly from entry to the asserted outcome? Note any branch the tests don't exercise, any dead branch, any path where the trace breaks.
+Trace the new or changed code paths end-to-end against the integration tests. For each path, determine whether data flows correctly from entry to the asserted outcome. Note any branch the tests do not exercise, any dead branch, or any path where the trace breaks. Include file and line evidence. If there are no findings, report `No findings` explicitly.

package/docs/developer-usage-guide.md

@@ -1,6 +1,6 @@
 # Developer Usage Guide
 
-How to install and use `pi-workflow-kit` with the Pi coding agent.
+How to install and use `pi-workflow-kit` with Pi, and how its workflow roles map to other agent hosts.
 
 ## What you get
 
@@ -40,11 +40,19 @@ You control each phase by invoking the skill. A design doc is one PR; a requirem
 
 ### 1. Brainstorm
 
+Before entering the gated phase in Pi, optionally install the canonical role definitions:
+
+```
+/pwk-setup
+```
+
+The command creates `.agents/agents/` and installs the five PWK roles. It preserves differing files unless `--force` is supplied and is refused during brainstorm and plan phases. It does not install a delegation provider.
+
 ```
 /skill:pwk-brainstorming
 ```
 
-Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review. On non-trivial topics with prior art, the agent dispatches the `pwk-recon-scout` package agent (read-only, fresh context) to map the codebase before design, so the main agent can design against prior art instead of loading files into its own context.
+Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review. On non-trivial topics with prior art, the skill requests the logical `codebase-recon` capability using the `pwk-recon-scout` role. A compatible host may dispatch that role in a fresh, bounded, read-only worker; otherwise the skill reports `Scout: unavailable` and performs the same five-section recon inline.
 
 Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list. For a too-big requirement, may start an **umbrella** (writes a status-free overview + the first part's design doc). ADRs go to `docs/adr/` (permanent).
 
@@ -68,13 +76,11 @@ Implement via the **feature-gate flow** with full autonomy: write the feature-ac
 
 ### 4. Code review (feature level)
 
-The `pwk-executing-tasks` skill invokes the `subagent` tool automatically at the feature-level review (programmatic, not user-driven). Four specialized reviewers launch in parallel over the whole feature diff — each from a different dimension (spec gaps & scope creep, end-to-end code tracing, code smells, production hazards). A per-requirement review runs the same way for a tagged requirement. The reviewers ship as **package agents** (`agents/pwk-*.md`, declared via the `pi-subagents.agents` manifest key) and are discovered natively by the optional **`pi-subagents`** package — no copy step. All report findings only; no agent edits files or produces commits. The main agent collects results, applies smell fixes itself, runs integration tests after each fix, then updates progress to `✅ done`.
+The `pwk-executing-tasks` skill requests the `parallel-review` capability for four logical roles over the whole feature diff: spec alignment, code tracing, code smells, and production hazards. The roles are independent, fresh-context, read-only reporters; the main agent collects their results, applies smell fixes itself, runs the tests, and flags other findings for the human.
 
-*Fallback:* if `pi-subagents` is not installed (so the `subagent` tool is unavailable), the skill falls back to inline `/skill:pwk-code-review` as before. Install it to enable parallel review:
+In Pi, `/pwk-setup` installs the canonical role definitions into `.agents/agents/`, where compatible providers such as `@tintinweb/pi-subagents` can discover them. Tintinweb may run the roles through its native `Agent` mechanism or map recon to its built-in read-only `Explore` type. The core kit does not require Tintinweb or any other provider.
 
-```bash
-pi install npm:pi-subagents
-```
+*Fallback:* if no host/provider can guarantee the requested capabilities, the skill performs the missing recon or review work inline. Other Pi extensions are supported only when they expose the documented capabilities or have a separate adapter; arbitrary extensions are not automatically compatible. See `docs/provider-delegation-contract.md` for the integration contract.
 
 ### 5. Finalize
 
@@ -102,7 +108,7 @@ A read-only overview of all active design topics — which phase each is in and
 
 ## What the extension does
 
-The `workflow-guard` extension watches `write`/`edit` and `bash` tool calls:
+The `workflow-guard` extension registers `/pwk-setup` and watches `write`/`edit` and `bash` tool calls:
 
 - **During brainstorm and writing-plans**: blocks writes outside `docs/plans/`, and blocks destructive bash via a simple common-blacklist (a command is allowed unless it matches a destructive pattern). A short phase reminder is shown once when the gated phase begins so the model self-restricts.
 - **During executing-tasks, code-review, finalizing, diagnose**: no restrictions.

package/docs/oversight-model.md

@@ -6,10 +6,10 @@
 
 Skills teach the agent the workflow. There are 5 pipeline skills:
 
-- **pwk-brainstorming** — explore ideas, produce a descriptive design doc that opens with a `## Requirements` list. For a requirement too big for one design doc, may start an **umbrella** (multiple design docs under one status-free overview, shipping as one PR)
+- **pwk-brainstorming** — explore ideas, produce a descriptive design doc that opens with a `## Requirements` list. For a requirement too big for one design doc, may start an **umbrella** (multiple design docs under one status-free overview, shipping as one PR). On non-trivial topics, requests the logical `codebase-recon` capability and falls back to the `pwk-recon-scout` role inline when unavailable or unsafe.
 - **pwk-writing-plans** — turn each requirement into acceptance criteria + integration-test cases (a behavioral spec, no implementation code)
 - **pwk-executing-tasks** — feature-gate flow: write the feature E2E first, implement the requirements, then one feature-level review; two mandatory checkpoints at the feature level, per-requirement ceremony opt-in
-- **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, the **feature-level review** (the default) runs **four specialized reviewers in parallel** over the whole feature diff via the `subagent` tool, each from a fresh context (spec gaps & scope creep, tracing, smells, hazards); a per-requirement review runs the same way for a tagged requirement. These ship as package agents (`agents/pwk-*.md`) discovered natively by the optional **`pi-subagents`** package; all report findings only — fixes are applied by the executing-tasks main agent. Falls back to inline `/skill:pwk-code-review` when `pi-subagents` is not installed.
+- **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, the feature-level review requests the `parallel-review` capability for four logical fresh-context, read-only roles; successful reports are retained and missing roles are retried or completed inline. It falls back to inline review when no safe compatible provider exists. The canonical provider contract is documented in `docs/provider-delegation-contract.md`.
 - **pwk-finalizing** — dispose consumed plan docs (archive or delete; for an umbrella, the overview + every part), curate lessons, update docs, create PR or merge
 
 Plus 2 on-demand skills:
@@ -21,7 +21,7 @@ They explain *what* to do and *when* to do it. Phase control is manual — you i
 
 ## Extension
 
-The `workflow-guard` extension enforces one rule:
+The `workflow-guard` extension registers the Pi-only `/pwk-setup` command and enforces one workflow rule:
 
 > During brainstorm and plan phases, `write` and `edit` are **hard-blocked** outside `docs/plans/`.
 
@@ -29,7 +29,7 @@ The agent can still use `read` and `bash` for investigation. During those gated
 
 During executing-tasks, code-review, finalizing, **and diagnose**, nothing is restricted (diagnosis needs to write failing tests and debug instrumentation, so it exits the gate). `pwk-status` stays inside the gate.
 
-Reviewer-agent checklists live only in `agents/pwk-*-reviewer.md` (single source of truth); `pwk-executing-tasks` passes each reviewer just the requirement scope + diff and names the agent.
+Canonical role contracts live in `agents/pwk-*.md` (single source of truth) and can be installed into `.agents/agents/` with `/pwk-setup`. `pwk-executing-tasks` requests logical review roles through the host’s delegation capabilities and passes each role just the requirement scope + diff.
 
 Phases follow the skill you invoke — there is no message-keyword unlock. Invoking `/skill:pwk-executing-tasks`, `pwk-finalizing`, `pwk-code-review`, or `pwk-diagnose` exits the gated phase (those skills write source); `pwk-status` deliberately does **not** (read-only orientation). `/pwk-guard on|off|auto` manually overrides the guard.
 

package/docs/provider-delegation-contract.md

@@ -0,0 +1,112 @@
+# Provider Delegation Contract
+
+This document defines the provider-neutral contract for running PWK roles outside the main agent. It is an integration contract for host adapters and extensions. The workflow skills describe the same behavior in portable language; they do not require this document’s TypeScript notation or any specific transport.
+
+## Logical operations
+
+A provider may support either operation independently:
+
+- `codebase-recon` — run one `pwk-recon-scout` role and return its five-section observation map.
+- `feature-review` — run the requested review roles over one feature scope and return one outcome per role.
+
+The logical role name is not the provider’s concrete agent type. A provider may map `pwk-recon-scout` to a safe built-in explorer, a custom agent definition, or a host-native read-only task.
+
+## Required capabilities
+
+A provider advertises capabilities independently from its name:
+
+| Capability | Meaning |
+|---|---|
+| `codebase-recon` | Can run one fresh, read-only recon worker and collect its report. |
+| `named-role-dispatch` | Can map each requested logical role to an appropriate worker. |
+| `parallel-review` | Can run independent review roles concurrently when requested. |
+| `result-collection` | Returns one distinguishable outcome for every requested role. |
+| `read-only-enforcement` | Prevents delegated workers from writing files or running destructive commands. |
+| `fresh-context` | Starts each requested worker without reusing an unrelated prior conversation. |
+| `bounded-execution` | Applies a timeout, turn limit, or equivalent resource bound. |
+
+A provider must not claim `read-only-enforcement` when it only adds a prompt instruction. Providers may support `codebase-recon` without supporting `parallel-review`.
+
+## Request shape
+
+The following TypeScript is illustrative. Implementations may use Pi events, tool calls, CLI processes, native task APIs, or another transport. A reference implementation of the outcome normalization lives in `extensions/workflow-guard.ts` (`assessDelegationCoverage`), exported as a pure helper so future adapters and tests share one definition of complete coverage.
+
+```ts
+type DelegationOperation = 'codebase-recon' | 'feature-review';
+type DelegationRole =
+  | 'pwk-recon-scout'
+  | 'pwk-spec-reviewer'
+  | 'pwk-tracing-reviewer'
+  | 'pwk-smell-reviewer'
+  | 'pwk-hazard-reviewer';
+
+type DelegationRequest = {
+  operation: DelegationOperation;
+  roles: DelegationRole[];
+  prompt: string;
+  cwd: string;
+  constraints: {
+    readOnly: true;
+    freshContext: true;
+    parallel: boolean;
+    bounded: true;
+  };
+};
+```
+
+The provider must preserve the logical roles and the repository root when translating a request. `parallel: true` requests concurrency; it does not permit unbounded concurrency. If the provider cannot satisfy a requested constraint, it must reject the delegated operation so the host can use inline fallback.
+
+## Normalized outcome shape
+
+```ts
+type DelegationStatus = 'completed' | 'failed' | 'timed-out' | 'skipped';
+
+type DelegationResult = {
+  role: DelegationRole;
+  status: DelegationStatus;
+  report?: string;
+  error?: string;
+  provider?: string;
+  runId?: string;
+};
+```
+
+Rules:
+
+- `role` is required and must identify one requested logical role.
+- `completed` requires a non-empty `report` that follows the role contract.
+- `failed` and `timed-out` require an `error` or equivalent failure explanation.
+- `skipped` is explicit and is not equivalent to completion.
+- `provider` identifies the adapter or host that produced the outcome when known.
+- `runId` is an opaque provider-local identifier when available; consumers must not interpret its format.
+- A multi-role operation is complete only when every requested role has a completed result or an explicit fallback result approved by the workflow.
+
+An empty report is not a successful result. A missing role is not silently discarded.
+
+## Fallback protocol
+
+If no provider satisfies the requested capabilities, the host performs the role inline using the same logical contract. For recon, it reports:
+
+```text
+Scout: unavailable — inline recon used.
+```
+
+For feature review, successful delegated reports remain usable. A failed or timed-out role is retried or performed inline. The host does not report a complete review while a required role has neither a delegated result nor an inline result.
+
+## Provider discovery and selection
+
+Provider discovery and transport are host-specific. A future Pi adapter may use a capability registry, an event-bus handshake, a shared extension RPC, or explicit configuration. The core PWK package does not assume that all Pi extensions are discoverable or that a package name identifies a compatible provider.
+
+If multiple providers are available, selection must be deterministic. A host may use explicit configuration or a documented priority order. It must not select a provider based only on extension load order when that changes safety or result semantics.
+
+## Role setup and provider loading
+
+The Pi-only `/pwk-setup` command copies the canonical role definitions into `.agents/agents/`. This makes named roles available to providers that discover the shared directory, including `@tintinweb/pi-subagents`. Setup creates role definitions; it does not install or configure a provider.
+
+Providers may cache role definitions. Hosts should tell the user when `/reload` or a new session is needed. Setup must not reload a session implicitly.
+
+## Safety boundary
+
+The provider is responsible for enforcing any capability it advertises. The role prompt is defense in depth, not a security boundary. The Pi workflow guard protects the main Pi session’s brainstorm and plan phases; it does not automatically protect Claude Code or another host, and it does not replace delegated-worker tool restrictions.
+
+The `/pwk-setup` installer itself is hardened in depth: it opens the target with `O_NOFOLLOW` and does every subsequent check, read, and write through that one descriptor (`fstat` regular-file check, content comparison, and post-write verification), so nothing swapped in on the path afterward can affect what is read or written. On platforms where `O_NOFOLLOW` is unavailable, a symlink swapped in before the initial open remains a narrow advisory window; setup is a user-invoked development command, not a security boundary.

package/docs/workflow-phases.md

@@ -43,7 +43,7 @@ Write boundary: only `docs/plans/` is writable.
 /skill:pwk-executing-tasks
 ```
 
-- **Feature-gate flow:** write the feature-acceptance E2E test (red) → **⏸ checkpoint: feature-spec** (human confirms the E2E proves the feature) → implement the requirements back-to-back with full autonomy (the executor chooses structure/signatures/internals) → **⏸ checkpoint: feature-complete** (full suite + feature E2E green) → **feature review** (four parallel reviewers over the whole feature diff via the `subagent` tool; falls back to inline `/skill:pwk-code-review` when `pi-subagents` is absent — see [code-review](#code-review)).
+- **Feature-gate flow:** write the feature-acceptance E2E test (red) → **⏸ checkpoint: feature-spec** (human confirms the E2E proves the feature) → implement the requirements back-to-back with full autonomy (the executor chooses structure/signatures/internals) → **⏸ checkpoint: feature-complete** (full suite + feature E2E green) → **feature review** (request the `parallel-review` capability for four logical read-only roles when the host supports it; otherwise run `/skill:pwk-code-review` inline — see [code-review](#code-review)).
 - Per-requirement checkpoints/reviews are **opt-in** — they fire only for requirements the plan tags (default off); see [Proportionality](#proportionality).
 - **Regression check after each commit** — run the full existing suite to catch cross-requirement regressions immediately. The feature E2E stays red until the last requirement and is gated only at `feature-complete` (the old integration gate folds into it).
 - Progress tracked in `docs/plans/*-progress.md` (feature phase + requirement checklist).
@@ -68,7 +68,7 @@ Flag a requirement for a checkpoint when it has complex logic or is the main par
 
 The **inline reviewer**: code tracing, spec alignment (vs acceptance criteria), code smells (applies fixes), production hazard check. Unlocked — may modify code to fix smells.
 
-**Not a phase you drive manually.** During `pwk-executing-tasks`, the **feature-level review** (the default) runs **four specialized reviewers in parallel** over the whole feature diff via the `subagent` tool (spec, tracing, smell, hazard — each fresh-context, read-only reporters); a per-requirement review runs the same way for a tagged requirement. This skill is the **fallback** when [`pi-subagents`](https://pi.dev/packages/pi-subagents) is not installed. You can also invoke `/skill:pwk-code-review` standalone for an ad-hoc review of any diff.
+**Not a phase you drive manually.** During `pwk-executing-tasks`, the feature-level review requests four logical roles (`pwk-spec-reviewer`, `pwk-tracing-reviewer`, `pwk-smell-reviewer`, `pwk-hazard-reviewer`) through the host’s `parallel-review` capability. Roles are fresh-context, read-only reporters; successful reports are retained and failed roles are retried or completed inline. If no compatible provider is available, the whole review runs inline. In Pi, `/pwk-setup` installs the canonical role definitions into `.agents/agents/`; [`@tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) is one compatible provider. See `docs/provider-delegation-contract.md` for the provider contract. You can also invoke `/skill:pwk-code-review` standalone for an ad-hoc review of any diff.
 
 No write restrictions.
 

package/extensions/workflow-guard.ts

@@ -1,4 +1,17 @@
-import { resolve } from "node:path";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  ftruncateSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  writeSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 /**
@@ -12,6 +25,192 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 type Phase = "brainstorm" | "plan" | null;
 
+type DelegationStatus = "completed" | "failed" | "timed-out" | "skipped";
+
+export interface DelegationOutcome {
+  role: string;
+  status: DelegationStatus;
+  report?: string;
+  error?: string;
+  provider?: string;
+  runId?: string;
+}
+
+export interface DelegationCoverage {
+  complete: boolean;
+  missing: string[];
+  retainedReports: string[];
+}
+
+/** Summarize role outcomes without treating failed or empty outcomes as coverage. */
+export function assessDelegationCoverage(
+  requiredRoles: readonly string[],
+  outcomes: readonly DelegationOutcome[],
+): DelegationCoverage {
+  const completedReports = new Map<string, string>();
+  for (const outcome of outcomes) {
+    if (outcome.status === "completed" && outcome.report) {
+      completedReports.set(outcome.role, outcome.report);
+    }
+  }
+
+  const missing = requiredRoles.filter((role) => !completedReports.has(role));
+  return {
+    complete: missing.length === 0,
+    missing,
+    retainedReports: [...completedReports.values()],
+  };
+}
+
+export const ROLE_NAMES = [
+  "pwk-recon-scout",
+  "pwk-spec-reviewer",
+  "pwk-tracing-reviewer",
+  "pwk-smell-reviewer",
+  "pwk-hazard-reviewer",
+] as const;
+
+const CANONICAL_AGENTS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "agents");
+
+function setupUsageError(): Error {
+  return new Error("Usage: /pwk-setup [--force]");
+}
+
+function parseSetupArgs(args: string): { force: boolean } {
+  const normalized = args.trim();
+  if (!normalized) return { force: false };
+  if (normalized === "--force") return { force: true };
+  throw setupUsageError();
+}
+
+function ensureDirectory(path: string): void {
+  const stats = statNoFollow(path);
+  if (!stats) {
+    mkdirSync(path);
+    return;
+  }
+  if (stats.isSymbolicLink()) throw new Error(`Refusing symlink destination: ${path}`);
+  if (!stats.isDirectory()) throw new Error(`Destination is not a directory: ${path}`);
+}
+
+/** lstat without following symlinks; null when the path does not exist. */
+function statNoFollow(path: string): ReturnType<typeof lstatSync> | null {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    return null;
+  }
+}
+
+/** Read exactly `size` bytes from `fd` starting at position 0, regardless of the fd's cursor. */
+function readAllFromFd(fd: number, size: number): string {
+  const buffer = Buffer.alloc(size);
+  let offset = 0;
+  while (offset < size) {
+    const bytesRead = readSync(fd, buffer, offset, size - offset, offset);
+    if (bytesRead === 0) break;
+    offset += bytesRead;
+  }
+  return buffer.toString("utf8");
+}
+
+/** Write `content` to `fd` at position 0 (truncating first) and verify by reading the same fd back. */
+function overwriteFd(fd: number, content: string, path: string): void {
+  ftruncateSync(fd, 0);
+  const buffer = Buffer.from(content, "utf8");
+  writeSync(fd, buffer, 0, buffer.length, 0);
+  if (readAllFromFd(fd, buffer.length) !== content) throw new Error(`Verification failed after writing: ${path}`);
+}
+
+function writeNewFile(path: string, content: string): void {
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+  const flags = constants.O_RDWR | noFollow | constants.O_CREAT | constants.O_EXCL;
+  const fd = openSync(path, flags, 0o644);
+  try {
+    overwriteFd(fd, content, path);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function installRoleFiles(cwd: string, force: boolean): { installed: string[]; skipped: string[] } {
+  const projectAgentsDir = join(cwd, ".agents");
+  const targetDir = join(projectAgentsDir, "agents");
+  ensureDirectory(projectAgentsDir);
+  ensureDirectory(targetDir);
+
+  const installed: string[] = [];
+  const skipped: string[] = [];
+  const failures: string[] = [];
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+
+  for (const roleName of ROLE_NAMES) {
+    const sourcePath = join(CANONICAL_AGENTS_DIR, `${roleName}.md`);
+    const targetPath = join(targetDir, `${roleName}.md`);
+
+    try {
+      // Read inside the try: one broken canonical source becomes a per-role failure
+      // instead of aborting the whole install and hiding other roles' results.
+      const content = readFileSync(sourcePath, "utf8");
+
+      // Open the existing target (if any) once and do every check/read/write through
+      // that single fd — the fd names one fixed inode, so nothing swapped in on the
+      // path between checks (TOCTOU) can affect what gets read or written.
+      let fd: number | null;
+      try {
+        fd = openSync(targetPath, constants.O_RDWR | noFollow);
+      } catch (error) {
+        const err = error as NodeJS.ErrnoException;
+        if (err.code === "ENOENT") {
+          fd = null;
+        } else if (err.code === "ELOOP") {
+          throw new Error(`Refusing symlink destination: ${targetPath}`);
+        } else {
+          throw error;
+        }
+      }
+
+      if (fd === null) {
+        writeNewFile(targetPath, content);
+        installed.push(roleName);
+        continue;
+      }
+
+      try {
+        const stats = fstatSync(fd);
+        if (!stats.isFile()) throw new Error(`Refusing non-regular destination: ${targetPath}`);
+
+        const existing = readAllFromFd(fd, stats.size);
+        if (existing === content) {
+          skipped.push(roleName);
+          continue;
+        }
+        if (!force) {
+          failures.push(`${targetPath}: conflict (use /pwk-setup --force to replace it)`);
+          continue;
+        }
+
+        overwriteFd(fd, content, targetPath);
+        installed.push(roleName);
+      } finally {
+        closeSync(fd);
+      }
+    } catch (error) {
+      failures.push(`${targetPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  if (failures.length > 0) {
+    const partial =
+      installed.length + skipped.length > 0
+        ? ` (${installed.length} installed, ${skipped.length} skipped before failure — installation is partial)`
+        : "";
+    throw new Error(`PWK setup incomplete${partial}:\n${failures.join("\n")}`);
+  }
+  return { installed, skipped };
+}
+
 // Destructive commands blocked in brainstorm/plan phases (simple common blacklist)
 const DESTRUCTIVE_PATTERNS = [
   /\brm\b/i,
@@ -181,6 +380,16 @@ function enforceLabel(): string {
   return guardOverride === "on" ? "GUARD ON" : phase ? phase.toUpperCase() : "";
 }
 
+/**
+ * Is `/pwk-setup` blocked right now? Deliberately NOT `enforceActive()`: setup must
+ * refuse during a gated phase even when the tool-call guard is manually disabled
+ * (`/pwk-guard off`), since its own banner promises writes stay confined to
+ * docs/plans/ for the whole gated phase, override or not.
+ */
+function setupBlocked(): boolean {
+  return phase !== null || guardOverride === "on";
+}
+
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", () => {
     phase = null;
@@ -188,6 +397,40 @@ export default function (pi: ExtensionAPI) {
     guardOverride = null;
   });
 
+  // --- Project role setup -------------------------------------------------
+  // This command writes through Node rather than the write tool, so it enforces
+  // the gated-phase boundary itself instead of relying on tool_call interception.
+  pi.registerCommand("pwk-setup", {
+    description: "Install PWK role agents into .agents/agents/",
+    handler: async (args, ctx) => {
+      // Refuse whenever the session is read-only in fact: gated phase (even with the
+      // tool-call guard manually disabled — the design mandates that) or the manual
+      // read-only lock, whose banner promises "writes only under docs/plans/".
+      if (setupBlocked()) {
+        const scope =
+          guardOverride === "on"
+            ? "the manual read-only lock (/pwk-guard on)"
+            : `${(phase as string).toUpperCase()} phase`;
+        const message = `Cannot run /pwk-setup during ${scope}. Run it before entering the gated workflow or after leaving it (guard auto/off).`;
+        ctx.ui.notify(message, "warning");
+        throw new Error(message);
+      }
+
+      const { force } = parseSetupArgs(args ?? "");
+      try {
+        const result = installRoleFiles(ctx.cwd, force);
+        const parts = [`PWK setup complete: ${result.installed.length} installed`];
+        if (result.skipped.length > 0) parts.push(`${result.skipped.length} skipped`);
+        if (force) parts.push("forced conflicts replaced");
+        ctx.ui.notify(`${parts.join(", ")}. Providers may require /reload to discover updated roles.`, "info");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(message, "error");
+        throw error;
+      }
+    },
+  });
+
   // --- Manual override (escape hatch) -----------------------------------
   // Phases are driven by `/skill:` commands; `/pwk-guard` lets the user pin the
   // guard regardless of phase. `/pwk-guard auto` returns control to skill transitions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",
@@ -32,6 +32,7 @@
     "docs/developer-usage-guide.md",
     "docs/workflow-phases.md",
     "docs/oversight-model.md",
+    "docs/provider-delegation-contract.md",
     "LICENSE",
     "README.md"
   ],

package/skills/pwk-brainstorming/SKILL.md

@@ -54,7 +54,7 @@ The whole umbrella is one branch and one PR: `pwk-writing-plans` creates the bra
 1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
 2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — glob `docs/plans/*-design.md` and `*-overview.md`; report in-flight topics and any active umbrella. If the new idea continues an existing topic, ask whether to extend it or start fresh. Part of an umbrella? An existing `*-overview.md` means the split is already decided — read it for the roster and design this part's `-design.md` against it (see [Umbrella](#umbrella)).
 3. **Understand the idea** — read only enough code/docs/commits to ground the design. **Check `docs/lessons.md`** — known constraints may shape it. Ask questions one at a time, prefer multiple choice. Once you can articulate what/why/constraints, present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
-4. **(skipped on trivial changes)** **Codebase recon** — for non-trivial topics with prior art, dispatch the `pwk-recon-scout` package agent (a fresh-context, read-only worker) with the topic, a one-line intent, and the repo root. Use the returned 5-section codebase map (Relevant files, Existing patterns, Call sites, Test layout, Gotchas) as the grounding context for the next two steps instead of reading those files inline. The scout is observations only — no design recommendations — and stays within the read-only tool set the guard already enforces. Skip this step on trivial changes (typo, version bump, single-function edit per the proportionality rule). If the `subagent` tool is unavailable (e.g. `pi-subagents` is not installed), skip the dispatch, do the recon inline as today, and append the literal line `Scout: unavailable (pi-subagents not installed) — inline recon used.` to the design doc at step 7.
+4. **(skipped on trivial changes)** **Codebase recon** — for non-trivial topics with prior art, request the host’s `codebase-recon` capability using the logical `pwk-recon-scout` role. Require a fresh-context, read-only, bounded worker and pass the topic, one-line intent, and repo root. Use the returned 5-section codebase map (Relevant files, Existing patterns, Call sites, Test layout, Gotchas) as the grounding context for the next two steps instead of reading those files inline. The scout is observations only — no design recommendations. Skip this step on trivial changes (typo, version bump, single-function edit per the proportionality rule). If no compatible capability is available or the provider cannot enforce the requested constraints, report `Scout: unavailable` and do the same recon inline, preserving the five-section map and `file:line` citations; do not silently omit recon.
 5. **Explore approaches** — propose 2–3, leading with your recommendation. Sketch the concrete interface (types, signatures, example caller) for each so the comparison is grounded in code, not abstractions.
 6. **Present the design** in one pass, organized into sections (architecture, components, data flow, error handling, testing) — the human comments on any section; re-present only revised sections.
 

package/skills/pwk-executing-tasks/SKILL.md

@@ -7,7 +7,7 @@ description: "Implement a plan via the feature-gate flow: write the feature-acce
 
 Implement the plan from `docs/plans/*-implementation.md` via the **feature-gate flow**. The plan is a behavioral spec (acceptance criteria + integration tests) — you choose structure, signatures, internals; the criteria define *what*, you decide *how*.
 
-The feature-acceptance E2E test is the primary enforced gate. The flow is always on: write the E2E first (red), implement the requirements back-to-back, then run one feature-level review over the whole diff. Per-requirement checkpoints and reviews are **opt-in** — they fire only for requirements the plan tags (default off); the feature gate covers everything else.
+The feature-acceptance E2E test is the primary enforced gate and the primary enforced spec for the feature. The flow is always on: write the E2E first (red), implement the requirements back-to-back, then run one feature-level review over the whole diff. Per-requirement checkpoints and reviews are **opt-in** — they fire only for requirements the plan tags (default off); the feature gate covers everything else.
 
 ## Before you start
 
@@ -93,25 +93,10 @@ The old "integration gate" is gone — the feature E2E at `feature-complete` *is
 
 After `feature-complete` is approved, run **one** review over the **whole feature diff**, driven by the plan's feature-level `### Feature review` tag. This is the single thorough review — per-requirement reviews, if any, only saw slices in isolation.
 
-- **`parallel`** (default) — four fresh-context reviewers via the `subagent` tool. Gather scope (the plan's acceptance criteria + Feature acceptance, `git log --oneline && git diff <merge-base>...HEAD`) and invoke:
-
-  ```json
-  {
-    "tasks": [
-      {"agent": "pwk-spec-reviewer", "task": "<scope + whole diff here>"},
-      {"agent": "pwk-tracing-reviewer", "task": "<scope + whole diff here>"},
-      {"agent": "pwk-smell-reviewer", "task": "<scope + whole diff here>"},
-      {"agent": "pwk-hazard-reviewer", "task": "<scope + whole diff here>"}
-    ],
-    "agentScope": "both",
-    "cwd": "<repo-root>"
-  }
-  ```
-
-  The reviewer checklists live only in `agents/pwk-*-reviewer.md` — don't restate them in the task strings (duplication guarantees drift). Reviewers are read-only reporters; you apply smell fixes yourself (full suite + E2E must stay green, commit) and flag trace/spec/hazard findings as follow-ups for the human.
-
-- **`inline`** — run `/skill:pwk-code-review` over the whole diff as a single pass.
-- **Fallback** — subagent tool unavailable or errors → run `/skill:pwk-code-review` inline instead.
+- **`parallel`** (default) — request the host’s `parallel-review` capability for four fresh-context, read-only logical roles: `pwk-spec-reviewer`, `pwk-tracing-reviewer`, `pwk-smell-reviewer`, and `pwk-hazard-reviewer`. Gather scope (the plan's acceptance criteria + Feature acceptance, `git log --oneline && git diff <merge-base>...HEAD`) and provide it to every role. Require independent execution and one collected outcome per role. The reviewer role contracts live in `agents/pwk-*-reviewer.md`; do not duplicate their checklists in the workflow instructions. Reviewers are read-only reporters; you apply smell fixes yourself (full suite + E2E must stay green, commit) and flag trace/spec/hazard findings as follow-ups for the human.
+
+- **`inline`** — perform `/skill:pwk-code-review` over the whole diff as a single pass.
+- **Fallback** — if the host has no compatible parallel-review capability, cannot prove the requested read-only/fresh-context/bounded constraints, or delegation fails, perform the missing review work inline. Retain successful delegated reports and do not mark the feature fully reviewed while a required role is missing.
 
 On success, set `Feature phase: done`.
 

package/skills/pwk-writing-plans/SKILL.md

@@ -23,7 +23,7 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
    - **Integration tests** — test name + what each asserts. This is the spec the executor writes tests from.
    - **Meaningful tests** — write acceptance criteria and tests as observable behavior: (1) **Test observable behavior** — assert on what the feature produces or changes (a return value, persisted/updated data, an emitted event, an HTTP response) through its public interface; these assertions keep passing as the implementation changes. (2) **Write a per-slice test when the slice has its own observable behavior** — when a slice is pure config or a trivial extraction, the feature E2E covers it and a per-slice test is unnecessary.
    - **`### Checkpoints: none | full | spec`** — how many human stops. `none` = no per-requirement stop (default — the feature gate covers it); `full` = tests + complete stops; `spec` = tests stop only. Flag a requirement `full` or `spec` when it contains complex logic or is the main part of the feature — where a human look at the slice is worth the stop.
-   - **`### Review: skip | parallel | inline`** — `skip` = no per-requirement review (default — the feature-level review covers it); `parallel` = four reviewers via subagent; `inline` = one `pwk-code-review` pass. The auto-tag bullet below is the single source of truth for risky-requirement tagging.
+   - **`### Review: skip | parallel | inline`** — `skip` = no per-requirement review (default — the feature-level review covers it); `parallel` = four reviewers via delegated parallel roles; `inline` = one `pwk-code-review` pass. The auto-tag bullet below is the single source of truth for risky-requirement tagging.
    - **`### Feature review: parallel | inline`** — one review over the **whole feature diff**, always present (the single thorough pass). `parallel` (default — thoroughness lives here, since it is the only review in the common case); `inline` for small features.
    - Tag every requirement — missing tags default to `none` / `skip`. **`spec` requires at least `inline` review** — dropping the complete checkpoint is only safe when review covers implementation quality; never combine `spec` with `Review: skip` (use `Checkpoints: none` instead).
    - **Production-risk notes** — carry forward the design's `## Production-risk areas`, if any.