Running Workflows
Run a workflow from the work item that owns the prompt, acceptance criteria, comments, documents, and final result. The run history stays attached to that initiative, bug, or todo.
Launch from work detail
Launch a published workflow from a task, bug, or initiative detail page:
- Open the work item.
- Open Send to....
- Select a published workflow from the top of the menu.
- Confirm the run starts.
Published workflows appear only when their Start from setting matches the work item type. If more than one workflow matches, the menu lists each by name and description. There is no default workflow.
Direct assignment to a local or cloud agent stays in the same menu. That path runs one agent session. A saved workflow runs multiple steps across agents or human gates.
After a successful launch, a confirmation toast names the first active step. That step comes from the workflow run the execution service creates when the first step starts.
Active-run blocking
A work item can have only one active workflow run at a time. While a run is Running, Waiting for review, or Stalled, Send to... blocks another workflow launch for that item.
Wait for the run to finish, cancel it, or resolve the active gate before starting another workflow. If the workflow is missing from the menu, check the workflow Start from setting in Building Workflows.
Run lifecycle
Workflow runs move through these statuses:
| Status | Meaning |
|---|---|
not_started | The run exists but has not entered the first step yet. |
running | An agent step is active or ready to be claimed. |
waiting_for_review | A human review step is waiting for a reviewer decision. |
stalled | The run needs intervention, such as a missing branch handoff. |
completed | The workflow reached a successful terminal route. |
cancelled | A user or system cancelled the run. |
failed | The workflow could not finish. |
Events record run creation, step entry, routing, agent start and completion, review requests, review decisions, review reassignment or escalation, resumption, cancellation, failure, and completion.
Where to monitor progress
Open Workflows to see online agents, definitions, recent sessions, and recent runs. Open Work queue from the menu or title bar to inspect the active queue without leaving your page.
Queued work is not running yet. An eligible agent must claim the session before execution starts. Workflow runs and direct agent sessions share the same claim model.
Use Monitoring for local agent heartbeats, session state, stale claims, and review-gate visibility across Workflows, Work queue, agent details, and linked work items.
Review handoffs
Human review steps wait in Work Inbox until a reviewer approves, sends feedback, rejects, or reassigns the gate.
Agent review steps must finish with one verdict: approve, feedback, or reject. Missing or unknown verdicts stall the workflow instead of assuming success.
Feedback routes return to the configured earlier step and inject the feedback into the next agent session. Reject routes follow the configured destination; they end the run only when the workflow points Reject to Failed.
Outputs and results
Workflow output stays on the linked work item. The run can add plan, review, and result-summary documents, plus branch and PR/MR details when the agent reports them.
Each linked task keeps at most one canonical document per workflow artifact type. A feedback loop updates the same plan, review, or summary document instead of creating a new document for every run attempt.
For artifact types, document blocks, task modes, branches, and custom-agent responsibilities, see Workflow Reference.
Launch failures
If launch fails, the dashboard shows an error and does not create a workflow run. Common causes include no eligible agent, an invalid definition, a workflow that does not match the work item type, or another active run on the same item.
Fix the issue and launch again. Detailed fixes live in Troubleshooting.