Building and Running Workflows

This guide walks the full loop: build a workflow definition, launch it on a task, watch the run, resolve anything that pauses it, and ship the result. For what workflows are — blocks, gates, budgets — read Workflows first.

Build a definition

Open Settings › Workflows. Each definition is a card with a compact preview of its block chain; New workflow opens the builder.

The builder is a canvas of block cards you edit in place:

Add blocks — Step, Parallel, Loop, or Orchestrate — and steps inside containers.
Per step, set the agent (any provider, or one of your custom agents, with model and instructions), the goal (the step’s prompt), the gate, per-step budgets, and which messaging capabilities it gets (report / ask).
Parallel blocks get a join policy (all / any), whether to merge results, and a concurrency cap. Loops get a max iteration count and the step whose done verdict ends them. Orchestrate blocks get the lead agent, child templates, and sub-workflow limits.
A finalize section sets what happens when the run completes: push the run branch, and optionally open a PR against a base branch.

Validation runs as you edit and gates the Save, so you can’t persist a definition with a dangling reference or an empty goal.

Definitions are portable. On any card, Export YAML writes the definition to a file you can commit or send around; Import reads one back. Import is forgiving by design: agent aliases in the file are matched against your local custom agents — for each one you choose map to your local agent or use the embedded definition — and missing skills or unknown providers surface as warnings, never as a failed import.

Launch a run

Create a new agent draft as usual (+ New agent or ⌘N). Once at least one workflow is defined, the draft screen shows an Agent / Workflow toggle at the top. Pick Workflow, and the heading becomes “What should the workflow do?”: choose a definition, describe the task in the composer — @ file attachments are delivered to the run’s first step — and launch. The run gets its own branch in the wf/ namespace and appears in the sidebar under its project, like any agent.

Read the run monitor

Selecting a run opens the monitor:

Header — the task, workflow name, run branch, and status.
Budget meters — turns, tokens (if capped), and minutes used against the caps frozen at launch, restyled as a warning at 90%.
Attempt rail — every step and attempt; select one to read that attempt’s full chat, preserved and replayable like any agent session.
Timeline — a live feed of engine events in plain language (step started, gate passed, budget warning…), with raw event JSON behind a per-row expand if you want it.

When a run pauses

A paused run shows a banner naming the cause, with the action that resolves it — there is never a pause without a button:

Pause	What happened	You do
Approval	a step’s gate is your sign-off	review the attempt, Approve
Question	a step asked something and no orchestrator can answer	answer inline (⌘Enter to send); the run resumes
Blocked gate	a step finished but its gate isn’t satisfied, even after a re-prompt	fix or reword, Retry
Stalled	a step stopped progressing and didn’t recover after a nudge	Retry the attempt
Budget	a cap was hit	raise it inline (+turns / +tokens / +minutes) and continue
Conflict	merging parallel work hit a git conflict	hand it to an agent, or resolve it yourself in the run’s integration worktree and continue

Runs survive app restarts: the engine journals every decision, so quitting mid-run just means the run resumes when you’re back.

Finish and ship

When the tree completes, finalize runs: the wf/… branch is pushed and, if configured, a PR opens against your chosen base. Review and merge it like any other agent’s work, then archive or delete the run from the sidebar.

Workflows — the concepts behind all of this
Pull Requests and CI
Choosing an Agent