Workflows

Workflows turn a repeatable delivery process into agent steps, human review gates, and explicit routes. Each run stays attached to its initiative, bug, or todo.

The overview shows definitions, online agents, recent sessions, and active runs in one place.

Before you start

A workflow needs at least one eligible agent before agent steps can run. For local execution, make Git available, choose a writable repository folder, and authenticate Claude Code or Cursor when using those runtimes. Codex is bundled. The full local checklist lives in Local agents.

If the workflow should create a pull request or merge request, connect the code provider first and make sure the agent can push the workflow branch.

Create and publish a workflow

Name the workflow after the reusable process, not one task. Plan, approve, code, review is reusable; Implement billing export is usually a task title.

1. 1

   Create the definition

   Open Workflows and select New workflow. Choose a starting template or start from scratch, then enter a name and description. Drafts autosave while you work.

2. 2

   Configure the workflow

   Choose the Start from work types and runtime defaults. Add agent and human review steps, then assign the agent, task mode, expected inputs, expected outputs, and reviewer policy each step needs.

3. 3

   Validate the routes

   Connect success, approve, feedback, and reject outcomes. Feedback must return to an earlier step; reject can return to an earlier step or end at Failed.

4. 4

   Publish the definition

   Select Publish. One Horizon validates the start step, routes, reviewers, agent targets, and required capabilities before the workflow becomes available for new runs.

5. 5

   Launch the workflow

   Open a matching initiative, bug, or todo, select Send to…, and choose the published workflow. A work item can have only one active workflow run at a time.

The workflow run receives a snapshot of the published definition when it starts.

At launch, One Horizon reconstructs the work item from the linked initiative, bug, or todo. The dashboard sends only parent-initiative and taxonomy metadata that the backend cannot reconstruct, so the first step does not receive a duplicate copy of the task body or comments. Explicit launch instructions supplied through the API remain first-step instructions.

Designer layout

The workflow designer has a header, a canvas, and a right sidebar.

Area	What it does
Header	Shows the breadcrumb, workflow switcher, publish button, and workflow actions menu.
Canvas	Shows the start marker, steps, route outcome chips, add-step controls, and end markers.
Sidebar	Shows workflow details when no step is selected, or step settings when a step is selected.

Inspect the header for publish state and the right sidebar for definition settings before editing the canvas.

The breadcrumb switcher moves between workflows without returning to the overview. The workflow actions menu has Duplicate, Unpublish workflow, and Archive workflow.

The canvas is linear. The first step starts the run. Drag step cards by their handle to reorder, use the plus control between steps to insert one, or use Add step in the bottom toolbar.

Selecting a step updates the URL and opens its settings in the sidebar. Select the empty canvas or clear the selection to return to workflow details.

Configure workflow details

With no step selected, the sidebar edits the workflow name, description, icon, and Start from entity types. It also shows creation and update metadata.

Icon helps you recognize the workflow in lists, the designer switcher, and launch menus.

Start from controls which work item types can launch the workflow from their detail page: TODOs, Bugs, and Initiatives. Select at least one. Published workflows appear in Send to... only on matching entity types.

Runtime defaults

Workflow runtime defaults apply to workflow-backed agent sessions at claim time. They do not replace agent-owned settings such as local paths, daemon capacity, or autostart behavior.

Setting	Meaning
Code isolation	Worktree per run prepares an isolated worktree for each workflow run. Branch per run runs each workflow on a branch in the agent checkout.
Create PR/MR	When enabled, One Horizon creates a GitHub pull request or GitLab merge request after the workflow branch has been pushed. The agent needs to commit changes; it does not need to run provider PR commands.

Direct agent assignments keep the agent runtime. Workflow runs use the saved workflow runtime for each claimed session.

Configure agent steps

Agent steps assign one part of the workflow to an agent. Settings: Agent, Task mode, Expected inputs, and Expected outputs.

Task mode is the role contract for the session. One Horizon adds mode-specific instructions before the agent starts:

• Plan creates the plan artifact and should not change product code.
• Code implements the approved work on the workflow branch.
• Review inspects the declared inputs and returns approve, feedback, or reject.

Pair task mode with expected inputs and outputs to keep each step focused. A reviewer can review only a plan document, a code branch, a pull request, or a specific artifact. A builder can be limited to specific artifacts it may write back.

Field	Meaning
Agent	Local or cloud agent that should run the step.
Task mode	Plan, Code, or Review.
Expected inputs	Artifacts the step expects before it can run safely, such as the plan document, code changes, or an earlier review document.
Expected outputs	Artifacts the step may produce or update, such as the plan document, review document, code changes, PR/MR review artifact, or result summary.
Guidance	Step-specific instructions delivered with this step's work context.

Guidance and agent custom instructions are separate. Agent custom instructions apply to every session that uses the agent. Guidance applies only to this workflow step and appears under Step instructions in prompt diagnostics, not under Agent custom instructions.

The run captures Guidance as part of its definition snapshot. Editing and republishing a workflow does not change a run that already started; Resume, Try again, and feedback loops in that run continue to use the captured Guidance. Publish the change and launch a new run to use the updated text.

In Desktop, the Agent selector includes Create agent. This opens the same setup flow as the Agents page, keeps you in the designer, and selects the new agent after setup. See Local agents for setup.

Expected inputs are readiness checks and trusted context, not the document read-permission boundary. Agents can discover available workflow document blocks when they need more context. Expected outputs control writes: if a review step does not declare Review in Expected outputs, the agent cannot append review findings.

A required Plan becomes the primary handoff for Code after the Plan document is completed, contains at least one nonblank document-block:v1 body, and has provenance from the current workflow run. The same compact handoff applies to Review when that step also declares code changes or a pull request. These sessions keep the title, a bounded description, recent comments, supporting documents, Plan index, step instructions, and review feedback; only the canonical full task document is omitted.

Missing, malformed, blank, incomplete, or older-run Plans block a required handoff. Optional Plans do not change task context, and plan-only Review keeps the full linked work item.

Required document outputs finish before an agent step can report success or route onward. The runtime reloads every required output, validates its blocks, and refreshes run, step, and session provenance even when the document was reused without edits.

When Task mode is Review, the step becomes a review gate. The agent inspects declared inputs, writes findings to the review document when it is an expected output, and returns approve, feedback, or reject. If the agent cannot judge safely, it rejects with the reason in the review document instead of leaving the verdict empty.

When an agent step routes directly to another agent step, the next step needs an agent or agent group target so the delegated session has somewhere to go.

Configure human review steps

Human review steps pause the workflow until a reviewer decides what happens next.

Setting	Meaning
Assignee or Assignees	Specific workspace users who can act on the review gate.
Team or Teams	Teams whose members can act on the review gate.
Approval policy	Any reviewer, All reviewers, or One per team.
Allow reassignment	Lets a reviewer move the gate to another user or team without advancing the workflow.
Guidance	Optional decision guidance authored with the step.

A human review step needs at least one assignee or team before publishing. The backend enforces this, so an incomplete human review step cannot go live from saved UI state alone.

The lower sidebar section controls non-approval routes. Feedback routes work back to an earlier step. Reject routes to a prior step or to a failed end state.

Route review outcomes

Routes define what happens after a step completes.

Step type	Main outcome	Additional outcomes
Agent: Plan or Code	Success	None in the sidebar. Reorder steps or insert the next step in the canvas.
Agent: Review	Approve	Feedback and Reject.
Human review	Approve	Feedback and Reject.

Route chips on the canvas show outcomes such as Success, Approve, Feedback, and Reject. Completed terminal routes appear as End. Failed terminal routes appear as Failed.

For review-mode agent steps, Approve is the forward route. Feedback and Reject use the destinations in What happens next, and the agent verdict chooses the route. A review-mode agent that finishes without approve, feedback, or reject stalls the run instead of assuming success.

Rejection is not an implicit cancellation. It follows the configured reject route. Point Reject to Failed only when rejection should end the run.

Reassignment is not a route. It changes review ownership and keeps the run on the same human review step.

Assigned reviewers receive requests in Work Inbox. Approve, send feedback, reject, or reassign from the inbox drawer, or open the task context for step details.

Publish and validation

Select Publish when the definition is ready for runs. The dashboard sends it through backend publish validation before it can go active.

Validation checks:

• At least one step and a start step
• Every route points to an existing step or an explicit end state
• Plan and Code agent steps have a success route
• Review agent steps have approve, feedback, and reject routes
• Human review steps have reviewer assignments and approve, feedback, and reject routes
• Feedback routes point to a prior step
• Reject routes point to a prior step or an explicit end state
• Agent-to-agent handoffs have an agent or group target on the next agent step
• Code-producing steps use agents with the required capability

If validation fails, the workflow stays a draft and the dashboard highlights invalid steps. Draft autosave is allowed, but incomplete drafts cannot publish. Fix validation and publish again, or use Troubleshooting for common publish failures.

Editing a published workflow returns it to draft with unpublished changes. Publish again after changes pass validation. Use Unpublish workflow when a workflow should no longer be selected for new runs but should stay editable.

Deleting a targeted agent, removing the last agent in a targeted group, or deactivating a targeted agent profile unpublishes affected workflows, cancels their active runs, and returns the definitions to draft.

Run states and actions

Workflow status tells you whether to wait, review, intervene, or inspect the result.

Status	Meaning
not_started	The run exists but has not entered its first step.
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 or exhausted pass limit.
completed	The workflow reached a successful terminal route.
cancelled	A user or system cancelled the run.
failed	The workflow reached a failed route or could not continue.

The Runs tab shows step progress, attempts, route outcomes, and the shared workflow branch.

Human review requests appear in Work Inbox. Approve follows the forward route, feedback returns to the configured earlier step, and reject follows its explicit route. Agent review steps must return one of the same verdicts; a missing verdict stalls the run.

Plan, review, and result-summary documents remain attached to the linked task. Branch and pull request or merge request details appear when the runtime reports them. Monitoring covers queue actions, recovery, provider deep links, activities, and agent health.