Workflows

A workflow is a repeatable delivery process made of agent steps, human review steps, and the routes between them. Each run stays attached to the initiative, bug, or todo it started from.

Workflows in the sidebar shows your workflows, online agents, recent sessions, and active runs.

Before you start

• At least one agent that can run the steps. The quickstart sets one up in Desktop.
• For pull requests or merge requests, a connected Git provider and an agent that can push the workflow branch.

Create and publish a workflow

Name the workflow after the process, not a task. "Research, plan, approve, code, review" is a workflow. "Implement billing export" is 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 which work types can start it (Start from) and the harness defaults. Add agent and human review steps, then set each step's agent, task mode, expected inputs and outputs, or reviewers.

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. The workflow becomes available for new runs once it passes validation.

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 first step receives the linked initiative, bug, or todo as its context. Launch instructions passed through the API are added to the first step.

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.

The breadcrumb switcher moves between workflows without returning to the overview. The workflow actions menu has Validate, Duplicate, sharing and template controls, version history, Unpublish workflow, and Archive.

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 appears in lists, the designer switcher, and launch menus.

Start from sets which work types can launch the workflow: TODOs, Bugs, and Initiatives. Select at least one. A published workflow only appears in Send to... on those types.

Harness defaults

Harness defaults apply to every session this workflow starts. They do not override settings that belong to the agent, such as local paths, concurrency, or auto start.

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	One Horizon opens the pull request or merge request after the workflow branch is pushed. The agent only needs to commit.

Work sent directly to an agent uses that agent's own settings instead.

Capabilities

Select an agent step, then Add beside Capabilities to attach a skill, MCP server, or plugin from the catalog. The step also inherits capabilities from its agent and worker, and inherited ones stay visible on the step.

A required capability that is unavailable at kickoff blocks the run. Agent capabilities covers required, optional, and disabled rules, credentials, and session evidence.

Configure agent steps

An agent step hands one part of the workflow to an agent. The task mode tells the agent its role. One Horizon adds instructions for that mode before the agent starts:

• Planning writes the plan document and does not change product code.
• Researching investigates an open question and records evidence and recommendations in a research document. It must not change the repository.
• Coding implements the work on the workflow branch.
• Reviewing checks the declared inputs and returns approve, feedback, or reject.
• Executing carries out work that does not change code and reports the result in a required summary. It cannot commit or open pull requests.
• Use default keeps the agent's own default mode.

Field	Meaning
Agent	Local or cloud agent that should run the step.
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, research, or review document, code changes, PR/MR review artifact, or result summary.
Guidance	Step-specific instructions delivered with this step's work context.

Expected inputs do not limit what a step can read: agents can still open other workflow documents for context. Expected outputs do limit writes. A review step without Review in its expected outputs cannot record findings.

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.

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.

Choose Researching while the question is still open and the evidence may change direction. Choose Planning once requirements are known and you need an implementation sequence. Research documents stay linked to the work item, so later steps can use the findings.

When a coding step requires a plan, the plan becomes its main brief. The plan must be completed, non-empty, and written in the current run, or the step will not start. Review steps that check code or a pull request get the same brief. An optional plan does not change what the agent receives.

A step with required document outputs cannot finish until those documents are complete and valid.

A Reviewing agent that cannot judge safely rejects with the reason in the review document instead of leaving the verdict empty.

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 you can publish.

The lower sidebar section sets the Feedback and Reject routes.

Review passes

Review steps, human or agent, have a Review passes setting: Once, Up to 3 times (the default), or a custom number. After final pass decides what happens when the limit is reached. Skip this step on the next loop (the default) lets the run move past the review the next time work comes back. Stop the workflow stalls the run until someone chooses Resume.

Route review outcomes

Step type	Main outcome	Additional outcomes
Agent: Planning, Researching, Coding, or Executing	Success	None. Reorder or insert steps on the canvas.
Agent: Reviewing	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 follows the configured reject route; it does not cancel the run by itself. 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

Publishing checks that:

• There is at least one step, and a start step.
• Every route points to an existing step or an end state.
• Agent steps that are not review steps have a success route.
• Reviewing steps and human review steps have approve, feedback, and reject routes.
• Human review steps have reviewers.
• Feedback routes point to an earlier step, and reject routes to an earlier step or an end state.
• An agent step that follows another agent step has an agent or agent group target.
• Researching steps require a research document output, and Executing steps require a summary output.
• Code-producing steps use agents that can write code.

If a check fails, the workflow stays a draft and the invalid steps are highlighted. Fix them and publish again.

Editing a published workflow returns it to draft with unpublished changes until you publish again. Unpublish workflow keeps a workflow editable but removes it from new runs.

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.

Share and template workflows

A Shared Workflow is published to the whole workspace instead of staying private to its owner. Everyone in the workspace can run it, and only workspace owners and admins can edit it.

A template is a reusable starting point created from a workflow. Installing one creates an independent, editable copy: later edits to the template and the installed copy do not affect each other. Sharing and templating are separate actions, and one workflow can be both.

The workflow actions menu adds these controls:

Action	Available when	What it does
Create Template / Update Template	The workflow has no published template, or you own its template	Publishes the workflow as a new template, or pushes the current version to the existing one.
Share with Workspace	The workflow is private and you can manage it	Converts it into a Shared Workflow.
Publish workspace update	The workflow is already a Shared Workflow and you can manage it	Publishes the current version to everyone using it.
Version history	A template or Shared Workflow publication exists	Lists published versions and restores an earlier one.
Remove Template	You own the template	Stops new installs. Workflows already installed from it, and the source workflow, are unaffected.
Unpublish Shared Workflow	You can manage the Shared Workflow	Blocks new runs. Existing runs, local harnesses, and credentials are unaffected.

Configuring a Shared Workflow

Each workspace member needs a local agent and worker bound to a Shared Workflow's requirements before they can run it. Sharing or republishing records the author's own agent, tools, and permissions, so the author never configures it manually.

When another member opens Configure, a step is matched automatically if exactly one of their agents satisfies its requirements. If several qualify, they choose one. If none do, the step shows the reason, such as a missing harness or tool. The workflow stays Unconfigured for that member until every required step resolves.

Run states and actions

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 run's branch: the Git branch all its steps commit to.

Archiving a failed run removes its worktrees on every computer. On the run owner's computers and those of workspace owners and admins, it also discards their uncommitted changes; on a teammate's computer, a copy with changes waits for that teammate to confirm. Cleanup stays pending while a computer is offline and finishes when its agent reconnects; run details show the progress. The run keeps its failed outcome and its history. To keep a failed run's changes, remove its worktree with Manage worktree instead of archiving it.

Plan, review, and result-summary documents remain attached to the linked task. Branch and pull request or merge request details appear when the harness reports them. Monitoring covers session actions and recovery.