@yycholla/pi-dynamic-workflows 3.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 QuintinShaw
+Copyright (c) Michael Livs (original pi-dynamic-workflows)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/QuintinShaw/pi-dynamic-workflows/main/assets/readme/hero.png" width="100%" alt="pi-dynamic-workflows turns one prompt into a routed, resumable, cross-checked fleet of Pi subagents">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows"><img src="https://img.shields.io/npm/v/@quintinshaw/pi-dynamic-workflows?color=cb3837&logo=npm" alt="npm version"></a>
+  <a href="#license"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  <a href="https://pi.dev"><img src="https://img.shields.io/badge/for-Pi-7c3aed" alt="Built for Pi"></a>
+</p>
+
+<p align="center">
+  <a href="https://quintinshaw.github.io/pi-dynamic-workflows/">Documentation</a> ·
+  <a href="https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows">npm</a> ·
+  <a href="https://pi.dev/packages/@quintinshaw/pi-dynamic-workflows">Pi package</a>
+</p>
+
+Turn one request into a JavaScript orchestration script that fans work out across isolated subagents, routes each task to the right model, cross-checks the results, and returns one synthesized answer. Intermediate work stays in script variables instead of filling your chat context.
+
+Built for **codebase-wide audits, multi-perspective review, large refactors, and source-checked research**—the jobs that are too broad for one agent and one context window.
+
+![A real pi-dynamic-workflows run showing parallel agents and live progress](https://raw.githubusercontent.com/QuintinShaw/pi-dynamic-workflows/main/docs/media/demo.gif)
+
+## Start in 30 seconds
+
+```bash
+pi install npm:@quintinshaw/pi-dynamic-workflows
+```
+
+Run `/reload` in Pi, then ask naturally:
+
+```text
+Run a workflow to audit every route under src/routes/ for missing auth checks.
+```
+
+Pi writes and starts the workflow in the background. A live panel tracks progress while you keep working, and the final result is delivered back into the conversation automatically.
+
+Keyword triggering is on by default: use the bounded word **workflow** or **workflows** in a message to arm workflow mode — the assistant then handles a request by fanning it out across agents, but still answers plainly if you're only asking *about* workflows (the trigger authorizes the tool, it doesn't force it). Or run `/workflows run <prompt>` explicitly. Identifier-like text and paths such as `myworkflow`, `workflow_name`, and `src/workflow-editor.ts` do not trigger. You can change the keyword with `/workflows-trigger set pi-workflow` or disable it with `/workflows-trigger off`.
+
+## How it works
+
+![A prompt becomes deterministic orchestration, parallel routed agents, verification, and one result](https://raw.githubusercontent.com/QuintinShaw/pi-dynamic-workflows/main/assets/readme/workflow.png)
+
+1. **Orchestrate** — Pi writes a deterministic JavaScript workflow with `agent()`, `parallel()`, `pipeline()`, and `phase()`.
+2. **Fan out** — fresh subagent sessions run concurrently, optionally on different models or isolated git worktrees.
+3. **Verify and return** — the workflow cross-checks findings, journals completed work for resume, and delivers one result.
+
+The orchestration itself is plain JavaScript:
+
+```js
+export const meta = {
+  name: 'auth_audit',
+  description: 'Find routes missing auth checks and verify the findings',
+  phases: [{ title: 'Scan' }, { title: 'Review' }, { title: 'Verify' }],
+}
+
+phase('Scan')
+const files = await agent('List every route file under src/routes/.', { tier: 'small' })
+
+phase('Review')
+const findings = await parallel(
+  files.split('\n').filter(Boolean).map((file) =>
+    () => agent(`Audit ${file} for missing auth checks.`, {
+      tier: 'medium',
+      isolation: 'worktree',
+    }),
+  ),
+)
+
+phase('Verify')
+return await agent(
+  'Synthesize and double-check these findings:\n' + findings.join('\n\n'),
+  { tier: 'big' },
+)
+```
+
+## Why use it
+
+- **Real parallel orchestration** — fan out up to 16 concurrent and 1000 total subagents from one orchestration script.
+- **Per-agent model routing** — use `small`, `medium`, or `big` tiers, or choose an exact provider/model and thinking level.
+- **Journaled resume** — replay completed agents after interruption without rerunning them or spending their tokens again. The orchestrator can also resume with an **edited script** (`resumeFromRunId`): unchanged `agent()` calls replay from cache and only edited/new ones re-run — so a single bad prompt no longer means paying to re-run the whole workflow.
+- **Git worktree isolation** — let parallel agents edit safely on throwaway branches with `isolation: "worktree"`.
+- **Measured usage** — report real tokens and cost from each subagent session; add run, phase, or agent budgets only when you want them.
+- **Visible background runs** — track phases, agents, models, fresh/cache tokens, cost, and live tok/s from the progress panel or `/workflows` navigator.
+- **Quality patterns** — compose `verify()`, `judgePanel()`, `loopUntilDry()`, and `completenessCheck()` instead of rebuilding review loops.
+- **Reusable workflows** — save any run as a command and call saved workflows from other workflows.
+
+## Supported workflow capabilities
+
+The installed extension generates this compact index from its executable capability contract. Read the [workflow authoring guide](docs/workflow-authoring.md) or use the packaged `workflow-authoring` skill for constraints, lifecycle guidance, and adaptable examples; configured route and agent-type values remain environment-specific.
+
+<!-- BEGIN GENERATED SUPPORTED WORKFLOW CAPABILITIES -->
+| Name | Classification | Signature | Options and defaults |
+| --- | --- | --- | --- |
+| agent | runtime-global | `agent(prompt, options?) => Promise<string \| structured value \| null>` | `label`: string (optional; default: derived from phase and call count)<br>`phase`: string (optional; default: current phase)<br>`schema`: plain JSON Schema (optional)<br>`model`: string (optional)<br>`tier`: string (optional)<br>`isolation`: "worktree" (optional)<br>`agentType`: string (optional)<br>`timeoutMs`: number \| null (optional; default: run timeout; null disables)<br>`retries`: number (optional; default: run retry count) |
+| parallel | runtime-global | `parallel(thunks) => Promise<Array<unknown \| null>>` | — |
+| pipeline | runtime-global | `pipeline(items, ...stages) => Promise<Array<unknown \| null>>` | — |
+| workflow | runtime-global | `workflow(savedName, childArgs?) => Promise<unknown>` | — |
+| verify | runtime-global | `verify(item: unknown, options?: { reviewers?: number; threshold?: number; lens?: string \| string[] }) => Promise<{ real: boolean; realCount: number; total: number; votes: Array<{ real: boolean; reason?: string }> }>` | `reviewers`: number (optional; default: 2)<br>`threshold`: number (optional; default: 0.5)<br>`lens`: string \| string[] (optional) |
+| judgePanel | runtime-global | `judgePanel(attempts: unknown[], options?: { judges?: number; rubric?: string }) => Promise<{ index: number; attempt: unknown; score: number; judgments: Array<{ score: number; reason?: string }> } \| undefined>` | `judges`: number (optional; default: 3)<br>`rubric`: string (optional; default: "overall quality and correctness") |
+| loopUntilDry | runtime-global | `loopUntilDry(options: { round: (roundIndex: number) => unknown[] \| Promise<unknown[]>; key?: (item: unknown) => string; consecutiveEmpty?: number; maxRounds?: number }) => Promise<unknown[]>` | `round`: (roundIndex: number) => unknown[] \| Promise<unknown[]> (required)<br>`key`: (item: unknown) => string (optional; default: JSON.stringify)<br>`consecutiveEmpty`: number (optional; default: 2)<br>`maxRounds`: number (optional; default: 50) |
+| completenessCheck | runtime-global | `completenessCheck(taskArgs: unknown, results: unknown) => Promise<{ complete: boolean; missing?: string[] } \| null>` | — |
+| retry | runtime-global | `retry(thunk: (attempt: number) => unknown \| Promise<unknown>, options?: { attempts?: number; until?: (result: unknown) => boolean }) => Promise<unknown>` | `attempts`: number (optional; default: 3)<br>`until`: (result: unknown) => boolean (optional; default: accept first result when omitted) |
+| gate | runtime-global | `gate(thunk: (feedback: string \| undefined, attempt: number) => unknown \| Promise<unknown>, validator: (value: unknown) => { ok: boolean; feedback?: string } \| Promise<{ ok: boolean; feedback?: string }>, options?: { attempts?: number }) => Promise<{ ok: boolean; value: unknown; attempts: number }>` | `attempts`: number (optional; default: 3) |
+| checkpoint | runtime-global | `checkpoint(prompt, options?) => Promise<unknown>` | `default`: unknown (optional; default: true when no UI and omitted)<br>`headless`: "default" \| "abort" (optional; default: "default")<br>`kind`: "confirm" \| "input" \| "select" (optional; default: "confirm")<br>`choices`: string[] (optional)<br>`timeoutMs`: number (optional) |
+| log | runtime-global | `log(message) => void` | — |
+| phase | runtime-global | `phase(title, options?) => void` | `budget`: number (optional) |
+| args | runtime-global | `args: unknown` | — |
+| cwd | runtime-global | `cwd: string` | — |
+| process | runtime-global | `process: { cwd(): string }` | — |
+| budget | runtime-global | `budget: { total, spent(), remaining() }` | — |
+| script | workflow-tool-input | `script?: string` | — |
+| name | workflow-tool-input | `name?: string` | — |
+| args | workflow-tool-input | `args?: unknown` | — |
+| background | workflow-tool-input | `background?: boolean = true` | — |
+| maxAgents | workflow-tool-input | `maxAgents?: number = 1000` | — |
+| concurrency | workflow-tool-input | `concurrency?: number` | — |
+| agentRetries | workflow-tool-input | `agentRetries?: number = configured value or 0` | — |
+| agentTimeoutMs | workflow-tool-input | `agentTimeoutMs?: number = configured default or unbounded` | — |
+| tokenBudget | workflow-tool-input | `tokenBudget?: number = configured default or unlimited` | — |
+| resumeFromRunId | workflow-tool-input | `resumeFromRunId?: string` | — |
+<!-- END GENERATED SUPPORTED WORKFLOW CAPABILITIES -->
+
+## Built-in workflows
+
+```text
+/deep-research <question>   source-checked web research with citations
+/adversarial-review <task>  findings challenged by skeptical reviewers
+/multi-perspective "<topic>" [angle …]
+                            independent angles followed by synthesis
+/code-review [target]       7 parallel review angles plus verification
+/codebase-audit <scope> "<check>" …
+                            parallel checks followed by cross-validation
+```
+
+`/code-review` defaults to the current working diff. It also accepts a git range, a file, or a GitHub PR number:
+
+```text
+/code-review
+/code-review HEAD~3..HEAD
+/code-review src/foo.ts
+/code-review 42
+```
+
+For an always-on exhaustive mode, use `/ultracode`; `/effort high` is the lighter standing option.
+
+These same 5 patterns are also reachable by name without a slash command — Pi can recognize a decomposable request and run the matching curated pattern directly:
+
+```text
+Do a deep-research on whether Bun's test runner is production-ready.
+```
+
+is equivalent to `/deep-research "..."`. A saved workflow always wins over a built-in of the same name, on both the slash-command and natural-language paths — so saving your own `code-review` shadows the built-in one everywhere.
+
+## Commands and run control
+
+Pi can manage background runs directly with the `workflow_control` tool instead of asking you to type a command. It supports `list`, `status`, `pause`, `resume`, and `stop`; run-specific actions use the canonical run ID returned when the workflow starts. Status output includes the run state, current phase, agent counts, active labels, and recorded token total.
+
+| Command | Purpose |
+| --- | --- |
+| `/workflows` | Open the interactive run navigator |
+| `/workflows run <prompt>` | Arm workflow mode for a prompt even when keyword triggering is off |
+| `/workflows status <id>` | Watch a run and print its result when complete |
+| `/workflows pause\|resume\|stop\|rm <id>` | Control a run |
+| `/workflows save <name>` | Save the latest script as a reusable command |
+| `/workflows-trigger off\|on\|status` | Control automatic keyword triggering |
+| `/workflows-trigger set <word>\|reset` | Set or reset the trigger word |
+| `/workflows-progress compact\|detailed\|status\|max <N>` | Live-panel detail level (and max agents shown per phase in detailed mode) |
+| `/workflows-models` | Map model tiers and thinking levels |
+| `/ultracode [off]` | Toggle exhaustive automatic workflows |
+| `/effort off\|high\|ultra` | Set the standing orchestration effort |
+
+In the navigator: `↑/↓` select · `enter/→` open · `esc/←` back · `p` pause · `x` stop · `r` restart · `s` save · `q` quit.
+
+Agent details use a compact summary by default: completed agents show their final result, while active agents show the prompt and two latest history events. Press `enter` to open the full syntax-highlighted pager. In the pager, use `j/k` or `↑/↓` for lines, `PgUp/PgDn` for pages, `g/G` for the ends, and `t` to toggle live tail mode.
+
+## Runtime reference
+
+| Global | What it does |
+| --- | --- |
+| `agent(prompt, opts)` | Spawn an isolated subagent; optionally validate its result with JSON Schema |
+| `parallel(thunks)` | Run `() => agent(...)` thunks concurrently and preserve input order |
+| `pipeline(items, ...stages)` | Fan items through sequential stages |
+| `phase(title, { budget? })` | Group work in the live view and optionally set a phase budget |
+| `verify` / `judgePanel` | Cross-check a result or choose the best candidate |
+| `loopUntilDry` / `completenessCheck` | Repeat discovery until no new findings remain |
+| `workflow(name, args)` | Run a saved workflow inline |
+| `checkpoint(prompt, opts)` | Add a journaled human-approval gate |
+| `budget` | Inspect real tokens spent and remaining |
+
+| Agent option | Description |
+| --- | --- |
+| `tier` | `small`, `medium`, or `big` model routing |
+| `model` | Exact `provider/modelId` or `provider/modelId:thinking`; overrides `tier` |
+| `agentType` | Named role, tool, and model definition |
+| `isolation` | Use `"worktree"` for conflict-free parallel edits |
+| `schema` | JSON Schema for a validated structured result |
+| `label` / `phase` | Display label and phase override |
+| `timeoutMs` / `retries` | Optional per-agent timeout and recoverable-failure retries |
+
+The [full documentation](https://quintinshaw.github.io/pi-dynamic-workflows/) covers every option, structured output, determinism, saved workflows, and operational control.
+
+<details>
+<summary><strong>Model tiers and run controls</strong></summary>
+
+Model tiers live at `~/.pi/workflows/model-tiers.json` and accept Pi CLI-style thinking suffixes:
+
+```json
+{
+  "tiers": {
+    "small": "openai-codex/gpt-5.4-mini:low",
+    "medium": "openai-codex/gpt-5.4:medium",
+    "big": "openai-codex/gpt-5.5:xhigh"
+  }
+}
+```
+
+Use `/workflows-models` to edit them interactively. Without a config, the extension ranks authenticated models by capability hints and assigns distinct models when possible.
+
+Omitted `tokenBudget` and `agentTimeoutMs` values use configured `defaultTokenBudget` and `defaultAgentTimeoutMs` settings; without them, runs are unlimited and have no hard per-agent timeout. Add per-run or per-agent values when you need explicit gates. `concurrency` is clamped to 16; `agentRetries` retries only recoverable failures. Defaults live in `~/.pi/workflows/settings.json`; `defaultTokenBudget` is a soft pre-call gate, and a project-level override of `null` cancels a global budget.
+
+Pausing and resuming a run keeps the limits it started with — `maxAgents`, `agentTimeoutMs`, `concurrency`, and `agentRetries` carry over instead of falling back to defaults, and `tokenBudget` tracking is cumulative across the pause, so a run can't reset its spend by pausing and resuming.
+
+</details>
+
+<details>
+<summary><strong>Storage, resume, and persisted sessions</strong></summary>
+
+Extension state lives outside the repository under `~/.pi/workflows`:
+
+- global settings and tiers: `~/.pi/workflows/settings.json` and `model-tiers.json`
+- project runs, journals, locks, and saved overrides: `~/.pi/workflows/projects/<project>/`
+- older project-local `.pi/workflows/runs` and `.pi/workflows/saved` remain readable as fallbacks
+
+Subagents are in-memory by default. Set `persistAgentSessions: true` to retain full transcripts in Pi's standard session directory. This creates one file per agent and may store sensitive material that an agent read, so enable it deliberately.
+
+Completed background runs persist their full result in the project run JSON. The conversation delivery includes a pointer to that file when the visible summary is shortened.
+
+Pi's `/reload` keeps the live workflow manager in-process when the installed extension version has not changed. Active background runs therefore continue streaming progress, remain controllable, and deliver their result through the freshly loaded extension; session-local `/effort` also survives the reload. If the package version changes, active runs are paused and a fresh manager loads, leaving them safely resumable through the journal instead of mixing extension versions. This handoff applies only to `/reload`. A process restart still uses the same durable journal path, recovering an interrupted running workflow as paused so it can be resumed safely.
+
+Finished runs (completed, failed, or aborted) are retained in full on disk, capped at the 300 most recent per project — older ones are evicted first, and a running or paused run is never touched. Only a smaller number (20 by default) also stay fully loaded in memory for instant access right after they finish; older finished runs still show up in `/workflows` and `workflow_control list`, just read back from disk instead of memory. Library embedders can tune both caps — `maxTerminalRunsInMemory` on `WorkflowManager` and `maxTerminalRunsOnDisk` on the run-persistence layer.
+
+</details>
+
+<details>
+<summary><strong>Keyword trigger</strong></summary>
+
+Set a literal, case-insensitive custom trigger in `~/.pi/workflows/settings.json`:
+
+```json
+{
+  "keywordTriggerWord": "pi-workflow"
+}
+```
+
+The default `workflow` also matches `workflows`; a custom word matches exactly. Trigger words are case-insensitive and Unicode identifier-bounded, and do not activate inside paths, slash commands, or identifier-like text. Detection is purely textual, applied at submit time to the message you send — it does not depend on, or own, Pi's editor component, so it works the same regardless of what else is installed.
+
+</details>
+
+<details>
+<summary><strong>How it maps to Claude Code dynamic workflows</strong></summary>
+
+| Claude Code dynamic workflows | pi-dynamic-workflows on Pi |
+| --- | --- |
+| Code-mode orchestration | JavaScript `agent()` / `parallel()` / `pipeline()` / `phase()` in a VM realm (for determinism, not a security boundary) |
+| Isolated subagent contexts | Fresh in-memory Pi sessions; results remain in variables |
+| Structured outputs | JSON Schema validation with bounded repair |
+| Background runs | Non-blocking run, live panel, and automatic result delivery |
+| Resume | Journaled replay of the unchanged completed prefix, including edit-and-resume with a revised script (`resumeFromRunId`) |
+| Model selection | Per-agent and per-phase routing across authenticated providers |
+| Ultracode | `/ultracode` or `/effort ultra` |
+| Additional Pi features | Worktree isolation, real cost accounting, deep research, and quality-pattern helpers |
+
+</details>
+
+## Determinism and limits
+
+Workflow scripts run in a Node `vm` sandbox. `Date.now()`, `Math.random()`, `new Date()`, `require`, `import`, filesystem access, and network access are unavailable inside the orchestration script. Subagents use their assigned tools; keeping the orchestrator deterministic is what makes journal replay reliable.
+
+Journal replay — including edit-and-resume via `resumeFromRunId` — matches cached agent results by **positional call index** (the order in which `agent()` calls execute), the same contract Claude Code uses. Editing an `agent()` prompt in place reuses the cache up to that call and re-runs it and everything after. Inserting, removing, or reordering an `agent()` call before others shifts their positions and invalidates the cache from that point on (mismatched calls simply re-run — no crash). To preserve the cached prefix, keep the earlier still-good `agent()` calls unchanged and in the same order.
+
+## Upgrading to 3.0
+
+3.0 is a milestone release. The one behavior change to know about:
+
+- **Keyword triggering now _authorizes_ the workflow tool instead of _forcing_ it.** In 2.x, typing the trigger word (default `workflow`) rewrote your message into a directive that forced a background workflow. In 3.0 it _arms_ the tool and the model decides: a real, decomposable request is fanned out across agents, but a message that only mentions workflows — a question, a filename, a passing reference — is answered normally. Nothing to configure. If you relied on the word always kicking off a run, use `/workflows run <prompt>` for the explicit path. Keyword triggering stays on by default; `/workflows-trigger off` disables it and `/workflows-trigger set <word>` changes the word.
+
+Everything else is additive or a fix: the `workflow_control` tool (list/status/pause/resume/stop), edited-script resume, auto-resume on provider usage limits, and persistence/perf hardening. Requires pi ≥ 0.80.8.
+
+Library API note: the unused `createSharedStoreTools` export was removed — use `createAgentStoreTools`.
+
+## Upgrading past 3.2
+
+Two behavior changes to know about:
+
+- **Subagents no longer load host extensions by default.** Each run now builds one shared, extension-free resource loader for all of its subagents (a memory-leak mitigation). Skills, prompts, and `AGENTS.md` context still load, and the coding tools and any toolset (e.g. `web-research`) you hand a subagent are unaffected. What subagents lose is **host-extension-registered tools** — MCP bridges, browser tools, or anything else another installed extension adds. If an `agentType` names one of those tools in its allowlist, that entry now matches nothing. This also means a subagent can no longer recurse into another orchestration extension, even one not covered by the existing tool denylist.
+- **Checkpoints persisted before this release re-run once.** `checkpoint()`'s resume-identity hash now also covers `default`, `headless`, and `timeoutMs`, so changing any of them between runs correctly invalidates a stale cached answer. This is a one-time effect: any checkpoint cached under the old hash simply re-prompts once and then caches normally again.
+
+## Development
+
+```bash
+npm install
+npm test     # Biome, TypeScript, unit tests, and release checks
+```
+
+### Optional model-comprehension evidence
+
+The comprehension harness is manual and never runs in normal CI, `npm test`, or the release gate. Select an available model explicitly; the harness never embeds or chooses from a static model or agent-type catalogue.
+
+```bash
+npm run comprehension -- --model provider/model                    # quick writing scenario
+npm run comprehension -- --model provider/model --suite full       # write, edit, review, and debug
+npm run comprehension -- --model provider/model --output runs/a.json
+```
+
+By default, evidence is written under ignored `.pi/model-comprehension/`. Each JSON run records the exact prompts and versions, generated workflows, skill reads, provider token usage, deterministic runtime calls/topology/results, assertions, and failure details. Scenario failures are retained as non-blocking evidence and do not produce a failing exit status; argument, model-selection, and setup errors do.
+
+Features are also verified end-to-end against real Pi subagent sessions before release. See [CONTRIBUTING.md](./CONTRIBUTING.md) to contribute.
+
+## Credits
+
+The code-mode orchestration idea comes from [Michael Livs' original pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynamic-workflows) and Anthropic's [dynamic workflows in Claude Code](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code). This project adds model routing, journaled resume, worktree isolation, measured usage, an interactive TUI, and built-in research and review workflows.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/assets/readme/hero.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="420" viewBox="0 0 1200 420" role="img" aria-labelledby="title desc">
+  <title id="title">pi-dynamic-workflows</title>
+  <desc id="desc">One prompt fans out to small, medium, and big Pi agents before returning one verified result.</desc>
+
+  <defs>
+    <pattern id="grid" width="44" height="44" patternUnits="userSpaceOnUse">
+      <path d="M44 0H0V44" fill="none" stroke="#273045" stroke-width="1"/>
+    </pattern>
+    <linearGradient id="title-accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#61D2B4"/>
+      <stop offset="1" stop-color="#85E3CA"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="1200" height="420" rx="28" fill="#111827"/>
+  <rect width="1200" height="420" rx="28" fill="url(#grid)" opacity=".58"/>
+  <circle cx="1160" cy="16" r="116" fill="#FF725E" opacity=".10"/>
+  <circle cx="1080" cy="420" r="126" fill="#61D2B4" opacity=".08"/>
+
+  <g id="title-block" transform="translate(62 58)">
+    <text x="0" y="0" fill="#AAB3C6" font-size="15" font-weight="700" letter-spacing="3" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">ONE PROMPT · MANY AGENTS</text>
+    <rect x="0" y="20" width="56" height="6" rx="3" fill="#FF725E"/>
+    <text x="0" y="103" fill="#F6F0E5" font-size="64" font-weight="800" letter-spacing="-2" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">pi-dynamic-</text>
+    <text x="0" y="168" fill="#F6F0E5" font-size="64" font-weight="800" letter-spacing="-2" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">workflows</text>
+    <rect x="0" y="184" width="400" height="10" rx="5" fill="url(#title-accent)"/>
+    <text x="0" y="235" fill="#D7DCE7" font-size="22" font-weight="600" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">Fan out. Route models. Cross-check.</text>
+    <text x="0" y="267" fill="#D7DCE7" font-size="22" font-weight="600" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">Return one result.</text>
+    <text x="0" y="316" fill="#8F9AAF" font-size="14" font-weight="700" letter-spacing="2" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">JOURNALED RESUME · WORKTREE ISOLATION · REAL USAGE</text>
+  </g>
+
+  <g id="agent-cards">
+    <g transform="translate(745 55) rotate(5 160 64)">
+      <rect x="9" y="10" width="320" height="128" rx="20" fill="#05070B" opacity=".30"/>
+      <rect width="320" height="128" rx="20" fill="#F6F0E5"/>
+      <rect x="22" y="20" width="48" height="6" rx="3" fill="#FF725E"/>
+      <text x="22" y="52" fill="#111827" font-size="14" font-weight="800" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">SMALL / SCAN</text>
+      <rect x="22" y="69" width="276" height="38" rx="9" fill="#172133"/>
+      <path d="M40 81l8 7-8 7" fill="none" stroke="#61D2B4" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+      <path d="M58 94h86" stroke="#9FABC0" stroke-width="6" stroke-linecap="round"/>
+      <circle cx="279" cy="88" r="5" fill="#61D2B4"/>
+    </g>
+
+    <g transform="translate(678 181) rotate(-5 170 68)">
+      <rect x="9" y="10" width="340" height="136" rx="20" fill="#05070B" opacity=".26"/>
+      <rect width="340" height="136" rx="20" fill="#61D2B4"/>
+      <text x="24" y="39" fill="#12322D" font-size="14" font-weight="800" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">MEDIUM / REVIEW</text>
+      <text x="24" y="76" fill="#10231F" font-size="24" font-weight="800" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">Parallel specialists</text>
+      <g transform="translate(24 93)">
+        <rect width="72" height="24" rx="7" fill="#F6F0E5"/>
+        <rect x="82" width="72" height="24" rx="7" fill="#111827"/>
+        <rect x="164" width="72" height="24" rx="7" fill="#6C5CE7"/>
+        <circle cx="18" cy="12" r="5" fill="#FF725E"/>
+        <circle cx="100" cy="12" r="5" fill="#61D2B4"/>
+        <circle cx="182" cy="12" r="5" fill="#F6F0E5"/>
+      </g>
+    </g>
+
+    <g transform="translate(908 264) rotate(5 128 64)">
+      <rect x="9" y="10" width="256" height="128" rx="20" fill="#05070B" opacity=".30"/>
+      <rect width="256" height="128" rx="20" fill="#6C5CE7"/>
+      <text x="22" y="35" fill="#E6E0FF" font-size="13" font-weight="800" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">BIG / SYNTHESIZE</text>
+      <path d="M32 86H73L94 66 126 94 157 61 202 86" fill="none" stroke="#F6F0E5" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+      <circle cx="32" cy="86" r="9" fill="#61D2B4"/>
+      <circle cx="94" cy="66" r="9" fill="#FF725E"/>
+      <circle cx="126" cy="94" r="9" fill="#FFD166"/>
+      <circle cx="157" cy="61" r="9" fill="#F6F0E5"/>
+      <circle cx="202" cy="86" r="11" fill="#111827" stroke="#F6F0E5" stroke-width="3"/>
+    </g>
+  </g>
+</svg>

package/assets/readme/package-cover.svg

@@ -0,0 +1,66 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="750" viewBox="0 0 1200 750" role="img" aria-labelledby="title desc">
+  <title id="title">pi-dynamic-workflows package cover</title>
+  <desc id="desc">A Pi extension that routes one prompt through parallel small, medium, and big agents and returns a verified result.</desc>
+  <defs>
+    <pattern id="grid" width="48" height="48" patternUnits="userSpaceOnUse">
+      <path d="M48 0H0V48" fill="none" stroke="#273045" stroke-width="1"/>
+    </pattern>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#61D2B4"/>
+      <stop offset="1" stop-color="#85E3CA"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="1200" height="750" rx="32" fill="#111827"/>
+  <rect width="1200" height="750" rx="32" fill="url(#grid)" opacity=".58"/>
+  <circle cx="1164" cy="16" r="150" fill="#FF725E" opacity=".11"/>
+  <circle cx="44" cy="742" r="170" fill="#61D2B4" opacity=".08"/>
+
+  <g transform="translate(68 62)" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+    <text x="0" y="16" fill="#AAB3C6" font-size="16" font-weight="800" letter-spacing="3">PI EXTENSION · MULTI-AGENT ORCHESTRATION</text>
+    <rect x="0" y="37" width="60" height="7" rx="3.5" fill="#FF725E"/>
+    <text x="0" y="126" fill="#F6F0E5" font-size="68" font-weight="800" letter-spacing="-2">pi-dynamic-workflows</text>
+    <rect x="0" y="149" width="510" height="10" rx="5" fill="url(#accent)"/>
+    <text x="0" y="207" fill="#D7DCE7" font-size="27" font-weight="650">One prompt. Routed agents. One checked result.</text>
+  </g>
+
+  <g transform="translate(68 340)" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+    <path d="M310 103H370 M680 103H740" stroke="#78849A" stroke-width="4"/>
+    <path d="M352 93l18 10-18 10M722 93l18 10-18 10" fill="none" stroke="#78849A" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+
+    <g>
+      <rect x="10" y="12" width="300" height="206" rx="22" fill="#05070B" opacity=".34"/>
+      <rect width="300" height="206" rx="22" fill="#F6F0E5"/>
+      <text x="26" y="39" fill="#111827" font-size="15" font-weight="800" letter-spacing="1.5">01 / ORCHESTRATE</text>
+      <text x="26" y="84" fill="#111827" font-size="30" font-weight="800">Write the workflow</text>
+      <rect x="26" y="111" width="248" height="62" rx="10" fill="#172133"/>
+      <text x="43" y="137" fill="#61D2B4" font-size="14" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">parallel(agents)</text>
+      <text x="43" y="160" fill="#AAB3C6" font-size="14" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">verify(findings)</text>
+    </g>
+
+    <g transform="translate(370)">
+      <rect x="10" y="12" width="310" height="206" rx="22" fill="#05070B" opacity=".30"/>
+      <rect width="310" height="206" rx="22" fill="#61D2B4"/>
+      <text x="26" y="39" fill="#15463D" font-size="15" font-weight="800" letter-spacing="1.5">02 / FAN OUT</text>
+      <text x="26" y="84" fill="#102D28" font-size="30" font-weight="800">Route by model</text>
+      <g transform="translate(26 108)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="700">
+        <rect width="258" height="25" rx="7" fill="#F6F0E5"/><text x="13" y="17" fill="#16342F">small  · scan</text>
+        <rect y="32" width="258" height="25" rx="7" fill="#111827"/><text x="13" y="49" fill="#F6F0E5">medium · review</text>
+        <rect y="64" width="258" height="25" rx="7" fill="#6C5CE7"/><text x="13" y="81" fill="#F6F0E5">big    · synthesize</text>
+      </g>
+    </g>
+
+    <g transform="translate(740)">
+      <rect x="10" y="12" width="320" height="206" rx="22" fill="#05070B" opacity=".30"/>
+      <rect width="320" height="206" rx="22" fill="#6C5CE7"/>
+      <text x="26" y="39" fill="#E6E0FF" font-size="15" font-weight="800" letter-spacing="1.5">03 / RETURN</text>
+      <text x="26" y="84" fill="#F6F0E5" font-size="30" font-weight="800">Verified result</text>
+      <circle cx="67" cy="143" r="28" fill="#111827"/>
+      <path d="M53 143l9 9 20-22" fill="none" stroke="#61D2B4" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+      <text x="110" y="137" fill="#F6F0E5" font-size="15" font-weight="800">JOURNALED</text>
+      <text x="110" y="161" fill="#DCD5FF" font-size="14">resumable without reruns</text>
+    </g>
+  </g>
+
+  <text x="68" y="699" fill="#8F9AAF" font-size="15" font-weight="700" letter-spacing="2.2" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">MODEL ROUTING · WORKTREE ISOLATION · REAL TOKEN &amp; COST ACCOUNTING</text>
+</svg>

package/assets/readme/workflow.svg

@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="460" viewBox="0 0 1200 460" role="img" aria-labelledby="title desc">
+  <title id="title">How pi-dynamic-workflows orchestrates a task</title>
+  <desc id="desc">A task becomes deterministic orchestration, runs through parallel routed agents, then passes a verification gate before one result is returned.</desc>
+
+  <defs>
+    <pattern id="grid" width="46" height="46" patternUnits="userSpaceOnUse">
+      <path d="M46 0H0V46" fill="none" stroke="#D9D3C8" stroke-width="1"/>
+    </pattern>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto">
+      <path d="M0 0l10 5-10 5z" fill="#495266"/>
+    </marker>
+  </defs>
+
+  <rect width="1200" height="460" rx="28" fill="#F6F0E5"/>
+  <rect width="1200" height="460" rx="28" fill="url(#grid)" opacity=".52"/>
+
+  <g id="heading" transform="translate(54 44)" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+    <text x="0" y="15" fill="#687286" font-size="14" font-weight="800" letter-spacing="3">A DETERMINISTIC PATH THROUGH PARALLEL WORK</text>
+    <rect x="0" y="33" width="54" height="6" rx="3" fill="#FF725E"/>
+    <text x="0" y="89" fill="#111827" font-size="36" font-weight="800" letter-spacing="-1">One task. Coordinated agents. One checked result.</text>
+  </g>
+
+  <g id="flow" transform="translate(48 172)" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+    <path d="M250 126H278 M536 126H564 M822 126H850" fill="none" stroke="#495266" stroke-width="3" marker-end="url(#arrow)"/>
+
+    <g id="prompt-card">
+      <rect x="7" y="8" width="246" height="252" rx="18" fill="#AAA49B" opacity=".28"/>
+      <rect width="246" height="252" rx="18" fill="#111827"/>
+      <text x="22" y="33" fill="#61D2B4" font-size="13" font-weight="800" letter-spacing="1.4">01 / PROMPT</text>
+      <text x="22" y="75" fill="#F6F0E5" font-size="24" font-weight="800">Describe</text>
+      <text x="22" y="104" fill="#F6F0E5" font-size="24" font-weight="800">the task</text>
+      <rect x="22" y="130" width="202" height="76" rx="10" fill="#1E293B"/>
+      <text x="36" y="159" fill="#AAB3C6" font-size="13" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">audit every route</text>
+      <text x="36" y="183" fill="#AAB3C6" font-size="13" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">for missing auth</text>
+      <circle cx="216" cy="226" r="5" fill="#61D2B4"/>
+    </g>
+
+    <g id="orchestrate-card" transform="translate(286)">
+      <rect x="7" y="8" width="246" height="252" rx="18" fill="#AAA49B" opacity=".28"/>
+      <rect width="246" height="252" rx="18" fill="#DCD5FF"/>
+      <text x="22" y="33" fill="#5A49CB" font-size="13" font-weight="800" letter-spacing="1.4">02 / ORCHESTRATE</text>
+      <text x="22" y="75" fill="#171431" font-size="24" font-weight="800">Write the</text>
+      <text x="22" y="104" fill="#171431" font-size="24" font-weight="800">workflow</text>
+      <g transform="translate(22 139)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13">
+        <text x="0" y="0" fill="#5A49CB">phase</text><text x="46" y="0" fill="#4A4560">('Review')</text>
+        <text x="0" y="30" fill="#5A49CB">parallel</text><text x="65" y="30" fill="#4A4560">(agents)</text>
+        <text x="0" y="60" fill="#5A49CB">verify</text><text x="49" y="60" fill="#4A4560">(findings)</text>
+      </g>
+    </g>
+
+    <g id="fanout-card" transform="translate(572)">
+      <rect x="7" y="8" width="246" height="252" rx="18" fill="#AAA49B" opacity=".28"/>
+      <rect width="246" height="252" rx="18" fill="#61D2B4"/>
+      <text x="22" y="33" fill="#15463D" font-size="13" font-weight="800" letter-spacing="1.4">03 / FAN OUT</text>
+      <text x="22" y="75" fill="#102D28" font-size="24" font-weight="800">Route parallel</text>
+      <text x="22" y="104" fill="#102D28" font-size="24" font-weight="800">agents</text>
+      <g transform="translate(22 130)" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="12" font-weight="700">
+        <rect width="202" height="28" rx="7" fill="#F6F0E5"/><text x="12" y="19" fill="#16342F">small  · scan</text>
+        <rect y="36" width="202" height="28" rx="7" fill="#111827"/><text x="12" y="55" fill="#F6F0E5">medium · review</text>
+        <rect y="72" width="202" height="28" rx="7" fill="#6C5CE7"/><text x="12" y="91" fill="#F6F0E5">big    · synthesize</text>
+      </g>
+    </g>
+
+    <g id="result-card" transform="translate(858)">
+      <rect x="7" y="8" width="246" height="252" rx="18" fill="#AAA49B" opacity=".28"/>
+      <rect width="246" height="252" rx="18" fill="#FFD166"/>
+      <text x="22" y="33" fill="#6A4B00" font-size="13" font-weight="800" letter-spacing="1.4">04 / RETURN</text>
+      <text x="22" y="75" fill="#2C240D" font-size="24" font-weight="800">Deliver one</text>
+      <text x="22" y="104" fill="#2C240D" font-size="24" font-weight="800">result</text>
+      <rect x="22" y="130" width="202" height="92" rx="12" fill="#F6F0E5" opacity=".72"/>
+      <circle cx="61" cy="176" r="25" fill="#111827"/>
+      <path d="M48 176l8 8 18-20" fill="none" stroke="#61D2B4" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+      <text x="96" y="169" fill="#46370C" font-size="14" font-weight="800">VERIFIED</text>
+      <text x="96" y="192" fill="#6A5518" font-size="11">journaled + resumable</text>
+    </g>
+  </g>
+</svg>

package/dist/accept-workflow-guidance.d.ts

@@ -0,0 +1,14 @@
+/** A reviewed frozen-guidance hash transition recorded in the coverage manifest. */
+export interface WorkflowGuidanceAcceptance {
+    path: string;
+    previousSha256: string;
+    sha256: string;
+    changed: boolean;
+}
+/**
+ * Accepts reviewed changes to explicitly named frozen workflow-authoring files.
+ *
+ * Throws before writing when no path is supplied, a path is not frozen, a file
+ * is missing, or the coverage manifest no longer contains the expected entry.
+ */
+export declare function acceptWorkflowGuidance(root: string, requestedPaths: readonly string[]): WorkflowGuidanceAcceptance[];