pi-workflow-engine 0.5.0 → 0.7.0

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

@@ -65,7 +65,11 @@ 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 code-review --inspect  # open the live workflow inspector while the run is active
+/workflow:inspector              # open the current or last 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. It accepts either a registered workflow `name` or a one-off inline workflow `script`:
@@ -78,15 +82,17 @@ Opt into dynamic multi-agent orchestration with the literal `dynamax` token, or
 
 ```text
 dynamax inspect this bug with multiple focused agents
-/dynamax on
-/dynamax status
-/dynamax off
+/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.
+`dynamax` is a one-shot 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. Dynamax workflow-tool runs open the live workflow inspector in the TUI while they run. `/workflow:dynamax on|off|status` controls sticky mode, and `/hotkeys` shows the registered inspector shortcut (`ctrl+shift+m` by default). Sticky mode, one-shot pending mode, and active Dynamax workflow runs show compact status with the relevant commands while active and leave no persistent UI when cleared. 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.
@@ -104,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` during or after a run to open the 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
@@ -172,7 +194,7 @@ 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.
-- **Three surfaces are registered**: `/workflow <name> [args]` for direct use, `/dynamax on|off|status` for sticky orchestration opt-in, and a `workflow` tool for host-agent delegation by `name` or inline `script`.
+- **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
 
@@ -186,7 +208,7 @@ bun run typecheck
 bun run test
 ```
 
-The test suite is no-LLM and uses Bun's built-in `bun test` runner, not a third-party test framework.
+Typechecking uses TypeScript Native Preview (`tsgo`) through `bun run typecheck`. 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
 

package/USAGE.md

@@ -1,9 +1,10 @@
 # Usage
 
-`pi-workflow-engine` adds multi-agent workflows to pi. Most users only need two surfaces:
+`pi-workflow-engine` adds multi-agent workflows to pi. Most users only need these surfaces:
 
 - `/workflow <name> [args]` to run a saved workflow directly.
-- `dynamax` when you want the host agent to author a one-off inline workflow for investigation/review.
+- `/workflow:*` commands for related actions such as inspector reopening and Dynamax control.
+- `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
 
@@ -22,7 +23,10 @@ The built-in workflows are advisory. They inspect, verify, and report; they do *
 Useful flags:
 
 ```text
-/workflow code-review --inspect          # show live inspector
+/workflow code-review --inspect          # show the live inspector while the run is active
+/workflow:inspector                      # open the current or last 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
 ```
@@ -54,15 +58,33 @@ dynamax create a one-off workflow to compare the parser and tests before we chan
 dynamax use parallel agents to review this design and report the risks
 ```
 
-Sticky for the session:
+Sticky mode and inspector shortcut:
 
 ```text
-/dynamax on
-/dynamax off
-/dynamax status
+/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.
+The workflow inspector is also registered as a first-class shortcut shown by `/hotkeys`; the default is `ctrl+shift+m`. `ctrl+o` is intentionally not used because pi already uses it for tool-output expansion and tree filtering.
+
+When only the literal `dynamax` token is used, the opt-in is one-shot: the next agent run receives the workflow permission reminder, stays visibly active for that run, then clears after the run ends. When `/workflow:dynamax on` is used, the opt-in is sticky for the current pi session until `/workflow:dynamax off`. Sticky mode, one-shot pending mode, and active Dynamax workflow runs show compact TUI status with `/workflow:dynamax on|off` and the inspector shortcut; off mode clears that status line.
+
+When the host agent calls the `workflow` tool from a TUI session, pi opens the live workflow inspector for that run. The compact workflow widget still shows the latest moving status above the editor, but the inspector is the richer view for phases, agents, findings, and logs.
+
+Configure the inspector shortcut by creating `~/.pi/agent/extensions/pi-workflow-engine.json`:
+
+```json
+{
+  "shortcuts": {
+    "inspector": "ctrl+shift+x"
+  }
+}
+```
+
+Set `"inspector": null` to disable the shortcut while keeping `/workflow:dynamax` and `/workflow:inspector` available.
+
+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
 
@@ -75,7 +97,9 @@ Workflow results are rendered in pi with:
 - 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.
+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
 
@@ -115,9 +139,23 @@ Core primitives:
 | `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. |
+| `workflow(ref, args?)` | Runs another workflow inline as a sub-step and returns its result. |
 
 Set `thinkingLevel` on fan-out agents. Otherwise many subagents can inherit an expensive global reasoning level.
 
+### Compose workflows
+
+`workflow(ref, args?)` runs a registered workflow by name as a sub-step, returning its result. The child shares the parent run's concurrency cap, abort signal, and perf timing, and its phases nest under `<name> ▸ <phase>` in the live UI.
+
+```ts
+export default async function run({ workflow }: WorkflowApi) {
+  const review = await workflow("code-review", "HEAD~3");
+  return { review };
+}
+```
+
+Nesting is one level only: calling `workflow()` from inside a sub-workflow rejects. Resolution throws on an unknown name — wrap the call in `try/catch` if a missing sub-workflow should be non-fatal (note `parallel()` rejects the whole batch on the first error, so catch inside each thunk for per-branch resilience).
+
 ### Where workflows live
 
 Guaranteed built-ins are statically registered:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "A customisable multi-agent workflow-orchestration engine for the pi coding agent.",
   "keywords": [
@@ -23,18 +23,20 @@
   "files": [
     ".pi/extensions/pi-workflow-engine",
     ".pi/settings.json",
-    "assets",
+    "assets/preview.png",
+    "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": {
-    "typecheck": "tsc --noEmit",
-    "test": "bun test",
+    "typecheck": "tsgo --noEmit",
+    "test": "bun test --timeout=30000",
     "test:changedlines": "bun test tests/changedlines.test.ts",
     "test:concurrency": "bun test tests/concurrency.test.ts",
     "test:smoke": "bun test tests/discovery.test.ts",
@@ -44,7 +46,7 @@
     "bench:discovery": "bun run scripts/bench/discovery.ts",
     "bench:startup": "bun run scripts/bench/startup.ts",
     "bench:ui": "bun run scripts/bench/ui.ts",
-    "prepublishOnly": "tsc --noEmit && bun run test"
+    "prepublishOnly": "tsgo --noEmit && bun run test"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -55,6 +57,6 @@
   },
   "devDependencies": {
     "@types/node": "^22",
-    "typescript": "^5.6.0"
+    "@typescript/native-preview": "^7.0.0-dev.20260615.1"
   }
 }

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.