pi-workflow-engine 0.2.0 → 0.4.0

package/README.md

@@ -1,10 +1,27 @@
-<p align="center">
-  <img src="assets/preview.png" width="200" alt="pi-workflow-engine — a central agent orchestrating a ring of subagents" />
-</p>
+![agents](assets/preview.png)
 
 # pi-workflow-engine
 
-A customisable multi-agent workflow-orchestration engine for the [pi](https://pi.dev) coding agent — your own version of Claude Code's built-in `/code-review`, built on pi's SDK. Workflows fan out to many subagents, pass validated structured data between stages, and synthesise a result.
+Programmable multi-agent workflows for the [pi](https://pi.dev) coding agent.
+
+This is not just a way to run a prompt. It is a way to turn an agentic procedure into code: scope the task, fork isolated subagents, fan out across review lenses, validate every handoff with schemas, verify candidate findings, and synthesize one ranked result.
+
+The built-in workflows are advisory: they inspect, fan out, verify, and report. They do not edit files. Start with `/workflow code-review`, or use the focused scouts for refactors, diagnosis, and performance.
+
+## Why workflows matter
+
+The best agentic coding work is rarely a single chat turn. It is a repeatable loop of context gathering, delegated investigation, structured handoffs, verification, and synthesis.
+
+`pi-workflow-engine` brings that shape to pi with static TypeScript workflows:
+
+- **Procedures, not prompts**: write the workflow once, then invoke it with `/workflow` or let the host agent call the `workflow` tool.
+- **Isolated subagents**: each `agent()` runs in its own in-memory pi session, so exploratory work does not pollute the main conversation.
+- **Parallel cognition**: run many focused agents at once, with a shared concurrency cap so large workflows stay bounded.
+- **Typed handoffs**: pass structured data between stages using typebox schemas instead of asking the model to emit parseable prose.
+- **Verifier stages**: make verification part of the control flow, not an optional final instruction.
+- **Live progress**: surface phases, agent status, counters, and lane items in the TUI while the run is still moving.
+
+The result is closer to an executable review playbook than a chatbot shortcut.
 
 ## Install
 
@@ -18,118 +35,201 @@ Or from npm:
 pi install npm:pi-workflow-engine
 ```
 
-That's all — pi fetches the package and serves its dependencies from its own bundle, so there's no clone, install, or build step. Restart pi (or run `/reload` in an open session), then confirm it's registered:
+That's all. pi fetches the package and serves its core dependencies from its own bundle, so there is no clone, install, or build step. The package entrypoint is the canonical pi extension module at `.pi/extensions/pi-workflow-engine/index.ts`. Restart pi, or run `/reload` in an open session, then confirm it is registered:
 
 ```bash
 pi list
 ```
 
-Scope it to a single repo instead of globally (writes to that repo's `.pi/settings.json`):
+Scope it to a single repo instead of globally. This writes to that repo's `.pi/settings.json`:
 
 ```bash
 pi install git:github.com/timbrinded/pi-workflow-engine -l
 ```
 
-Uninstall with `pi remove git:github.com/timbrinded/pi-workflow-engine`.
+Uninstall with:
+
+```bash
+pi remove git:github.com/timbrinded/pi-workflow-engine
+```
 
 ## Usage
 
 In a pi session, from inside a git repo with changes:
 
-```
-/workflow code-review            # review the current branch
-/workflow code-review HEAD~3     # review a ref range / target / focus area
-/workflow ping                   # quick engine smoke test (one agent)
+```text
+/workflow code-review            # review the current branch or open PR
+/workflow code-review HEAD~3     # review a ref range, target, or focus area
+/workflow refactor-scout src/    # find safe refactor opportunities
+/workflow diagnose "typecheck fails after the schema change"
+/workflow perf-review "workflow startup latency"
+/workflow code-review --inspect  # open the live workflow inspector
+/workflow ping                   # quick engine smoke test
 ```
 
-The host agent can also invoke the `workflow` tool itself mid-conversation (e.g. "run the code-review workflow") and fold the structured result back into its reasoning.
-
-`code-review` returns a verified, ranked report:
-
-```json
-{
-  "summary": "1 confirmed bug: off-by-one loop boundary in sum.js ...",
-  "findings": [
-    {
-      "file": "sum.js",
-      "line": 3,
-      "severity": "bug",
-      "verdict": "CONFIRMED",
-      "summary": "Off-by-one: `i <= arr.length` should be `i < arr.length`; accesses arr[arr.length] (undefined) → NaN."
-    }
-  ]
-}
+The host agent can also invoke the `workflow` tool mid-conversation:
+
+```text
+Run the code-review workflow on this PR and use the result before deciding what to fix.
 ```
 
-## How it works
+The advisory workflows inspect and report only; they do not edit files. They return the same shape: summary, ranked findings, evidence, impact, recommendations, and next steps.
+
+## Built-in workflows
+
+- `code-review`: Reviews the current branch, open PR, ref range, or target. It looks for correctness bugs and cleanup issues, then independently verifies candidates before ranking them.
+- `refactor-scout`: Looks for small, safe refactor opportunities: duplication, complexity, weak types, boundary leaks, dead code, and convention drift.
+- `diagnose`: Investigates a symptom, failing command, or regression. It generates competing root-cause hypotheses, verifies them, and returns the most likely causes with next validation steps.
+- `perf-review`: Reviews a slow path or workload for bottleneck hypotheses, measurement gaps, and safe optimization directions. It avoids claiming certainty when measurement evidence is missing.
+- `ping`: Minimal smoke workflow for checking that the engine can run one structured agent call.
+
+## The code-review workflow
+
+The bundled review workflow is deliberately shaped like a serious review process:
 
-A **workflow** is a TypeScript module that exports `meta` plus a default `async (api) => result`. The injected `api` gives you five primitives:
+1. **Scope**: detect the open PR or branch diff, list changed files, and read relevant project conventions.
+2. **Find**: fan out across focused review lenses such as logic bugs, error paths, edge cases, simplification, and conventions.
+3. **Gate and dedupe**: bound candidates to changed lines and collapse duplicate findings before spending verifier tokens.
+4. **Verify**: send each survivor to an independent verifier that must confirm, mark plausible, or refute with evidence.
+5. **Synthesize**: produce one ranked report with stats, verdicts, and concrete locations.
+
+The review lenses live in `.pi/extensions/pi-workflow-engine/workflows/code-review.ts`. That is where your repo's real failure modes belong.
+
+## Authoring workflows
+
+A workflow is a TypeScript module that exports `meta` plus a default `async (api) => result`. The injected `api` gives you the primitives:
 
 | Primitive | Behaviour |
 |-----------|-----------|
-| `agent(prompt, { schema })` | Runs a subagent in an isolated session; with a typebox `schema` it returns validated structured data, otherwise the final text. |
-| `parallel(thunks)` | Runs every thunk concurrently and waits for all (a barrier). |
-| `pipeline(items, ...stages)` | Runs each item through all stages independently — no barrier between stages. |
-| `phase(title)` / `log(msg)` | Drive the live progress tree shown in the TUI. |
+| `agent(prompt, { schema })` | Runs a subagent in an isolated session. With a typebox `schema`, returns validated structured data; otherwise returns final text. |
+| `parallel(thunks)` | Runs every thunk concurrently and waits for all results. |
+| `pipeline(items, ...stages)` | Runs each item through all stages independently, with no barrier between stages. |
+| `phase(title)` / `log(msg)` | Drives the live progress tree shown in the TUI and stderr breadcrumbs when headless. |
+| `progress(event)` | Emits structured progress for richer workflow UI surfaces. |
 
 ```ts
 import { Type } from "typebox";
 import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
-export const meta: WorkflowMeta = { name: "my-workflow", description: "..." };
+export const meta: WorkflowMeta = {
+  name: "my-workflow",
+  description: "Find, verify, and summarize something important.",
+};
 
-export default async function run({ agent, parallel, pipeline, phase, log, args }: WorkflowApi) {
+const FindingSchema = Type.Object({
+  summary: Type.String(),
+  file: Type.String(),
+  line: Type.Optional(Type.Number()),
+});
+
+export default async function run({ agent, parallel, phase }: WorkflowApi) {
   phase("Find");
-  const result = await agent("find issues ...", { schema: Type.Object({ /* ... */ }) });
-  return result; // a typed object, validated against the schema
+
+  const findings = await parallel([
+    () => agent("Find correctness bugs in the diff.", { schema: FindingSchema, thinkingLevel: "low" }),
+    () => agent("Find error-handling bugs in the diff.", { schema: FindingSchema, thinkingLevel: "low" }),
+  ]);
+
+  phase("Synthesize");
+  return agent(`Summarize these findings: ${JSON.stringify(findings)}`, { thinkingLevel: "medium" });
 }
 ```
 
 Under the hood:
 
-- **Each `agent()` is an in-process pi `AgentSession`** (`createAgentSession` + `SessionManager.inMemory()`), inheriting the host's model unless you set one.
-- **Structured output is a terminating tool**: the engine registers one tool whose `parameters` *is* your schema; pi validates the call and the engine captures the args — no parsing.
-- **A single global semaphore caps concurrent agents**, so `parallel`/`pipeline` nest freely while the cap holds inside every `agent()` call.
-- **Surfaces**: a `/workflow <name> [args]` command, plus a `workflow` tool the host agent can call.
+- **Each `agent()` is an in-process pi `AgentSession`** using `createAgentSession` and `SessionManager.inMemory()`.
+- **Structured output is a terminating tool**. The engine registers one tool whose `parameters` is your schema; pi validates the call and the engine captures the args. There is no JSON scraping.
+- **A single global semaphore caps concurrent agents**, so `parallel` and `pipeline` can nest freely while every `agent()` call still respects the run cap.
+- **Two surfaces are registered**: `/workflow <name> [args]` for direct use, and a `workflow` tool for host-agent delegation.
 
 ## Local development
 
-Only needed if you want to **add or customise workflows, or contribute** — using the bundled workflows requires none of this.
+Only needed if you want to add workflows, customise workflows, or contribute. Using the bundled workflows requires none of this.
 
 ```bash
 git clone https://github.com/timbrinded/pi-workflow-engine
 cd pi-workflow-engine
-bun install            # dev deps for typechecking only; pi serves bundled copies at runtime
-bun run typecheck      # tsc --noEmit
-bun scripts/smoke.ts   # no-LLM check: module graph loads + workflow discovery resolves
+bun install
+bun run typecheck
+bun run test
 ```
 
-Load your working copy into a session without installing it (ephemeral — overrides nothing):
+The test suite is no-LLM and uses Bun's built-in `bun test` runner, not a third-party test framework.
+
+### Performance controls and benchmarks
+
+The workflow engine is measurement-first: tune only after checking queue wait, local orchestration, discovery, and UI render costs on the machine where you run pi.
+
+Runtime controls:
+
+- `PI_WORKFLOW_PERF=1` enables the internal per-run performance recorder used by the orchestration instrumentation.
+- `PI_WORKFLOW_CONCURRENCY=N` sets the per-run agent semaphore cap. The default remains `min(8, max(2, CPU count))`.
+- `PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT=N` limits how many `parallel()` thunks are submitted at once; this is separate from the running-agent semaphore cap.
+- `PI_WORKFLOW_LANE_ITEM_LIMIT=N` caps retained progress lane items per lane; snapshots report how many older items are hidden.
+- Slash commands can override selected controls per run: `/workflow <name> --concurrency=N --parallel-limit=N ...`.
+
+No-LLM benchmark scripts:
 
 ```bash
-pi -e ./src/index.ts -p "/workflow ping"
+bun run bench:concurrency -- --items 200 --concurrency 8 --json
+bun run bench:discovery -- --iterations 3 --json
+bun run bench:startup -- --json
+bun run bench:ui -- --agents 1000 --lane-items 1000 --json
 ```
 
-**Add a workflow:** drop a `.ts` in `workflows/`, import it in `src/workflows.ts`, and add it to `BUILTIN_WORKFLOWS`. Statically-imported workflows share pi's bundled `typebox`, which guarantees schema validation. (Files in `workflows/` and `~/.pi/agent/workflows/` are also discovered dynamically at runtime, best-effort.)
+Add `--out` to write machine-local JSON under `.artifacts/benchmarks/`. These timings are advisory, not portable thresholds. Optional LLM smoke timing is separate from the required gates:
 
-**Customise the review:** edit the `ANGLES` array in `workflows/code-review.ts` — the lenses are where your codebase's real failure modes and conventions belong. Tune `model` / `thinkingLevel` / `tools` per `agent()` call, and `DEFAULT_CONCURRENCY` in `src/engine.ts`.
+```bash
+pi -e . -p "/workflow ping"
+```
 
-### Layout
+Guardrails:
+
+- Do not pool or reuse subagent sessions until `agent.create_session_ms` is proven material and isolation semantics are reviewed.
+- Do not lazy-load guaranteed built-in workflow modules until pi/jiti bundled `typebox` identity is proven for that path.
+- Do not raise the default concurrency without queue-wait versus run-time evidence.
+
+Load your working copy through the package manifest without installing it. This is ephemeral and exercises the same `.pi/extensions/pi-workflow-engine/index.ts` entrypoint that installed packages use:
 
+```bash
+pi -e . -p "/workflow ping"
+```
+
+This repo also includes `.pi/settings.json` for project-local auto-discovery. If you also have the global package installed, pi may report duplicate `/workflow` or `workflow` tool diagnostics; remove one source or force pi to ignore discovered extensions and load this working copy instead:
+
+```bash
+pi -ne -e .
 ```
-src/
-  index.ts         extension entry (registers the command + tool)
-  types.ts         WorkflowApi / WorkflowModule contracts
-  agent-runner.ts  the createAgentSession + terminating-tool schema bridge
-  concurrency.ts   Semaphore, parallel(), pipeline()
-  engine.ts        runWorkflow() — binds the primitives to a run
-  progress.ts      live phase/agent tree via ctx.ui.setWidget
-  discovery.ts     static registry + best-effort drop-in loading
-workflows/
-  code-review.ts   the example: scope → find → verify → synthesize
-  ping.ts          minimal smoke workflow
+
+Add a built-in workflow by creating `.pi/extensions/pi-workflow-engine/workflows/<name>.ts`, importing it in `.pi/extensions/pi-workflow-engine/src/workflows.ts`, and adding it to `BUILTIN_WORKFLOWS`. Statically imported workflows share pi's bundled `typebox`, which guarantees schema validation. Files in `.pi/extensions/pi-workflow-engine/workflows/` and `~/.pi/agent/workflows/` are also discovered dynamically at runtime on a best-effort basis.
+
+Keep guaranteed built-ins statically imported. Optimize cold startup at the extension entrypoint or discovery boundary first; do not lazy-load built-in workflow modules unless a test proves pi/jiti preserves the same bundled `typebox` identity for dynamically imported built-ins.
+
+Tune the built-in review workflow by editing the `ANGLES` array in `.pi/extensions/pi-workflow-engine/workflows/code-review.ts`. Tune `model`, `thinkingLevel`, and `tools` per `agent()` call, and use `PI_WORKFLOW_CONCURRENCY` or `/workflow <name> --concurrency=N` for measured per-run concurrency experiments.
+
+### Layout
+
+```text
+.pi/
+  settings.json                         project-local pi resource settings
+  extensions/pi-workflow-engine/
+    index.ts                            canonical extension entry; registers the command and tool
+    src/
+      types.ts                          WorkflowApi / WorkflowModule contracts
+      agent-runner.ts                   createAgentSession + terminating-tool schema bridge
+      concurrency.ts                    Semaphore, parallel(), pipeline()
+      engine.ts                         runWorkflow(); binds primitives to one run
+      progress.ts                       live phase/agent tree via ctx.ui.setWidget
+      discovery.ts                      static registry + best-effort drop-in loading
+      workflows.ts                      statically registered built-in workflows
+    workflows/
+      code-review.ts                    scope -> find -> verify -> synthesize
+      refactor-scout.ts                 advisory refactor opportunities
+      diagnose.ts                       advisory bug diagnosis
+      perf-review.ts                    advisory performance investigation
+      ping.ts                           minimal smoke workflow
 ```
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,23 +1,49 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "A customisable multi-agent workflow-orchestration engine for the pi coding agent.",
-  "keywords": ["pi-package"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-workflow",
+    "workflow-engine",
+    "multi-agent",
+    "coding-agent"
+  ],
   "license": "MIT",
+  "homepage": "https://github.com/timbrinded/pi-workflow-engine#readme",
+  "bugs": {
+    "url": "https://github.com/timbrinded/pi-workflow-engine/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timbrinded/pi-workflow-engine.git"
   },
-  "files": ["src", "workflows"],
+  "files": [
+    ".pi/extensions/pi-workflow-engine",
+    ".pi/settings.json",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
   "pi": {
-    "extensions": ["./src/index.ts"],
+    "extensions": [".pi/extensions/pi-workflow-engine/index.ts"],
     "image": "https://raw.githubusercontent.com/timbrinded/pi-workflow-engine/master/assets/preview.png"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test:ui": "bun scripts/test-workflow-ui.ts",
-    "prepublishOnly": "tsc --noEmit"
+    "test": "bun test",
+    "test:changedlines": "bun test tests/changedlines.test.ts",
+    "test:concurrency": "bun test tests/concurrency.test.ts",
+    "test:smoke": "bun test tests/discovery.test.ts",
+    "test:ui": "bun test tests/workflow-ui.test.ts",
+    "bench": "bun run bench:concurrency && bun run bench:discovery && bun run bench:ui",
+    "bench:concurrency": "bun run scripts/bench/concurrency.ts",
+    "bench:discovery": "bun run scripts/bench/discovery.ts",
+    "bench:startup": "bun run scripts/bench/startup.ts",
+    "bench:ui": "bun run scripts/bench/ui.ts",
+    "prepublishOnly": "tsc --noEmit && bun run test"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",

package/src/agent-runner.ts

@@ -1,122 +0,0 @@
-import { createAgentSession, defineTool, SessionManager } from "@earendil-works/pi-coding-agent";
-import type { ModelRegistry, ToolDefinition } from "@earendil-works/pi-coding-agent";
-import type { Model } from "@earendil-works/pi-ai";
-import type { AgentState } from "@earendil-works/pi-agent-core";
-import type { AgentOptions } from "./types.ts";
-import type { Semaphore } from "./concurrency.ts";
-import type { ProgressTracker } from "./progress.ts";
-
-/** Name of the synthetic terminating tool that carries structured output. */
-const FINAL_TOOL = "final_answer";
-
-/** Shared per-run context threaded into every agent() call. */
-export interface RunContext {
-  cwd: string;
-  hostModel: Model<any> | undefined;
-  modelRegistry: ModelRegistry;
-  semaphore: Semaphore;
-  progress: ProgressTracker;
-  signal: AbortSignal | undefined;
-}
-
-/** Pull the last assistant message's plain text out of a finished session. */
-function lastAssistantText(state: AgentState): string {
-  const messages = state.messages;
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i];
-    if ("role" in message && message.role === "assistant") {
-      const content = (message as { content?: Array<{ type: string; text?: string }> }).content ?? [];
-      return content
-        .filter((part) => part.type === "text")
-        .map((part) => part.text ?? "")
-        .join("")
-        .trim();
-    }
-  }
-  return "";
-}
-
-/**
- * Run one subagent to completion in an isolated in-memory session.
- *
- * Structured output trick: when `opts.schema` is set we register a single
- * terminating tool whose `parameters` IS the schema. The agent's last action is to
- * call it; pi validates the args against the schema, hands them to `execute`, and
- * `terminate: true` ends the turn with no extra LLM round-trip. We capture those
- * validated args in a closure — that captured object is the structured result, so
- * no event-stream parsing is needed.
- */
-export async function runAgent(rc: RunContext, prompt: string, opts: AgentOptions = {}): Promise<unknown> {
-  const label = opts.label ?? "agent";
-
-  // Track queued agents before acquiring a global concurrency slot.
-  const rowId = rc.progress.agentQueued(opts.phase, label);
-  return rc.semaphore.run(async () => {
-    rc.progress.agentStart(opts.phase, label, rowId);
-
-    let captured: unknown = null;
-    let failed = false;
-    const customTools: ToolDefinition[] = opts.schema
-      ? [
-          defineTool({
-            name: FINAL_TOOL,
-            label: "Final Answer",
-            description:
-              "Return your final structured answer. This MUST be your last action — do not write a normal reply after calling it.",
-            parameters: opts.schema,
-            async execute(_toolCallId, params) {
-              captured = params;
-              return { content: [{ type: "text", text: "Recorded." }], details: params, terminate: true };
-            },
-          }),
-        ]
-      : [];
-
-    // When the workflow restricts built-in tools, keep the terminating tool visible.
-    const allow = opts.tools
-      ? opts.schema
-        ? [...opts.tools, FINAL_TOOL]
-        : opts.tools
-      : undefined;
-
-    // Resolve the model by runtime id lookup (no compile-time model-id union); fall back to the host's model.
-    const model = opts.model ? rc.modelRegistry.find("anthropic", opts.model) ?? rc.hostModel : rc.hostModel;
-
-    const { session } = await createAgentSession({
-      cwd: rc.cwd,
-      model,
-      modelRegistry: rc.modelRegistry,
-      thinkingLevel: opts.thinkingLevel,
-      tools: allow,
-      customTools,
-      sessionManager: SessionManager.inMemory(rc.cwd),
-    });
-
-    const unsubscribe = session.subscribe((event) => {
-      if (event.type === "tool_execution_start" && event.toolName !== FINAL_TOOL) {
-        rc.progress.agentTool(label, event.toolName, rowId);
-      }
-    });
-
-    try {
-      const finalPrompt = opts.schema
-        ? `${prompt}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
-        : prompt;
-      await session.prompt(finalPrompt);
-      if (opts.schema) {
-        if (captured === null) rc.progress.log(`${label}: no structured answer returned`);
-        return captured;
-      }
-      return lastAssistantText(session.state);
-    } catch (error) {
-      failed = true;
-      rc.progress.agentFailed(label, error, rowId);
-      rc.progress.log(`${label} failed: ${error instanceof Error ? error.message : String(error)}`);
-      throw error;
-    } finally {
-      unsubscribe();
-      session.dispose();
-      if (!failed) rc.progress.agentDone(label, rowId);
-    }
-  });
-}

package/src/concurrency.ts

@@ -1,55 +0,0 @@
-/**
- * A counting semaphore: bounds how many async tasks run at once.
- *
- * This is the single global concurrency cap for a workflow run. Every `agent()`
- * call acquires a slot before spawning a session and releases it when done, so the
- * cap holds no matter how `parallel`/`pipeline` are nested — exactly like the
- * built-in Workflow tool, where "concurrent agent() calls are capped and excess queue".
- */
-export class Semaphore {
-  private active = 0;
-  private readonly waiters: Array<() => void> = [];
-
-  constructor(private readonly max: number) {}
-
-  async run<T>(fn: () => Promise<T>): Promise<T> {
-    if (this.active >= this.max) {
-      await new Promise<void>((resolve) => this.waiters.push(resolve));
-    }
-    this.active++;
-    try {
-      return await fn();
-    } finally {
-      this.active--;
-      this.waiters.shift()?.();
-    }
-  }
-}
-
-/** Run every thunk concurrently and wait for all results (a barrier). */
-export async function parallel<T>(thunks: Array<() => Promise<T>>): Promise<T[]> {
-  return Promise.all(thunks.map((thunk) => thunk()));
-}
-
-/**
- * Run each item through all stages independently. There is NO barrier between
- * stages: item A can be in stage 3 while item B is still in stage 1. Actual agent
- * concurrency is bounded by the run's Semaphore (inside each `agent()`), not here —
- * so launching every item at once is safe.
- *
- * Each stage receives (previousResult, originalItem, index).
- */
-export async function pipeline(
-  items: unknown[],
-  ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
-): Promise<unknown[]> {
-  return Promise.all(
-    items.map(async (item, index) => {
-      let acc: unknown = item;
-      for (const stage of stages) {
-        acc = await stage(acc, item, index);
-      }
-      return acc;
-    }),
-  );
-}

package/src/discovery.ts

@@ -1,54 +0,0 @@
-import { readdir } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import type { WorkflowModule } from "./types.ts";
-import { BUILTIN_WORKFLOWS } from "./workflows.ts";
-
-function isWorkflowModule(value: unknown): value is WorkflowModule {
-  if (!value || typeof value !== "object") return false;
-  const candidate = value as { meta?: { name?: unknown }; default?: unknown };
-  return typeof candidate.meta?.name === "string" && typeof candidate.default === "function";
-}
-
-/** Best-effort dynamic load of every `*.ts` workflow in a directory. */
-async function loadDir(dir: string): Promise<WorkflowModule[]> {
-  let entries: string[];
-  try {
-    entries = await readdir(dir);
-  } catch {
-    return [];
-  }
-
-  const modules: WorkflowModule[] = [];
-  for (const name of entries) {
-    if (!name.endsWith(".ts") || name.startsWith("_") || name.startsWith(".")) continue;
-    try {
-      const loaded: unknown = await import(pathToFileURL(join(dir, name)).href);
-      if (isWorkflowModule(loaded)) modules.push(loaded);
-    } catch (error) {
-      // Drop-in loading depends on the runtime resolving TS + the bundled typebox.
-      // Failures here are non-fatal: the static registry still works.
-      console.error(`[workflow-engine] skipped ${name}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-  return modules;
-}
-
-/**
- * All available workflows by name. Static registry wins on name collisions, so the
- * bundled example is always the verified one even if a same-named file is dropped in.
- */
-export async function discoverWorkflows(repoDir: string): Promise<Map<string, WorkflowModule>> {
-  const byName = new Map<string, WorkflowModule>();
-  for (const mod of BUILTIN_WORKFLOWS) byName.set(mod.meta.name, mod);
-
-  const dynamic = [
-    ...(await loadDir(join(repoDir, "workflows"))),
-    ...(await loadDir(join(homedir(), ".pi", "agent", "workflows"))),
-  ];
-  for (const mod of dynamic) {
-    if (!byName.has(mod.meta.name)) byName.set(mod.meta.name, mod);
-  }
-  return byName;
-}