Workflows

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.

Workflow catalog

Open Workflows to browse saved definitions. Each entry shows its name, version, and pack. Point to a card, or switch to list view, to see its actions. Use Show all versions when you need an older active version.

• Run (the play icon before the wrench) opens Run saved workflow for that exact version, where you fill in its inputs and choose Run workflow. Retired versions don’t show it.
• Open in Builder (the wrench icon) loads that version in the Builder.
• Test (the play icon after the wrench) opens that version in the Builder with its test form ready, so you can try it as a draft.
• 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.

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.

Installed user tools appear in their own User tools library group, such as GitHub CLI or Maven. Click or drag one onto the canvas, then check Installed revision before saving; the Builder prefers the highest semantic version. If it has one action, that action is selected automatically, otherwise choose one in the inspector. The step pins the exact revision and content hash shown under Installed revision, so later imports never change it. Unsupported actions show the reason they can’t run, and the optional Working directory (cwd) field overrides where the tool runs for that step.

Use the toolbar to:

• Edit workflow details, and declare inputs and outputs under Variables. Built-in runtime values such as ${runtime.projectKey} need no declaring, so they aren’t listed there.
• Test the visible draft.
• Inspect or apply YAML for advanced configuration.
• Undo, redo, and auto-layout the graph.

In a reference field, type ${ to choose a workflow input or step output, or select built-in context from the Runtime values group. The runtime choices match the current field and step: branch conditions offer loop counters within a loop, while previous-pass results belong in execution fields such as step inputs and outputs. See Runtime values for the supported references.

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.

Connect reusable steps visually, map their inputs and outputs, and test the visible draft before saving a version.

Start or test a workflow

Choose Run on an active version in the catalog. In Run saved workflow, check the version, fill in its inputs, and choose Run workflow. Valdr opens the new run in Runs. From an MCP client, start a saved version with pm_workflow start instead; Run Your First Workflow walks through that MCP path with the included Deliver Task definition.

The Run scope task/project controls select an optional association and supply defaults. Step targets can use other tasks or projects; changing the association does not replace declared workflow inputs. See task and project targets.

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 provider presets, plus typed controls for booleans, numbers, arrays, and objects. Use a draft test to try changes; use Run when the run must use exactly the saved version you picked.

Test executes real steps. It can launch agents, run commands and user tools, or change records. For a check without execution, use the Builder diagnostics or pm_workflow validate.

The task Workflows tab shows runs already tied to that task. Before a saved run, draft test, or rerun starts, Valdr checks required inputs, workflow availability, and the agent and provider-preset selections it can resolve. The form also checks destinations bound to launch inputs: fill a required target or choose a usable Run scope default, even when the workflow input itself is optional. A failed check stays on the form so you can correct it without creating a partial run. A value supplied by an earlier step, provider sign-in or availability, an incompatible worktree, or a busy session can still cause a step to fail during execution.

Run inspector

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

• Needs input surfaces runs waiting for an operator decision or answers to questions.
• 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.

Choose Select runs to show checkboxes for bulk cancellation or deletion. While nothing is selected, Select all matching runs selects roots matching the current search and filter, including later result pages. Review the selected count before acting; Done leaves selection mode. The same cancellation and deletion rules apply to each selected run.

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.

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.

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.

Tools

Open Workflows > Tools, next to Runs, to see every user tool installed on this machine. That includes tools you’ve built yourself and, once you import the valdr-tools starter pack, its GitHub, AWS, Google Cloud, and Atlassian adapters and Maven. Each card shows the tool’s icon, name, ID, revision, description, pack, and number of actions.

One catalog for every tool your workflows can call, with the revision each card represents.

• Search by name, ID, pack, description, or revision.
• Show all versions to see older revisions; by default each tool shows its newest.
• Import or export packs opens Settings > Valdr Packs.

Click a card to open that revision’s details: whether it’s available in workflows, its content hash, the command it runs, and the Tool root folder where its reviewed source is kept. Expand YAML manifest to read its actions, schemas, files, and requested environment variables before you use it.

Inspect exactly what a tool will run before a workflow ever calls it.

Remove from catalog hides that revision from new steps. Workflows that already pin it keep working, and run history is preserved. To remove an older revision, turn on Show all versions and open its card first. Removal doesn’t stop a tool that’s already running or undo its effects.

The User Tools guide walks through a safe first run.

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.

When a gate asks questions, choose Answer questions from the waiting run’s input panel. On desktop, the questions open in a dialog; on a phone, the same form fits the available screen and scrolls so you can answer each item. The form shows which questions are required, supports text, single choice, multiple choice, and yes/no answers, and lets you write your own answer to a choice or yes/no question. Required questions need a selection, a yes/no response, or a nonblank written answer. The run remains waiting until valid answers or the authored rejection outcome is submitted.

When questions include document context, select a Context document above the form to read it alongside the questions. Reload context reads the current contents. Document selection, reloading, and preview errors keep your drafted answers; a preview error shows a reload control and does not prevent you from answering.

Question gates appear under Needs input in the run rail and under Needs your input in the selected run. The prompt and authored wording explain what is needed; this neutral status does not imply that a change has been approved. After a successful submission, Valdr shows Input recorded. Check run status as the workflow continues. A question response records input for the workflow and any later agent step, but does not approve a diff or publish work.

Unsubmitted drafts are kept in this browser, including when you close the dialog, refresh, or encounter a submission error. They remain available for the same waiting question set, but do not sync across devices. If a submission reports that input was recorded but the workflow could not advance, refresh the run and check its status before taking action. If it is still waiting after an uncertain submission, refresh the status and submit the retained answers again.

If authored or generated question data is missing or invalid, the blocked run explains that questions need attention. A running workflow keeps its selected version, so correct the question list in a new workflow version and start a new run. An invalid question set cannot be answered from the run.

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.

Review the recorded evidence and refine this example proposal before deciding whether to publish or reject it.

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.
• For an eligible Command retry, Retry with saved Command changes? appears when saved command, directory, timeout, or environment settings changed. Review the listed fields and saved definition before choosing Retry with saved changes. Environment changes list variable names only.
• Run again creates a separate run from the same workflow versions. Declared inputs, including task and project targets, remain editable; the original association and context stay fixed.
• 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 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.

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 to start a saved definition with pm_workflow, then inspect and recover the run in Valdr UI.