@fyeeme/pi-dynamic-workflows 0.1.1 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyeeme/pi-dynamic-workflows",
-  "version": "0.1.1",
+  "version": "2.0.1",
   "description": "Deterministic TypeScript workflow orchestration for pi. Fuses the pi-dynamic-workflows design (declarative graph, 10 step primitives, heuristic planner, outcome collectors) with Claude Code's workflow engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort map, dynamic budget, runaway caps).",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,9 @@
     "*.ts",
     "src/**/*.ts",
     "sessions/**/*.ts",
+    "workflows/**/*.ts",
+    "skills/**/*.md",
+    "prompts/**/*.md",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"
@@ -29,6 +32,12 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "skills/workflow-author"
+    ],
+    "prompts": [
+      "prompts"
     ]
   },
   "scripts": {
@@ -36,20 +45,20 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@fyeeme/pi-subagent-core": "^0.3.2"
+    "@fyeeme/pi-subagents": "2.1.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.84.1",
-    "@earendil-works/pi-coding-agent": ">=0.84.1",
-    "@earendil-works/pi-tui": ">=0.84.1",
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
+    "@earendil-works/pi-tui": ">=0.84.4",
     "jiti": ">=2.0.0",
     "typebox": ">=1.0.0",
     "typescript": ">=5.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.1",
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "@earendil-works/pi-tui": "0.84.1",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
     "@types/node": "22.19.19",
     "jiti": "2.7.0",
     "typebox": "1.1.38",

package/prompts/implement-and-review.md

@@ -0,0 +1,29 @@
+---
+description: Implement → review → fix loop via successive subagent calls
+argument-hint: <what to implement>
+---
+Execute this three-stage loop with the `subagent` tool — one call per stage.
+You are the coordinator: pass each stage's complete output text into the next
+stage's `task` yourself (chain mode no longer exists).
+
+1. **Implement** — call `subagent` with agent `worker`, task: $@ plus any repo
+   context it needs. Ask for the final implementation summary in the result.
+
+2. **Review** — call `subagent` with agent `reviewer`. Its task must begin:
+   "Review the following implementation." followed by the worker's COMPLETE
+   result verbatim, plus the files/areas touched.
+
+3. **Fix** — if and only if the reviewer reported issues, one more `worker`
+   call: "Apply this feedback to your earlier implementation." followed by the
+   reviewer's findings verbatim.
+
+Rules:
+
+- Forward results between stages verbatim — never paraphrase or summarize;
+  each subagent has zero memory of its predecessor.
+- Run stages strictly sequentially; a later stage always needs the earlier
+  stage's full output as input.
+- Skip stages 2–3 only for trivial changes (< ~20 lines, no behavior change);
+  state explicitly that you did so and why.
+- Finish by reporting: what was implemented, the review verdict, and anything
+  still open.

package/prompts/wf-review.md

@@ -0,0 +1,30 @@
+---
+description: Heavy review pipeline via deterministic workflow (budget + resume + adversarial verify)
+---
+Run the heavy review pipeline now. Target: $@
+
+First resolve the diff yourself (run `git diff` against the appropriate
+range — upstream merge-base if configured, else HEAD; pass the diff text as
+the workflow `input`).
+
+Then call `run_workflow` with `source: "library"`:
+
+- For a plain local diff → name `review-local-diff` (5 finders at
+  parallelism 4, adversarial verify judges 3 / minPass 2, budget 12 agents /
+  2M tokens).
+- For changed packages under an extensions submodule → name
+  `review-extension` (one reviewer per changed package at parallelism 3).
+
+Budget guidance: pass a per-call `budget` override on the run_workflow call —
+halve `maxAgents` when the diff exceeds ~150 files; without an override the
+workflow's own declared budget applies.
+
+Resume behavior: on journal keys already present from a prior partial run
+the engine skips completed steps — do not re-dispatch them yourself.
+
+When the run completes, report the merged, verified findings via
+`review_report` (if available) or as a markdown list ranked most-severe
+first.
+
+For tuning the pipeline itself (steps, rubric, determinism constraints),
+load the workflow-author skill.

package/sessions/spawn.ts

@@ -3,7 +3,7 @@
  *
  * Thin barrel over src/agent/dispatch.ts: the spawn registry + per-agent
  * abort primitives. The core spawn implementation lives in
- * `@fyeeme/pi-subagent-core`; skip/retry (workflows-specific) stay in
+ * `@fyeeme/pi-subagents`; skip/retry (workflows-specific) stay in
  * dispatch.ts.
  */
 export {

package/skills/workflow-author/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: workflow-author
+description: "Author and tune deterministic workflow definitions for run_workflow: step-type selection, rubric writing, the single-file determinism constraint, budget/parallelism as declared data, and resume semantics."
+---
+
+# Authoring workflow-library definitions
+
+A library workflow is a single `.ts` file under `.pi/workflows/lib/`
+(project) or the package's bundled `workflows/` (reference examples:
+`review-local-diff`, `review-extension`). It exports a workflow and becomes
+runnable by name (`run_workflow` with `source: "library"`) on the next call —
+dropping the file in IS the registration; no code change, no restart.
+
+## The hard constraint: single-file determinism
+
+The loader runs the ast determinism guard on the entry source and REJECTS
+`Date.now()`, `Math.random()`, and `new Date()` **before** executing. This is
+not a style rule — cache-key resume is only sound when the same workflow
+source produces the same cache keys. The guard scans **only the entry file**:
+a helper imported from another file could smuggle in non-determinism and
+silently break resume. Therefore: **library workflows must stay
+single-file.** Inline everything; if you need `now`, the engine passes it
+(the `now` run parameter / `ctx` plumbing) — never read the clock yourself.
+
+## Choosing step types
+
+| Need | Step | Notes |
+|---|---|---|
+| One LLM call | `agent` | prompt may be a function of `ctx.input` / `ctx.step(id)` |
+| N parallel calls over a list | `fan_out` | `over` may be dynamic (`ctx => …`); declare `parallelism`; `merge` folds results |
+| Produce + judge | `adversarial` | rubric criteria become judge prompts; `judges`/`minPass` (majority default) |
+| Best-of-N | `tournament` | candidates × judges |
+| Route by classification | `classify_route` | classifier replies `{category}`; routes + fallback |
+| Iterate to convergence | `loop_until` | `until` condition + `maxIterations` (TS-only — library files only, not inline JSON) |
+| Zero-token narrative | `log` | journal annotation only |
+
+## Writing rubrics (adversarial / tournament)
+
+A rubric entry is a judge prompt, not a checkbox. Write each criterion as a
+falsifiable, self-contained sentence: `"finding is concretely actionable
+(file:line present)"` — not `"quality"`. 2–4 criteria; a judge that cannot
+verify a criterion from the material in front of it will guess, and guessing
+flattens the verdict distribution.
+
+## Budget and parallelism are data
+
+`budget: { maxAgents, maxTokens, maxDurationMs }` at the workflow level and
+`parallelism` on fan-out steps are declared fields the engine enforces
+(fan-out pre-checks the batch fits; a step exceeding budget follows its
+`onBudgetExhaust` policy — throw, or degrade to null). Tune them by editing
+the file; orchestration prompts may also pass tighter values per call.
+
+## Resume semantics
+
+Every dispatched call is cache-keyed (workflow source + prompts + inputs).
+Re-running with unchanged definition and inputs skips completed steps from
+the journal — do not "help" by re-dispatching; change an input only when you
+want a step actually re-run. Editing the workflow source changes the keys:
+that is the intended way to invalidate stale cache.
+
+## Checklist before shipping a library workflow
+
+1. Single file, and imports type-only: `import type { WorkflowDefinition } from ...` (erased at load — nothing outside the file executes, so the entry-only guard scan covers everything). NEVER value-import the engine by relative path: from `.pi/workflows/lib/` it does not resolve (bricking the whole library), and any value import puts un-scanned code on the load path. Plain `export const workflow = { name, steps }` with no import at all works too (the loader validates shape, not `defineWorkflow`).
+2. No `Date.now` / `Math.random` / `new Date` anywhere in the source.
+3. `name` is unique and descriptive (it is the invocation key); `description`
+   one line — it appears in the unknown-name listing.
+4. Budget and parallelism declared, sized to the worst expected input.
+5. Verified locally: `run_workflow` with `source: "library"`, then re-run to
+   see journal hits skip completed steps.

package/src/agent/dispatch.ts

@@ -3,7 +3,7 @@
  *
  * The core spawn primitive (`spawnAgent`, `mapWithConcurrencyLimit`,
  * `createSpawnRegistry`, `abortAgent`, `getPiInvocation` + the registry/
- * options/result types) lives in the shared `@fyeeme/pi-subagent-core`
+ * options/result types) lives in the shared `@fyeeme/pi-subagents`
  * package — extracted from the duplicate copies that used to live here and
  * in pi-review. This module keeps the workflows-specific layer on top:
  * `skipAgent`/`retryAgent` (with `AbortReason` semantics) and the lifecycle
@@ -19,7 +19,7 @@
  */
 import type { AgentLifecycleListeners } from "../lifecycle.ts";
 import { notifyRetry, notifySkip } from "../lifecycle.ts";
-import type { AgentSpawnRegistry } from "@fyeeme/pi-subagent-core";
+import type { AgentSpawnRegistry } from "@fyeeme/pi-subagents";
 
 // Re-export the core dispatch surface so existing importers of this module
 // (`../agent/dispatch.ts`) keep working unchanged.
@@ -29,7 +29,7 @@ export {
 	getPiInvocation,
 	mapWithConcurrencyLimit,
 	spawnAgent,
-} from "@fyeeme/pi-subagent-core";
+} from "@fyeeme/pi-subagents";
 export type {
 	AgentAbortMap,
 	AgentCallId,
@@ -37,7 +37,7 @@ export type {
 	AgentSpawnRegistry,
 	AgentSpawnResult,
 	AgentUsage,
-} from "@fyeeme/pi-subagent-core";
+} from "@fyeeme/pi-subagents";
 
 export type AbortReason = "user-skip" | "user-retry";
 

package/src/format.ts

@@ -1,22 +1,13 @@
 /**
- * src/format.ts — shared display/parsing helpers (progress widget + /wf-inspect + runner).
+ * src/format.ts — shared parsing helper used by the runner.
  *
- * fmtTokens + ANSI color helpers: used by `buildProgressWidget` (index.ts) and
- * `WorkflowInspect` (src/inspect.ts) — one copy so the two UIs cannot drift.
  * stepIdOf: callId → step-id attribution, used by the runner (degraded-step
- * accounting) and the widget (grouping by step). Extracted from the verbatim
- * duplicates that used to live in each file.
+ * accounting, sibling abort scoping) and by the engine's dispatchOpts (the
+ * monitor `displayName` for the shared sub-agent UI). The former ANSI color
+ * helpers + fmtTokens were progress-widget/`/wf-inspect` rendering aids and
+ * were removed together with those surfaces (live progress is now rendered by
+ * the shared @fyeeme/pi-subagents extension).
  */
-export const GREEN = (s: string): string => `\x1b[32m${s}\x1b[0m`;
-export const RED = (s: string): string => `\x1b[31m${s}\x1b[0m`;
-export const YELLOW = (s: string): string => `\x1b[33m${s}\x1b[0m`;
-export const DIM = (s: string): string => `\x1b[2m${s}\x1b[0m`;
-export const CYAN = (s: string): string => `\x1b[36m${s}\x1b[0m`;
-export const BOLD = (s: string): string => `\x1b[1m${s}\x1b[0m`;
-
-export function fmtTokens(n: number): string {
-	return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
-}
 
 /** Extract the step id from a callId of the form `${stepId}#${n}` (e.g.
  *  "fan#2", "adv#produce", "cr#classify"). Falls back to the whole callId when

package/src/library.ts

@@ -0,0 +1,143 @@
+/**
+ * src/library.ts — named workflow library: the persistence layer for
+ * workflows (PR3 of the sandwich refactor).
+ *
+ * Workflows are single-file `.ts` definitions (full step set including the
+ * TS-only steps like loop_until) discovered from:
+ *
+ *   1. project — nearest `.pi/workflows/lib/` walking up from cwd
+ *   2. bundled — this package's own `workflows/` directory (seed workflows)
+ *
+ * The project entry overrides a bundled entry of the same name. Discovery and
+ * loading go through the existing loader (jiti + the ast determinism guard),
+ * so a library workflow is rejected before execution when its source
+ * smuggles in non-deterministic APIs — the precondition cache-key resume
+ * relies on.
+ *
+ * The library directory is deliberately distinct from the journal output
+ * tree (`.pi/workflows/runs/<runId>/`): definitions and run state never
+ * collide. Adding a workflow = dropping a file; no code change.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadWorkflowModule } from "./loader.ts";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import type { WorkflowDefinition } from "./types.ts";
+
+/** This file lives at <pkg>/src/ → the bundled library is <pkg>/workflows. */
+const PKG_ROOT = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+const BUNDLED_LIB_DIR = path.join(PKG_ROOT, "workflows");
+
+/** Project-level library directory, relative to the project root. */
+const PROJECT_LIB_REL = path.join(CONFIG_DIR_NAME, "workflows", "lib");
+
+/** One library entry, after loading the module. */
+export interface LibraryEntry {
+	readonly name: string;
+	readonly description?: string;
+	readonly filePath: string;
+	readonly workflow: WorkflowDefinition;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Nearest project library dir walking up from cwd (like agent discovery). */
+export function findProjectLibDir(cwd: string): string | null {
+	let dir = path.resolve(cwd);
+	for (;;) {
+		const candidate = path.join(dir, PROJECT_LIB_REL);
+		if (isDirectory(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** Library directories in priority order (later wins on name collision). */
+function libDirs(cwd: string): string[] {
+	const dirs = [BUNDLED_LIB_DIR];
+	const project = findProjectLibDir(cwd);
+	if (project) dirs.push(project);
+	return dirs;
+}
+
+function isValidWorkflow(value: unknown): value is WorkflowDefinition {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		typeof (value as WorkflowDefinition).name === "string" &&
+		Array.isArray((value as WorkflowDefinition).steps)
+	);
+}
+
+/** Load one workflow file: ast-guard + jiti import + shape validation. */
+async function loadEntry(filePath: string): Promise<LibraryEntry | null> {
+	try {
+		const mod = (await loadWorkflowModule({ filePath })) as {
+			workflow?: unknown;
+			default?: unknown;
+		};
+		const wf = mod.workflow ?? mod.default;
+		if (!isValidWorkflow(wf)) return null;
+		return {
+			name: wf.name,
+			description: wf.description,
+			filePath,
+			workflow: wf,
+		};
+	} catch (err) {
+		// Fail-fast, deliberately: a library file that fails the determinism
+		// guard or errors at import must NOT silently disappear from the
+		// available list (a poisoned entry re-appearing would break cache-key
+		// resume). The error names the offending file; remove or fix the file
+		// to restore discovery. Shape-invalid files (below) are the exception
+		// — they are skipped silently as non-workflows.
+		throw new Error(`library workflow ${path.basename(filePath)} failed to load: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+
+/**
+ * Discover the library: load every `.ts` workflow in the library dirs and
+ * index by workflow name (later dirs override earlier same-name entries).
+ * A file whose module import or the determinism guard check FAILS aborts the
+ * whole discovery with an error naming the file (fail-fast — see loadEntry);
+ * a file that imports cleanly but is not a valid workflow shape is skipped
+ * silently.
+ */
+export async function discoverWorkflowLibrary(cwd: string): Promise<Map<string, LibraryEntry>> {
+	const byName = new Map<string, LibraryEntry>();
+	for (const dir of libDirs(cwd)) {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue; // unreadable/missing dir — skip
+		}
+		for (const entry of entries) {
+			if (!entry.name.endsWith(".ts") || entry.name.startsWith(".")) continue;
+			if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+			const loaded = await loadEntry(path.join(dir, entry.name));
+			if (loaded) byName.set(loaded.name, loaded);
+		}
+	}
+	return byName;
+}
+
+/** Resolve one workflow by name, or null when not in the library. */
+export async function loadLibraryWorkflow(
+	name: string,
+	cwd: string,
+): Promise<LibraryEntry | null> {
+	// Fast path: only load the files that could define the name. Files export
+	// the workflow's name, so discovery is required either way — but skipping
+	// the project/bundled distinction keeps override semantics identical.
+	const lib = await discoverWorkflowLibrary(cwd);
+	return lib.get(name) ?? null;
+}

package/src/runner/index.ts

@@ -14,6 +14,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
 import { BudgetPool } from "../budget/index.ts";
 import { Journal, type RunManifest } from "../cache/index.ts";
 import type { AgentLifecycleListeners } from "../lifecycle.ts";
@@ -81,7 +82,7 @@ export async function runWorkflow(opts: RunWorkflowOptions): Promise<RunResult>
 	const budget = opts.budget ?? workflow.budget ?? {};
 	const journalDir =
 		opts.journalDir ??
-		path.join(cwd, ".pi", "workflows", sanitizeWorkflowName(workflow.name));
+		path.join(cwd, CONFIG_DIR_NAME, "workflows", sanitizeWorkflowName(workflow.name));
 
 	await fs.promises.mkdir(journalDir, { recursive: true });
 	const journal = new Journal({ dir: journalDir });

package/src/runner/stage-executor.ts

@@ -985,6 +985,11 @@ function dispatchOpts(
 		systemPrompt: spec.systemPrompt,
 		signal,
 		allowChildRecursion,
+		// UI display name for the shared sub-agent widget/FleetView (purely
+		// observational metadata consumed by the pi-subagents monitor): the
+		// step id ("fan", "adv"), so workflow rows are distinguishable from other
+		// agents. Cache hits never spawn, so they never appear — zero dispatch.
+		displayName: stepIdOf(callId),
 		// C3: bridge the spawn's streamed deltas to the lifecycle onUpdate listener,
 		// attributed to this callId. When no listener is registered, the subprocess
 		// drops the deltas (its onUpdate stays undefined — same as before).
@@ -1013,6 +1018,12 @@ function usageStats(res: AgentSpawnResult, durationMs: number, ok: boolean): Ste
 		durationMs,
 		agents: 1,
 		failures: ok ? 0 : 1,
+		usage: {
+			input: res.usage.input,
+			output: res.usage.output,
+			cacheRead: res.usage.cacheRead,
+			cacheWrite: res.usage.cacheWrite,
+		},
 	};
 }
 
@@ -1023,6 +1034,20 @@ function addStats(a: StepStats, b: StepStats): StepStats {
 		durationMs: a.durationMs + b.durationMs,
 		agents: a.agents + b.agents,
 		failures: a.failures + b.failures,
+		usage: mergeUsage(a.usage, b.usage),
+	};
+}
+
+function mergeUsage(
+	a: StepStats["usage"],
+	b: StepStats["usage"],
+): StepStats["usage"] {
+	if (!a && !b) return undefined;
+	return {
+		input: (a?.input ?? 0) + (b?.input ?? 0),
+		output: (a?.output ?? 0) + (b?.output ?? 0),
+		cacheRead: (a?.cacheRead ?? 0) + (b?.cacheRead ?? 0),
+		cacheWrite: (a?.cacheWrite ?? 0) + (b?.cacheWrite ?? 0),
 	};
 }
 
@@ -1033,14 +1058,16 @@ export function aggregateStats(stats: readonly StepStats[], durationMs: number):
 	let agents = 0;
 	let failures = 0;
 	let dur = 0;
+	let usage: StepStats["usage"];
 	for (const s of stats) {
 		tokens += s.tokens;
 		cost += s.cost;
 		agents += s.agents;
 		failures += s.failures;
 		dur += s.durationMs;
+		usage = mergeUsage(usage, s.usage);
 	}
-	return { tokens, cost, durationMs: durationMs > 0 ? durationMs : dur, agents, failures };
+	return { tokens, cost, durationMs: durationMs > 0 ? durationMs : dur, agents, failures, usage };
 }
 
 function withDuration(stats: StepStats, start: number): StepStats {

package/src/types.ts

@@ -55,6 +55,15 @@ export interface StepStats {
 	readonly durationMs: number;
 	readonly agents: number;
 	readonly failures: number;
+	/** Nested-LLM usage split, populated for agent-dispatch steps and surfaced
+	 *  as `usage` on the run_workflow tool result (pi usage accounting). Absent
+	 *  for zero-dispatch steps (code/log) and journals written before this field. */
+	readonly usage?: {
+		readonly input: number;
+		readonly output: number;
+		readonly cacheRead: number;
+		readonly cacheWrite: number;
+	};
 }
 
 export interface StepResult<T = unknown> {
@@ -247,23 +256,11 @@ export interface StepRetry {
 	 * spec revision; add `retryStage` back with implementation when ready. */
 }
 
-/** A phase groups related steps for UI progress-tree rendering.
- *  Steps not assigned to any phase render under an implicit default group. */
-export interface PhaseDefinition {
-	readonly title: string;
-	readonly detail?: string;
-	readonly stepIds: readonly string[];
-	/** Optional model override for all agents in this phase. */
-	readonly model?: string;
-}
-
 export interface WorkflowDefinition {
 	readonly name: string;
 	readonly description?: string;
 	readonly steps: readonly StepDefinition[];
 	readonly budget?: Budget;
-	/** Optional phase groupings for progress-tree UI rendering. */
-	readonly phases?: readonly PhaseDefinition[];
 }
 
 /** Typed identity helper: gives a workflow literal full union checking. */

package/workflows/review-extension.ts

@@ -0,0 +1,51 @@
+/**
+ * Seed library workflow: review-extension — the extensions-submodule review
+ * fan-out distilled from this repository's review-local-extensions-fanout
+ * pipeline: scope the changed packages first, then one reviewer per changed
+ * extension directory (parallelism 3), then merge.
+ *
+ * Input: newline-separated list of changed paths under packages/extensions
+ * (or a single path). Prompts use prompt functions (ctx.input /
+ * ctx.step(id)) — the TS API does not substitute {{...}} tokens.
+ * Runtime-single-file: `import type` is erased at load (see
+ * review-local-diff.ts).
+ */
+import type { WorkflowDefinition } from "../src/index.ts";
+
+export const workflow: WorkflowDefinition = {
+	name: "review-extension",
+	description: "Review each changed extension package: one reviewer per package (parallelism 3), merged findings",
+	budget: { maxAgents: 9, maxTokens: 2_000_000 },
+	steps: [
+		{
+			id: "scope",
+			type: "agent",
+			prompt: (ctx) =>
+				"The input lists changed paths under packages/extensions. Reduce it to the set of " +
+				"distinct top-level extension directories (e.g. \"pi-review\", \"pi-subagents\"). " +
+				"Return ONLY the directory names, one per line, no commentary.\n\n" +
+				String(ctx.input),
+		},
+		{
+			id: "reviewers",
+			type: "fan_out",
+			over: (ctx) =>
+				String(ctx.step("scope").results)
+					.split("\n")
+					.map((l) => l.trim())
+					.filter(Boolean),
+			parallelism: 3,
+			agent: (pkg, _index, ctx) => ({
+				prompt:
+					`Review the uncommitted changes in packages/extensions/${pkg} (run ` +
+					`\`git -C packages/extensions/${pkg} diff\` yourself; read the touched files for ` +
+					`context). Report findings as \`file:line\` — one-line summary — the concrete cost. ` +
+					`Cover correctness, reuse, simplification, efficiency, altitude. Report only.\n\n` +
+					`Changed paths:\n${ctx.input}`,
+			}),
+			merge: (results) => results.join("\n---\n"),
+		},
+	],
+};
+
+export default workflow;

package/workflows/review-local-diff.ts

@@ -0,0 +1,64 @@
+/**
+ * Seed library workflow: review-local-diff — the local-diff review pipeline
+ * actually run in this repository (distilled from the .pi/workflows journals
+ * of review-local-changes / review-local-extensions-fanout runs).
+ *
+ * Input: the unified diff to review (run input). Fan out one finder per
+ * angle (parallelism 4), adversarially verify a merged candidate list, and
+ * return the verified findings. Budget and parallelism are declared here as
+ * data — the engine enforces them.
+ *
+ * Prompts reference run context via prompt FUNCTIONS (ctx.input /
+ * ctx.step(id)) — the {{...}} template tokens are the inline-JSON tool
+ * surface only; the TS API never substitutes them in plain strings.
+ *
+ * Runtime-single-file: `import type` is erased at load, so nothing outside
+ * this file executes and the ast determinism guard's entry-only scan covers
+ * everything that runs (a VALUE import from another file would not be
+ * scanned — keep imports type-only).
+ */
+import type { WorkflowDefinition } from "../src/index.ts";
+
+const ANGLES = ["correctness", "reuse", "simplification", "efficiency", "altitude"] as const;
+
+export const workflow: WorkflowDefinition = {
+	name: "review-local-diff",
+	description: "Fan out diff-scoped finders, adversarially verify the merged candidates, return verified findings",
+	budget: { maxAgents: 12, maxTokens: 2_000_000 },
+	steps: [
+		{
+			id: "finders",
+			type: "fan_out",
+			over: () => [...ANGLES],
+			parallelism: 4,
+			agent: (angle, _index, ctx) => ({
+				prompt:
+					`You are a code-review finder for the "${angle}" angle. Review the diff below. ` +
+					`Report each finding as \`file:line\` — one-line summary — the concrete cost ` +
+					`(for correctness: the input/state that triggers it → wrong output). Report only; ` +
+					`an empty list is a valid answer.\n\nDiff:\n${ctx.input}`,
+			}),
+			merge: (results) => results.join("\n---\n"),
+		},
+		{
+			id: "verify",
+			type: "adversarial",
+			produce: {
+				prompt: (ctx) =>
+					"Dedup and merge these code-review findings into a numbered candidate list " +
+					"(same defect + same location + same reason → keep one; different reasons for " +
+					"the same line are NOT duplicates — keep both). Return only the numbered list.\n\n" +
+					String(ctx.step("finders").results),
+			},
+			rubric: [
+				"finding is concretely actionable (file:line present)",
+				"the failure scenario or cost is stated and realistic",
+				"not a duplicate of another kept finding",
+			],
+			judges: 3,
+			minPass: 2,
+		},
+	],
+};
+
+export default workflow;