pi-workflow-engine 0.4.0 → 0.6.1

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-result-renderer.ts

@@ -2,7 +2,9 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Box, type Component, Text } from "@earendil-works/pi-tui";
 import type { AdvisoryFinding, AdvisoryLocation, AdvisoryReport } from "../advisory-schema.ts";
 import type { PerfAggregate } from "../perf.ts";
-import { badge, formatCount, type WorkflowThemeColor } from "./workflow-format.ts";
+import { renderIssueDetails, renderIssuesTable } from "../review/review-format.ts";
+import { toReviewIssues, type ReviewContext } from "../review/review-issues.ts";
+import { formatCount } from "./workflow-format.ts";
 
 export interface WorkflowPerfDetails {
   readonly enabled: boolean;
@@ -19,6 +21,7 @@ export interface WorkflowResultEnvelope {
 
 export interface AdvisoryWorkflowResult extends AdvisoryReport {
   stats?: Record<string, string | number>;
+  reviewContext?: ReviewContext;
 }
 
 export function isWorkflowResult(value: unknown): value is WorkflowResultEnvelope {
@@ -82,33 +85,18 @@ function renderAdvisoryResult(name: string, result: AdvisoryWorkflowResult, expa
     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(renderAdvisoryFinding(finding, expanded, theme));
-  }
-  if (!expanded && result.findings.length > findings.length) {
-    lines.push(theme.fg("dim", `… ${result.findings.length - findings.length} more finding(s)`));
+  const issues = toReviewIssues(name, result);
+  lines.push(theme.fg("dim", "Findings:"));
+  lines.push(renderIssuesTable(issues, theme, { maxRows: expanded ? issues.length : 12 }));
+  if (expanded) {
+    for (const issue of issues) {
+      lines.push(renderIssueDetails(issue, theme));
+    }
   }
   if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
   return lines.join("\n");
 }
 
-function renderAdvisoryFinding(finding: AdvisoryFinding, expanded: boolean, theme: Theme): string {
-  const location = formatLocation(finding.locations[0]);
-  let text =
-    `  ${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) {
-    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) {
@@ -116,35 +104,6 @@ function renderNextSteps(nextSteps: string[], lines: string[], theme: Theme): vo
   }
 }
 
-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);

package/.pi/extensions/pi-workflow-engine/src/workflow-module.ts

@@ -0,0 +1,57 @@
+import type { WorkflowMeta, WorkflowModule } from "./types.ts";
+
+type WorkflowMetaCandidate = {
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly phases?: unknown;
+};
+
+type WorkflowModuleCandidate = {
+  readonly meta?: unknown;
+  readonly default?: unknown;
+};
+
+/** Validate and normalize workflow metadata without executing workflow code. */
+export function parseWorkflowMeta(value: unknown): { meta: WorkflowMeta } | { reason: string } {
+  if (!isRecord(value)) return { reason: "meta export must be an object" };
+  return parseWorkflowMetaObject(value);
+}
+
+export function parseWorkflowModule(value: unknown): { module: WorkflowModule } | { reason: string } {
+  if (!isRecord(value)) return { reason: "module export is not an object" };
+  const candidate = value as WorkflowModuleCandidate;
+  const meta = candidate.meta;
+  if (!isRecord(meta)) return { reason: "missing meta export" };
+
+  const parsedMeta = parseWorkflowMetaObject(meta);
+  if ("reason" in parsedMeta) return parsedMeta;
+  if (!isWorkflowRun(candidate.default)) return { reason: "default export must be a function" };
+
+  return { module: { meta: parsedMeta.meta, default: candidate.default } };
+}
+
+function parseWorkflowMetaObject(meta: WorkflowMetaCandidate): { meta: WorkflowMeta } | { reason: string } {
+  if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
+
+  const description = meta.description;
+  if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
+
+  const phases = meta.phases;
+  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
+
+  const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
+  if (phases !== undefined) workflowMeta.phases = phases;
+  return { meta: workflowMeta };
+}
+
+function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
+  return typeof value === "function";
+}
+
+function isWorkflowPhases(value: unknown): value is Array<{ title: string }> {
+  return Array.isArray(value) && value.every((phase) => isRecord(phase) && typeof phase.title === "string");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

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

@@ -1,6 +1,5 @@
 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";
@@ -19,6 +18,6 @@ import * as perfReview from "../workflows/perf-review.ts";
  * dynamically imported built-ins. Startup optimizations should happen at the extension
  * entrypoint/discovery boundary first.
  */
-export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, ping, refactorScout, diagnose, perfReview];
-export const BUILTIN_WORKFLOW_FILES = new Set(["code-review.ts", "ping.ts", "refactor-scout.ts", "diagnose.ts", "perf-review.ts"]);
+export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, refactorScout, diagnose, perfReview];
+export const BUILTIN_WORKFLOW_FILES = new Set(["code-review.ts", "refactor-scout.ts", "diagnose.ts", "perf-review.ts"]);
 export const BUILTIN_WORKFLOW_NAMES = BUILTIN_WORKFLOWS.map((mod) => mod.meta.name);

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

@@ -16,6 +16,7 @@ import {
   verdictConfidence,
 } from "../src/workflow-advisory-utils.ts";
 import { captureDiff } from "../src/diff-capture.ts";
+import type { ReviewContext } from "../src/review/review-issues.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
@@ -137,6 +138,15 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   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) };
   }
+
+  const reviewContext: ReviewContext = {
+    workflowName: "code-review",
+    target,
+    diffCommand: scope.diffCommand,
+    files: scope.files,
+    summary: scope.summary,
+  };
+
   log(`${scope.files.length} changed files`);
 
   // Capture the diff once, deterministically, so findings can be bounded to changed lines in code.
@@ -259,7 +269,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   log(`${verified.length} verified → ${surviving.length} kept`);
 
   if (surviving.length === 0) {
-    return { summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats };
+    return { summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats, reviewContext };
   }
 
   // ─── Synthesize: rank, merge, report ───
@@ -283,10 +293,10 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
   );
 
-  if (!report) return { summary: "Synthesis produced no output.", findings: [], nextSteps: ["Re-run the workflow or inspect verifier evidence manually."], stats };
+  if (!report) return { summary: "Synthesis produced no output.", findings: [], nextSteps: ["Re-run the workflow or inspect verifier evidence manually."], stats, reviewContext };
 
   const findings = backfillAdvisoryFindings(report.findings, ranked, {
     impact: "Impact not restated by synthesis.",
   });
-  return { ...report, findings, stats };
+  return { ...report, findings, stats, reviewContext };
 }

package/README.md

@@ -55,6 +55,8 @@ pi remove git:github.com/timbrinded/pi-workflow-engine
 
 ## Usage
 
+For the complete installation, invocation, authoring, tuning, and troubleshooting guide, see [USAGE.md](USAGE.md).
+
 In a pi session, from inside a git repo with changes:
 
 ```text
@@ -63,25 +65,40 @@ In a pi session, from inside a git repo with changes:
 /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
+/workflow code-review --inspect  # open the live workflow inspector while the run is active
+/workflow:inspector              # reopen the last completed workflow inspector
+/workflow code-review --result-viewer     # explicitly open the post-review results viewer
+/workflow code-review --review-viewer     # alias for --result-viewer
+/workflow code-review --no-result-viewer  # explicitly keep the post-review viewer closed
 ```
 
-The host agent can also invoke the `workflow` tool mid-conversation:
+The host agent can also invoke the `workflow` tool mid-conversation. It accepts either a registered workflow `name` or a one-off inline workflow `script`:
 
 ```text
 Run the code-review workflow on this PR and use the result before deciding what to fix.
 ```
 
+Opt into dynamic multi-agent orchestration with the literal `dynamax` token, or keep it sticky for the session:
+
+```text
+dynamax inspect this bug with multiple focused agents
+/workflow:dynamax on
+/workflow:dynamax status
+/workflow:dynamax off
+```
+
+`dynamax` is a permission signal for the host agent: once opted in, it may run an existing named workflow or author an inline workflow script through the `workflow` tool. 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 author/run a temporary inline workflow.
+
 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.
 
+The package also ships the `workflow-code-review-actions` skill. When you select review findings in the results viewer, the parent agent can use that skill to either make minimal local fixes or raise GitHub PR inline comments through GitHub MCP/tools or `gh`.
+
 ## 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
 
@@ -93,6 +110,22 @@ 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.
 
+After a direct TUI `/workflow code-review` run produces findings, pi records a readable table-formatted result message without asking whether to open another surface. Use `--result-viewer`/`--review-viewer` when you want the interactive findings viewer to open immediately, or `--no-result-viewer`/`--no-review-viewer` when a script or alias should explicitly keep it closed. Use `/workflow:inspector` after a run to reopen the last completed workflow inspector.
+
+Viewer controls:
+
+- `↑`/`↓`: move between findings.
+- `1`-`9`: jump directly to a visible finding.
+- `space`: tag/untag the current finding.
+- `a`: tag or untag all visible findings.
+- `enter`: expand/collapse the detail pane.
+- `←`/`→` or `pageup`/`pagedown`: scroll detail text.
+- `f`: hand selected findings to the parent agent for minimal local fixes.
+- `c`: comment on selected findings upstream.
+- `q`/`escape`: close the viewer.
+
+GitHub inline comments require a GitHub PR checkout, an authenticated `gh`, and findings with changed-file line numbers. If direct PR context resolution or posting is unavailable, the viewer queues a parent-agent fallback prompt that can use installed GitHub MCP/tools, project skills, or `gh`. Workflow tool invocations remain non-interactive: they do not prompt or open the viewer, and they return table-formatted results only.
+
 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
@@ -135,12 +168,33 @@ export default async function run({ agent, parallel, phase }: WorkflowApi) {
 }
 ```
 
+Inline workflow scripts use the same primitives, but are passed as a string to the `workflow` tool instead of being saved as files. A minimal inline workflow starts with `export const meta` and uses the injected Type object for schemas:
+
+```ts
+export const meta = {
+  name: "inline-review",
+  description: "One-off focused review workflow.",
+};
+
+export default async function run({ agent, parallel, phase, args }) {
+  phase("Find");
+  const Finding = Type.Object({ summary: Type.String() });
+  const findings = await parallel([
+    () => agent(`Find correctness issues: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+    () => agent(`Find edge cases: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+  ]);
+  return { summary: JSON.stringify(findings) };
+}
+```
+
+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. This v1 path is permissive rather than sandboxed.
+
 Under the hood:
 
 - **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.
+- **Three surfaces are registered**: `/workflow <name> [args]` for direct use, grouped workflow commands such as `/workflow:dynamax on|off|status` and `/workflow:inspector`, and a `workflow` tool for host-agent delegation by `name` or inline `script`.
 
 ## Local development
 
@@ -177,11 +231,7 @@ 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"
-```
+Add `--out` to write machine-local JSON under `.artifacts/benchmarks/`. These timings are advisory, not portable thresholds.
 
 Guardrails:
 
@@ -192,7 +242,7 @@ Guardrails:
 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"
+pi -e .
 ```
 
 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:
@@ -227,7 +277,6 @@ Tune the built-in review workflow by editing the `ANGLES` array in `.pi/extensio
       refactor-scout.ts                 advisory refactor opportunities
       diagnose.ts                       advisory bug diagnosis
       perf-review.ts                    advisory performance investigation
-      ping.ts                           minimal smoke workflow
 ```
 
 ## License

package/USAGE.md

@@ -0,0 +1,189 @@
+# Usage
+
+`pi-workflow-engine` adds multi-agent workflows to pi. Most users only need two surfaces:
+
+- `/workflow <name> [args]` to run a saved workflow directly.
+- `/workflow:*` commands for related actions such as inspector reopening and dynamax sticky mode.
+- `dynamax` as a literal one-shot opt-in token when you want the host agent to author a one-off inline workflow for investigation/review.
+
+## Run a workflow
+
+From inside a repo:
+
+```text
+/workflow code-review
+/workflow code-review HEAD~3
+/workflow refactor-scout src/
+/workflow diagnose "typecheck fails after the schema change"
+/workflow perf-review "workflow startup latency"
+```
+
+The built-in workflows are advisory. They inspect, verify, and report; they do **not** edit files.
+
+Useful flags:
+
+```text
+/workflow code-review --inspect          # show the live inspector while the run is active
+/workflow:inspector                      # reopen the last completed workflow inspector
+/workflow code-review --result-viewer    # explicitly open the findings viewer
+/workflow code-review --review-viewer    # alias for --result-viewer
+/workflow code-review --concurrency=4    # cap concurrent subagents
+/workflow code-review --refresh          # rediscover newly added workflow files
+```
+
+## Built-in workflows
+
+| Name | Purpose |
+| --- | --- |
+| `code-review` | Reviews a PR, branch diff, ref range, or focus area. |
+| `refactor-scout` | Finds small, safe refactor opportunities. |
+| `diagnose` | Investigates a bug, failing command, or regression. |
+| `perf-review` | Reviews a slow path or performance concern. |
+
+`code-review` auto-detects a diff when you do not pass args. If there is an open GitHub PR for the current branch, it uses that PR diff; otherwise it falls back to branch-vs-main/master or `HEAD~1`.
+
+## Use `dynamax` for inline workflows
+
+Use `dynamax` when the built-in workflows are not specific enough and you want the main pi agent to author a temporary workflow for the current question.
+
+Interactive shortcut: run `/workflow` with no arguments, choose `✍ Author temporary one-shot workflow…`, and type a brief. pi will send that brief back to the host agent as a `dynamax` request so it can author and run an inline workflow with the `workflow` tool's `script` argument.
+
+That inline workflow should investigate, fan out, verify, and summarize. It is **not** where code edits happen. If you want changes made, use the workflow result as evidence and then ask pi to edit separately.
+
+One-off examples:
+
+```text
+dynamax author an inline workflow to investigate why typecheck is failing
+dynamax create a one-off workflow to compare the parser and tests before we change code
+dynamax use parallel agents to review this design and report the risks
+```
+
+Sticky for the session:
+
+```text
+/workflow:dynamax on
+/workflow:dynamax off
+/workflow:dynamax status
+```
+
+With dynamax enabled, the host agent usually calls the `workflow` tool with `script`: a one-off inline workflow. It can still call a saved workflow by `name` when one already fits.
+
+## Workflow results
+
+Workflow results are rendered in pi with:
+
+- summary;
+- ranked findings;
+- locations and evidence;
+- recommendations;
+- next steps;
+- run stats when available.
+
+During a run, pi shows live phases and subagent status. Use `--inspect` if you want a larger live view while the workflow is active, then `/workflow:inspector` if you want to bring the last completed inspector back up afterward.
+
+Code-review findings are rendered as a formatted result message by default. pi no longer asks whether to open the findings viewer. Use `--result-viewer` or `--review-viewer` when you want to inspect findings interactively, press `enter` to expand/collapse the nicely formatted finding text, and use `1`-`9` to jump directly to a visible finding.
+
+## Author a saved workflow
+
+Saved workflows are TypeScript modules with `meta` plus a default async function:
+
+```ts
+import { Type } from "typebox";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "my-workflow",
+  description: "Find and summarize something important.",
+};
+
+const Finding = Type.Object({
+  summary: Type.String(),
+});
+
+export default async function run({ agent, parallel, phase, args }: WorkflowApi) {
+  phase("Find");
+  const findings = await parallel([
+    () => agent(`Find correctness issues: ${args}`, { schema: Finding, tools: ["read", "bash"], thinkingLevel: "low" }),
+    () => agent(`Find edge cases: ${args}`, { schema: Finding, tools: ["read", "bash"], thinkingLevel: "low" }),
+  ]);
+
+  phase("Synthesize");
+  return agent(`Summarize: ${JSON.stringify(findings)}`, { thinkingLevel: "medium" });
+}
+```
+
+Core primitives:
+
+| Primitive | What it does |
+| --- | --- |
+| `agent(prompt, opts)` | Runs one isolated subagent. With `schema`, returns validated structured data. |
+| `parallel(thunks)` | Runs thunks concurrently and waits for all. |
+| `pipeline(items, ...stages)` | Runs each item through stages independently. |
+| `phase(title)` / `log(message)` | Updates workflow progress UI. |
+| `progress(event)` | Emits counters, summaries, and lane items. |
+
+Set `thinkingLevel` on fan-out agents. Otherwise many subagents can inherit an expensive global reasoning level.
+
+### Where workflows live
+
+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.
+
+## Author an inline workflow
+
+Inline workflows are passed to the `workflow` tool as a script string. They are useful for one-off dynamax orchestration.
+
+```ts
+export const meta = {
+  name: "inline-review",
+  description: "One-off focused review.",
+};
+
+export default async function run({ agent, parallel, phase, args }) {
+  phase("Find");
+  const Finding = Type.Object({ summary: Type.String() });
+  const findings = await parallel([
+    () => agent(`Find correctness issues: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+    () => agent(`Find edge cases: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+  ]);
+  return { summary: JSON.stringify(findings) };
+}
+```
+
+Inline rules:
+
+- start with `export const meta = { ... }`;
+- default-export an async workflow function;
+- no imports or dynamic `import()`;
+- use the injected `Type` object for schemas;
+- no extra exports or code after the default export.
+
+Inline workflows run in-process with extension permissions, so treat them as trusted task automation.
+
+## Runtime knobs
+
+Only tune these when a workflow is too slow, too expensive, or too noisy:
+
+| Knob | Meaning |
+| --- | --- |
+| `--concurrency=N` / `PI_WORKFLOW_CONCURRENCY=N` | Cap concurrent subagents. Default is `min(8, max(2, CPU count))`. |
+| `--parallel-limit=N` / `PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT=N` | Limit eager `parallel()` submission. |
+| `--perf` / `PI_WORKFLOW_PERF=1` | Include internal timing aggregates. |
+| `PI_WORKFLOW_LANE_ITEM_LIMIT=N` | Cap retained progress lane items. |
+
+## Common fixes
+
+- **Unknown workflow**: confirm the extension is loaded with `pi list`; use `--refresh` for new drop-ins.
+- **Inline compile error**: check the inline rules above.
+- **Slow run**: lower fan-out, set `thinkingLevel`, or reduce `--concurrency`.
+- **Duplicate command/tool warnings while developing**: avoid loading both the global package and the working copy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "A customisable multi-agent workflow-orchestration engine for the pi coding agent.",
   "keywords": [
@@ -24,11 +24,14 @@
     ".pi/extensions/pi-workflow-engine",
     ".pi/settings.json",
     "assets",
+    "skills",
     "README.md",
+    "USAGE.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [".pi/extensions/pi-workflow-engine/index.ts"],
+    "skills": ["skills"],
     "image": "https://raw.githubusercontent.com/timbrinded/pi-workflow-engine/master/assets/preview.png"
   },
   "scripts": {

package/skills/workflow-code-review-actions/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: workflow-code-review-actions
+description: "Act on selected code-review findings from pi-workflow-engine: make minimal fixes or post GitHub PR inline comments using gh, GitHub MCP/tools, or project-specific tools."
+---
+
+Use this skill when the parent agent receives selected code-review finding JSON from `pi-workflow-engine`.
+
+## Inputs
+
+The prompt will include compact JSON with:
+
+- `context`: workflow name, target, diff command, changed files, and optional summary.
+- `issues`: selected findings with `id`, `summary`, `category`, `severity`, `confidence`, `location`, `impact`, `evidence`, and `recommendation`.
+
+## Fix mode
+
+When mode is `fix selected code-review findings`:
+
+1. Inspect the selected issue JSON before editing.
+2. Make minimal edits that address only the selected findings.
+3. Preserve unrelated user changes and avoid broad refactors.
+4. Run focused validation if available for the touched files or behavior.
+5. Summarize changed files and validation results.
+6. Do not post GitHub PR comments in fix mode.
+
+## Comment mode
+
+When mode is `post inline GitHub PR comments`:
+
+1. Do not edit files or make code changes.
+2. Prefer installed GitHub MCP/tools if visible in the active tool list.
+3. If no GitHub MCP/tools are available, use `gh`:
+   - Resolve the PR with `gh pr view --json number,headRefOid,url,headRepositoryOwner,headRepository`.
+   - Resolve the repository with `gh repo view --json nameWithOwner` when owner/name is missing.
+   - Post each inline comment with `gh api repos/{owner}/{repo}/pulls/{number}/comments` and include `commit_id`, `path`, `line`, and `side=RIGHT`.
+4. Keep each comment concise: summary, severity/confidence/category, impact, evidence, and recommendation.
+5. Report posted, skipped, and failed counts.
+
+## Safety rules
+
+- Do not post duplicate comments.
+- Do not comment line-less findings inline.
+- Ask the user if the upstream PR cannot be identified.
+- Keep actions scoped to the selected issue IDs only.

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

@@ -1,29 +0,0 @@
-import { Type } from "typebox";
-import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
-
-/** Minimal engine smoke test: a single structured-output agent call. Fast + cheap. */
-export const meta: WorkflowMeta = {
-  name: "ping",
-  description: "Engine smoke test — one structured agent call, no tools.",
-  phases: [{ title: "Ping" }],
-};
-
-export default async function run(api: WorkflowApi): Promise<unknown> {
-  const { agent, phase, log } = api;
-  phase("Ping");
-  log("calling one structured agent");
-  const result = await agent(
-    "You are a code-review workflow engine. Return a one-word headline and a one-sentence summary of what you do.",
-    {
-      phase: "Ping",
-      label: "ping",
-      tools: [],
-      thinkingLevel: "low",
-      schema: Type.Object({
-        headline: Type.String({ description: "One word" }),
-        summary: Type.String({ description: "One sentence" }),
-      }),
-    },
-  );
-  return result ?? { headline: "none", summary: "no structured answer returned" };
-}