@signalridge/pi-workflows 1.3.2 → 1.5.0

package/skills/workflow-authoring/references/capability-details.md

@@ -1,8 +1,8 @@
 <!-- GENERATED from WORKFLOW_CAPABILITY_CONTRACT; do not edit by hand. -->
 # Exhaustive workflow capability facts
 
-Contract format: `1.0.0`<br>
-Contract content / skill / extension: `1.3.2`
+Contract format: `2.0.0`<br>
+Contract content / skill / extension: `1.5.0`
 
 Every exact fact below is projected from the installed extension's capability contract. Explanatory judgment belongs in the hand-written references next to this file.
 
@@ -16,8 +16,7 @@ Every exact fact below is projected from the installed extension's capability co
 - `label`: string (optional); default: derived from phase and call count
 - `phase`: string (optional); default: current phase
 - `schema`: plain JSON Schema (optional)
-- `model`: string (optional); default: pi-subagents model resolver
-- `tier`: small\|medium\|large (optional); default: pi-subagents workflow tier
+- `tier`: agent tier key (optional); default: the agent's own tier, else agentTiers.defaultTier
 - `isolation`: "worktree" (optional); default: pi-subagents worktree policy
 - `thread`: string (optional); default: fresh session per call
 - `toolset`: string (optional); default: configured host/agent toolset hint
@@ -28,8 +27,11 @@ Every exact fact below is projected from the installed extension's capability co
 - Constraint: recoverable failures return null after retries; nonrecoverable failures throw
 - Constraint: schema noncompliance after bounded repair attempts is nonrecoverable
 - Constraint: resume replays only the longest unchanged prefix; the first miss and every later call execute live
+- Constraint: replayed calls do not consume the real-dispatch maxAgents or token/phase budgets
 - Constraint: spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict
-- Constraint: explicit model is resolved and scope-checked by pi-subagents; unavailable selectors fail closed
+- Constraint: tier names a key in the host's agentTiers catalogue; a key it does not define is rejected before dispatch
+- Constraint: resolveAgentTier in pi-subagents owns model, thinking, clamping, availability, and the resolution snapshot
+- Constraint: there is no per-call model or thinking: a tier is the only model policy a workflow can express
 - Constraint: same-thread calls must be sequential and preserve a stable workflow thread name
 - Constraint: threads cannot be combined with worktree isolation
 
@@ -41,8 +43,9 @@ Every exact fact below is projected from the installed extension's capability co
 - Signature: `parallel(thunks) => Promise<Array<unknown \| null>>`
 - Constraint: requires functions rather than promises
 - Constraint: result order matches input order
-- Constraint: recoverable thunk failures become null; nonrecoverable failures throw
+- Constraint: recoverable thunk failures become null; nonrecoverable failures throw after the batch barrier settles
 - Constraint: a breached agent cap cancels only its own batch
+- Constraint: accepts at most 4096 thunks per call
 
 <a id="runtime-global-pipeline"></a>
 ## pipeline
@@ -53,6 +56,21 @@ Every exact fact below is projected from the installed extension's capability co
 - Constraint: items run concurrently while stages per item run sequentially
 - Constraint: each stage receives previousValue, originalItem, and zero-based index
 - Constraint: a null stage result is passed to the next stage
+- Constraint: accepts at most 4096 items per call and awaits the whole batch before surfacing fatal errors
+
+<a id="runtime-global-orchestrate"></a>
+## orchestrate
+
+- Classification: `runtime-global`
+- Support: `supported`
+- Signature: `orchestrate(tasks, options?) => Promise<{ results, tasks }>`
+- `onError`: "skip-dependents"\|"continue"\|"fail-fast" (optional); default: "skip-dependents"
+- Constraint: task ids and dependencies are validated before any callback runs
+- Constraint: ready tasks run in declaration-order layers with a barrier between layers
+- Constraint: task context carries detached named results and statuses
+- Constraint: ordinary task failures can retry up to three times; fatal workflow errors propagate
+- Constraint: failed or skipped dependencies skip descendants by default; continue runs them with null values
+- Constraint: the graph accepts at most 128 tasks and emits task start/retry/end/skip runtime events
 
 <a id="runtime-global-workflow"></a>
 ## workflow
@@ -60,9 +78,9 @@ Every exact fact below is projected from the installed extension's capability co
 - Classification: `runtime-global`
 - Support: `supported`
 - Signature: `workflow(savedName, childArgs?) => Promise<unknown>`
-- Constraint: one nested level
+- Constraint: one nested level; concurrent sibling nested calls are allowed
 - Constraint: shares limiter, counters, token accounting, and store
-- Constraint: nested runs get unique runIds via nestedCallSeq
+- Constraint: nested calls use call-index/generation namespaces and replay as one parent result
 
 <a id="runtime-global-verify"></a>
 ## verify
@@ -270,6 +288,7 @@ Every exact fact below is projected from the installed extension's capability co
 - Support: `supported`
 - Signature: `resumeFromRunId?: string`
 - Constraint: resumes a prior incomplete run with an edited script
+- Constraint: original args and execution limits are reused on resume
 - Constraint: unchanged positional calls replay from cache until the first changed call
 - Constraint: always runs in the background
 
@@ -281,6 +300,7 @@ Every exact fact below is projected from the installed extension's capability co
 - Signature: `export const meta = { name, description, phases? }`
 - Constraint: must be the first statement
 - Constraint: name and description must be nonblank literals
+- Constraint: workflow meta and phase metadata cannot contain model or thinking fields
 - Constraint: spread, computed keys, methods, template interpolation, and __proto__/constructor/prototype are rejected
 
 <a id="script-contract-determinism"></a>

package/skills/workflow-authoring/references/debugging.md

@@ -8,7 +8,7 @@ Start from the symptom, then reproduce through the real workflow runtime with de
 | `parallel()` rejects input | Promises were passed instead of thunks | [runtime](runtime.md#topology) |
 | Synthesis starts early | Fan-out was not awaited as one complete result set | [pattern selection](pattern-selection.md#fan-out-and-synthesize) |
 | Coverage silently disappears | `null` results were filtered before IDs were ledgered | [lifecycle](lifecycle.md#retry-and-recoverable-failure) |
-| Wrong model is used | A higher-priority selector overrides the expected route | [registry ownership](registry-ownership.md#priority) |
+| Wrong model or thinking is used | The call named no tier and fell to a default, or named one whose profile is not what you expected | [registry ownership](registry-ownership.md#priority) |
 | Unknown `agentType` log | A live registry name was guessed or is unavailable | [registry ownership](registry-ownership.md#agent-types) |
 | Budget exceeds the number shown | The budget is a soft pre-call gate and work was in flight | [lifecycle](lifecycle.md#bounds-and-budget) |
 | Later calls rerun on resume | An earlier call missed or changed, ending the replayable prefix | [lifecycle](lifecycle.md#resume) |
@@ -23,7 +23,7 @@ Start from the symptom, then reproduce through the real workflow runtime with de
 
 1. Reduce to the smallest script that preserves metadata, labels, work IDs, and the failing topology.
 2. Replace provider calls with deterministic, schema-aware fake agents.
-3. Record call order, labels, phases, prompts, results, and `null` entries.
+3. Record call order, labels, phases, prompts, resolved tiers, results, and `null` entries.
 4. When the failure turns on a disputed signature or default, compare it with the compact [capability index](capabilities.md); follow its exhaustive-facts pointer only when needed.
 5. Separate runtime defects from unsupported authoring assumptions and compatibility-only behavior.
 6. Fix only the demonstrated authoring issue; do not rely on known out-of-scope gaps in nested persistence, resume accounting, checkpoint forms/timeouts, metadata validation, or budget overshoot.

package/skills/workflow-authoring/references/focused-recipes.md

@@ -4,6 +4,7 @@ Read only the recipe matching the concern. Change task prompts, schemas, bounds,
 
 | Concern | Preserve when adapting | Tested recipe |
 | --- | --- | --- |
+| Named dependencies | Validate stable task IDs before dispatch; use the default skip policy unless dependents can consume `statuses` and null results. | [Named task graph](../examples/named-task-graph.js) |
 | Phased budgets | Phase and run budgets are soft pre-call gates; active work can overshoot. Report shared spend and bound calls independently. | [Phased budgets](../examples/phased-budgets.js) |
 | Saved workflows | Use a context-supplied name, await jobs sequentially, nest one level, and treat shared limits, counters, tokens, limiter, and store as parent capacity. | [Saved nested workflows](../examples/saved-nested-workflows.js) |
 | Semantic retry | Separate it from recoverable runtime retries. Use a new unique label per bounded attempt and return the attempt ledger plus exhausted outcome. | [Bounded semantic retry](../examples/bounded-semantic-retry.js) |

package/skills/workflow-authoring/references/lifecycle.md

@@ -2,7 +2,7 @@
 
 ## Bounds and budget
 
-Set finite bounds that match the work for `maxAgents`, `concurrency`, and `agentRetries`; bound loops and semantic retries inside the script. Treat invocation-level `agentTimeoutMs` and `tokenBudget` as opt-in user constraints, not precautionary defaults. Omit `tokenBudget` unless the user supplies a cap or explicitly asks you to choose one. If asked to choose, allow for every planned agent call, retry, synthesis, and verification pass, with headroom. A tight gate can terminate coverage; it does not reduce work already in flight. An omitted `agentTimeoutMs` uses the configured `defaultAgentTimeoutMs` and is otherwise unbounded. An omitted `tokenBudget` uses the configured `defaultTokenBudget` and is otherwise unlimited.
+Set finite bounds that match the work for `maxAgents`, `concurrency`, and `agentRetries`; bound graph tasks, fan-out items, loops, and semantic retries inside the script. A journal replay is logical work and does not consume the real-dispatch `maxAgents` cap, but it still counts toward reported call totals. Treat invocation-level `agentTimeoutMs` and `tokenBudget` as opt-in user constraints, not precautionary defaults. Omit `tokenBudget` unless the user supplies a cap or explicitly asks you to choose one. If asked to choose, allow for every planned agent call, retry, synthesis, and verification pass, with headroom. A tight gate can terminate coverage; it does not reduce work already in flight. An omitted `agentTimeoutMs` uses the configured `defaultAgentTimeoutMs` and is otherwise unbounded. An omitted `tokenBudget` uses the configured `defaultTokenBudget` and is otherwise unlimited.
 
 Enter a phase budget with `phase("Name", { budget: N })`; phase metadata does not carry budgets. `N` is a token allowance, not a call or round count: size it for the intended agent work instead of copying a small iteration limit. Token and phase budgets are soft pre-call gates. Spend lands after agents finish, so concurrent work can overshoot. A phase budget gates later calls in that phase; it neither reserves tokens nor cancels active calls. `budget.spent()` and `budget.remaining()` include nested work.
 
@@ -22,9 +22,9 @@ Always retain `{ id, status, result }` or an equivalent ledger for each intended
 
 ## Resume
 
-Resume replays only the longest unchanged prefix of journaled calls. Once one call is new, changed, or unusable, that call and all later calls execute live. Stable lexical call ordering, prompts, labels, routing options, and inputs therefore matter. Retry chains can cascade after an upstream miss. Nested workflows do not reuse the parent's resume journal.
+Resume replays only the longest unchanged prefix of journaled calls. Once one call is new, changed, or unusable, that call and all later calls execute live. Stable lexical call ordering, prompts, labels, routing options, and inputs therefore matter. Retry chains can cascade after an upstream miss. A nested workflow is cached as one parent call; an unchanged child replays its complete result, while a changed or interrupted child runs live in a generation-scoped namespace.
 
-Only a call that finishes with a real result is journaled. A call whose every attempt was recoverable (including one that only ever produced `AGENT_EMPTY_OUTPUT`) contributes no journal entry, so resuming that run reruns exactly that call and everything lexically after it live; the earlier, already-succeeded prefix still replays from cache.
+Only a call that finishes with a real result is journaled. A call whose every attempt was recoverable (including one that only ever produced `AGENT_EMPTY_OUTPUT`) contributes no journal entry, so resuming that run reruns exactly that call and everything lexically after it live; the earlier, already-succeeded prefix still replays from cache. Schema repair retries include the concrete validation errors in the next prompt.
 
 The runtime blocks common accidental nondeterminism, but this is not a security boundary. Pass timestamps, randomness, and external decisions through `args`.
 

package/skills/workflow-authoring/references/pattern-selection.md

@@ -5,6 +5,7 @@ Choose from data dependencies, then read only the matching example. JavaScript o
 <a id="fan-out-and-synthesize"></a>
 | Dependency shape | Pattern | Preserve when adapting | Example |
 | --- | --- | --- | --- |
+| Named steps have explicit dependencies | Named task graph | Give every task a stable ID; let `orchestrate()` validate cycles, run declaration-order layers, and pass named results/statuses to dependents | [Adapt](../examples/named-task-graph.js) |
 | Heterogeneous items need different handling | Classify and act | Finish all classification before routed action; ledger classification and action failures by item ID | [Adapt](../examples/classify-and-act.js) |
 | Independent work needs whole-set judgment | Fan out and synthesize | Pass thunks; await the full set; give synthesis every intended ID, including `null` | [Adapt](../examples/fan-out-and-synthesize.js) |
 | Claims need skeptical checks | Adversarial verification | Use separate producer and skeptic calls; start skepticism after production; ledger both failures | [Adapt](../examples/adversarial-verification.js) |

package/skills/workflow-authoring/references/registry-ownership.md

@@ -4,14 +4,16 @@ Model routes and agent types are dynamic references. Their shape and owner are d
 
 ## Model routes
 
-The `pi-subagents` workflow-tier settings own route names. Standard routes are `small`, `medium`, and `large`; use another route only when its name and purpose are supplied in context. A route is selected with `tier`. An exact user-requested model is selected with `model` and is resolved/scope-checked by pi-subagents.
+pi-subagents owns the agent-tier catalogue; a workflow names a key from it and nothing else. Available tier names depend on active configuration and are intentionally absent from static skill files — read them from the destination context.
+
+A name a script writes is not a claim that the name exists. Scripts that ship with this package name `low`/`medium`/`high` — the profiles a fresh install receives — and a host that does not define one of those drops it in favour of that host's default, with a log line. A script you write is held to the stricter rule: an undefined tier is a typo in a catalogue you own, so it is rejected before dispatch rather than rerouted. Write the tier you mean for the host you are targeting; do not copy `low`/`medium`/`high` in on the assumption that every machine has them.
 
 ## Agent types
 
-The agent registry owns agent-type names and their bound instructions, tools, model, and isolation policy. Use `agentType` only when context supplies both its name and purpose. Do not infer an agent type from a role-like label.
+The agent registry owns agent-type names and their bound instructions, tools, Agent-tier defaults, and isolation policy. Use `agentType` only when context supplies both its name and purpose. Do not infer an agent type from a role-like label.
 
 ## Priority
 
-Routing priority is explicit `model` > named `tier` > phase/run model > pi-subagents agent configuration > parent session. Higher priority means selection, not "try this then fall back to the next selector." Avoid specifying competing selectors unless deliberately overriding a lower-priority default.
+A call's `tier` takes precedence over an agent type's own tier default, which takes precedence over `agentTiers.defaultTier`. `resolveAgentTier()` in pi-subagents then resolves model, thinking, clamping, availability, and the immutable snapshot as one decision. Neither a call, nor workflow meta, nor a phase may carry model or thinking fields.
 
-Unavailability is fail-closed for explicit `model` and named tiers: pi-subagents reports the selector and does not silently run a different model. An omitted selector may inherit the parent session according to the companion's current settings.
+Unavailability is fail-closed: pi-subagents names the tier and does not silently run a different model. A managed call with no tier and no applicable default is rejected rather than inheriting the parent session.

package/skills/workflow-authoring/references/review.md

@@ -6,23 +6,25 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 
 - Is literal `export const meta` the first statement, with a short unique name and useful description?
 - Are only used phases declared, and does each named phase begin at the intended boundary?
+- Are workflow meta and phase objects free of retired `model`/`thinking` fields?
 - Does the script call at least one agent and explicitly return JSON-serializable data?
 - Are imports and nondeterministic APIs absent?
 
 ## Topology and identity
 
-- Does topology match dependencies: thunks for independent parallel work, stages for per-item pipelines, barriers before whole-set synthesis?
-- Is cardinality bounded before fan-out?
+- Does topology match dependencies: `orchestrate` for named graphs, thunks for independent parallel work, stages for per-item pipelines, barriers before whole-set synthesis?
+- Is cardinality bounded before graph construction and fan-out?
 - Is every agent label short and unique?
-- Are stable work-unit IDs retained beside ordered results?
+- Are stable graph/work-unit IDs retained beside ordered results?
 - Are failed/null identities recorded before any filtering?
 
 ## Data and routing
 
 - Does JavaScript consume structured fields only after a small plain JSON Schema guarantees them?
 - Does synthesis receive complete coverage and failure ledgers?
-- Are `model`, `tier`, and `agentType` used according to selector priority?
-- Did every nonstandard route or agent type come from context with a name and purpose?
+- Does every `tier` name a key the destination host actually defines, rather than a guessed one?
+- Is the tier the only model/thinking policy source, via pi-subagents' `resolveAgentTier()`?
+- Did every tier or agent-type name come from context with a name and purpose?
 
 ## Lifecycle
 
@@ -30,12 +32,15 @@ Review author-visible behavior, not formatting preferences. When behavior depend
 - Are loops, agents, concurrency, timeout, and token spend bounded appropriately?
 - Are budget claims honest about soft gates and in-flight overshoot?
 - Are checkpoints limited to implemented confirmation/headless behavior?
-- Does nesting stay one level and account for shared limits/store?
-- Would lexical call order remain stable under resume?
+- Does nesting stay one level, allow only safe sibling concurrency, and account for shared limits/store?
+- Are helper attempts and graph retries finite and separately visible?
+- Would lexical call order and generated graph order remain stable under resume?
+- Does the journal/tombstone retain the resolved `tier`, including one the host defaulted to?
 
 ## Compatibility and publication
 
 - Does new code use `log()` rather than compatibility-only `console`?
+- Are runtime progress events and background result delivery described without promising durability the engine does not provide?
 - Is compatibility behavior clearly distinguished from supported authoring behavior and VM substrate?
 - Do package, skill, and generated contract versions match?
 - Do all relative links resolve within the publishable package?

package/skills/workflow-authoring/references/runtime.md

@@ -4,19 +4,20 @@ Use this page for routine scripts. Open the generated capability index only when
 
 ## Script envelope
 
-Start with the only legal export: `export const meta = { name, description, phases?: [{ title, detail?, model? }] }`. Values are nonblank literals; declare only used phases and call `phase()` before each phase's work. The remaining body already runs inside an async function: write helpers as ordinary declarations; `export default` and other exports are invalid. Return the result explicitly.
+Start with the only legal export: `export const meta = { name, description, phases?: [{ title, detail? }] }`. Values are nonblank literals; declare only used phases and call `phase()` before each phase's work. Workflow meta and phase objects must not contain `model` or `thinking`; those retired fields are rejected. The remaining body already runs inside an async function: write helpers as ordinary declarations; `export default` and other exports are invalid. Return the result explicitly.
 
-The runtime supplies `agent`, `parallel`, `pipeline`, `workflow`, quality/control helpers, `phase`, `log`, `args`, `cwd`, restricted `process.cwd()`, and `budget`. Imports, `require()`, filesystem modules, `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable. The Node VM realm is implementation substrate, not a security boundary or public API.
+The runtime supplies `agent`, `parallel`, `pipeline`, `orchestrate`, `workflow`, quality/control helpers, `phase`, `log`, `args`, `cwd`, restricted `process.cwd()`, and `budget`. Imports, `require()`, filesystem modules, `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable. The Node VM realm is implementation substrate, not a security boundary or public API.
 
 ## Topology
 
 - `parallel()` takes thunks, runs independent work, and preserves input order. Await the whole array before whole-set synthesis.
 - `pipeline()` runs stages sequentially per item while items proceed concurrently. Each stage receives `(previousValue, originalItem, index)` and forwards `null` to the next stage, so guard missing coverage first.
-- `workflow(name, childArgs?)` runs a context-supplied saved workflow. Nesting is one level and shares limits, counters, tokens, and store.
+- `orchestrate()` is the preferred topology for named dependencies. Give each task a unique `id`, optional `dependsOn`, and a `run({ id, attempt, results, statuses })` callback. The runtime validates the graph, executes declaration-order ready layers behind barriers, and returns `{ results, tasks }`; use `onError: "continue"` only when a downstream task can handle failed dependencies.
+- `workflow(name, childArgs?)` runs a context-supplied saved workflow. Nesting is one level, shares limits/counters/tokens/store, and journals the complete child result as one parent replay boundary.
 
 ## Data and failure
 
-Call `agent(prompt, { label, schema? })`; it returns text, a schema-validated value, or recoverable `null`. Nonrecoverable limit, validation, and budget failures throw. Record each intended work ID before filtering. A `null` means missing coverage, never a negative finding.
+Call `agent(prompt, { label, schema?, tier? })`; it returns text, a schema-validated value, or recoverable `null`. `tier` names a key in the host's agent-tier catalogue. Nonrecoverable limit, validation, budget, unknown-tier, and unavailable-tier failures throw. Record each intended work ID before filtering. A `null` means missing coverage, never a negative finding.
 
 Use `agent(prompt, { thread: "implementer" })` when the same managed subagent must receive a later follow-up with its complete conversation intact. Reuse a thread name sequentially; never put same-thread calls in one `parallel()` batch. Threads are scoped to one workflow run/session and cannot use worktree isolation. A pause or process restart may require a fresh thread session.
 
@@ -24,6 +25,6 @@ When JavaScript reads fields, pass a small plain JSON Schema. Schema noncomplian
 
 ## Routing and support
 
-Selector priority is explicit `model` > named `tier` > phase/run model > pi-subagents agent configuration > parent session. An unavailable explicit selector fails closed rather than silently choosing another model. Worktree isolation is also fail-closed and remains owned by pi-subagents. See [registry ownership](registry-ownership.md).
+`tier` is a key in the host's agent-tier catalogue, not a model ID. The catalogue and its names belong to the user running the workflow; read the available keys from the destination context rather than assuming any particular name exists. A tier this host does not define is rejected before dispatch — only the scripts shipped with this package reroute to the host default instead, because they cannot know the catalogue they will land in. pi-subagents' `resolveAgentTier()` alone resolves the final model, thinking, clamping, availability, and snapshot. A tier the host does not define is rejected before dispatch. Omitting `tier` uses the agent's own tier, then `agentTiers.defaultTier`; a host whose default has been cleared rejects the call instead of inheriting the parent model. There is no per-call model or thinking, and workflow meta and phases may not carry them either. Worktree isolation remains owned by pi-subagents. See [registry ownership](registry-ownership.md).
 
 Generated entries marked `supported` are authoring API. `console` and whole-script Markdown fences are compatibility-only. VM realm facilities are internal. Active model routes and agent types are dynamic. Use `log()` in new scripts.

package/skills/workflow-authoring/references/versions.md

@@ -9,5 +9,5 @@ When copying a workflow between installations:
 1. Check the destination's generated version and exact capability facts.
 2. Re-check every supported global, option, and constraint used by the script.
 3. Treat compatibility entries as preservation aids, not portable recommendations.
-4. Re-resolve dynamic model routes and agent types from destination context; static docs intentionally contain no live entries.
+4. Re-resolve tier keys and agent types from destination context; both come from the destination host's configuration, and static docs intentionally contain no live catalogue entries.
 5. Prefer runtime behavior when prose and execution disagree, and report the documentation mismatch rather than changing behavior during an authoring fix.

package/skills/workflow-patterns/SKILL.md

@@ -1,51 +1,90 @@
 ---
 name: workflow-patterns
-description: Argument shapes for the 5 built-in workflow patterns — deep-research, adversarial-review, code-review, multi-perspective, codebase-audit — runnable via the `workflow` tool's `name` input, without slash-command syntax. Use for requests like "research X", "fact-check/adversarially review this", "review this diff/PR", "analyze from multiple perspectives", or "audit the codebase for Y". Not for authoring a new workflow script — see workflow-authoring.
+description: Choose and run one of Pi's built-in multi-agent workflows for research, adversarial review, code review, multi-perspective analysis, or codebase auditing. Use when the request matches a named pattern; use workflow-authoring instead for a new script or custom topology.
 metadata:
-  version: "1.2.1"
+  version: "1.5.0"
 ---
 
 # Built-in workflow patterns
 
-@signalridge/pi-workflows ships 5 curated, tested workflow patterns. Each is also a
-slash command (`/deep-research`, `/adversarial-review`, `/code-review`,
-`/multi-perspective`, `/codebase-audit`), but they are equally reachable from
-the `workflow` tool directly: call it with `name` set to the pattern name
-below and `args` matching its shape, instead of writing an equivalent script
-from scratch. Prefer this over authoring a new script whenever the request
-fits one of these shapes — the curated version is already reviewed and tested.
+Use a built-in when its input shape matches the request. The built-ins are
+reviewed scripts with bounded fan-out, structured intermediate results, and a
+final aggregation step. Prefer them over writing a new script for a standard
+research or review task.
 
-A project or user saved workflow of the same name always takes precedence
-over a built-in of that name — on the slash command, too.
+## Choose by task shape
 
-These 5 names are reachable only at the `workflow` tool's top-level `name`
-input, not via the in-script `await workflow(savedName, childArgs)` helper —
-that helper resolves saved workflows only. Calling `workflow('deep-research')`
-from inside a script fails as an unknown saved workflow; use the top-level
-`name` input instead.
+| Request | Pattern | Input |
+| --- | --- | --- |
+| Investigate a question with cross-checked sources | `deep-research` | `{ question, angles?, minSupport? }` |
+| Test a claim or task with skeptical reviewers | `adversarial-review` | `{ task, reviewers?, threshold? }` |
+| Review a diff or change set from multiple angles | `code-review` | `{ diff, diffSource? }` |
+| Compare a topic from independent viewpoints | `multi-perspective` | `{ topic, perspectives? }` |
+| Assess codebase health, risk, and debt | `codebase-audit` | `{ scope?, root?, focus?, checks? }` |
 
-## Patterns
+Do not use a built-in for one direct question, one simple delegation, or a
+custom dependency graph. Use the ordinary agent tool for small work and load
+[workflow-authoring](../workflow-authoring/SKILL.md) for custom scripts.
 
-| `name` | When to reach for it | `args` |
-| --- | --- | --- |
-| `deep-research` | Research a question across the web with cross-checked sources | `{ question: string, angles?: number, minSupport?: number }` — `angles` (default 4) is the number of distinct search queries; `minSupport` (default 2) is the minimum distinct sources required for a claim to survive cross-checking |
-| `adversarial-review` | Investigate a task/claim, then cross-check each finding with skeptical reviewers | `{ task: string, reviewers?: number, threshold?: number }` |
-| `code-review` | Multi-angle review of a diff (correctness, reuse, simplification, efficiency, altitude) | `{ diff: string, diffSource?: string }` — get `diff` yourself first (e.g. `git diff`, `gh pr diff <n>`); this path does not fetch it for you |
-| `multi-perspective` | Analyze a topic from several independent perspectives in parallel, then synthesize | `{ topic: string, perspectives?: string[] }` — omit or give fewer than 2 to use the default set (technical, product, security, user experience, maintainability) |
-| `codebase-audit` | Audit a codebase for health, risk, and debt across dimensions | `{ scope?: string, root?: string, focus?: string, checks?: string[] }` — `scope`/`root` chooses the directory and `focus`/`checks` refines what the agents inspect |
+## Invocation contract
 
-## Example
+The model-facing call is a `workflow` tool call, not JavaScript:
 
 ```json
-{ "name": "deep-research", "args": { "question": "What are the tradeoffs of X vs Y?" } }
+{
+  "name": "deep-research",
+  "args": { "question": "What are the trade-offs between X and Y?" },
+  "background": true
+}
 ```
 
-This is a `workflow` tool call, not a script — omit `script` entirely. The run
-starts in the background exactly like the slash-command form; `background`,
-`maxAgents`, `concurrency`, `agentRetries`, `agentTimeoutMs`, and `tokenBudget`
-all still apply.
+`name` resolves a saved workflow before the built-in. A saved workflow with the
+same name intentionally overrides the built-in. Do not send `script` together
+with `name`; choose one form. `background` defaults to `true`; use
+`background: false` only when the caller needs the result inline or a human
+checkpoint must be shown.
+
+## Input rules
+
+- `deep-research` requires a non-empty `question`; `angles` and `minSupport`
+  should be small positive bounds appropriate to the question.
+- `adversarial-review` requires a non-empty `task`; use reviewer counts and
+  thresholds that fit the risk rather than maximizing votes.
+- `code-review` requires the actual diff. Obtain it first with the host's safe
+  diff path; do not ask the workflow to guess which files changed.
+- `multi-perspective` requires a non-empty `topic`; provide at least two
+  distinct perspectives when overriding the defaults.
+- `codebase-audit` accepts a scope/root and optional focus/check list. Keep the
+  scope narrow enough that every worker can inspect it and cite concrete paths.
+
+## Result and recovery rules
+
+Every built-in returns a bounded aggregate of successful intermediate results
+and a final report. Failed worker calls can remain `null` or be omitted from that
+aggregate, but stay visible in run details. A background call returns a run ID
+immediately; inspect it with `workflow_control` (`get`, `pause`, `resume`, or
+`stop`) rather than starting a duplicate run. If a provider limit pauses the run, resume the same
+run after the configured retry window. A changed script or saved workflow
+replays only its unchanged journal prefix, so preserve the original inputs when
+resuming.
+
+Inspect run details for missing or `null` worker results before treating the
+aggregate as complete. State when sources, review angles, or audit dimensions
+were unavailable; a settled workflow may still contain incomplete evidence.
+
+## Built-in topology summary
 
-## Writing a new workflow instead
+- Research plans queries, gathers them concurrently, cross-checks claims, then
+  writes a cited report.
+- Adversarial review separates finding generation from skeptical verification
+  before consensus.
+- Code review fans out correctness, reuse, simplification, efficiency,
+  architecture, security, and testability lenses, then verifies candidates
+  before ranking them.
+- Multi-perspective analysis runs independent views behind a barrier before
+  synthesis.
+- Codebase audit maps structure first, then runs bounded dimension audits before
+  its roadmap.
 
-If the request doesn't fit one of these 5 shapes, author a script with
-`script` as usual — see the workflow-authoring skill.
+When a built-in needs a dependency beyond these shapes, author a custom
+`orchestrate()` graph instead of adding hidden assumptions to a built-in.

package/skills/workflow-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: workflow-review
+description: Audit an existing Pi JavaScript workflow for topology, prompt/data flow, limits, failure handling, cancellation, resume safety, and publication compatibility. Use when reviewing or debugging a workflow script or saved run; do not use to run a standard named workflow.
+metadata:
+  version: "1.5.0"
+---
+
+# Workflow review
+
+Review the workflow as an executable orchestration program, not as prose. The
+review is read-only unless the user explicitly asks for a fix. Report concrete
+failure scenarios and evidence; do not recommend extra agents merely because
+they are available.
+
+## Review procedure
+
+1. **Identify the boundary.** Read the complete script, its invocation `args`,
+   saved-workflow source if applicable, and the relevant package version. Do not
+   infer behavior from a truncated run notification.
+2. **Map the topology.** List every work unit and its stable ID. Mark each as a
+   direct call, `orchestrate` task, `parallel` item, `pipeline` stage, loop
+   round, quality helper, checkpoint, or nested workflow. Draw the dependency
+   edges and barriers in declaration order.
+3. **Trace data flow.** For every downstream prompt, identify the exact input
+   values and their bounds. Confirm that structured fields have a schema and
+   that failed/null results remain visible in a ledger.
+4. **Check admission.** Verify finite bounds for task count, fan-out, loops,
+   retries, concurrency, token budget, timeout, and evidence size. Check that
+   a graph validates IDs, references, duplicate edges, and cycles before any
+   callback runs.
+5. **Check failure policy.** Distinguish recoverable child `null` from fatal
+   workflow errors. For graphs, verify whether the default
+   `skip-dependents`, explicit `continue`, or `fail-fast` policy matches the
+   task. Ensure ordinary task retries do not silently duplicate side effects.
+6. **Check lifecycle.** Verify every batch is awaited, cancellation stops
+   owned work, checkpoints have a headless behavior, and nested workflows stay
+   within one level and shared capacity.
+7. **Check resume.** Keep call order, labels, prompts, routing options, and
+   inputs stable. Confirm that edited or missing calls invalidate downstream
+   replay and that nested results use a generation-scoped boundary. Treat
+   effectful worktree/file changes as non-replayable unless its effects are
+   explicitly restored.
+8. **Check publication.** Confirm the literal meta envelope, no imports or
+   nondeterministic APIs, safe relative links, current capability facts, and
+   an appropriate changeset when shipped package files changed.
+
+## Output format
+
+Rank findings by severity and include:
+
+- `file:line` or the task ID;
+- the concrete input or lifecycle sequence that triggers it;
+- the incorrect or risky behavior;
+- the smallest safe fix;
+- whether it blocks correctness, loses coverage, wastes tokens, or is only a
+  documentation concern.
+
+End with a short topology summary and a list of verified strengths. If no
+finding is reproducible, say so and state which paths were checked.
+
+## References
+
+- Use [the review checklist](../workflow-authoring/references/review.md) for
+  the compact acceptance gate.
+- Use [lifecycle](../workflow-authoring/references/lifecycle.md) for pause,
+  stop, budget, retry, and resume semantics.
+- Use [debugging](../workflow-authoring/references/debugging.md) to reduce a
+  failure to a deterministic fake-agent reproduction.
+- Use [the generated capability index](../workflow-authoring/references/capabilities.md)
+  only when a signature or support boundary is disputed.