# Concepts
{{< tier level="sovereign" note="Workflow concepts make repeated agent processes easier to build, operate, and explain." >}}

Valdr Workflows turn a repeatable process into a saved definition with an inspectable execution history. These are the concepts you need to build and operate them confidently.

## Definitions and versions

A **workflow definition** is the saved recipe. It contains a key, name, version, inputs, outputs, steps, and their dependencies.

Versions let you improve a workflow without changing the graph, bindings, and selected child versions of runs that already started. When a workflow uses another saved workflow, it selects an exact child version so a later update cannot silently change the process.

An eligible Command retry is the deliberate recovery exception: it can reread only `command`, `cwd`, and `timeoutSeconds` from the active definition at the same key and version. Valdr records the source content hash while the rest of the run remains frozen.

## Runs

A **run** is one execution of a workflow. It records the selected version, supplied inputs, step progress, declared results, and related evidence in your local workspace.

| Status | Meaning |
| --- | --- |
| `pending` | Created and ready to begin |
| `running` | Work is progressing |
| `waiting` | Paused for evidence, another workflow, or a human decision |
| `blocked` | Cannot advance without operator intervention or an applicable recovery action |
| `failed` | Ended without completing |
| `completed` | Finished successfully |
| `cancelled` | Orchestration was stopped |

## Steps and attempts

A **step** is one named unit of work: call a Valdr Tool, Git action, or trusted command; launch an agent; request review; wait for evidence; ask for approval; choose a path; or run another workflow.

Each execution of a step is an **attempt**. Retrying creates another attempt instead of replacing the earlier record, so you can see what failed, what changed, and what eventually worked.

## Inputs and outputs

Workflow inputs provide the values a run needs. Steps publish named outputs for later steps, and the workflow publishes only the final outputs declared by its definition.

{{< thumbcard src="/images/workflows/workflow-data-flow.svg" fit="contain" alt="Declared workflow data moving from inputs through a step to later steps and selected workflow results" caption="Named inputs and outputs keep data flow understandable as a workflow grows." >}}

Use `needs` whenever one step depends on another step or consumes its output. This keeps execution order explicit instead of relying on visual placement.

## Waiting states and human gates

A run enters a **waiting** state when orchestration must pause for expected work, evidence, or authority—for example, an agent session, review verdict, child workflow, or human decision.

An [`await_condition` step](../steps/await-condition/) waits for an authored outcome from an agent session, review, or authorized callback. A [`human_gate` step](../steps/human-gate/) waits for an explicit operator decision and presents its approval or rejection choices in Valdr UI. Review evidence cannot impersonate a human decision, and human approval does not replace an independent review.

## Child workflows

A workflow can run another saved workflow as a child. The parent supplies the child's declared inputs, waits for it to finish, and maps selected child results into its own named outputs.

Composition keeps large processes understandable: planning, sprint preparation, delivery, and review can each remain useful workflows while participating in a larger lifecycle.

## Review and approval outcomes

Review verdicts and human decisions intentionally use different values:

| Decision | Values |
| --- | --- |
| Verified review | `review_approved`, `review_changes_requested` |
| Human gate | `approved`, `rejected` |

Keeping them separate makes it clear whether work advanced because evidence passed review or because an operator made a decision.

## Recovery

- **Retry step** adds another attempt when Valdr determines the step can be repeated safely.
- **Run again** starts a distinct run with the same workflow versions and prefilled inputs. You can edit non-scope inputs before launch; task, project, and context remain fixed.
- **Cancel run** stops workflow orchestration. See [cancellation scope](/valdr/docs/workflows/reliability-and-recovery/#cancellation) for how this affects related work.
- **Delete run** permanently removes workflow history for a failed, completed, cancelled, or blocked run. The UI also removes linked session records by default; choose **Keep linked sessions** to retain them.

## Next steps

- Explore [Workflow Steps](../steps/) to choose the right step kinds.
- Continue to [Definition Authoring](../definition-authoring/) to build a workflow.
- Open the [Workflow UI](/valdr/docs/ui/workflows/) to test definitions and inspect runs.