pi-workflow-engine 0.10.3 → 0.12.0

package/README.md

@@ -1,259 +1,134 @@
-![agents](assets/preview.png)
-
 # pi-workflow-engine
 
-Zero-dependency Dynamax workflows for [pi](https://pi.dev): opt into live, parallel subagents when one coding agent is not enough.
-
-Use `dynamax` when a task needs several independent passes: review from different angles, compare options, chase a bug through multiple suspects, or stress-test a plan. pi can spin up a temporary workflow, run focused subagents in parallel, show progress in the TUI, and return one synthesized result.
+[![CI](https://github.com/timbrinded/pi-workflow-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/timbrinded/pi-workflow-engine/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-workflow-engine)](https://www.npmjs.com/package/pi-workflow-engine)
+[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-The package ships no bundled runtime dependencies. It uses the pi SDK and pi's bundled core packages, so installing it does not pull in a second agent stack.
+**Multi-agent workflows for [pi](https://pi.dev).**
 
-The built-in workflows are advisory by default. They inspect, verify, and report; they do not edit files. Workflow authors can opt individual subagents into disposable git worktrees when they want reviewable patches instead of direct edits.
+When a task benefits from independent review, competing hypotheses, or separate
+verification, pi-workflow-engine fans it out to subagents and synthesizes one
+result. Run a built-in workflow or add `dynamax` to a prompt so pi can compose a
+one-off workflow for the task.
 
-## Install
+![A lead agent coordinating subagents](assets/preview.png)
 
-```bash
-pi install npm:pi-workflow-engine
-```
+## Quick start
 
-Or install from GitHub:
+Requires **pi 0.80.10 or newer**.
 
 ```bash
-pi install git:github.com/timbrinded/pi-workflow-engine
-```
-
-Restart pi, or run `/reload` in an open session, then confirm it loaded:
-
-```bash
-pi list
-```
-
-For project-local install:
-
-```bash
-pi install npm:pi-workflow-engine -l
-```
-
-## Use Dynamax
-
-Put the word `dynamax` in your prompt when you want pi to use a custom multi-agent workflow for the current task.
-
-```text
-dynamax investigate why typecheck started failing after this branch
+pi install npm:pi-workflow-engine
 ```
 
-What to expect:
-
-1. pi decides whether a saved workflow fits or whether to write a one-off workflow.
-2. The workflow runs focused subagents in parallel.
-3. You can watch phases, agents, findings, and logs in the workflow inspector.
-4. You get a summarized result with evidence, risks, next steps, and workflow-level token/cost totals gathered from subagent sessions.
-5. You can then ask pi to make changes using that result.
-
-Workflow usage totals are reported on the workflow result itself. pi's built-in footer and `/session` stats may still show host-session usage only unless pi core adds a first-class extension usage API.
-
-Dynamax is one-shot by default. It applies to the next agent run and then clears. Keep it on for the session with:
+Restart pi or run `/reload`, then try either style:
 
 ```text
-/workflow:dynamax on
-/workflow:dynamax status
-/workflow:dynamax off
-```
-
-The workflow inspector is available with:
+dynamax investigate why typecheck started failing on this branch
 
-```text
-/workflow:inspector
+/workflow code-review
+/workflow refactor-scout src/
+/workflow diagnose "the schema migration broke typecheck"
 ```
 
-In interactive mode, `/workflow` with no arguments also offers `Author temporary one-shot workflow...`. Choose it, type a brief, and pi will ask the host agent to write and run a temporary workflow.
+Built-in workflows inspect and report by default; they do not edit your working
+tree.
 
-## Example Dynamax Prompts
+## What you get
 
-Use Dynamax when you want breadth, independent judgment, or adversarial pressure before editing.
+- **Independent analysis.** Give correctness, testing, performance, or other
+  concerns to separate agents instead of asking one agent to cover everything.
+- **Verified results.** Workflows can check and rank findings before presenting
+  a single synthesis.
+- **Live visibility.** Follow phases and agents in the TUI, with usage and cost
+  totals when the provider reports them.
+- **Controlled execution.** Concurrency, timeouts, agent counts, and token
+  budgets keep fan-out bounded.
+- **Safe follow-up.** Advisory runs leave the checkout alone, while selected
+  review fixes can return isolated patch previews.
 
-```text
-dynamax do an adversarial review of this branch. I want correctness bugs, hidden coupling, test gaps, and over-engineered parts called out separately.
-```
-
-Expected result: several review angles run independently, likely findings are verified, duplicates are merged, and you get a ranked report with concrete evidence before deciding what to fix.
-
-```text
-dynamax investigate this flaky test. Split the work between recent diffs, test setup, async timing, and external dependencies.
-```
+## Built-in workflows
 
-Expected result: parallel hypotheses, evidence for or against each one, and the most likely root cause with a small validation step.
+| Workflow | Best used for |
+| --- | --- |
+| `code-review` | PRs, branch diffs, ref ranges, or focused targets |
+| `refactor-scout` | Small, defensible refactors without broad rewrites |
+| `diagnose` | Competing explanations for bugs or failing commands |
+| `perf-review` | Measured bottlenecks rather than performance guesses |
+| `research` | Cited external evidence with independent claim verification |
 
-```text
-dynamax compare these two implementation approaches and argue both sides before recommending one.
-```
-
-Expected result: separate agents inspect each approach, another pass looks for failure modes, and the final answer separates tradeoffs from the recommendation.
+The `research` workflow needs an installed pi tool that can search or browse the
+web. See the [built-in workflow guide](USAGE.md#built-in-workflows) for behavior
+and requirements.
 
-```text
-dynamax review this migration plan like a hostile reviewer. Focus on rollback, data loss, concurrency, and missing operational steps.
-```
+## Use Dynamax for one-off workflows
 
-Expected result: an adversarial checklist with concrete risks, what would break, and which items are blockers versus follow-ups.
+Use `dynamax` when no saved workflow quite fits and independent passes are
+likely to change the answer:
 
 ```text
-dynamax find the simplest safe refactor path for this module. Avoid broad rewrites.
+dynamax review this branch for correctness, tests, and maintainability; verify every finding
+dynamax investigate this flaky test using separate timing, fixture, diff, and external-state hypotheses
+dynamax argue both implementation options, then have another agent challenge the recommendation
 ```
 
-Expected result: small refactor opportunities, why they are safe, and what not to touch.
+The token enables Dynamax for one turn. Sticky mode remains active for the pi
+session:
 
 ```text
-dynamax inspect this performance issue. Separate measurement gaps from real bottleneck hypotheses.
+/workflow:dynamax on
+/workflow:dynamax off
+/workflow:dynamax status
 ```
 
-Expected result: a performance-focused report that distinguishes known evidence from guesses and suggests the next measurement command.
+In the TUI, a standalone `dynamax` token receives a short moving-shine sweep and
+then stays highlighted. Use `PI_DYNAMAX_EFFECT=static` or
+`PI_DYNAMAX_EFFECT=off` to reduce or disable the cue; the
+[prompt editor guide](USAGE.md#prompt-editor-cue) has the full details.
 
-## Saved Workflows
+Tiny edits and straightforward questions are still better handled by one agent.
+Dynamax is useful when independence or breadth materially improves the result.
 
-You can also run saved workflows directly:
+## Review and inspect results
 
-```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"
-```
-
-Built-ins:
-
-- `code-review`: reviews a PR, branch diff, ref range, or target.
-- `refactor-scout`: finds small, safe refactor opportunities.
-- `diagnose`: investigates a bug, failing command, or regression.
-- `perf-review`: reviews a slow path or performance concern.
-
-Useful flags:
+`code-review` verifies, deduplicates, and ranks candidate findings. Open the
+interactive findings view for follow-up, or bring back the latest result without
+rerunning the workflow:
 
 ```text
-/workflow code-review --inspect
 /workflow code-review --result-viewer
-/workflow code-review --no-result-viewer
-/workflow code-review --concurrency=4
-/workflow code-review --budget=50000
-/workflow code-review --resume <run-id>
-/workflow code-review --refresh
+/workflow:results
+/workflow:inspector
 ```
 
-Every workflow result includes a run id. If a long run is interrupted, rerun the same workflow with `--resume <run-id>` to replay matching completed `agent()` calls from the journal and run only the first changed or missing call onward. Resume is deterministic-prefix based: keep prompts and agent options stable if you want cache hits.
+The viewer can produce isolated patch previews for selected findings without
+changing the active checkout. The [usage guide](USAGE.md#workflow-results)
+covers review actions and recent run history.
 
-The code-review workflow can open an interactive findings viewer. Select findings and hand them back to the parent agent for minimal fixes, or ask it to raise GitHub PR comments when `gh` is authenticated and PR context is available.
+## Create your own workflows
 
-For the full command guide, see [USAGE.md](USAGE.md).
+Saved workflows are TypeScript modules for repeatable orchestration; inline
+workflows are useful for one-off Dynamax tasks. The
+[workflow authoring guide](USAGE.md#author-a-saved-workflow) covers the API,
+typed handoffs, model profiles, tool access, composition, and registration.
 
-## What Dynamax Is Good For
-
-Use it for:
-
-- adversarial reviews before you trust a plan or diff;
-- debugging where several causes are plausible;
-- design comparisons where you want both sides argued;
-- refactor scouting where broad rewrites would be risky;
-- performance investigations where measurement gaps matter;
-- documentation reviews where consistency and reader expectations both matter.
-
-Do not use it for every tiny task. A single prompt is still better for simple edits, one-file explanations, and obvious mechanical changes.
-
-## Local Development
-
-Only needed if you want to add workflows, customize workflows, or contribute. Using the package does not require a clone, install, or build step.
+## Develop locally
 
 ```bash
 git clone https://github.com/timbrinded/pi-workflow-engine
 cd pi-workflow-engine
 bun install
-bun run typecheck
-bun run test
-```
-
-Load your working copy through the package manifest without installing it:
-
-```bash
-pi -e .
-```
-
-If you also have the global package installed, pi may report duplicate `/workflow` or `workflow` tool diagnostics. Remove one source or load only this working copy:
-
-```bash
+bun run typecheck && bun run test
 pi -ne -e .
 ```
 
-### Add A Workflow
-
-A workflow is a TypeScript module that exports `meta` plus a default async function. The `api` object gives you `agent`, `parallel`, `pipeline`, `workflow`, `phase`, `log`, and `progress`.
-
-Guaranteed built-ins are statically registered:
-
-1. Add `.pi/extensions/pi-workflow-engine/workflows/<name>.ts`.
-2. Import it in `.pi/extensions/pi-workflow-engine/src/workflows.ts`.
-3. Add it to `BUILTIN_WORKFLOWS`.
-
-Drop-in workflows are also discovered best-effort from:
-
-- `.pi/extensions/pi-workflow-engine/workflows/*.ts`
-- `~/.pi/agent/workflows/*.ts`
-
-Use `/workflow <name> --refresh` after adding a drop-in file.
-
-Inline workflows are passed to the `workflow` tool as a script string. They are useful for one-off Dynamax orchestration. Inline v1 rules: no imports, no dynamic `import()`, pure-literal `meta`, schemas must use the injected `Type` value, and scripts run in-process with the extension's permissions.
-
-### Technical Notes
+`pi -ne -e .` loads the working copy without also loading an installed global
+copy. There is no build step; pi loads the TypeScript extension directly.
 
-- Each `agent()` runs an in-process pi `AgentSession` with `SessionManager.inMemory()`.
-- Workflow results aggregate the finalized assistant usage from those subagent sessions before disposal and show token/cost totals separately from pi's host-session footer accounting.
-- Structured output uses a terminating tool whose `parameters` is your schema. pi validates the call; the engine captures the args. There is no JSON scraping.
-- A schema agent that finishes without calling `final_answer` is re-prompted once before returning `null`.
-- Runs write completed `agent()` results to `.pi/.workflow-runs/<run-id>.jsonl`; `--resume <run-id>` replays the longest unchanged prefix and writes a fresh journal for the resumed run.
-- `agent(..., { isolation: "worktree" })` runs in a disposable git worktree and returns `{ result, patch, changed }`; the user working tree is not mutated.
-- A single run-level semaphore caps concurrent agents, so nested `parallel`, `pipeline`, and `workflow()` calls stay bounded.
-- `parallel()` and `pipeline()` are fail-soft: recoverable branch failures, including budget backstops, become `null` slots while survivors continue. A genuine run abort still rejects.
-- Built-in workflows stay statically imported so they share pi's bundled `typebox` identity.
-- Set `thinkingLevel` per fan-out agent. Otherwise many subagents can inherit an expensive global reasoning level.
-- Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; clear prompt text like `include skill name` also works when `skills` is omitted.
-- `tools` is a strict allowlist for subagents. Use `toolHints: ["search"]` to dynamically expose installed grep/find/search-like tools such as `ast-grep`, `mgrep`, `ffgrep`, or `fffind` without hard-coding a specific extension.
-- Set `model` per agent only when needed: bare ids are Anthropic shorthand, and `provider/id` targets other providers.
-  Omitted models inherit the host/session default; malformed or unknown explicit refs fail fast.
+For the complete command reference, model configuration, workflow authoring,
+runtime controls, resume behavior, and troubleshooting, see
+[USAGE.md](USAGE.md).
 
-### Performance Controls
-
-Runtime controls:
-
-- `PI_WORKFLOW_PERF=1` enables per-run performance timing. This is timing-only; workflow usage/cost totals are reported separately when subagent usage is available.
-- `PI_WORKFLOW_CONCURRENCY=N` sets the per-run agent cap. The default is `min(8, max(2, CPU count))`.
-- `PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT=N` limits how many `parallel()` thunks are submitted at once.
-- `PI_WORKFLOW_LANE_ITEM_LIMIT=N` caps retained progress lane items per lane.
-
-No-LLM benchmark scripts:
-
-```bash
-bun run bench:concurrency -- --items 200 --concurrency 8 --json
-bun run bench:discovery -- --iterations 3 --json
-bun run bench:startup -- --json
-bun run bench:ui -- --agents 1000 --lane-items 1000 --json
-```
-
-### Layout
-
-```text
-.pi/
-  settings.json
-  extensions/pi-workflow-engine/
-    index.ts
-    src/
-      types.ts
-      agent-runner.ts
-      concurrency.ts
-      engine.ts
-      progress.ts
-      discovery.ts
-      workflows.ts
-    workflows/
-      code-review.ts
-      refactor-scout.ts
-      diagnose.ts
-      perf-review.ts
-```
+Questions and ideas are welcome in
+[GitHub Issues](https://github.com/timbrinded/pi-workflow-engine/issues).
+MIT licensed.