@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/skills/pi-extensible-workflows/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: pi-extensible-workflows
+description: Author, run, inspect, and recover deterministic Pi workflows. Load when a task needs multi-agent orchestration or the user explicitly requests a workflow; not for ordinary single-agent repository edits.
+---
+
+# pi-extensible-workflows
+
+## Default path
+
+Use ordinary tools for work one agent can finish; use `subagents_run` for one independent delegated task. Use `workflow` for orchestration, with distinct phase responsibilities and explicit result flow.
+
+For most multi-agent tasks, start with a named inline workflow: provide a non-empty `name` and a `script` that fans out independent work with `parallel(...)`, awaits the keyed results, passes them into one summarizing `agent(...)`, and returns.
+
+```js
+const reports = await parallel("research", {
+  first: () => agent("Research the first target."),
+  second: () => agent("Research the second target."),
+});
+
+return await agent(
+  prompt("Summarize these reports:\n\n{reports}", { reports }),
+);
+```
+
+## Runtime and safety rules
+
+Functions returned by `workflow_catalog` are globals inside workflow source. You can compose them with other workflow operations by calling them in `script`; pass their inputs through `args` when appropriate:
+```js
+// other code
+const res = await fnName(args);
+// consume res
+return ...;
+```
+
+A reviewed JavaScript file on disk can use `scriptPath` instead of `script`.
+
+Call `workflow_catalog` once to list functions and model aliases before the first workflow for a task; call `workflow_catalog({ name })` again for full detail of a function you intend to use.
+
+Workflow JavaScript has no imports, filesystem, network, process, or timers. Delegate that work to agents. `shell(command, options)` is the trusted host RPC for deterministic gates: it inherits the workflow or active-worktree cwd, merges string `env` overrides, and returns `{ exitCode, stdout, stderr }`; nonzero exits are results, but launch failures and timeouts fail with `SHELL_FAILED`.
+
+Example use of `shell`:
+
+```js
+// ... other code
+const testRes = await shell("yarn test", { env: { CI: "1" } });
+if (testRes.exitCode === 0) {
+  // success path
+  return { ok: true };
+}
+```
+
+Most of the time using `shell()` to perform mutations is an antipattern. Use it mainly for verifications or idempotent actions.
+
+## Advanced capabilities
+
+Registered functions, `outputSchema`, budgets, checkpoints, worktrees, retry/resume, CLI export, and `pipeline(...)` remain available for workflows that need them. Treat these as advanced controls rather than requirements for the default inline path.
+
+### Recovery
+
+For a failed run, call `workflow_status({ runId })` first: a compact authoritative summary (metadata, state, delivery, budget/usage, agent summary shims; no transcripts) for a run in the current project, across sessions. Pass its returned `state` as `expectedState` to the recovery tool. After a `CANCELLED` or `interrupted` follow-up, confirm whether the user accepted a recovery prompt before starting replacement work.
+
+- `agent(..., { retries })` reruns one agent call in the same run for transient failures.
+- `workflow_retry({ runId, expectedState?, foreground? })` replays a failed run into a linked child: completed agent, shell, function, and checkpoint operations replay; incomplete work executes.
+- `workflow_resume({ runId, expectedState?, budget?, foreground? })` continues a `budget_exhausted` run.
+- Recovery inherits the source snapshot's launch mode (legacy snapshots without `launchMode` recover in background); set `foreground` to override.
+- `parentRunId` on a new launch only borrows named worktrees and never replays or resumes.
+- `workflow_stop` requires the exact run ID.
+
+## `agent()` options
+
+```typescript
+export interface AgentOptions {
+  label?: string; // display name
+  model?: string; // provider/model:thinking, or alias[:thinking]
+  role?: string; // role file name
+  contextFiles?: Array<"global" | "project" | "cwd">; // which Pi context files to load
+  skills?: string[]; // minimatch overlay after the role list
+  extensions?: string[]; // minimatch overlay after the role list
+  tools?: string[]; // minimatch overlay after the role list
+  outputSchema?: JsonSchema; // structured result for a later phase
+  retries?: number; // extra same-run retries for this agent
+  timeoutMs?: number | null; // attempt timeout; null = none
+  [key: string]: JsonValue;
+}
+```
+
+A `role` already sets model, tools, skills, extensions, and context files; call-level options silently override them. Pass `{ role }` alone unless an override is indispensable for that call. When overriding, selectors overlay the role list: restrict with `["!*", "read", "grep"]`; `["*"]` turns everything back on.
+
+Extensions may add JSON-compatible agent options such as `advisor: true`; core keys retain validation and role constraints. Extension options go to setup hooks/native setup and are not inherited by child agents.
+
+Agent calls are unnamed. Direct calls receive hidden source call-site identity; aliases are unsupported, and calls from one source site must not race outside `parallel` or `pipeline`, whose structural keys make replay deterministic.
+
+## Persistent agent handles
+
+Use `agent.create(...)` when one agent must keep its transcript across several turns; use plain `agent(...)` calls for independent work.
+
+```js
+const author = agent.create({ name: "author", role: "developer" });
+const draft = await author.send("Create the first draft");
+const revised = await author.send(
+  prompt("Apply these findings:\n\n{findings}", { findings }),
+  { outputSchema },
+);
+```
+
+`agent.create({ name, ... })` takes a stable explicit string-literal `name` plus AgentOptions. Names must be unique in one run. `handle.send(prompt, options?)` accepts only `outputSchema` and `timeoutMs`, returns the same value shape as `agent(...)`, and must not overlap with another `send(...)` on the same handle: await each turn. Every `send(...)` must run in the scope that created the handle, so a handle created outside `parallel`/`pipeline` cannot send from inside one of their branches.
+
+Persistent agents are useful in certain patterns and loops when you do not want to lose the previous iteration context.
+
+## Passing agent results
+
+Use independent `agent(prompt, options)` calls and pass each completed result explicitly to the next prompt, or one `agent.create(...)` handle when the same agent must keep its own context. This keeps workflow execution deterministic and makes replay state local to each call:
+
+```js
+const findings = await agent("Inspect the implementation.");
+const fix = await agent(
+  prompt("Propose the smallest fix from these findings:\n\n{findings}", {
+    findings,
+  }),
+);
+return { findings, fix };
+```
+
+## Worktrees
+
+Use `withWorktree(name, callback)` for top-level agents that collaborate in one explicitly named worktree scope:
+
+```js
+const result = await withWorktree("issue", async ({ path, branch }) => {
+  const report = await agent("Implement the issue");
+  return { path, branch, report };
+});
+```
+
+Entering the scope materializes its worktree from the launch repository's current `HEAD`. The launch working tree must be clean. If `worktreePostCreateCommand` is configured in global or trusted project settings, its executable and arguments run directly once after checkout from the launch-relative directory inside the new worktree; it is disabled by default and the external executable must be installed separately. Failures, including the fixed 60-second timeout, fail worktree creation and roll back its artifacts. Reused, borrowed, retried, and resumed worktrees are not reseeded. The callback receives a frozen reference containing only the real string `path` and `branch`; callbacks may ignore the argument, and their bare return value is preserved. Concurrent agents share mutable files, so assign non-conflicting work or coordinate explicitly.
+
+Branches may call any workflow function, not only `agent()`. Use separate named scopes when parallel branches need isolated worktrees:
+
+```js
+const results = await parallel("implementation", {
+  api: () => withWorktree("api", () => agent("Implement the API")),
+  ui: () => withWorktree("ui", () => agent("Implement the UI")),
+});
+```
+
+Registered extension functions receive `withWorktree` in context and can compose other registered functions with `context.invoke("reviewRepository", { focus: "security" }, "security-review")`. The optional label is presentation-only; journal identity remains the function name and occurrence. Their public inputs and outputs remain JSON; callbacks cannot cross the extension boundary.
+
+## Rules
+
+- Workflow run does not inherit any of the main agent context. Keep that in mind when creating agent's prompts.
+- `model` must be a configured alias or the canonical `provider/model:thinking` form. Aliases are listed by `workflow_catalog`; prefer a suitable alias over a hardcoded model. Never guess a model identifier: verify unknown names with `pi --list-models "search term"` first, then use the fully qualified identifier it returns.
+- Use `log(messageString)` for brief operator status and `phase(phaseName)` to signal the start of another phase.
+- Use `parallel()` for independent tasks with different flows and `pipeline()` when every keyed item follows the same ordered stages; do not duplicate identical chains in `parallel()`. Signatures are `parallel(operationName, tasksRecord)` and `pipeline(operationName, itemsRecord, stagesRecord)`; keys are stable task, item, and stage names.
+- Use a JavaScript loop for repeated work; each direct `agent(...)` call gets deterministic call-site and occurrence identity.
+- Runs default to background; set tool-call `foreground: true` when asked to wait.
+- Add `budget` only for aggregate limits; omit unless the user explicitly asks. Valid dimensions are exactly `tokens`, `costUsd`, `durationMs`, and `agentLaunches`; each is `{ soft?: number, hard?: number }` with `soft < hard`.
+- `budget_exhausted` runs resume through `workflow_resume`: omitted patch values stay unchanged, `null` removes a limit, and tightening resumes directly. Relaxation stores the exact proposal and returns `{ state: "awaiting_approval", proposalId }`; `workflow_respond` must answer that ID. Rejection leaves the run exhausted; approval applies the budget and cold-resumes it. `workflow_retry` is only for persisted `failed` runs and inherits cumulative usage; replay itself consumes no budget.
+- `parallel()` and `pipeline()` return keyed bare values; await them before use. Interpolate results with `prompt("...{value}", { value })`; placeholders in plain strings remain literal.
+- Every agent must call `workflow_result` exactly once to submit its final result; unstructured agents pass `{ result: "final response" }`, while `outputSchema` agents pass a schema-valid value. One repair prompt is built in. Use `outputSchema` only when another phase compares, aggregates, or validates a result, never for final prose. Omit `retries` unless an extra retry is justified and work is idempotent.
+- Do not add persona specifications to agent prompts; define the task directly.