Workflow controls
For screenshots and detailed instructions, open the Workflow UI guide.
Choose an entry point
| Location | Use it to |
|---|---|
| Workflows | Browse saved definitions |
| Workflow Builder | Create, adapt, or test a draft |
| Workflows > Runs | Inspect and operate runs |
| Task Workflows tab | Inspect runs already tied to that task |
Start a saved run or test a draft
Choose Run on an active catalog version. In Run saved workflow, check the version, fill in its inputs, and choose Run workflow. The run opens in Runs. Automation can use pm_workflow start.
The optional Run scope controls supply task/project defaults independently of declared inputs. Steps can have their own destinations; see task and project targets.
Builder Test executes the visible draft without saving a definition. Association, agent, preset, input, or missing-target errors stay on the form without creating a partial run. Test runs remain in Runs.
Testing runs the actual steps and can launch agents or change data. Use the Builder diagnostics or pm_workflow validate for validation without execution. Launch checks cover values known before the run starts; provider credentials, availability, and worktree compatibility are checked when work executes.
Follow the run
Runs groups work under Needs approval, Needs attention, Active, and Recent. Expand child workflows and steps to inspect attempts and the Timeline.
Use Agents, Inputs / Outputs, Response, Events, and Diagnose to inspect sessions, results, history, and problems. See the run inspector for navigation and evidence details.
Recover or repeat
| Control | Effect |
|---|---|
| Step | Advances one ready transition |
| Run until wait | Advances up to ten ready transitions, stopping sooner for input, a wait, or a closed run; choose it again if ready work remains |
| Retry step | Retries an eligible blocked or failed step, preserving earlier attempts; read the reason when unavailable |
| Run again | Creates a separate run with the same workflow versions and original association/context; declared inputs remain editable |
Run again requires a completed, failed, or cancelled root run. Draft tests cannot rerun; blocked runs must be retried or cancelled first. For updated behavior, choose Run on the newer version.
Cancel run stops orchestration; cancellation scope explains which sessions and commands it stops and what may continue.
Delete run requires the root and every child to be blocked, failed, completed, or cancelled. Cancel pending, running, or waiting work first. Deletion has no restore path and also removes linked session records, events, transcripts, and session-owned worktrees by default. Select Keep linked sessions to preserve them.
Adapt a workflow
- Use as starting point creates a separate draft.
- Open in Builder loads the selected version; Create new version saves changed behavior under a new version.
- Retire removes a version from use when nothing active depends on it. Use Show retired and Restore to bring it back.
Next step
Run Your First Workflow walks through task delivery and review.