agwab/pi-workflow/workflow-guide

Workflow Guide

Use this skill before creating, editing, or reviewing a pi-workflow workflow.

Required first step

Read the public usage guide and bundled workflow notes before giving workflow-authoring advice:

• ../../docs/usage.md
• ../../workflows/README.md

Resolve paths relative to this skill directory. Treat those docs as the source of truth for command surface, workflow resolution, artifact-graph semantics, safety policy, and validation.

Then read at least one shipped bundled spec as a quality reference before authoring, not only the scaffolds. The scaffolds show correct JSON shape; the bundled specs show correct quality — prompt discipline, evidence gates, partial-failure handling, and control/analysis split proven on real runs. Prefer the closest match:

• ../../workflows/deep-research/spec.json — plan -> foreach research -> normalize/verify/audit -> synthesis; strong evidence and verification discipline, expensive/cheap stage separation.
• ../../workflows/deep-review/spec.json — triage -> foreach reviewers -> support dedup -> foreach devil's-advocate -> support partition -> report; multi-pass challenge and deterministic verdict joins.
• ../../workflows/spec-review/spec.json and ../../workflows/impact-review/spec.json — mapping/synthesis shapes.

Copy their proven conventions (see "Quality design patterns"), not just their structure.

Core rules

• Prefer a bundled workflow before inventing a new topology.
• When authoring a new workflow and a scaffold topology fits, start from ./scaffolds/<name>/ rather than inventing the JSON shape from scratch.
• Public schemaVersion: 1 workflow specs use artifactGraph.stages.
• Stage order controls scheduling only; it does not pass prior output into a later plain single stage.
• If a model stage needs prior artifacts, use single.from or reduce.from; use foreach.from for array fan-out and support from for deterministic helpers. after is order-only.
• For static data-driven fan-out, use foreach.from with a simple dot path into upstream control.json.
• Use each.itemIdentityPath only for non-streaming foreach items with a stable string identity, and each.itemPayloadPath only for a distinct object payload. The runtime rejects missing, duplicate, unsafe, or colliding identities rather than falling back silently.
• Use inputPolicy.terminalBarrier: "all-sources" for an intentional all-terminal fan-in, invalidateOnDependencyResume: true only for static graph consumers that must discard stale generated evidence on source resume, and maxCompiledPromptChars when the final prompt needs a hard code-point ceiling. All three are opt-in; unsupported replay ownership fails closed.
• Use type: "dynamic" only for trusted adaptive orchestration that must create official child tasks at runtime with ctx.agent(), ctx.helper(), or ctx.workflow(). maxNestedWorkflowDepth is actual ancestor-relative nonconsumable headroom: depth 1 allows sibling children, not grandchildren; child settings cannot widen ancestor allowances. Missing/ambiguous ancestry grants no new depth. Keep the other work/runtime/tool budgets; depth is not a sibling-work cap. Hot counters.nestedWorkflowDepth is only a local 0/1 launch projection. Full retained historical depth requires explicit readOrRebuildDynamicState(cwd, runId, { observeDescendants: true }) runtime inspection, is not persisted into the hot cache, and is never launch authority. Do not import private runtime modules into reusable helpers.
• For synthesis/fan-in, use reduce.from and require/encourage workflow_artifact reads for detailed upstream artifacts.
• For deterministic local post-processing, declare a support object with support.uses pointing to a bundle-local ./*.mjs helper; support is trusted local code, not sandboxed subagent work and does not use a separate type value.
• Put already-known, caller-authorized inventory, canonical task binding, IDs, schemas, joins, counts, escaping, and rendering in static code instead of asking a model to restate or transform them. Keep models for requirements, topology, unknown discovery, domain semantics, and substantive judgment. Never substitute a fixed inventory when the workflow must discover the inventory.
• For iteration, use loop with fixed child stages, maxRounds, and deterministic until. A positive maxRounds bounds rounds; explicit maxRounds: null removes the round cap. For unlimited loops, omit progressPath to terminate only by until, blocking failure, or explicit stop; an explicit progressPath opts into no-progress stopping. Model-task time limits are separate (maxRuntimeMs: 0 disables them). Loop children are single/reduce only, run serially, and must not declare from/after: each child implicitly sources the earlier children of its round (for example <loop>.r01.compare), and the first child of every later round sources the previous round plus a # Loop Carry-Forward Context block. until must target the final child ({ "stage": "<final-child>", "path": "$.field", "equals": true }, or all/any combinators; predicates equals, notEquals, lengthEquals, exists), and that path must exist in the final child's control schema and few-shot example. Loops cannot be resumed; start a fresh run after changing the spec. See "Loop behavior" in docs/usage.md for the exact contract.
• Agent-declared tools are the authority ceiling; workflow tools can only narrow them.
• To reuse agent knowledge across stages, declare top-level roles (fromAgent extracts safe agent sections; prompt appends literal text). Compiled role text is injected as a # Role Context block; check the result with /workflow roles <workflow>. See "Roles" in docs/usage.md.
• Independently classify every model-backed stage with profileRole: planning, research-execution, synthesis, verification, or final-judgment. This is required for Codex/Codex High/Claude/Mixed/Custom user profile coverage and must reflect the work's semantic purpose, never a stage-name guess. Put it on single/foreach/reduce/dynamic stages, nested DAG/loop children, and model-backed onExhausted; a dynamic stage's role classifies its generated-agent runtime defaults, and each present decision-loop planner/workerDefaults/verifier/synthesis profile object also needs its own role. Do not put it on support or DAG/loop containers. profileRole is not the agent-context role field.
• Keep review/research workflows read-only unless the workflow explicitly documents managed-worktree mutation.
• Write-capable workflows need explicit worktree policy, validation/check stages, and protected-path awareness.
• In non-git workspaces with worktreePolicy: "off", writes mutate the live directory.
• Choose one of three user workflow scopes: project-private .pi/workflows/<name>/spec.json, project-shared/tracked workflows/<name>/spec.json, or user/global ~/.pi/agent/workflows/<name>/spec.json. Flat <name>.json is fine only when no local schemas/helpers are needed.
• Name priority is project-shared workflows/, project-private .pi/workflows/, user/global, then the installed package bundle; higher roots shadow lower ones and ambiguity is fail-closed only within the winning priority.
• If the user asks to create a workflow but does not specify storage scope, ask them to choose project-private, project-shared/tracked, or user/global before writing. Treat changes to pi-workflow's official package workflows/ as a separate promotion step requiring an explicit package-distribution request.
• For natural-language execution of existing workflows, prefer workflow_list and workflow_run when those tools are available; use /workflow ... commands as the deterministic manual fallback.
• Always run /workflow validate <workflow-or-file> before handing off or running a reusable workflow. There is no validate tool, so from an agent/tool context run it non-interactively from the project directory: pi -p --no-session "/workflow validate <workflow-or-file>"; it prints the same summary and Warnings: list as the interactive command and exits non-zero on an invalid spec.

Authoring intake

When the workflow-definition request is vague, broad, or self-contradictory, do not write a spec yet. Clarify the authoring target first, then build collaboratively.

1. Identify the requested workflow-definition action: create new, modify existing, review existing, validate existing, or explain authoring rules.
2. Identify the workflow target path/name and storage scope. If not explicit, ask the user to choose project-private .pi/workflows/, project-shared/tracked workflows/, or user/global ~/.pi/agent/workflows/ before writing files. Modifying pi-workflow's official package bundle is a distinct, explicit package-distribution choice.
3. Ask only for decisions that determine the workflow graph and safety posture:

• What runtime task will the workflow handle, and what final artifact should it produce?
• What downstream decision depends on the output?
• Where should the workflow live: project-private, project-shared/tracked, or user/global? Treat official package distribution as a later explicit promotion decision.
• Is the workflow read-only, or write-capable with managed worktree expectations?
• Is the graph a fixed DAG, static fan-out (foreach), synthesis (reduce), bounded loop, nested dag, support-helper pipeline, or trusted adaptive dynamic stage?
• Which agents must exist, and what tool ceiling do they allow?
• Which stage outputs are machine-read by later stages and therefore need control schemas?

1. For storage scope, prefer Pi's question tool when available instead of free-text. Use descriptions so the user can choose without knowing workflow internals:

• project-private: save under the current project's .pi/workflows/<name>/; best for local paths or experiments. Discoverable only from this project and usually ignored by git.
• project-shared: save under workflows/<name>/; best for a repo-committed workflow shared with the team.
• global: save under ~/.pi/agent/workflows/<name>/; best for personal workflows reused across projects. Avoid hard-coded project paths unless intentional.

Example question tool shape: question({questions:[{id:"workflow_storage_scope",label:"Storage",prompt:"Where should I save this workflow?",options:[{value:"project-private",label:"Project-private",description:"Use only in this project; save under .pi/workflows/<name>/."},{value:"project-shared",label:"Project-shared/tracked",description:"Commit with this repo under workflows/<name>/."},{value:"global",label:"Global/user",description:"Reuse from any project; save under ~/.pi/agent/workflows/<name>/."}],allowOther:true}]}).

1. Survey existing workflows only when choosing a base template, adapting a known workflow, or checking whether a requested new workflow is unnecessary. Do not invent a new topology when an existing workflow definition already satisfies the authoring request.
2. If the request is contradictory (for example "read-only" plus "edit and commit"), name the conflict and offer concrete alternatives rather than silently resolving it. Workflow workers do not commit; mutation goes through a managed worktree for human review with no auto-merge.
3. Before writing a new or revised spec, briefly note the chosen stage graph (nodes, from/foreach.from/reduce.from/support edges, read/write policy, schemas/helpers, and storage path) when it materially affects cost, safety, or output shape. Do not ask the user to approve internal graph details unless the choice changes user-visible behavior, cost, storage scope, or mutation risk.

Authoring workflow

When creating or changing a workflow: