Getting Started

Use a workflow when a process repeats, spans several agents or people, needs review or approval, or must survive a restart. For a one-off command with no saved state, a direct agent session is usually simpler.

Choose an entry point

For your first saved run, follow Run Your First Workflow to start Deliver Task through pm_workflow, then open it in Runs. The task must already have an assigned executor and reviewer assignments.

Start a saved run or test a draft

Use pm_workflow start when you want to run one exact saved definition version. The new run appears in Runs and, when task-scoped, in that task’s Workflows tab.

Use Test in the Builder when you want to execute the visible draft before saving it. The guided form checks required scope, agents, presets, and inputs first; a failed check stays on the form so you can correct it without creating a partial run.

Follow the run

After a run starts, Runs places it under Needs approval, Needs attention, Active, or Recent according to its current state. Search or filter the run rail when you have more than a few roots; Up and Down Arrow moves between the visible results.

The selected run opens as a nested waterfall. Expand child workflows to follow the full composition, or collapse them to keep the parent run readable. The Timeline column shows where execution ran, waited, or stopped; arrow keys move between rows and expand or collapse the tree.

The run inspector shows:

• Current status and step.
• Elapsed time, step progress, linked sessions, and child-run count.
• Declared inputs and results.
• Every attempt for each step.
• Open waits and decisions.
• Accepted review or approval evidence.
• Linked sessions, reviews, tasks, and child workflows.
• Errors and available recovery actions.

Use the Agents, Inputs / Outputs, Response, Events, and Diagnose tabs to move from the summary into the exact record you need. Agents shows which agent performed each step alongside linked-session duration and token activity; session links open a quick view without taking you away from the run.

Recover or repeat

Choose Retry step when Valdr offers it for a blocked or failed attempt. Retrying adds another attempt and preserves the earlier one. If a step cannot be safely retried, the displayed reason explains what needs attention.

Choose Run again on a completed, failed, or cancelled root run to create a separate run with the same workflow versions. Draft-test runs do not offer it, and blocked runs must be retried or cancelled first. Start the newer version through pm_workflow when you want updated behavior.

Use Step to advance one ready transition, or Run until wait to advance up to ten ready transitions before stopping at input, a wait, a closed run, or the operation limit. Choose it again if ready work remains.

Cancel run stops workflow orchestration. See cancellation scope for which sessions and commands it stops.

Use Delete run only when the root and every child are blocked, failed, completed, or cancelled; cancel pending, running, or waiting work first. Deletion is permanent. It also deletes linked session records, events, transcripts, and session-owned worktrees by default; select Keep linked sessions to preserve them.

Adapt a workflow

From the catalog:

• Use as starting point creates a separate workflow draft.
• Open loads the selected version in the builder.
• Test runs the definition without creating a reusable version.
• Retire removes an exact version from ordinary catalog use when nothing active depends on it.

Use Show retired and Restore for retired definitions. In the builder, use Create new version to evolve the same workflow deliberately.

Next step

Follow Run Your First Workflow from start through independent review and verification.