pi-workflows

name	pi-workflows
description	Use when creating, reviewing, debugging, starting, inspecting, or controlling pi-workflows; authoring .workflow.ts files; using the workflow tool; handling workflow step contracts, checkpoints, updates, or progress; or deciding how a task should compose workflow primitives.
compatibility	Requires the pi-workflows extension.

pi-workflows

Use pi-workflows for durable multi-step work that needs explicit routing, retries, checkpoints, scheduled waits, or progress. Keep simple one-turn work outside a workflow.

The workflow tool schema is the authority for call shapes. A workflow step message is the authority for its current step id, attempt id, and expected output. Do not guess these values from an earlier attempt.

Operate workflows

Use the smallest applicable action:

• list discovers available workflows. Use its offset for later pages.
• start starts a discovered workflow name or workflow file path with structured input.
• status reads the active run, or the named run when runId is supplied.
• pause, resume, and cancel control the current active run.
• answer supplies input to an ordinary waiting checkpoint. It cannot satisfy a protected humanDecision() gate.
• update publishes a non-completing durable update for the active step attempt.
• submit completes an active submitted agent step with its required output. An assistant-message step completes through its normal visible reply instead.

When the user asks to continue or resume the active workflow, call workflow with action: "resume" immediately. Do not use workflow status as a substitute or prerequisite.

Use start only once for one requested run. Before starting, load the matching workflow skill when one exists and build its complete input. Include scope, authority, constraints, identifiers, and finish criteria required by that skill. Do not start with placeholders that still need user or model repair.

For a workflow without a specialized skill, inspect its input contract and make one complete call. For example:

{
  "action": "start",
  "workflow": "examples/workflows/echo.workflow.ts",
  "input": {
    "task": "Summarize this repository in one sentence."
  }
}

Do not build a manual polling loop around a workflow that already schedules its own work. Use the monitor skill for monitoring requests.

Complete agent steps

When a workflow step message arrives:

1. Do the requested work with the available tools.
2. Follow the completion form in the current step contract.
3. For a submitted step, produce the exact expected shape and call workflow with action: "submit" exactly once, using the current step and attempt ids. If validation rejects the output, correct it and submit again with the same ids.
4. For an assistant-message step, reply with the requested normal assistant message. Do not call workflow submit; the settled visible reply is the node output.
5. After completion, do not add another response. The workflow sends the next step or final presentation when needed.

A node id can run more than once in a loop. Each run has a new attempt id. Never reuse an attempt id from conversation history.

Publish updates and progress

Use update only while the named step attempt is active. An update does not complete the step and does not control routing.

For progress, publish pi-workflows.progress.v1 data with stable track keys. Report observed counts and source-provided estimates. Do not invent totals, rates, confidence, or completion times. Use separate keys for concurrent processes and send explicit terminal states before a track disappears.

The workflow definition should publish progress from function and shell actions when the runtime already has exact counts. Do not add an agent step only to format data that code can publish directly.

Read ../../docs/WORKFLOW_UPDATES.md before adding update producers or progress estimation.

Author workflows

A workflow is a .workflow.ts, .workflow.js, .workflow.mts, or .workflow.mjs module whose default export comes from defineWorkflow(...).

Follow these rules:

• Compose the existing node and edge primitives before adding a new primitive.
• Reuse a finite workflow with a direct typed includeWorkflow() mount. Use a controller only when the child needs an independent run or indefinite reconciliation.
• Give included workflows named exits, map their input explicitly, and keep parent edges out of child internals.
• Keep compute pure. Put external effects in agent, function-action, or shell-action nodes.
• Use structured node outputs when the graph must inspect fields or choose a route. Use expectedOutput: assistantMessage() when exact visible text is the node result.
• Use an ordinary checkpoint for external continuation data that the model may submit. Use humanDecision() for a verified human choice. Use its typed onTimeout policy only when the workflow may supply a named automatic response after a durable deadline. A timeout response is recorded as policy provenance, not as a human answer.
• Use the shared internal plan-change workflow for Autoplan, Autodoc, plan approval, and bounded exact-text replanning. Do not copy that sequence into Autoimplement, Monitor, or another workflow.
• Set explicit step and command timeouts.
• Bound ordinary loops with maxSteps or another clear finish rule.
• Use a controller instead of a workflow for indefinite resource reconciliation.
• Keep presentation separate from execution. Use presentationPrompt for one root response after the run. Use an assistant-message agent when the visible response belongs inside the graph and a parent must continue after it.
• Preserve the single active workflow rule in one Pi session.

Read ../../docs/workflows.md before creating or changing a workflow. Read ../../docs/WORKFLOW_COMPOSITION.md for nested workflows. Read ../../docs/HUMAN_DECISIONS.md before adding a human gate or channel. Read ../../docs/DESIGN_PHILOSOPHY.md before adding public primitives. Use the examples under ../../examples/workflows as starting points.

Verify changes

For workflow definitions, test success, failure, routing, retries or loops, checkpoints, timeouts, cancellation, and resume behavior that applies.

For extension or engine changes, run the repository checks and the real-Pi end-to-end suite. Verify discovery through the installed package path rather than only loading the source extension file.