pi-workflow-engine 0.2.0 → 0.3.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.
+Claude Code style 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
+
+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.
+
+`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,154 @@ 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. 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:
+
+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.
 
-A **workflow** is a TypeScript module that exports `meta` plus a default `async (api) => result`. The injected `api` gives you five primitives:
+The review lenses live in `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.",
+};
+
+const FindingSchema = Type.Object({
+  summary: Type.String(),
+  file: Type.String(),
+  line: Type.Optional(Type.Number()),
+});
 
-export default async function run({ agent, parallel, pipeline, phase, log, args }: WorkflowApi) {
+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 scripts/smoke.ts
 ```
 
-Load your working copy into a session without installing it (ephemeral — overrides nothing):
+Load your working copy into a session without installing it. This is ephemeral and overrides nothing:
 
 ```bash
 pi -e ./src/index.ts -p "/workflow ping"
 ```
 
-**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 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.
 
-**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`.
+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`.
 
 ### Layout
 
-```
+```text
 src/
-  index.ts         extension entry (registers the command + tool)
+  index.ts         extension entry; registers the command and tool
   types.ts         WorkflowApi / WorkflowModule contracts
-  agent-runner.ts  the createAgentSession + terminating-tool schema bridge
+  agent-runner.ts  createAgentSession + terminating-tool schema bridge
   concurrency.ts   Semaphore, parallel(), pipeline()
-  engine.ts        runWorkflow() — binds the primitives to a run
+  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   the example: scope → find → verify → synthesize
-  ping.ts          minimal smoke workflow
+  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,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A customisable multi-agent workflow-orchestration engine for the pi coding agent.",
   "keywords": ["pi-package"],

package/src/advisory-schema.ts

@@ -0,0 +1,64 @@
+import { Type, type Static } from "typebox";
+
+export const AdvisorySeveritySchema = Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")], {
+  description: "Impact level of an advisory finding.",
+});
+
+export const AdvisoryConfidenceSchema = Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")], {
+  description: "Confidence that the finding is actionable.",
+});
+
+export const AdvisoryVerifierVerdictSchema = Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED")], {
+  description: "Verifier judgment for a candidate finding.",
+});
+
+export const AdvisoryLocationSchema = Type.Object({
+  file: Type.String({ description: "Repository-relative file path." }),
+  line: Type.Optional(Type.Number({ description: "Relevant 1-based line number when known." })),
+  symbol: Type.Optional(Type.String({ description: "Relevant function, class, type, or other symbol when known." })),
+});
+
+export const AdvisoryCandidateSchema = Type.Object({
+  summary: Type.String({ description: "One-line candidate finding or hypothesis." }),
+  category: Type.String({ description: "Workflow-specific category such as bug, duplication, root-cause, or io." }),
+  locations: Type.Array(AdvisoryLocationSchema, { description: "Relevant code or configuration locations." }),
+  impact: Type.String({ description: "Concrete consequence if this candidate is real." }),
+  recommendation: Type.Optional(Type.String({ description: "Optional first-step recommendation before synthesis." })),
+});
+
+export const AdvisoryCandidatesSchema = Type.Object({
+  candidates: Type.Array(AdvisoryCandidateSchema, { description: "Candidate advisory findings or hypotheses." }),
+});
+
+export const AdvisoryVerdictSchema = Type.Object({
+  verdict: AdvisoryVerifierVerdictSchema,
+  evidence: Type.Array(Type.String({ description: "Quoted or cited evidence supporting the verdict." })),
+  confidence: Type.Optional(AdvisoryConfidenceSchema),
+});
+
+export const AdvisoryFindingSchema = Type.Object({
+  summary: Type.String({ description: "One-line final finding." }),
+  category: Type.String({ description: "Workflow-specific category for grouping and display." }),
+  severity: AdvisorySeveritySchema,
+  confidence: AdvisoryConfidenceSchema,
+  locations: Type.Array(AdvisoryLocationSchema, { description: "Relevant code or configuration locations." }),
+  evidence: Type.Array(Type.String({ description: "Quoted or cited evidence." })),
+  impact: Type.String({ description: "Concrete user, runtime, maintenance, or performance impact." }),
+  recommendation: Type.String({ description: "Advisory next action; not an automatic edit." }),
+});
+
+export const AdvisoryReportSchema = Type.Object({
+  summary: Type.String({ description: "Short overall advisory summary." }),
+  findings: Type.Array(AdvisoryFindingSchema, { description: "Verified and ranked advisory findings." }),
+  nextSteps: Type.Array(Type.String({ description: "Concrete follow-up commands, inspections, or decisions." })),
+});
+
+export type AdvisorySeverity = Static<typeof AdvisorySeveritySchema>;
+export type AdvisoryConfidence = Static<typeof AdvisoryConfidenceSchema>;
+export type AdvisoryVerifierVerdict = Static<typeof AdvisoryVerifierVerdictSchema>;
+export type AdvisoryLocation = Static<typeof AdvisoryLocationSchema>;
+export type AdvisoryCandidate = Static<typeof AdvisoryCandidateSchema>;
+export type AdvisoryCandidates = Static<typeof AdvisoryCandidatesSchema>;
+export type AdvisoryVerdict = Static<typeof AdvisoryVerdictSchema>;
+export type AdvisoryFinding = Static<typeof AdvisoryFindingSchema>;
+export type AdvisoryReport = Static<typeof AdvisoryReportSchema>;

package/src/ui/workflow-result-renderer.ts

@@ -1,6 +1,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Box, type Component, Text } from "@earendil-works/pi-tui";
-import { badge, formatCount } from "./workflow-format.ts";
+import type { AdvisoryFinding, AdvisoryLocation, AdvisoryReport } from "../advisory-schema.ts";
+import { badge, formatCount, type WorkflowThemeColor } from "./workflow-format.ts";
 
 export interface WorkflowResultEnvelope {
   name: string;
@@ -8,19 +9,7 @@ export interface WorkflowResultEnvelope {
   completedAt: number;
 }
 
-export interface CodeReviewFinding {
-  file: string;
-  line?: number;
-  severity?: string;
-  verdict?: string;
-  summary: string;
-  evidence?: string;
-  failure_scenario?: string;
-}
-
-export interface CodeReviewResult {
-  summary: string;
-  findings: CodeReviewFinding[];
+export interface AdvisoryWorkflowResult extends AdvisoryReport {
   stats?: Record<string, string | number>;
 }
 
@@ -29,21 +18,32 @@ export function isWorkflowResult(value: unknown): value is WorkflowResultEnvelop
   return typeof value.name === "string" && "result" in value && typeof value.completedAt === "number";
 }
 
-export function isFinding(value: unknown): value is CodeReviewFinding {
+export function isAdvisoryLocation(value: unknown): value is AdvisoryLocation {
   if (!isRecord(value)) return false;
-  if (typeof value.file !== "string" || typeof value.summary !== "string") return false;
+  if (typeof value.file !== "string") return false;
   if (value.line !== undefined && typeof value.line !== "number") return false;
-  if (value.severity !== undefined && typeof value.severity !== "string") return false;
-  if (value.verdict !== undefined && typeof value.verdict !== "string") return false;
-  if (value.evidence !== undefined && typeof value.evidence !== "string") return false;
-  if (value.failure_scenario !== undefined && typeof value.failure_scenario !== "string") return false;
+  if (value.symbol !== undefined && typeof value.symbol !== "string") return false;
+  return true;
+}
+
+export function isAdvisoryFinding(value: unknown): value is AdvisoryFinding {
+  if (!isRecord(value)) return false;
+  if (typeof value.summary !== "string") return false;
+  if (typeof value.category !== "string") return false;
+  if (!isSeverity(value.severity)) return false;
+  if (!isConfidence(value.confidence)) return false;
+  if (!Array.isArray(value.locations) || !value.locations.every(isAdvisoryLocation)) return false;
+  if (!Array.isArray(value.evidence) || !value.evidence.every((entry) => typeof entry === "string")) return false;
+  if (typeof value.impact !== "string") return false;
+  if (typeof value.recommendation !== "string") return false;
   return true;
 }
 
-export function isCodeReviewResult(value: unknown): value is CodeReviewResult {
+export function isAdvisoryReport(value: unknown): value is AdvisoryWorkflowResult {
   if (!isRecord(value)) return false;
   if (typeof value.summary !== "string" || !Array.isArray(value.findings)) return false;
-  if (!value.findings.every(isFinding)) return false;
+  if (!value.findings.every(isAdvisoryFinding)) return false;
+  if (!Array.isArray(value.nextSteps) || !value.nextSteps.every((entry) => typeof entry === "string")) return false;
   if (value.stats !== undefined && !isStats(value.stats)) return false;
   return true;
 }
@@ -55,13 +55,13 @@ export function renderWorkflowResult(name: string, result: unknown, expanded: bo
 }
 
 export function renderWorkflowResultText(name: string, result: unknown, expanded: boolean, theme: Theme): string {
-  if (name === "code-review" && isCodeReviewResult(result)) {
-    return renderCodeReviewResult(name, result, expanded, theme);
+  if (isAdvisoryReport(result)) {
+    return renderAdvisoryResult(name, result, expanded, theme);
   }
   return renderGenericWorkflowResult(name, result, expanded, theme);
 }
 
-function renderCodeReviewResult(name: string, result: CodeReviewResult, expanded: boolean, theme: Theme): string {
+function renderAdvisoryResult(name: string, result: AdvisoryWorkflowResult, expanded: boolean, theme: Theme): string {
   const icon = theme.fg("success", "✓");
   const title = theme.fg("accent", theme.bold(`Workflow: ${name}`));
   const lines = [`${icon} ${title}`, theme.fg("muted", result.summary)];
@@ -70,35 +70,73 @@ function renderCodeReviewResult(name: string, result: CodeReviewResult, expanded
 
   if (result.findings.length === 0) {
     lines.push(theme.fg("success", "No findings."));
+    if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
     return lines.join("\n");
   }
 
   const findings = expanded ? result.findings : result.findings.slice(0, 3);
   lines.push(theme.fg("dim", expanded ? "Findings:" : "Top findings:"));
   for (const finding of findings) {
-    lines.push(renderFinding(finding, expanded, theme));
+    lines.push(renderAdvisoryFinding(finding, expanded, theme));
   }
   if (!expanded && result.findings.length > findings.length) {
     lines.push(theme.fg("dim", `… ${result.findings.length - findings.length} more finding(s)`));
   }
+  if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
   return lines.join("\n");
 }
 
-function renderFinding(finding: CodeReviewFinding, expanded: boolean, theme: Theme): string {
-  const location = `${finding.file}${finding.line != null ? `:${finding.line}` : ""}`;
-  const severityColor = finding.severity === "bug" ? "error" : "warning";
-  const verdictColor = finding.verdict === "CONFIRMED" ? "success" : finding.verdict === "PLAUSIBLE" ? "warning" : "muted";
+function renderAdvisoryFinding(finding: AdvisoryFinding, expanded: boolean, theme: Theme): string {
+  const location = formatLocation(finding.locations[0]);
   let text =
-    `  ${badge(finding.severity ?? "finding", severityColor, theme)} ` +
-    `${badge(finding.verdict ?? "", verdictColor, theme)} ` +
+    `  ${badge(finding.category, "accent", theme)} ` +
+    `${badge(finding.severity, severityColor(finding.severity), theme)} ` +
+    `${badge(`${finding.confidence} confidence`, confidenceColor(finding.confidence), theme)} ` +
     `${theme.fg("accent", location)} ${theme.fg("muted", finding.summary)}`;
   if (expanded) {
-    if (finding.failure_scenario) text += `\n    ${theme.fg("dim", `Failure: ${finding.failure_scenario}`)}`;
-    if (finding.evidence) text += `\n    ${theme.fg("dim", `Evidence: ${finding.evidence}`)}`;
+    text += `\n    ${theme.fg("dim", `Impact: ${finding.impact}`)}`;
+    text += `\n    ${theme.fg("dim", `Evidence: ${finding.evidence.join("; ") || "(none cited)"}`)}`;
+    text += `\n    ${theme.fg("dim", `Recommendation: ${finding.recommendation}`)}`;
   }
   return text;
 }
 
+function renderNextSteps(nextSteps: string[], lines: string[], theme: Theme): void {
+  lines.push(theme.fg("dim", "Next steps:"));
+  for (const step of nextSteps) {
+    lines.push(`  - ${theme.fg("muted", step)}`);
+  }
+}
+
+function formatLocation(location: AdvisoryLocation | undefined): string {
+  if (!location) return "(no location)";
+  const line = location.line != null ? `:${location.line}` : "";
+  const symbol = location.symbol ? ` (${location.symbol})` : "";
+  return `${location.file}${line}${symbol}`;
+}
+
+function severityColor(severity: AdvisoryFinding["severity"]): WorkflowThemeColor {
+  switch (severity) {
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}
+
+function confidenceColor(confidence: AdvisoryFinding["confidence"]): WorkflowThemeColor {
+  switch (confidence) {
+    case "high":
+      return "success";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}
+
 function renderGenericWorkflowResult(name: string, result: unknown, expanded: boolean, theme: Theme): string {
   const lines = [`${theme.fg("success", "✓")} ${theme.fg("accent", theme.bold(`Workflow: ${name}`))}`];
   const summary = extractSummary(result);
@@ -139,6 +177,14 @@ function safeJson(value: unknown): string {
   }
 }
 
+function isSeverity(value: unknown): value is AdvisoryFinding["severity"] {
+  return value === "low" || value === "medium" || value === "high";
+}
+
+function isConfidence(value: unknown): value is AdvisoryFinding["confidence"] {
+  return value === "low" || value === "medium" || value === "high";
+}
+
 function isStats(value: unknown): value is Record<string, string | number> {
   if (!isRecord(value)) return false;
   return Object.values(value).every((entry) => typeof entry === "string" || typeof entry === "number");

package/src/workflows.ts

@@ -1,6 +1,9 @@
 import type { WorkflowModule } from "./types.ts";
 import * as codeReview from "../workflows/code-review.ts";
 import * as ping from "../workflows/ping.ts";
+import * as refactorScout from "../workflows/refactor-scout.ts";
+import * as diagnose from "../workflows/diagnose.ts";
+import * as perfReview from "../workflows/perf-review.ts";
 
 /**
  * Workflows statically imported by the extension. These are loaded through pi's own
@@ -11,4 +14,4 @@ import * as ping from "../workflows/ping.ts";
  * it to this array. (Drop-in workflows discovered at runtime are also supported — see
  * discovery.ts — but the static registry is the always-correct path.)
  */
-export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, ping];
+export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, ping, refactorScout, diagnose, perfReview];