pi-workflow-engine 0.10.2 → 0.11.0

package/.pi/extensions/pi-workflow-engine/workflows/code-review.ts

@@ -18,8 +18,9 @@ import {
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
 import { compactResults } from "../src/concurrency.ts";
-import { captureDiff } from "../src/diff-capture.ts";
-import type { ReviewContext } from "../src/review/review-issues.ts";
+import { formatReviewDiffTarget, parseAllowedDiffCommand } from "../src/diff-capture.ts";
+import type { ReviewContext } from "../src/review/review-report.ts";
+import { captureReviewMaterial, type ReviewMaterialCaptureResult } from "../src/review/review-snapshot.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
@@ -95,7 +96,15 @@ export function inDiff(changed: Map<string, Set<number>>, file: string, line?: n
   return set.has(line) || set.has(line - 1) || set.has(line + 1);
 }
 
-export default async function run(api: WorkflowApi): Promise<unknown> {
+export interface CodeReviewDependencies {
+  readonly captureReviewMaterial?: (
+    target: Parameters<typeof captureReviewMaterial>[0],
+    cwd: string,
+    signal?: AbortSignal,
+  ) => Promise<ReviewMaterialCaptureResult>;
+}
+
+export default async function run(api: WorkflowApi, dependencies: CodeReviewDependencies = {}): Promise<unknown> {
   const { agent, parallel, phase, log, progress, args, cwd, signal } = api;
   const target = args.trim();
   let fileCount = 0;
@@ -116,6 +125,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       (target
         ? `Target / instructions (verbatim): "${target}". If it names a PR number, branch, ref range, or files, build the matching diff command (use 'gh pr diff <number>' for a PR). Otherwise use the default selection below.\n`
         : "No explicit target — select the diff to review using the default below.\n") +
+      "Canonical Git syntax: use `git diff -- <path> [<path>...]` for file paths; use one `A..B` or `A...B` range operand for two revisions. Never emit ambiguous two-operand forms such as `git diff A B`.\n" +
       "Default selection — run commands to decide, falling through until you get a NON-EMPTY diff:\n" +
       "1. Get the current branch: `git branch --show-current`.\n" +
       "2. Check for an OPEN GitHub PR for this branch: `gh pr list --head <branch> --state open --json number,title`. " +
@@ -136,45 +146,53 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
 
   fileCount = scope.files.length;
   progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
-  progress({ type: "summary", key: "diffCommand", value: scope.diffCommand });
+  const diffTarget = parseAllowedDiffCommand(scope.diffCommand);
+  if ("error" in diffTarget) {
+    throw new Error(`Code-review target rejected: ${diffTarget.error}`);
+  }
+  const diffCommand = formatReviewDiffTarget(diffTarget);
+  progress({ type: "summary", key: "diffCommand", value: diffCommand });
   progress({ type: "counter", key: "files", label: "files", value: fileCount });
 
   if (scope.files.length === 0) {
     return { summary: "No changes found to review.", findings: [], nextSteps: ["Provide a PR, ref range, or changed files to review."], stats: makeStats(0, 0) };
   }
 
+  log(`${scope.files.length} changed files`);
+
+  // Capture the diff once, deterministically, so findings can be bounded to changed lines in code.
+  const reviewMaterial = await (dependencies.captureReviewMaterial ?? captureReviewMaterial)(diffTarget, cwd, signal);
+  if (!reviewMaterial.ok) {
+    throw new Error(`Code-review diff capture failed: ${reviewMaterial.error}`);
+  }
+  const diffText = reviewMaterial.diff;
+  const changed = changedLines(diffText);
+  progress({ type: "summary", key: "diffBytes", value: Buffer.byteLength(diffText) });
+  if (reviewMaterial.snapshot.status === "unavailable") {
+    log(`review snapshot unavailable (${reviewMaterial.snapshot.reason}) — patch previews will be unavailable`);
+  }
+
   const reviewContext: ReviewContext = {
     workflowName: "code-review",
     target,
-    diffCommand: scope.diffCommand,
+    diffTarget,
     files: scope.files,
     summary: scope.summary,
+    ...(reviewMaterial.snapshot.status === "verified"
+      ? { snapshot: reviewMaterial.snapshot.identity }
+      : {}),
   };
 
-  log(`${scope.files.length} changed files`);
-
-  // Capture the diff once, deterministically, so findings can be bounded to changed lines in code.
-  let changed: Map<string, Set<number>> | null = null;
-  let diffText = "";
-  const capturedDiff = await captureDiff(scope.diffCommand, { cwd, signal, timeoutMs: 30_000, maxBufferBytes: 16 << 20 });
-  if (capturedDiff.ok) {
-    diffText = capturedDiff.stdout;
-    changed = changedLines(diffText);
-    progress({ type: "summary", key: "diffBytes", value: capturedDiff.bytes });
-  } else {
-    log(`diff capture failed (${capturedDiff.error ?? "unknown error"}) — reviewing without the line gate`);
-  }
-
   const diffBlock = diffText
     ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
         diffText.length > DIFF_EMBED_CAP
-          ? `${diffText.slice(0, DIFF_EMBED_CAP)}\n... (truncated — run \`${scope.diffCommand}\` for the full diff)`
+          ? `${diffText.slice(0, DIFF_EMBED_CAP)}\n... (truncated — run \`${diffCommand}\` for the full diff)`
           : diffText
       }\n\`\`\`\n`
     : "";
 
   const scopeBlock =
-    `## Diff command\n${scope.diffCommand}\n\n## Changed files\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
+    `## Diff command\n${diffCommand}\n\n## Changed files\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
     `## Summary\n${scope.summary}\n\n## Conventions\n${scope.conventions ?? "(none noted)"}\n` +
     diffBlock +
     (target ? `\n## User instructions (verbatim)\n${target}\n` : "");
@@ -204,14 +222,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       const raw = (found?.candidates ?? []).slice(0, PER_ANGLE);
       rawCandidateCount += raw.length;
       progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
-      const gate = changed;
-      const bounded = gate ? raw.filter((candidate) => inDiff(gate, primaryLocation(candidate).file, primaryLocation(candidate).line)) : raw;
+      const bounded = raw.filter((candidate) => inDiff(changed, primaryLocation(candidate).file, primaryLocation(candidate).line));
       const dropped = raw.length - bounded.length;
       if (dropped > 0) {
         droppedCandidateCount += dropped;
         progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
-      }
-      if (gate && dropped > 0) {
         log(`find:${angle.label}: dropped ${dropped} out-of-diff candidate(s)`);
       }
       for (const candidate of bounded) {
@@ -295,7 +310,14 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
       "Return summary, findings, and nextSteps. For each finding: category must be bug or cleanup; severity is impact level (low/medium/high), not category; " +
       "confidence must be high for CONFIRMED and medium for PLAUSIBLE; copy locations and evidence arrays from the verified finding; impact is the concrete failure or maintenance scenario; recommendation is an advisory fix direction, not an edit. Structured output only.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      thinkingLevel: "medium",
+      resume: "read-only",
+      schema: AdvisoryReportSchema,
+    },
   );
 
   if (!report) return { summary: "Synthesis produced no output.", findings: [], nextSteps: ["Re-run the workflow or inspect verifier evidence manually."], stats, reviewContext };

package/.pi/extensions/pi-workflow-engine/workflows/diagnose.ts

@@ -212,7 +212,14 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Produce the shared advisory report shape. Only include confirmed or plausible root causes in findings. " +
       "Use categories such as root-cause, regression, configuration, dependency, or test-fixture. " +
       "Recommendation must be a validation/fix plan, not a patch. nextSteps must be the minimum commands or code inspections needed to confirm the top diagnosis. Structured output only.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      thinkingLevel: "medium",
+      resume: "read-only",
+      schema: AdvisoryReportSchema,
+    },
   );
 
   if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun diagnose with a narrower symptom."], stats);

package/.pi/extensions/pi-workflow-engine/workflows/perf-review.ts

@@ -168,7 +168,14 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Produce the shared advisory report shape. Categories should be algorithmic, io, concurrency, startup, allocation, or measurement when applicable. " +
       "Severity is expected performance impact for the target workload. Prefer measurement recommendations before optimization recommendations when evidence is weak. " +
       "Recommendations must be safe advisory next actions, not patches. Include risky optimizations to avoid in recommendations or nextSteps when relevant. Structured output only.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      thinkingLevel: "medium",
+      resume: "read-only",
+      schema: AdvisoryReportSchema,
+    },
   );
 
   if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun perf-review with a narrower target."], stats);
@@ -189,4 +196,3 @@ function rank(finding: Verified): number {
   const measurementPenalty = finding.category === "measurement" ? 1 : 0;
   return verdictRank + measurementPenalty;
 }
-

package/.pi/extensions/pi-workflow-engine/workflows/refactor-scout.ts

@@ -162,7 +162,14 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Return the shared advisory report shape. Categories should come from the verified candidates. " +
       "Severity is maintenance or future-correctness impact. Confidence is high for CONFIRMED, medium for PLAUSIBLE unless verifier confidence says otherwise. " +
       "Recommendations must be safe first refactor steps, not rewrites. Include concrete nextSteps for the host developer. Structured output only.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      thinkingLevel: "medium",
+      resume: "read-only",
+      schema: AdvisoryReportSchema,
+    },
   );
 
   if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun the workflow with a narrower target."], stats);

package/README.md

@@ -1,259 +1,203 @@
-![agents](assets/preview.png)
-
 # pi-workflow-engine
 
-Zero-dependency Dynamax workflows for [pi](https://pi.dev): opt into live, parallel subagents when one coding agent is not enough.
-
-Use `dynamax` when a task needs several independent passes: review from different angles, compare options, chase a bug through multiple suspects, or stress-test a plan. pi can spin up a temporary workflow, run focused subagents in parallel, show progress in the TUI, and return one synthesized result.
-
-The package ships no bundled runtime dependencies. It uses the pi SDK and pi's bundled core packages, so installing it does not pull in a second agent stack.
-
-The built-in workflows are advisory by default. They inspect, verify, and report; they do not edit files. Workflow authors can opt individual subagents into disposable git worktrees when they want reviewable patches instead of direct edits.
-
-## Install
-
-```bash
-pi install npm:pi-workflow-engine
-```
+[![CI](https://github.com/timbrinded/pi-workflow-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/timbrinded/pi-workflow-engine/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-workflow-engine)](https://www.npmjs.com/package/pi-workflow-engine)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Or install from GitHub:
+**A multi-agent workflow engine for [pi](https://pi.dev).**
 
-```bash
-pi install git:github.com/timbrinded/pi-workflow-engine
-```
+One coding agent is usually enough. When a task needs independent opinions,
+competing hypotheses, or a verifier that did not write the first answer, this
+extension lets pi fan the work out and bring the evidence back together.
 
-Restart pi, or run `/reload` in an open session, then confirm it loaded:
+The process is simple: **scope → fan out → verify → synthesize**. You see the work
+live in the TUI, concurrency stays bounded, and the final answer includes the
+subagents' combined usage and estimated cost when the provider exposes enough
+data to calculate them.
 
-```bash
-pi list
-```
+![A lead agent coordinating subagents](assets/preview.png)
 
-For project-local install:
+## Quick start
 
 ```bash
-pi install npm:pi-workflow-engine -l
-```
-
-## Use Dynamax
-
-Put the word `dynamax` in your prompt when you want pi to use a custom multi-agent workflow for the current task.
-
-```text
-dynamax investigate why typecheck started failing after this branch
-```
-
-What to expect:
-
-1. pi decides whether a saved workflow fits or whether to write a one-off workflow.
-2. The workflow runs focused subagents in parallel.
-3. You can watch phases, agents, findings, and logs in the workflow inspector.
-4. You get a summarized result with evidence, risks, next steps, and workflow-level token/cost totals gathered from subagent sessions.
-5. You can then ask pi to make changes using that result.
-
-Workflow usage totals are reported on the workflow result itself. pi's built-in footer and `/session` stats may still show host-session usage only unless pi core adds a first-class extension usage API.
-
-Dynamax is one-shot by default. It applies to the next agent run and then clears. Keep it on for the session with:
-
-```text
-/workflow:dynamax on
-/workflow:dynamax status
-/workflow:dynamax off
-```
-
-The workflow inspector is available with:
-
-```text
-/workflow:inspector
-```
-
-In interactive mode, `/workflow` with no arguments also offers `Author temporary one-shot workflow...`. Choose it, type a brief, and pi will ask the host agent to write and run a temporary workflow.
-
-## Example Dynamax Prompts
-
-Use Dynamax when you want breadth, independent judgment, or adversarial pressure before editing.
-
-```text
-dynamax do an adversarial review of this branch. I want correctness bugs, hidden coupling, test gaps, and over-engineered parts called out separately.
-```
-
-Expected result: several review angles run independently, likely findings are verified, duplicates are merged, and you get a ranked report with concrete evidence before deciding what to fix.
-
-```text
-dynamax investigate this flaky test. Split the work between recent diffs, test setup, async timing, and external dependencies.
-```
-
-Expected result: parallel hypotheses, evidence for or against each one, and the most likely root cause with a small validation step.
-
-```text
-dynamax compare these two implementation approaches and argue both sides before recommending one.
-```
-
-Expected result: separate agents inspect each approach, another pass looks for failure modes, and the final answer separates tradeoffs from the recommendation.
-
-```text
-dynamax review this migration plan like a hostile reviewer. Focus on rollback, data loss, concurrency, and missing operational steps.
-```
-
-Expected result: an adversarial checklist with concrete risks, what would break, and which items are blockers versus follow-ups.
-
-```text
-dynamax find the simplest safe refactor path for this module. Avoid broad rewrites.
+pi install npm:pi-workflow-engine
 ```
 
-Expected result: small refactor opportunities, why they are safe, and what not to touch.
+Restart pi or run `/reload`, then add `dynamax` to a prompt:
 
 ```text
-dynamax inspect this performance issue. Separate measurement gaps from real bottleneck hypotheses.
+dynamax investigate why typecheck started failing on this branch
 ```
 
-Expected result: a performance-focused report that distinguishes known evidence from guesses and suggests the next measurement command.
-
-## Saved Workflows
+`dynamax` is a one-shot opt-in. It lets the host agent choose a saved workflow
+or author a temporary one for this task. Use `/workflow:dynamax on` when you
+want that permission to remain active for the session.
 
-You can also run saved workflows directly:
+Saved workflows are available directly:
 
 ```text
 /workflow code-review
-/workflow code-review HEAD~3
 /workflow refactor-scout src/
-/workflow diagnose "typecheck fails after the schema change"
+/workflow diagnose "the schema migration broke typecheck"
 /workflow perf-review "workflow startup latency"
 ```
 
-Built-ins:
-
-- `code-review`: reviews a PR, branch diff, ref range, or target.
-- `refactor-scout`: finds small, safe refactor opportunities.
-- `diagnose`: investigates a bug, failing command, or regression.
-- `perf-review`: reviews a slow path or performance concern.
-
-Useful flags:
-
-```text
-/workflow code-review --inspect
-/workflow code-review --result-viewer
-/workflow code-review --no-result-viewer
-/workflow code-review --concurrency=4
-/workflow code-review --budget=50000
-/workflow code-review --resume <run-id>
-/workflow code-review --refresh
-```
-
-Every workflow result includes a run id. If a long run is interrupted, rerun the same workflow with `--resume <run-id>` to replay matching completed `agent()` calls from the journal and run only the first changed or missing call onward. Resume is deterministic-prefix based: keep prompts and agent options stable if you want cache hits.
-
-The code-review workflow can open an interactive findings viewer. Select findings and hand them back to the parent agent for minimal fixes, or ask it to raise GitHub PR comments when `gh` is authenticated and PR context is available.
-
-For the full command guide, see [USAGE.md](USAGE.md).
-
-## What Dynamax Is Good For
-
-Use it for:
-
-- adversarial reviews before you trust a plan or diff;
-- debugging where several causes are plausible;
-- design comparisons where you want both sides argued;
-- refactor scouting where broad rewrites would be risky;
-- performance investigations where measurement gaps matter;
-- documentation reviews where consistency and reader expectations both matter.
-
-Do not use it for every tiny task. A single prompt is still better for simple edits, one-file explanations, and obvious mechanical changes.
-
-## Local Development
-
-Only needed if you want to add workflows, customize workflows, or contribute. Using the package does not require a clone, install, or build step.
+The package uses pi's bundled SDK and core packages; it does not install or
+bundle a second agent runtime.
+
+## What it gives you
+
+- **Independent passes.** Different agents can inspect correctness, tests,
+  coupling, performance, or any lenses you define.
+- **Typed handoffs.** A TypeBox schema becomes the agent's terminating tool
+  contract—there is no JSON scraping.
+- **Live progress.** Phases, agents, findings, and logs are visible in the TUI,
+  alongside usage and estimated cost when provider data is available.
+- **Bounded execution.** One semaphore covers nested fan-out, pipelines, and
+  sub-workflows.
+- **Evidence before action.** Built-in workflows inspect and report by default;
+  they do not edit your working tree.
+- **Reviewable mutation.** An author can opt a mutating agent into a disposable
+  git worktree and receive its patch.
+- **Safe replay.** Interrupted runs reuse a completed call only when every
+  captured observable surface and its effective execution identity still match.
+
+## Built-in workflows
+
+| Workflow | Best used for |
+| --- | --- |
+| `code-review` | PRs, branch diffs, ref ranges, or focused targets |
+| `refactor-scout` | Small, defensible refactors without broad rewrites |
+| `diagnose` | Competing explanations for bugs or failing commands |
+| `perf-review` | Measured bottlenecks versus performance guesses |
+
+These are starting points, not a fixed menu. Dynamax can author a one-off
+workflow when the question needs different lenses or an adaptive second pass.
+
+## The review experience
+
+When reviewing a PR, `code-review` uses its cumulative diff, so superseded code
+from earlier commits does not become a finding. Candidate issues are
+independently verified, deduplicated, and ranked before synthesis.
+
+Add `--result-viewer` to open the interactive findings view. It exposes a findings list for follow-up. Reopen the current session's latest review
+with `/workflow:results` or `ctrl+shift+r`—it does not rerun the workflow.
+
+The **Fix** action creates one disposable worktree per selected finding and
+returns separate patch previews without touching the active checkout. GitHub
+comments are available only for a verified PR target; the engine checks the
+snapshot and PR head again and skips exact duplicates before posting.
+
+## Prompts that benefit from Dynamax
+
+- **Review:** `dynamax` review this branch from correctness, test,
+  security-boundary, and maintainability angles; verify every finding.
+- **Debug:** `dynamax` investigate this flaky test using separate hypotheses for
+  timing, fixtures, recent diffs, and external state.
+- **Decide:** `dynamax` argue both implementation options, then have another
+  agent attack the recommendation.
+- **Refactor:** `dynamax` find the smallest safe path through this module and
+  identify what should not change.
+
+Tiny edits and straightforward questions are still better handled by one agent.
+Dynamax earns its cost when independence or breadth changes the answer.
+
+## Write a workflow
+
+A saved workflow is a TypeScript module with metadata and one async function.
+The injected API supplies agents, concurrency primitives, phases, progress,
+budgets, cancellation, and sub-workflow composition.
+
+```ts
+import { Type } from "typebox";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "two-angle-review",
+  description: "Find issues independently, then synthesize.",
+};
+
+const Finding = Type.Object({
+  summary: Type.String(),
+  evidence: Type.Array(Type.String()),
+});
+const reviewTools = ["read", "grep", "find", "ls"];
+
+export default async function run(
+  { agent, parallel, phase, args }: WorkflowApi,
+) {
+  phase("Find");
+  const findings = await parallel([
+    () => agent(`Review correctness: ${args}`, {
+      schema: Finding,
+      tools: reviewTools,
+      thinkingLevel: "low",
+      resume: "read-only",
+    }),
+    () => agent(`Review edge cases: ${args}`, {
+      schema: Finding,
+      tools: reviewTools,
+      thinkingLevel: "low",
+      resume: "read-only",
+    }),
+  ]);
+
+  phase("Synthesize");
+  return agent(`Merge and rank these findings: ${JSON.stringify(findings)}`, {
+    tools: [],
+    thinkingLevel: "medium",
+    resume: "read-only",
+  });
+}
+```
+
+Set `thinkingLevel` on fan-out agents so they do not all inherit an expensive
+global setting. The [usage guide](USAGE.md#author-a-saved-workflow) covers
+schemas, tools, skills, pipelines, settled results, worktree isolation, inline
+workflows, and registration.
+
+## Design choices
+
+- **Agent sessions:** each call uses an in-process pi `AgentSession` with an
+  in-memory session manager.
+- **Structured output:** the schema is a terminating tool definition validated
+  by pi.
+- **Recoverable failures:** a failed parallel branch becomes `null`; surviving
+  work continues.
+- **Fatal failures:** cancellation aborts siblings and drains submitted work
+  before rejection.
+- **Mutating agents:** disposable worktrees isolate edits and return
+  baseline-relative patches.
+- **Resume:** journals bind workspace-aware calls to repository state and all
+  calls to workflow, model, prompt, skill, and tool identity.
+- **Dependencies:** pi and TypeBox remain host-provided peers; the package ships
+  no duplicate runtime stack.
+
+The replay contract deliberately fails closed. For workspace-aware calls,
+changed commits, dirty state, and declared ignored inputs invalidate a hit.
+Workflow source, effective model or prompt, selected skills, and executable
+tools remain part of the relevant identity; unsafe or unbounded surfaces run
+live instead.
+
+## Develop locally
 
 ```bash
 git clone https://github.com/timbrinded/pi-workflow-engine
 cd pi-workflow-engine
 bun install
-bun run typecheck
-bun run test
-```
-
-Load your working copy through the package manifest without installing it:
-
-```bash
-pi -e .
-```
-
-If you also have the global package installed, pi may report duplicate `/workflow` or `workflow` tool diagnostics. Remove one source or load only this working copy:
-
-```bash
+bun run typecheck && bun run test
 pi -ne -e .
 ```
 
-### Add A Workflow
-
-A workflow is a TypeScript module that exports `meta` plus a default async function. The `api` object gives you `agent`, `parallel`, `pipeline`, `workflow`, `phase`, `log`, and `progress`.
-
-Guaranteed built-ins are statically registered:
-
-1. Add `.pi/extensions/pi-workflow-engine/workflows/<name>.ts`.
-2. Import it in `.pi/extensions/pi-workflow-engine/src/workflows.ts`.
-3. Add it to `BUILTIN_WORKFLOWS`.
-
-Drop-in workflows are also discovered best-effort from:
-
-- `.pi/extensions/pi-workflow-engine/workflows/*.ts`
-- `~/.pi/agent/workflows/*.ts`
-
-Use `/workflow <name> --refresh` after adding a drop-in file.
-
-Inline workflows are passed to the `workflow` tool as a script string. They are useful for one-off Dynamax orchestration. Inline v1 rules: no imports, no dynamic `import()`, pure-literal `meta`, schemas must use the injected `Type` value, and scripts run in-process with the extension's permissions.
+`pi -ne -e .` loads the working copy without also loading an installed global
+copy. There is no build step; pi loads the TypeScript extension directly.
 
-### Technical Notes
+For the complete command reference, runtime controls, authoring rules, and
+troubleshooting, see [USAGE.md](USAGE.md). The public API lives in
+[types.ts](.pi/extensions/pi-workflow-engine/src/types.ts), and the built-in
+[code-review workflow](.pi/extensions/pi-workflow-engine/workflows/code-review.ts)
+is the most complete example.
 
-- Each `agent()` runs an in-process pi `AgentSession` with `SessionManager.inMemory()`.
-- Workflow results aggregate the finalized assistant usage from those subagent sessions before disposal and show token/cost totals separately from pi's host-session footer accounting.
-- Structured output uses a terminating tool whose `parameters` is your schema. pi validates the call; the engine captures the args. There is no JSON scraping.
-- A schema agent that finishes without calling `final_answer` is re-prompted once before returning `null`.
-- Runs write completed `agent()` results to `.pi/.workflow-runs/<run-id>.jsonl`; `--resume <run-id>` replays the longest unchanged prefix and writes a fresh journal for the resumed run.
-- `agent(..., { isolation: "worktree" })` runs in a disposable git worktree and returns `{ result, patch, changed }`; the user working tree is not mutated.
-- A single run-level semaphore caps concurrent agents, so nested `parallel`, `pipeline`, and `workflow()` calls stay bounded.
-- `parallel()` and `pipeline()` are fail-soft: recoverable branch failures, including budget backstops, become `null` slots while survivors continue. A genuine run abort still rejects.
-- Built-in workflows stay statically imported so they share pi's bundled `typebox` identity.
-- Set `thinkingLevel` per fan-out agent. Otherwise many subagents can inherit an expensive global reasoning level.
-- Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; clear prompt text like `include skill name` also works when `skills` is omitted.
-- `tools` is a strict allowlist for subagents. Use `toolHints: ["search"]` to dynamically expose installed grep/find/search-like tools such as `ast-grep`, `mgrep`, `ffgrep`, or `fffind` without hard-coding a specific extension.
-- Set `model` per agent only when needed: bare ids are Anthropic shorthand, and `provider/id` targets other providers.
-  Omitted models inherit the host/session default; malformed or unknown explicit refs fail fast.
-
-### Performance Controls
-
-Runtime controls:
-
-- `PI_WORKFLOW_PERF=1` enables per-run performance timing. This is timing-only; workflow usage/cost totals are reported separately when subagent usage is available.
-- `PI_WORKFLOW_CONCURRENCY=N` sets the per-run agent cap. The default is `min(8, max(2, CPU count))`.
-- `PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT=N` limits how many `parallel()` thunks are submitted at once.
-- `PI_WORKFLOW_LANE_ITEM_LIMIT=N` caps retained progress lane items per lane.
-
-No-LLM benchmark scripts:
-
-```bash
-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
-```
-
-### Layout
-
-```text
-.pi/
-  settings.json
-  extensions/pi-workflow-engine/
-    index.ts
-    src/
-      types.ts
-      agent-runner.ts
-      concurrency.ts
-      engine.ts
-      progress.ts
-      discovery.ts
-      workflows.ts
-    workflows/
-      code-review.ts
-      refactor-scout.ts
-      diagnose.ts
-      perf-review.ts
-```
+Questions and ideas are welcome in
+[GitHub Issues](https://github.com/timbrinded/pi-workflow-engine/issues).
+MIT licensed.