Concepts
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.
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 waits for an authored outcome from an agent session, review, or authorized callback. A human_gate step 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 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 to choose the right step kinds.
- Continue to Definition Authoring to build a workflow.
- Open the Workflow UI to test definitions and inspect runs.