pi-workflow-engine 0.3.0 → 0.4.0

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

@@ -1,14 +1,16 @@
 import { Type } from "typebox";
 import {
-  AdvisoryCandidatesSchema,
   AdvisoryReportSchema,
-  AdvisoryVerdictSchema,
   type AdvisoryCandidate,
-  type AdvisoryFinding,
-  type AdvisoryLocation,
   type AdvisoryReport,
   type AdvisoryVerdict,
 } from "../src/advisory-schema.ts";
+import {
+  backfillAdvisoryFindings,
+  formatEvidence,
+  formatLocation,
+  runLensVerificationPipeline,
+} from "../src/workflow-advisory-utils.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
@@ -98,91 +100,39 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     `## Summary\n${scope.summary}\n\n## Known measurements\n${scope.knownMeasurements ?? "(none known)"}\n` +
     (args.trim() ? `\n## User instructions (verbatim)\n${args.trim()}\n` : "");
 
-  const seen = new Set<string>();
-
   phase("Find");
-  const perLens = await pipeline(
-    PERF_LENSES,
-    async (_prev, item) => {
-      const lens = item as PerfLens;
-      const found = await agent(
-        `## Perf-review finder — ${lens.label}\n\n${scopeBlock}\n` +
-          "This workflow is advisory-only: identify bottleneck hypotheses, measurement gaps, and safe optimization directions, but do not edit files.\n" +
-          `Investigate ONLY this lens:\n${lens.text}\n\n` +
-          `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
-          "Each candidate must include a one-line summary, locations, impact stating the suspected performance consequence and workload where it matters, " +
-          "and an optional recommendation. Prefer measurement recommendations when evidence is weak. Structured output only.",
-        { phase: "Find", label: `find:${lens.label}`, tools: TOOLS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
-      );
-      const raw = (found?.candidates ?? []).slice(0, PER_LENS);
-      rawCandidateCount += raw.length;
-      progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
-      for (const candidate of raw) {
-        progress({
-          type: "lane_item",
-          lane: "Candidates",
-          title: candidate.summary,
-          subtitle: formatLocation(candidate),
-          status: "pending",
-          details: candidate.impact,
-        });
-      }
-      return { lens, candidates: raw };
-    },
-    async (prev) => {
-      const { lens, candidates } = prev as { lens: PerfLens; candidates: Candidate[] };
-      const novel = candidates.filter((candidate) => {
-        const key = dedupKey(candidate);
-        if (seen.has(key)) return false;
-        seen.add(key);
-        return true;
-      });
-      const dropped = candidates.length - novel.length;
-      if (dropped > 0) {
-        droppedCandidateCount += dropped;
-        progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
-        log(`find:${lens.label}: dropped ${dropped} duplicate candidate(s)`);
-      }
-      const verdicts = await parallel(
-        novel.map((candidate) => async (): Promise<Verified | null> => {
-          const location = primaryLocation(candidate);
-          const judged = await agent(
-            `## Perf-review verifier\n\n${scopeBlock}\n## Candidate\n` +
-              `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
-              `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
-              "Read relevant files and package/scripts. Run only safe read-only measurement or inspection commands when useful. " +
-              "Return CONFIRMED, PLAUSIBLE, or REFUTED with evidence from code, scripts, config, or measurement output. " +
-              "Default toward PLAUSIBLE or REFUTED when no measurement exists; do not overstate a bottleneck. Structured output only.",
-            {
-              phase: "Verify",
-              label: `verify:${location.file.split("/").pop() ?? location.file}`,
-              tools: TOOLS,
-              thinkingLevel: "low",
-              schema: AdvisoryVerdictSchema,
-            },
-          );
-          if (!judged) return null;
-          progress({ type: "counter_delta", key: `verdict.${judged.verdict.toLowerCase()}`, label: judged.verdict, delta: 1 });
-          if (judged.verdict === "REFUTED") {
-            refutedCandidateCount += 1;
-            progress({ type: "counter_delta", key: "refuted", label: "refuted", delta: 1 });
-          }
-          progress({
-            type: "lane_item",
-            lane: verdictLane(judged.verdict),
-            title: candidate.summary,
-            subtitle: formatLocation(candidate),
-            status: verdictStatus(judged.verdict),
-            details: formatEvidence(judged.evidence),
-          });
-          return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, confidence: judged.confidence, lens };
-        }),
-      );
-      return verdicts.filter((value): value is Verified => value !== null);
-    },
-  );
-
-  const verified = (perLens as Verified[][]).flat();
+  const pipelineResult = await runLensVerificationPipeline({
+    api: { agent, parallel, pipeline, progress, log },
+    lenses: PERF_LENSES,
+    schedulingMode: "finder-barrier",
+    perLens: PER_LENS,
+    tools: TOOLS,
+    finderPrompt: (lens) =>
+      `## Perf-review finder — ${lens.label}\n\n${scopeBlock}\n` +
+      "This workflow is advisory-only: identify bottleneck hypotheses, measurement gaps, and safe optimization directions, but do not edit files.\n" +
+      `Investigate ONLY this lens:\n${lens.text}\n\n` +
+      `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
+      "Each candidate must include a one-line summary, locations, impact stating the suspected performance consequence and workload where it matters, " +
+      "and an optional recommendation. Prefer measurement recommendations when evidence is weak. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Perf-review verifier\n\n${scopeBlock}\n## Candidate\n` +
+      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+      `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+      "Read relevant files and package/scripts. Run only safe read-only measurement or inspection commands when useful. " +
+      "Return CONFIRMED, PLAUSIBLE, or REFUTED with evidence from code, scripts, config, or measurement output. " +
+      "Default toward PLAUSIBLE or REFUTED when no measurement exists; do not overstate a bottleneck. Structured output only.",
+    makeVerified: (candidate, lens, judged): Verified => ({
+      ...candidate,
+      verdict: judged.verdict,
+      evidence: judged.evidence,
+      confidence: judged.confidence,
+      lens,
+    }),
+  });
+  rawCandidateCount += pipelineResult.rawCandidates;
+  droppedCandidateCount += pipelineResult.dropped;
+  refutedCandidateCount += pipelineResult.refuted;
+  const verified = pipelineResult.verified;
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
   progress({ type: "counter", key: "verified", label: "verified", value: verified.length });
@@ -219,14 +169,9 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
 
   if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun perf-review with a narrower target."], stats);
 
-  const findings = report.findings.map((finding) => {
-    const source = ranked.find((candidate) => sameFinding(candidate, finding));
-    return {
-      ...finding,
-      evidence: finding.evidence.length > 0 ? finding.evidence : (source?.evidence ?? []),
-      impact: finding.impact || source?.impact || "Performance impact not restated by synthesis.",
-      recommendation: finding.recommendation || source?.recommendation || "Measure the target workload before changing code.",
-    };
+  const findings = backfillAdvisoryFindings(report.findings, ranked, {
+    impact: "Performance impact not restated by synthesis.",
+    recommendation: "Measure the target workload before changing code.",
   });
   return { ...report, findings, stats };
 }
@@ -235,61 +180,9 @@ function emptyReport(summary: string, nextSteps: string[], stats: WorkflowRunSta
   return { summary, findings: [], nextSteps, stats };
 }
 
-function primaryLocation(candidate: Pick<Candidate, "locations">): AdvisoryLocation {
-  return candidate.locations[0] ?? { file: "" };
-}
-
-function formatLocation(candidate: Pick<Candidate, "locations">): string {
-  const location = primaryLocation(candidate);
-  const line = location.line != null ? `:${location.line}` : "";
-  const symbol = location.symbol ? ` (${location.symbol})` : "";
-  return `${location.file}${line}${symbol}`;
-}
-
-function formatEvidence(evidence: string[]): string {
-  return evidence.join("; ");
-}
-
-function dedupKey(candidate: Candidate): string {
-  const location = primaryLocation(candidate);
-  const lineKey = location.line != null ? Math.round(location.line / 5) * 5 : "file";
-  return `${candidate.category}:${normalizePath(location.file)}:${lineKey}:${candidate.summary.slice(0, 60).toLowerCase()}`;
-}
-
-function normalizePath(path: string): string {
-  return path.replace(/^\.\//, "").replace(/^[ab]\//, "");
-}
-
 function rank(finding: Verified): number {
   const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
   const measurementPenalty = finding.category === "measurement" ? 1 : 0;
   return verdictRank + measurementPenalty;
 }
 
-function verdictLane(verdict: Verified["verdict"]): string {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "Confirmed";
-    case "PLAUSIBLE":
-      return "Plausible";
-    case "REFUTED":
-      return "Refuted";
-  }
-}
-
-function verdictStatus(verdict: Verified["verdict"]): "success" | "warning" | "error" {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "success";
-    case "PLAUSIBLE":
-      return "warning";
-    case "REFUTED":
-      return "error";
-  }
-}
-
-function sameFinding(candidate: Verified, finding: Pick<AdvisoryFinding, "locations" | "summary">): boolean {
-  const candidateLocation = primaryLocation(candidate);
-  const findingLocation = primaryLocation(finding);
-  return normalizePath(candidateLocation.file) === normalizePath(findingLocation.file) && candidateLocation.line === findingLocation.line;
-}

package/{workflows → .pi/extensions/pi-workflow-engine/workflows}/ping.ts

@@ -18,6 +18,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       phase: "Ping",
       label: "ping",
       tools: [],
+      thinkingLevel: "low",
       schema: Type.Object({
         headline: Type.String({ description: "One word" }),
         summary: Type.String({ description: "One sentence" }),

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

@@ -1,14 +1,16 @@
 import { Type } from "typebox";
 import {
-  AdvisoryCandidatesSchema,
   AdvisoryReportSchema,
-  AdvisoryVerdictSchema,
   type AdvisoryCandidate,
-  type AdvisoryFinding,
-  type AdvisoryLocation,
   type AdvisoryReport,
   type AdvisoryVerdict,
 } from "../src/advisory-schema.ts";
+import {
+  backfillAdvisoryFindings,
+  formatEvidence,
+  formatLocation,
+  runLensVerificationPipeline,
+} from "../src/workflow-advisory-utils.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
@@ -21,7 +23,7 @@ const ScopeSchema = Type.Object({
   target: Type.String({ description: "Verbatim target path, module, or focus area being scouted." }),
   files: Type.Array(Type.String(), { description: "Repository-relative files in scope." }),
   summary: Type.String({ description: "One-paragraph summary of the scoped code." }),
-  conventions: Type.Optional(Type.String({ description: "Relevant project conventions from AGENTS.md / CLAUDE.md / docs." })),
+  conventions: Type.Optional(Type.String({ description: "Relevant project conventions from AGENTS.md / docs." })),
 });
 
 interface RefactorLens {
@@ -71,7 +73,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const scope = await agent(
     "Establish the scope for an advisory-only refactor scout. Do not edit files.\n" +
       `Target / focus (verbatim): ${target}\n\n` +
-      "Inspect repository structure, the target path or module, and relevant AGENTS.md / CLAUDE.md conventions. " +
+      "Inspect repository structure, the target path or module, and relevant AGENTS.md / project docs conventions. " +
       "Return the concrete files that should be considered, a short summary, and any conventions that affect refactor advice. " +
       `This workflow will fan out across ${REFACTOR_LENSES.length} lenses with up to ${PER_LENS} candidates per lens. Structured output only.`,
     { phase: "Scope", label: "scope", tools: TOOLS, thinkingLevel: "medium", schema: ScopeSchema },
@@ -95,91 +97,39 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     `## Summary\n${scope.summary}\n\n## Conventions\n${scope.conventions ?? "(none noted)"}\n` +
     (args.trim() ? `\n## User instructions (verbatim)\n${args.trim()}\n` : "");
 
-  const seen = new Set<string>();
-
   phase("Find");
-  const perLens = await pipeline(
-    REFACTOR_LENSES,
-    async (_prev, item) => {
-      const lens = item as RefactorLens;
-      const found = await agent(
-        `## Refactor-scout finder — ${lens.label}\n\n${scopeBlock}\n` +
-          "This workflow is advisory-only: do not edit files and do not propose broad rewrites.\n" +
-          `Scout through ONLY this lens:\n${lens.text}\n\n` +
-          `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
-          "Each candidate must include a one-line summary, locations, impact on maintainability or future correctness, and an optional safe first recommendation. " +
-          "Only include opportunities where a small, reviewable first step is plausible. Structured output only.",
-        { phase: "Find", label: `find:${lens.label}`, tools: TOOLS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
-      );
-      const raw = (found?.candidates ?? []).slice(0, PER_LENS);
-      rawCandidateCount += raw.length;
-      progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
-      for (const candidate of raw) {
-        progress({
-          type: "lane_item",
-          lane: "Candidates",
-          title: candidate.summary,
-          subtitle: formatLocation(candidate),
-          status: "pending",
-          details: candidate.impact,
-        });
-      }
-      return { lens, candidates: raw };
-    },
-    async (prev) => {
-      const { lens, candidates } = prev as { lens: RefactorLens; candidates: Candidate[] };
-      const novel = candidates.filter((candidate) => {
-        const key = dedupKey(candidate);
-        if (seen.has(key)) return false;
-        seen.add(key);
-        return true;
-      });
-      const dropped = candidates.length - novel.length;
-      if (dropped > 0) {
-        droppedCandidateCount += dropped;
-        progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
-        log(`find:${lens.label}: dropped ${dropped} duplicate candidate(s)`);
-      }
-      const verdicts = await parallel(
-        novel.map((candidate) => async (): Promise<Verified | null> => {
-          const location = primaryLocation(candidate);
-          const judged = await agent(
-            `## Refactor-scout verifier\n\n${scopeBlock}\n## Candidate\n` +
-              `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
-              `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
-              "Read the relevant files and return CONFIRMED, PLAUSIBLE, or REFUTED. " +
-              "Default toward REFUTED if the opportunity is generic, too broad, not evidenced by code, or lacks a safe first step. " +
-              "Evidence must quote or cite code. Structured output only.",
-            {
-              phase: "Verify",
-              label: `verify:${location.file.split("/").pop() ?? location.file}`,
-              tools: TOOLS,
-              thinkingLevel: "low",
-              schema: AdvisoryVerdictSchema,
-            },
-          );
-          if (!judged) return null;
-          progress({ type: "counter_delta", key: `verdict.${judged.verdict.toLowerCase()}`, label: judged.verdict, delta: 1 });
-          if (judged.verdict === "REFUTED") {
-            refutedCandidateCount += 1;
-            progress({ type: "counter_delta", key: "refuted", label: "refuted", delta: 1 });
-          }
-          progress({
-            type: "lane_item",
-            lane: verdictLane(judged.verdict),
-            title: candidate.summary,
-            subtitle: formatLocation(candidate),
-            status: verdictStatus(judged.verdict),
-            details: formatEvidence(judged.evidence),
-          });
-          return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, confidence: judged.confidence, lens };
-        }),
-      );
-      return verdicts.filter((value): value is Verified => value !== null);
-    },
-  );
-
-  const verified = (perLens as Verified[][]).flat();
+  const pipelineResult = await runLensVerificationPipeline({
+    api: { agent, parallel, pipeline, progress, log },
+    lenses: REFACTOR_LENSES,
+    schedulingMode: "finder-barrier",
+    perLens: PER_LENS,
+    tools: TOOLS,
+    finderPrompt: (lens) =>
+      `## Refactor-scout finder — ${lens.label}\n\n${scopeBlock}\n` +
+      "This workflow is advisory-only: do not edit files and do not propose broad rewrites.\n" +
+      `Scout through ONLY this lens:\n${lens.text}\n\n` +
+      `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
+      "Each candidate must include a one-line summary, locations, impact on maintainability or future correctness, and an optional safe first recommendation. " +
+      "Only include opportunities where a small, reviewable first step is plausible. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Refactor-scout verifier\n\n${scopeBlock}\n## Candidate\n` +
+      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+      `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+      "Read the relevant files and return CONFIRMED, PLAUSIBLE, or REFUTED. " +
+      "Default toward REFUTED if the opportunity is generic, too broad, not evidenced by code, or lacks a safe first step. " +
+      "Evidence must quote or cite code. Structured output only.",
+    makeVerified: (candidate, lens, judged): Verified => ({
+      ...candidate,
+      verdict: judged.verdict,
+      evidence: judged.evidence,
+      confidence: judged.confidence,
+      lens,
+    }),
+  });
+  rawCandidateCount += pipelineResult.rawCandidates;
+  droppedCandidateCount += pipelineResult.dropped;
+  refutedCandidateCount += pipelineResult.refuted;
+  const verified = pipelineResult.verified;
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
   progress({ type: "counter", key: "verified", label: "verified", value: verified.length });
@@ -213,14 +163,9 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
 
   if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun the workflow with a narrower target."], stats);
 
-  const findings = report.findings.map((finding) => {
-    const source = ranked.find((candidate) => sameFinding(candidate, finding));
-    return {
-      ...finding,
-      evidence: finding.evidence.length > 0 ? finding.evidence : (source?.evidence ?? []),
-      impact: finding.impact || source?.impact || "Impact not restated by synthesis.",
-      recommendation: finding.recommendation || source?.recommendation || "Choose a small, behavior-preserving refactor first step.",
-    };
+  const findings = backfillAdvisoryFindings(report.findings, ranked, {
+    impact: "Impact not restated by synthesis.",
+    recommendation: "Choose a small, behavior-preserving refactor first step.",
   });
   return { ...report, findings, stats };
 }
@@ -229,61 +174,8 @@ function emptyReport(summary: string, nextSteps: string[], stats: WorkflowRunSta
   return { summary, findings: [], nextSteps, stats };
 }
 
-function primaryLocation(candidate: Pick<Candidate, "locations">): AdvisoryLocation {
-  return candidate.locations[0] ?? { file: "" };
-}
-
-function formatLocation(candidate: Pick<Candidate, "locations">): string {
-  const location = primaryLocation(candidate);
-  const line = location.line != null ? `:${location.line}` : "";
-  const symbol = location.symbol ? ` (${location.symbol})` : "";
-  return `${location.file}${line}${symbol}`;
-}
-
-function formatEvidence(evidence: string[]): string {
-  return evidence.join("; ");
-}
-
-function dedupKey(candidate: Candidate): string {
-  const location = primaryLocation(candidate);
-  const lineKey = location.line != null ? Math.round(location.line / 5) * 5 : "file";
-  return `${candidate.category}:${normalizePath(location.file)}:${lineKey}:${candidate.summary.slice(0, 60).toLowerCase()}`;
-}
-
-function normalizePath(path: string): string {
-  return path.replace(/^\.\//, "").replace(/^[ab]\//, "");
-}
-
 function rank(finding: Verified): number {
   const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
   const categoryRank = finding.category === "dead-code" || finding.category === "conventions" ? 2 : 0;
   return verdictRank + categoryRank;
 }
-
-function verdictLane(verdict: Verified["verdict"]): string {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "Confirmed";
-    case "PLAUSIBLE":
-      return "Plausible";
-    case "REFUTED":
-      return "Refuted";
-  }
-}
-
-function verdictStatus(verdict: Verified["verdict"]): "success" | "warning" | "error" {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "success";
-    case "PLAUSIBLE":
-      return "warning";
-    case "REFUTED":
-      return "error";
-  }
-}
-
-function sameFinding(candidate: Verified, finding: Pick<AdvisoryFinding, "locations" | "summary">): boolean {
-  const candidateLocation = primaryLocation(candidate);
-  const findingLocation = primaryLocation(finding);
-  return normalizePath(candidateLocation.file) === normalizePath(findingLocation.file) && candidateLocation.line === findingLocation.line;
-}

package/.pi/settings.json

@@ -0,0 +1,3 @@
+{
+  "extensions": ["extensions/pi-workflow-engine/index.ts"]
+}

package/README.md

@@ -2,7 +2,7 @@
 
 # pi-workflow-engine
 
-Claude Code style workflows for the [pi](https://pi.dev) coding agent.
+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.
 
@@ -10,7 +10,7 @@ The built-in workflows are advisory: they inspect, fan out, verify, and report.
 
 ## Why workflows matter
 
-Claude Code popularised a useful pattern: the best agentic coding work is not a single chat turn. It is a loop of context gathering, delegated action, verification, and synthesis. Its docs describe the [agentic loop](https://code.claude.com/docs/en/glossary#agentic-loop), [skills and commands](https://code.claude.com/docs/en/skills), and [subagents](https://code.claude.com/docs/en/glossary#subagent) as composable building blocks for repeatable engineering work.
+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:
 
@@ -35,7 +35,7 @@ Or from npm:
 pi install npm:pi-workflow-engine
 ```
 
-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. Restart pi, or run `/reload` in an open session, then confirm it is 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
@@ -93,7 +93,7 @@ The bundled review workflow is deliberately shaped like a serious review process
 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 `workflows/code-review.ts`. That is where your repo's real failure modes belong.
+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
 
@@ -151,36 +151,83 @@ git clone https://github.com/timbrinded/pi-workflow-engine
 cd pi-workflow-engine
 bun install
 bun run typecheck
-bun scripts/smoke.ts
+bun run test
 ```
 
-Load your working copy into a session without installing it. This is ephemeral and 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
+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 `--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:
+
+```bash
+pi -e . -p "/workflow ping"
+```
+
+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 ./src/index.ts -p "/workflow ping"
+pi -e . -p "/workflow ping"
 ```
 
-Add a workflow by creating `workflows/<name>.ts`, importing it in `src/workflows.ts`, and adding 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 on a best-effort basis.
+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 .
+```
+
+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 `workflows/code-review.ts`. Tune `model`, `thinkingLevel`, and `tools` per `agent()` call, and tune `DEFAULT_CONCURRENCY` in `src/engine.ts`.
+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
-src/
-  index.ts         extension entry; registers the command and tool
-  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/
-  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
+.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