@tianhai/pi-workflow-kit 1.5.0 → 1.6.1

package/README.md

@@ -20,6 +20,8 @@ For Pi delegation providers that discover project agents, install the canonical
 
 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.
 
+Optionally set a fast-tier model for the smell/hazard reviewers (they carry `thinking: low` and a turn budget by default): `/pwk-setup --fast-model <model>` — or pick one interactively when setup offers — and `--all-roles` to apply it to all four reviewers. The hint is advisory; hosts that cannot honor it keep the default model. Bare re-runs keep the recorded choice; only `--force` replaces local edits beyond the model line.
+
 **Want to try before committing?**
 
 ```bash
@@ -73,7 +75,7 @@ A **design doc is one PR**; a **requirement is one testable slice within it**. A
 | **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. Delegated review uses four logical roles when a safe provider is available; otherwise it runs inline. |
+| **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 tiered logical roles (smell/hazard on a fast model via `/pwk-setup --fast-model`) over a script-assembled review packet 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**. |

package/agents/pwk-hazard-reviewer.md

@@ -3,17 +3,30 @@ name: pwk-hazard-reviewer
 description: Production-hazard reviewer — audits for unbounded ops, missing indexes, unbounded concurrency, long transactions, injection, silent swallowing loops. Read-only reporter.
 tools: read, grep, find, ls, bash
 systemPromptMode: replace
+# model: <fast-tier> — set yours via /pwk-setup
+thinking: low
+max_turns: 20
 ---
 
-# PWK Hazard Reviewer
+# PWK Reviewer
 
-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.
+You are a read-only code 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 — audit each changed file
+## Reporting contract
+
+Every finding cites evidence as file and line (file:line). For each finding, state the affected location, what you observed, and why it matters. If there are no findings, report `No findings` explicitly — an empty or missing report is not a valid outcome.
+
+## Working from the packet
+
+The task provides a review packet: the diff under review plus the acceptance criteria, feature acceptance, production-risk notes, and a list of changed files. Work from the packet. Targeted reads of the files it lists are expected — read around the hunks you are judging. Reads beyond the packet are allowed only to verify a specific suspected finding; cite what sent you there. Do not re-derive scope: no re-running git log, no repo-wide sweeps. Your turn budget is a backstop, not a target. If you wrap up before completing your checklist — turn limit reached or otherwise — state explicitly what was not covered.
+
+## Your checklist
+
+### Production hazards — audit each changed file
 
 For each item below, write `[SAFE]` (1-line justification) or `[TRIGGERED]` (concrete mitigation):
 

package/agents/pwk-smell-reviewer.md

@@ -3,21 +3,32 @@ name: pwk-smell-reviewer
 description: Code-smell reviewer — flags shallow modules, duplication, missing seams, premature abstraction, poor naming, magic values, dead code. Read-only reporter.
 tools: read, grep, find, ls, bash
 systemPromptMode: replace
+# model: <fast-tier> — set yours via /pwk-setup
+thinking: low
+max_turns: 20
 ---
 
-# PWK Smell Reviewer
+# PWK Reviewer
 
-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.
+You are a read-only code 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.
 
-## Review scope
+## Reporting contract
 
-Review the changed code and affected files against the assigned requirement and feature scope.
+Every finding cites evidence as file and line (file:line). For each finding, state the affected location, what you observed, and why it matters. If there are no findings, report `No findings` explicitly — an empty or missing report is not a valid outcome.
 
-## Checklist — report what you find
+## Working from the packet
+
+The task provides a review packet: the diff under review plus the acceptance criteria, feature acceptance, production-risk notes, and a list of changed files. Work from the packet. Targeted reads of the files it lists are expected — read around the hunks you are judging. Reads beyond the packet are allowed only to verify a specific suspected finding; cite what sent you there. Do not re-derive scope: no re-running git log, no repo-wide sweeps. Your turn budget is a backstop, not a target. If you wrap up before completing your checklist — turn limit reached or otherwise — state explicitly what was not covered.
+
+## Your checklist
+
+### Code smells
+
+Review the changed code and affected files against the assigned requirement and feature scope. Flag only smells that require large refactors risky to the requirement; everything else is for the main agent to fix.
 
 - Shallow modules (interface nearly as complex as implementation)
 - Duplication

package/agents/pwk-spec-reviewer.md

@@ -3,16 +3,27 @@ name: pwk-spec-reviewer
 description: Spec-alignment reviewer — checks each acceptance criterion has covering code and tests; flags gaps and scope creep. Read-only reporter.
 tools: read, grep, find, ls, bash
 systemPromptMode: replace
+max_turns: 40
 ---
 
-# PWK Spec Reviewer
+# PWK Reviewer
 
-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.**
+You are a read-only code 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
+## Reporting contract
 
-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.
+Every finding cites evidence as file and line (file:line). For each finding, state the affected location, what you observed, and why it matters. If there are no findings, report `No findings` explicitly — an empty or missing report is not a valid outcome.
+
+## Working from the packet
+
+The task provides a review packet: the diff under review plus the acceptance criteria, feature acceptance, production-risk notes, and a list of changed files. Work from the packet. Targeted reads of the files it lists are expected — read around the hunks you are judging. Reads beyond the packet are allowed only to verify a specific suspected finding; cite what sent you there. Do not re-derive scope: no re-running git log, no repo-wide sweeps. Your turn budget is a backstop, not a target. If you wrap up before completing your checklist — turn limit reached or otherwise — state explicitly what was not covered.
+
+## Your checklist
+
+### Spec alignment
+
+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.

package/agents/pwk-tracing-reviewer.md

@@ -3,16 +3,27 @@ name: pwk-tracing-reviewer
 description: Code-tracing reviewer — traces new/changed paths end-to-end against tests; flags untested branches, dead branches, and broken traces. Read-only reporter.
 tools: read, grep, find, ls, bash
 systemPromptMode: replace
+max_turns: 40
 ---
 
-# PWK Trace Reviewer
+# PWK Reviewer
 
-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.**
+You are a read-only code 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
+## Reporting contract
 
-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.
+Every finding cites evidence as file and line (file:line). For each finding, state the affected location, what you observed, and why it matters. If there are no findings, report `No findings` explicitly — an empty or missing report is not a valid outcome.
+
+## Working from the packet
+
+The task provides a review packet: the diff under review plus the acceptance criteria, feature acceptance, production-risk notes, and a list of changed files. Work from the packet. Targeted reads of the files it lists are expected — read around the hunks you are judging. Reads beyond the packet are allowed only to verify a specific suspected finding; cite what sent you there. Do not re-derive scope: no re-running git log, no repo-wide sweeps. Your turn budget is a backstop, not a target. If you wrap up before completing your checklist — turn limit reached or otherwise — state explicitly what was not covered.
+
+## Your checklist
+
+### Code tracing
+
+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.

package/docs/developer-usage-guide.md

@@ -76,9 +76,9 @@ Implement via the **feature-gate flow** with full autonomy: write the feature-ac
 
 ### 4. Code review (feature level)
 
-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.
+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 scope is a script-assembled review packet (diff + acceptance criteria verbatim) handed to every role via a one-liner pointer — the packet never rides in spawn arguments. 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.
 
-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.
+In Pi, `/pwk-setup` installs the canonical role definitions into `.agents/agents/`, where compatible providers such as `@tintinweb/pi-subagents` can discover them. `/pwk-setup --fast-model <model>` (or the interactive picker) sets the fast-tier model for the smell/hazard reviewers — an advisory hint hosts may honor. 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.
 
 *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.
 

package/docs/oversight-model.md

@@ -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.
 
-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.
+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 a one-liner pointer to a script-assembled review packet — the packet defines the scope per review level (feature review: the whole feature diff; per-requirement: just that slice).
 
 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

@@ -27,6 +27,14 @@ A provider advertises capabilities independently from its name:
 
 A provider must not claim `read-only-enforcement` when it only adds a prompt instruction. Providers may support `codebase-recon` without supporting `parallel-review`.
 
+## Role resource hints
+
+Role definition frontmatter may declare optional resource hints: `model` (a host-resolvable model name), `thinking` (a reasoning-effort level), and `max_turns` (a turn budget — the per-role instance of `bounded-execution`). Hints are advisory:
+
+- Hosts that support per-role resources SHOULD honor them; hosts that do not ignore them without failing the operation.
+- If a `model` hint cannot be resolved to an available model, the host runs the role on its default model — an unresolvable hint MUST NOT fail the review.
+- `max_turns` is a graceful backstop: the role wraps up and reports rather than running unbounded. A capped role still follows the normalized outcome rules — a non-empty report is required for completion.
+
 ## 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.

package/docs/workflow-phases.md

@@ -56,7 +56,7 @@ The **feature-gate flow** is the default: write the feature E2E first, implement
 
 - **Checkpoints** — `none` (no per-requirement stop, **default**) | `full` (both stops) | `spec` (tests stop only — cheap spec-correctness gate, implementation covered by review). Test-first is preserved either way: even `none` writes a meaningful test first (red) and implements to green; only the human *stops* are optional. `spec` requires at least `inline` review (never combine with `skip`).
 - **Review** — `skip` (no per-requirement review, **default**) | `parallel` (four fresh-context reviewers) | `inline` (single `pwk-code-review` pass).
-- **Feature review** — `parallel` (four reviewers over the whole feature diff, **default**) | `inline` (one pass, small features). Always on.
+- **Feature review** — `parallel` (four reviewers over the whole feature diff, **default**) | `inline` (one pass, small features). Always on. The review scope is a script-assembled review packet (diff + criteria verbatim), so reviewers never re-derive scope; smell/hazard reviewers run on the fast tier set via `/pwk-setup --fast-model` (advisory hint).
 
 Flag a requirement for a checkpoint when it has complex logic or is the main part of the feature; for a review when it touches production-risk. A trivial fix can also skip the multi-turn brainstorm dialogue via the brainstorming trivial fast-path (compress to one turn, minimal design doc) — the guard still enforces read-only.
 

package/extensions/workflow-guard.ts

@@ -70,17 +70,91 @@ export const ROLE_NAMES = [
   "pwk-hazard-reviewer",
 ] as const;
 
+const REVIEWER_ROLES = ROLE_NAMES.filter((role) => role !== "pwk-recon-scout");
+const FAST_TIER_ROLES = ["pwk-smell-reviewer", "pwk-hazard-reviewer"];
+
+const FAST_MODEL_PLACEHOLDER = "# model: <fast-tier> — set yours via /pwk-setup";
+
+/** Split a role file into its frontmatter block (with fences) and body. */
+function splitFrontmatter(content: string): { frontmatter: string; rest: string } {
+  const match = content.match(/^(---\n[\s\S]*?\n---\n)([\s\S]*)$/);
+  return match ? { frontmatter: match[1], rest: match[2] } : { frontmatter: "", rest: content };
+}
+
+/** A model hint is a `model:` key line — one definition shared by every consumer
+ * (apply, detect, conflict-compare) so the three can never drift apart. Scoped to
+ * frontmatter: a body line that happens to start `model: ` is content, not config. */
+const MODEL_HINT_LINE = /^model: /m;
+
+/** Apply a fast-tier model hint to a role definition.
+ *
+ * Replaces an existing `model:` line; else swaps the commented placeholder for
+ * `model: <model>`; else inserts after `systemPromptMode:` when `insertIfAbsent`
+ * (the all-four path for judgment roles, which ship no placeholder). Pure: same
+ * input always yields the same output, so install comparisons stay byte-exact.
+ */
+export function applyFastModelHint(content: string, model: string, opts?: { insertIfAbsent?: boolean }): string {
+  const trimmed = model.trim();
+  if (!trimmed || /\s/.test(trimmed)) throw new Error(`Invalid fast model name: ${JSON.stringify(model)}`);
+  const { frontmatter, rest } = splitFrontmatter(content);
+  if (!frontmatter) return content;
+  const hintedFrontmatter = MODEL_HINT_LINE.test(frontmatter)
+    ? frontmatter.replace(/^model: .*$/m, `model: ${trimmed}`)
+    : frontmatter.includes(FAST_MODEL_PLACEHOLDER)
+      ? frontmatter.replace(FAST_MODEL_PLACEHOLDER, `model: ${trimmed}`)
+      : opts?.insertIfAbsent
+        ? frontmatter.replace("systemPromptMode: replace\n", `systemPromptMode: replace\nmodel: ${trimmed}\n`)
+        : frontmatter;
+  return hintedFrontmatter + rest;
+}
+
+/** True when the only difference between two contents is the model hint line
+ * (an uncommented `model:` line or the commented placeholder). Such deltas are
+ * kit-managed config and auto-update without --force; anything else conflicts.
+ */
+function differsOnlyByHint(a: string, b: string): boolean {
+  const strip = (content: string) => {
+    const { frontmatter, rest } = splitFrontmatter(content);
+    const stripped = frontmatter
+      .split("\n")
+      .filter((line) => !MODEL_HINT_LINE.test(line) && line !== FAST_MODEL_PLACEHOLDER)
+      .join("\n");
+    return stripped + rest;
+  };
+  return strip(a) === strip(b);
+}
+
 const CANONICAL_AGENTS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "agents");
 
 function setupUsageError(): Error {
-  return new Error("Usage: /pwk-setup [--force]");
+  return new Error("Usage: /pwk-setup [--force] [--fast-model <model>] [--all-roles]");
 }
 
-function parseSetupArgs(args: string): { force: boolean } {
-  const normalized = args.trim();
-  if (!normalized) return { force: false };
-  if (normalized === "--force") return { force: true };
-  throw setupUsageError();
+function parseSetupArgs(args: string): { force: boolean; fastModel?: string; allRoles: boolean } {
+  const tokens = args.trim().split(/\s+/).filter(Boolean);
+  let force = false;
+  let allRoles = false;
+  let fastModel: string | undefined;
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = tokens[i];
+    if (token === "--force") {
+      force = true;
+    } else if (token === "--all-roles") {
+      allRoles = true;
+    } else if (token.startsWith("--fast-model=")) {
+      fastModel = token.slice("--fast-model=".length);
+    } else if (token === "--fast-model") {
+      const next = tokens[i + 1];
+      if (next === undefined || next.startsWith("--")) throw setupUsageError();
+      fastModel = next;
+      i += 1;
+    } else {
+      throw setupUsageError();
+    }
+  }
+  if (fastModel !== undefined && !fastModel.trim()) throw setupUsageError();
+  if (allRoles && fastModel === undefined) throw setupUsageError(); // --all-roles pairs with --fast-model
+  return { force, fastModel, allRoles };
 }
 
 function ensureDirectory(path: string): void {
@@ -134,7 +208,10 @@ function writeNewFile(path: string, content: string): void {
   }
 }
 
-function installRoleFiles(cwd: string, force: boolean): { installed: string[]; skipped: string[] } {
+function installRoleFiles(
+  cwd: string,
+  opts: { force: boolean; hint?: { model: string; allRoles: boolean } },
+): { installed: string[]; skipped: string[] } {
   const projectAgentsDir = join(cwd, ".agents");
   const targetDir = join(projectAgentsDir, "agents");
   ensureDirectory(projectAgentsDir);
@@ -152,7 +229,11 @@ function installRoleFiles(cwd: string, force: boolean): { installed: string[]; s
     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");
+      const canonical = readFileSync(sourcePath, "utf8");
+      const hintApplies =
+        opts.hint !== undefined && (opts.hint.allRoles ? REVIEWER_ROLES : FAST_TIER_ROLES).includes(roleName);
+      const content =
+        hintApplies && opts.hint ? applyFastModelHint(canonical, opts.hint.model, { insertIfAbsent: true }) : canonical;
 
       // 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
@@ -186,7 +267,14 @@ function installRoleFiles(cwd: string, force: boolean): { installed: string[]; s
           skipped.push(roleName);
           continue;
         }
-        if (!force) {
+        if (opts.hint !== undefined && differsOnlyByHint(existing, content)) {
+          // Kit-managed only while a hint choice is active this run: bare runs treat
+          // any delta (including hand-added model lines) as content — conflict rules.
+          overwriteFd(fd, content, targetPath);
+          installed.push(roleName);
+          continue;
+        }
+        if (!opts.force) {
           failures.push(`${targetPath}: conflict (use /pwk-setup --force to replace it)`);
           continue;
         }
@@ -211,6 +299,57 @@ function installRoleFiles(cwd: string, force: boolean): { installed: string[]; s
   return { installed, skipped };
 }
 
+/** Minimal structural view of the command context the fast-model prompt needs. */
+interface FastModelPromptContext {
+  cwd: string;
+  hasUI?: boolean;
+  scopedModels?: { model?: string }[];
+  ui?: {
+    select?: (title: string, options: { value: string; label: string; description: string }[]) => Promise<string>;
+    confirm?: (title: string, message: string) => Promise<boolean>;
+  };
+}
+
+/** True when an installed fast-tier role already carries a model hint. */
+function installedHint(cwd: string): { model: string; allRoles: boolean } | undefined {
+  const frontmatterOf = (role: string): string => {
+    try {
+      return splitFrontmatter(readFileSync(join(cwd, ".agents", "agents", `${role}.md`), "utf8")).frontmatter;
+    } catch {
+      return "";
+    }
+  };
+  const modelOf = (frontmatter: string): string | undefined =>
+    frontmatter.match(/^model: (\S.*)$/m)?.[1]?.trim() || undefined;
+  const model = FAST_TIER_ROLES.map(frontmatterOf).map(modelOf).find(Boolean);
+  if (!model) return undefined;
+  const allRoles = REVIEWER_ROLES.some((role) => modelOf(frontmatterOf(role)) !== undefined);
+  return { model, allRoles };
+}
+
+/** Ask for the fast-tier model once, only when a picker is available, no hint is
+ * installed, and no --fast-model argument was given. Headless hosts skip silently
+ * and reviewers stay on default models. */
+async function promptFastModelChoice(
+  ctx: FastModelPromptContext,
+): Promise<{ model: string; allRoles: boolean } | undefined> {
+  const ui = ctx.ui;
+  if (typeof ui?.select !== "function" || ctx.hasUI === false) return undefined;
+  if (installedHint(ctx.cwd) !== undefined) return undefined;
+  const scoped = Array.isArray(ctx.scopedModels) ? ctx.scopedModels : [];
+  const models = scoped
+    .map((entry) => (typeof entry?.model === "string" ? entry.model : undefined))
+    .filter((model): model is string => model !== undefined && model.length > 0);
+  const options = [
+    ...models.map((model) => ({ value: model, label: model, description: "fast-tier reviewer model" })),
+    { value: "skip", label: "skip", description: "reviewers run on default models" },
+  ];
+  const choice = await ui.select("Fast-tier model for smell/hazard reviewers", options);
+  if (!choice || choice === "skip") return undefined;
+  const allRoles = (await ui.confirm?.("Apply to all four reviewers?", "No = smell+hazard only")) ?? false;
+  return { model: choice, allRoles };
+}
+
 // Destructive commands blocked in brainstorm/plan phases (simple common blacklist)
 const DESTRUCTIVE_PATTERNS = [
   /\brm\b/i,
@@ -416,12 +555,23 @@ export default function (pi: ExtensionAPI) {
         throw new Error(message);
       }
 
-      const { force } = parseSetupArgs(args ?? "");
+      const { force, fastModel, allRoles } = parseSetupArgs(args ?? "");
       try {
-        const result = installRoleFiles(ctx.cwd, force);
+        // Explicit arg wins; else the picker (only while no hint is installed);
+        // else re-apply the installed hint — the recorded choice — so bare runs
+        // are no-ops rather than stripping or conflicting on kit-managed lines.
+        const hint =
+          fastModel !== undefined
+            ? { model: fastModel, allRoles }
+            : ((await promptFastModelChoice(ctx)) ?? installedHint(ctx.cwd));
+        const result = installRoleFiles(ctx.cwd, { force, hint });
         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");
+        if (hint) {
+          const scope = hint.allRoles ? "all four reviewers" : "smell+hazard reviewers";
+          parts.push(`fast model ${hint.model} (${scope})`);
+        }
         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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",

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

@@ -68,7 +68,7 @@ Set `Feature phase: implementing (0/N)` and work the requirements in listed orde
 
 ### Per-requirement review (opt-in)
 
-If the requirement's `### Review` tag is `parallel` or `inline` (default `skip`), review that slice now — same mechanics as the [feature review](#feature-review), scoped to the requirement's diff. With `skip`, no per-requirement review; the feature-level review covers it.
+If the requirement's `### Review` tag is `parallel` or `inline` (default `skip`), review that slice now — same mechanics as the [feature review](#feature-review), with a requirement-scoped packet: the same recipe limited to the commits and criteria sections of that requirement, written to `docs/plans/<dated-stem>-review-packet-r<N>.md` (requirement-suffixed, so per-requirement packets never overwrite the feature packet or each other). With `skip`, no per-requirement review; the feature-level review covers it.
 
 `Checkpoints: 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).
 
@@ -93,7 +93,34 @@ 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) — 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.
+**Assemble the review packet first** — once, by script, so that no packet byte passes through model output (spawn arguments are model output; file reads are not). If commits land while the review is in flight, re-run the recipe before spawning any replacement role so the packet matches HEAD:
+
+```bash
+PACKET="docs/plans/<dated-stem>-review-packet.md"   # same dated stem as the plan docs
+{
+  echo "# Review packet: <topic> — feature review"
+  echo
+  echo "## Commits"
+  git log --oneline <merge-base>..HEAD
+  echo
+  echo "## Changed files"
+  git diff --stat <merge-base>...HEAD
+  echo
+  echo "## Acceptance criteria (verbatim from the plan)"
+  sed -n '/^## Requirement 1/,/^## Feature acceptance/p' docs/plans/<dated-stem>-implementation.md | sed '/^## Feature acceptance/,$d'
+  echo
+  echo "## Feature acceptance (verbatim)"
+  sed -n '/^## Feature acceptance/,/^### Feature review/p' docs/plans/<dated-stem>-implementation.md | sed '/^### Feature review/,$d'
+  echo
+  echo "## Production-risk notes (verbatim, if any)"
+  sed -n '/^### Production-risk notes/,/^## /p' docs/plans/<dated-stem>-implementation.md | sed '/^## /d'
+  echo
+  echo "## Diff"
+  git diff <merge-base>...HEAD
+} > "$PACKET"
+```
+
+- **`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`. Spawn each role with a **one-liner** — a pointer to the packet file with the role framing appended last: the checklist name of the role (`spec alignment`, `code tracing`, `code smells`, or `production hazards`). For example: `Read docs/plans/<dated-stem>-review-packet.md. Your role: spec alignment.` The packet never appears in spawn arguments. 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.

package/skills/pwk-finalizing/SKILL.md

@@ -27,7 +27,7 @@ Ship the completed work.
 
      ```bash
      # for each <topic> in the set:
-     rm -f docs/plans/????-??-??-<topic>-design.md docs/plans/????-??-??-<topic>-implementation.md docs/plans/????-??-??-<topic>-progress.md
+     rm -f docs/plans/????-??-??-<topic>-design.md docs/plans/????-??-??-<topic>-implementation.md docs/plans/????-??-??-<topic>-progress.md docs/plans/????-??-??-<topic>-review-packet*.md
      # umbrella only:
      rm -f docs/plans/????-??-??-<umbrella>-overview.md
      git add -A docs/plans/ && git commit -m "chore: delete planning docs for <topic-or-umbrella>"
@@ -41,6 +41,7 @@ Ship the completed work.
      mv docs/plans/????-??-??-<topic>-design.md          docs/plans/completed/ 2>/dev/null || true
      mv docs/plans/????-??-??-<topic>-implementation.md  docs/plans/completed/ 2>/dev/null || true
      mv docs/plans/????-??-??-<topic>-progress.md        docs/plans/completed/ 2>/dev/null || true
+     mv docs/plans/????-??-??-<topic>-review-packet*.md   docs/plans/completed/ 2>/dev/null || true
      # umbrella only:
      mv docs/plans/????-??-??-<umbrella>-overview.md     docs/plans/completed/ 2>/dev/null || true
      git add docs/plans/ && git commit -m "chore: archive planning docs for <topic-or-umbrella>"