# Workflows
{{< tier level="sovereign" note="The Workflow UI puts durable multi-agent processes, evidence, and human decisions in one operator surface." >}}

Use the Workflow UI when you want to work with workflows without hand-editing YAML. Browse included definitions, adapt and test a process visually, and inspect every run from one place.

{{< callout type="info" >}}
**Two launch paths:** Builder **Test** starts a durable run from the visible draft in Valdr UI. Starting an exact saved definition currently requires `pm_workflow start` from an [MCP client connected to Valdr](/valdr/docs/getting-started/install/#configure-your-mcp-host).
{{< /callout >}}

{{< cards >}}
  {{< card link="first-workflow/" title="Run Your First Workflow" subtitle="Deliver and review one prepared task without writing YAML" icon="check-circle" >}}
  {{< card link="getting-started/" title="Workflow UI Guide" subtitle="Browse, test, inspect, and recover workflows in Valdr UI" icon="play" >}}
{{< /cards >}}

## Workflow catalog

Open **Workflows** to browse saved definitions. Each entry shows its name, version, pack, and available actions. Use **Show all versions** when you need an older active version.

- **Open** loads the selected version in the builder.
- **Test** launches the current definition with test inputs.
- **Use as starting point** copies its structure into a new workflow draft.
- **Retire** removes an exact version from ordinary catalog use when nothing active depends on it.

Use **Show retired** to find a retired version and **Restore** to make it available again.

{{< thumbcard src="/images/ui/workflows/workflow-catalog.jpg" alt="Workflow catalog filtered to installed task workflows with version, pack, and step details" caption="Find the workflow version you need, then open, test, copy, retire, or restore it from one catalog." >}}

## Workflow Builder

The builder combines a step library, visual canvas, and per-step configuration. Add **Valdr** steps for action-based MCP operations, **Git** for bounded repository operations, **GitHub** for pull-request publication, **Command** for trusted shell execution, or agents, reviews, waits, outcome routes, human gates, and saved workflows, then connect dependencies explicitly.

Use the toolbar to:

- Edit workflow details, inputs, and outputs.
- Test the visible draft.
- Inspect or apply YAML for advanced configuration.
- Undo, redo, and auto-layout the graph.

Validation runs continuously as you edit. The diagnostics panel reports errors and warnings, and selecting an entry jumps to the affected step or field.

Saving creates a reusable workflow definition. In the builder, use **Create new version** when you change published behavior. Use **Use as starting point** from the catalog when the process should become a separate workflow.

{{< thumbcard src="/images/ui/workflows/workflow-builder.jpg" alt="Workflow Builder showing Deliver And Close Out Task as two connected child workflows with declared outputs" caption="Connect reusable steps visually, map their inputs and outputs, and test the visible draft before saving a version." >}}

## Start or test a workflow

Start a saved workflow version through [`pm_workflow start`](/valdr/docs/valdr-mcp/workflows/#start-a-run), then open **Runs** to inspect it in Valdr UI. [Run Your First Workflow](first-workflow/) walks through that path with the included Deliver Task definition.

In the Builder, **Test** runs the visible draft with guided inputs and keeps the durable test run in **Runs**. The form provides searchable controls for tasks, projects, agents, and launcher presets, plus typed controls for booleans, numbers, arrays, and objects. Use a draft test to validate behavior; start the saved version when exact version identity matters.

The task **Workflows** tab is a scoped inspection view for runs already tied to that task. Valdr checks required inputs, selected agents, launcher presets, and workflow availability before a draft test or rerun starts. A failed check stays on the form so you can correct it without creating a partial run.

## Run inspector

Open **Runs** to inspect active and completed work. The run rail groups roots by what needs attention:

- **Needs approval** surfaces runs waiting on a human gate.
- **Needs attention** collects blocked and failed runs.
- **Active** contains pending, running, and other waiting work.
- **Recent** keeps completed and cancelled runs close at hand.

Search by workflow or run, or filter the rail to all, waiting, running, or failed roots. Use Up and Down Arrow to move through visible runs without leaving the console.

The selected run opens as a nested execution waterfall. Parent runs, child workflows, steps, and attempts remain in one tree, with a Gantt-style **Timeline** showing when each row ran or waited. Use Up and Down Arrow to move between rows and Left and Right Arrow to collapse or expand composed work.

{{< thumbcard src="/images/ui/workflows/workflow-runs.jpg" alt="Completed Prepare, Deliver, And Publish Task run with nested child workflows, step progress, sessions, and timeline" caption="Follow a complete delivery from the root run into child workflows and individual steps without losing timing or progress context." >}}

The inspector shows:

- Run status, selected workflow version, and scope.
- Elapsed time, step progress, linked session count, and child-run count.
- Declared inputs and results.
- Every step and attempt.
- Open waits and human decisions.
- Linked sessions, reviews, tasks, and child workflows.
- Accepted evidence, errors, and available recovery actions.

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. Inspector tabs separate **Agents**, **Inputs / Outputs** (including **Run results**), **Response**, **Events**, and **Diagnose**.

The **Agents** tab appears when a run has linked sessions and shows which agent performed each step alongside duration and token activity. Select a session chip, output, or activity entry to open its session details without leaving the run. **Diagnose** gathers the state and failure details most useful when a run cannot advance.

{{< thumbcard src="/images/ui/workflows/workflow-usage.jpg" alt="Session Comparison chart grouping input, output, and cached tokens by workflow agent" caption="Compare average input, output, and cached tokens by agent, then switch dimensions to investigate token activity by model, role, step, or prompt." >}}

Select any child workflow or step to inspect its own record, then return to the parent without losing the larger process context.

## Human decisions

A human gate shows the workflow's prompt and approval or rejection labels. When a gate includes reviewed documents, choose **Review and decide** to preview them before acting.

Some gates also support feedback. Sending feedback returns a correction request to the configured writer and refreshes the preview; it does not approve or reject the gate. Make the decision only after reviewing the updated result.

Gate references open the supporting task, session, run, or URL directly from the decision. A pull-request proposal gate also lets the operator edit the title, body, and draft state before approving publication of the exact recorded head.

{{< thumbcard src="/images/ui/workflows/workflow-pr-proposal.jpg" alt="Pull request proposal gate showing recorded repository evidence and an editable example title and body" caption="Review the recorded evidence and refine this example proposal before deciding whether to publish or reject it." >}}

{{< thumbcard src="/images/ui/workflows/workflow-pr-changes.jpg" alt="Changes tab showing a two-line README diff for an example pull request proposal" caption="Inspect the recorded file comparison from the gate without leaving the run or locating the writer session." >}}

## Recovery controls

- **Retry step** adds another attempt when the selected blocked or failed step can be repeated safely. If a step cannot be safely retried, the displayed reason explains what needs attention.
- **Run again** creates a separate run from the same workflow versions.
- **Rerun workflow** appears on a step when its authored recovery action requires a separate workflow run.
- **Cancel run** stops workflow orchestration. The confirmation action is **Cancel workflow**. See [cancellation scope](/valdr/docs/workflows/reliability-and-recovery/#cancellation) for which sessions and commands it stops.
- **Delete run** permanently removes a blocked, failed, completed, or cancelled run tree. Pending, running, and waiting roots or children must be cancelled first. By default it also deletes linked session records, events, transcripts, and session-owned worktrees; select **Keep linked sessions** to preserve them.

Earlier attempts remain visible during retry and rerun. Deletion is permanent and has no restore path.

{{< thumbcard src="/images/ui/workflows/workflow-diagnose.jpg" alt="Diagnose tab showing an earlier blocked Choose launcher preset attempt and its recorded database-lock error" caption="After this example run recovered, Diagnose still preserves the earlier failure, its source error, and the evidence available for that attempt." >}}

## Next step

Follow [Run Your First Workflow](first-workflow/) to start a saved definition with `pm_workflow`, then inspect and recover the run in Valdr UI.