pi-workflows

name	pi-workflows
description	Orchestrates multi-step agent workflows defined in YAML with DAG-based execution, typed data flow, checkpoint/resume, and output validation. Use when running workflows, authoring workflow specs, debugging step failures, or inspecting agent configurations.

<tools_reference> Execute a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/. Auto-resumes the most recent compatible incomplete run unless fresh='true'. Use workflow-resume for explicit-only resume by runId.

Execute a multi-step workflow with typed data flow (auto-resumes compatible incomplete runs)

Parameter	Type	Required	Description
workflow	string	yes	Name of the workflow to run
input	unknown	no	Input data for the workflow (validated against workflow's input schema)
fresh	string	no	Set to 'true' to start a fresh run, ignoring any incomplete prior runs

Explicitly resume an incomplete workflow run by name + runId. Rejects when no incomplete run exists for the workflow OR when runId does not match the most recent incomplete run. Use workflow-execute for default auto-resume; this surface is for explicit-only scenarios where the caller wants to fail loudly if the run is gone or has been superseded.

Explicitly resume an incomplete workflow run by name + runId (rejects on no-match)

Parameter	Type	Required	Description
workflow	string	yes	Workflow name
runId	string	yes	Incomplete run ID — required, no auto-detect
input	unknown	no	Optional input override; defaults to the original run's input

List available workflows with names, descriptions, and sources.

List available workflows with names, descriptions, and sources

List available agents with full specs, or inspect a single agent by name. Returns role, description, model, tools, output format/schema, prompt template paths.

List available agents with specs, or inspect a single agent by name

Parameter	Type	Required	Description
name	string	no	Agent name to inspect (omit to list all)

Validate workflow specs — check agents, schemas, step references, and filters.

Validate workflow specs — check agents, schemas, step references, filters

Parameter	Type	Required	Description
name	string	no	Workflow name to validate (omit to validate all)

Get workflow vocabulary — step types, filters, available agents, workflows, schemas, templates.

Get workflow vocabulary — step types, filters, available agents, workflows, schemas

Initialize .workflows/ directory for workflow run state.

Initialize .workflows/ directory for workflow run state

Render a project block item by ID through its registered per-item macro. Resolves the item via the cross-block resolver, looks up the macro via the renderer registry, and renders with the supplied depth and depth-aware cross-reference recursion. Returns `[not-found: ]` on resolver miss and `[unrendered: /]` on registry miss — same fallback markers `render_recursive` emits inside agent prompts.

Render a project block item as prompt text via its per-item macro (with depth-controlled cross-ref recursion)

Parameter	Type	Required	Description
id	string	yes	Kind-prefixed ID, e.g., DEC-NNNN / FEAT-NNN
depth	number	no	0 = bare-ID refs (default), 1 = inline direct cross-references, 2+ = recurse further

Check rendered text against an `x-prompt-budget` annotation on a schema field. Returns `{ output, warning }` — `output` is the original text passed through when under budget, or tail-truncated text with `[…truncated to budget]` marker when over; `warning` is null when no truncation occurred or a structured BudgetWarning record otherwise. Annotation absence is pass-through (no error). Mirrors the behaviour of the `enforceBudget` Nunjucks global registered by compileAgent.

Validate rendered text against a schema field's prompt budget — returns truncated output and warning

Parameter	Type	Required	Description
rendered	string	yes	Rendered text to check against the field's prompt budget
blockName	string	yes	Block schema name (without .schema.json suffix), e.g. 'decisions' or 'features'
fieldPath	string	yes	JSON-pointer-style path to the field, e.g. '/properties/decisions/items/properties/context'

</tools_reference>

<commands_reference> List and run workflows

Subcommands: init, list, run, resume, validate, status, help

</commands_reference>

<keyboard_shortcuts>

• ctrl+h — Pause running workflow
• ctrl+j — Resume paused workflow </keyboard_shortcuts>

<bundled_resources> 15 workflows bundled. See references/bundled-resources.md for full inventory. </bundled_resources>

<validation_vocabulary>

Check	Severity	Description
agent-resolution	error	Referenced agents exist in search paths
monitor-resolution	warning	Referenced monitors exist in search paths
schema-existence	error	Referenced schema files exist on disk
step-references	error	Expression step references point to declared steps
step-ordering	error	Steps do not forward-reference later steps
context-references	error	context[] entries point to declared steps
filter-names	warning	Expression filters are recognized
steptype-metadata	error	retry/input/output declarations match step type capabilities
inputschema-required	error	Agent required input keys are provided by step
contextblocks-existence	warning	Declared context blocks exist in the substrate dir
template-alignment	error	Template variables match step inputs and source schemas

</validation_vocabulary>

pi-workflows orchestrates multi-step agent workflows defined in YAML. Workflows are DAGs of typed steps with data flow via `${{ }}` expressions.

<workflow_discovery> Workflows are discovered from three locations (first match wins):

1. .workflows/*.workflow.yaml — project-level
2. ~/.pi/agent/workflows/*.workflow.yaml — user-level
3. Package bundled workflows/ — built-in </workflow_discovery>

<step_types>

Type	Field	Description
agent	agent: name	Dispatch an LLM subprocess via pi --mode json
command	command: "..."	Run a shell command, capture stdout as output
monitor	monitor: name	Run a monitor classification as a verification gate
transform	transform: { mapping: {...} }	Pure data transformation via expressions, no LLM
gate	gate: { check: "..." }	Shell command exit code as pass/fail boolean
loop	loop: { maxAttempts, steps }	Repeat sub-steps until gate breaks or max reached
parallel	parallel: { a: ..., b: ... }	Run named sub-steps concurrently
pause	pause: true or pause: "message"	Pause execution, resumable later
block	block: { op: read|write|append|update|remove|… }	Validated in-process substrate block I/O via the block API — no LLM, no subprocess

forEach: "${{ expr }}" (iterate the step per array element) and as: are step MODIFIERS, not step types — they combine with any type above. </step_types>

<expression_syntax> ${{ expression }} resolves against scope: input, steps, loop, forEach.

Access step outputs: ${{ steps.investigate.output.findings }} Filters: ${{ steps.analyze.output | json }}, ${{ items | length }}, ${{ name | upper }}

Available filters: length, keys, filter, json, upper, lower, trim, default, first, last, join, split, replace, includes, map, sum, min, max, sort, unique, flatten, zip, group_by, count_by, chunk, pick, omit, entries, from_entries, merge, values, not, and, or. </expression_syntax>

<agent_resolution> Agent specs (.agent.yaml) are resolved from three locations (first match wins):

1. .pi/agents/<name>.agent.yaml — project-level
2. ~/.pi/agent/agents/<name>.agent.yaml — user-level
3. Package bundled agents/<name>.agent.yaml — built-in

Agent specs define: model, thinking level, tools, system prompt (or template), task template, output format/schema. </agent_resolution>

<execution_model>

1. Steps are ordered by YAML declaration order
2. DAG planner infers parallelism from ${{ steps.X }} references
3. Steps without explicit dependencies run after their predecessor (conservative sequential)
4. Each step's result is persisted atomically to <runDir>/state.json
5. TUI progress widget shows real-time step status, cost, and timing </execution_model>

<checkpoint_resume> Incomplete runs (failed or paused) are detected on next invocation. If the workflow spec hasn't changed incompatibly, execution resumes from the last completed step. Failed steps are re-executed. Use fresh: "true" to force a new run. </checkpoint_resume>

<output_validation> Steps with output.schema validate the agent's JSON output against a JSON Schema file. Validation failure marks the step as failed.

Use block:<name> to reference project block schemas portably: output.schema: block:project resolves to <substrate-dir>/schemas/project.schema.json from cwd. Works across monorepo, npm install, and user-customized schemas. Combined with retry: { maxAttempts: 2 }, the agent gets the schema validation error injected into its retry prompt and can self-correct. </output_validation>

Steps with `retry: { maxAttempts: N }` are re-executed on failure. Between retries: - Project block files are rolled back to pre-attempt state - Prior error messages are injected into the prompt - Optional `steeringMessage` provides custom retry guidance

<completion_messages> After execution, the workflow result is injected into the main LLM conversation. The completion field controls this: either a template (full ${{ }} template) or message + include (message text plus resolved data paths). </completion_messages>

Workflows can write post-completion files via the `artifacts` field. Paths may contain `${{ }}` expressions. Artifacts targeting `/*.json` are routed through `writeBlock()` for schema validation.

Block artifact write failures are fatal — if the data doesn't conform to the block's schema, the workflow fails. Non-block artifact failures remain non-fatal (warning). On resume, all steps are preserved; only artifact processing re-runs, so fixing the schema issue or agent output and resuming avoids re-running expensive LLM steps.

`validateWorkflow(spec, cwd)` runs authoring-time checks without executing the workflow:

1. Agent resolution — all referenced agents exist in the three-tier search
2. Monitor resolution — all referenced monitors exist in .pi/monitors/ or built-in examples
3. Schema resolution — all output schema file paths resolve to existing files
4. Step reference validity — ${{ steps.X }} expressions reference declared steps
5. Step ordering — referenced steps are declared before the referencing step
6. Filter name validity — ${{ value | filter }} uses known filter names

Returns { valid: boolean, issues: ValidationIssue[] } where each issue has severity, message, and field path. Use /workflow validate or /workflow validate <name> to run from the command line.

<success_criteria>

• Workflow completes all steps without unhandled failures
• Step outputs match declared output schemas
• State is persisted atomically after each step
• Completion message is delivered to main conversation
• /workflow validate returns no errors for authored specs
• Checkpoint/resume recovers from the last completed step </success_criteria>

Generated from source by scripts/generate-skills.js — do not edit by hand.