@signalridge/pi-workflows 1.3.2 → 1.4.0

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.4.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.4.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.

package/src/capabilities.ts

@@ -58,6 +58,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       "recoverable failures return null after retries; nonrecoverable failures throw",
       "schema noncompliance after bounded repair attempts is nonrecoverable",
       "resume replays only the longest unchanged prefix; the first miss and every later call execute live",
+      "replayed calls do not consume the real-dispatch maxAgents or token/phase budgets",
       "spawnKeys rotate by generation on resume so pi-subagents never raises a fingerprint conflict",
       "explicit model is resolved and scope-checked by pi-subagents; unavailable selectors fail closed",
       "same-thread calls must be sequential and preserve a stable workflow thread name",
@@ -72,8 +73,9 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     constraints: [
       "requires functions rather than promises",
       "result order matches input order",
-      "recoverable thunk failures become null; nonrecoverable failures throw",
+      "recoverable thunk failures become null; nonrecoverable failures throw after the batch barrier settles",
       "a breached agent cap cancels only its own batch",
+      "accepts at most 4096 thunks per call",
     ],
   },
   {
@@ -85,6 +87,28 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
       "items run concurrently while stages per item run sequentially",
       "each stage receives previousValue, originalItem, and zero-based index",
       "a null stage result is passed to the next stage",
+      "accepts at most 4096 items per call and awaits the whole batch before surfacing fatal errors",
+    ],
+  },
+  {
+    name: "orchestrate",
+    classification: "runtime-global",
+    signature: "orchestrate(tasks, options?) => Promise<{ results, tasks }>",
+    options: [
+      {
+        name: "onError",
+        kind: '"skip-dependents"|"continue"|"fail-fast"',
+        optional: true,
+        default: '"skip-dependents"',
+      },
+    ],
+    constraints: [
+      "task ids and dependencies are validated before any callback runs",
+      "ready tasks run in declaration-order layers with a barrier between layers",
+      "task context carries detached named results and statuses",
+      "ordinary task failures can retry up to three times; fatal workflow errors propagate",
+      "failed or skipped dependencies skip descendants by default; continue runs them with null values",
+      "the graph accepts at most 128 tasks and emits task start/retry/end/skip runtime events",
     ],
   },
   {
@@ -93,9 +117,9 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     signature: "workflow(savedName, childArgs?) => Promise<unknown>",
     options: [],
     constraints: [
-      "one nested level",
+      "one nested level; concurrent sibling nested calls are allowed",
       "shares limiter, counters, token accounting, and store",
-      "nested runs get unique runIds via nestedCallSeq",
+      "nested calls use call-index/generation namespaces and replay as one parent result",
     ],
   },
   {
@@ -271,6 +295,7 @@ export const WORKFLOW_CAPABILITIES: readonly CapabilityEntry[] = [
     options: [],
     constraints: [
       "resumes a prior incomplete run with an edited script",
+      "original args and execution limits are reused on resume",
       "unchanged positional calls replay from cache until the first changed call",
       "always runs in the background",
     ],