Building Workflows
Build a workflow when the same kind of work should move through a known sequence: plan, review, code, verify, or any smaller set your team repeats.
Before you start
A workflow needs at least one eligible agent before agent steps can run. For local execution, install the selected coding tool, sign in, make Git available, and choose a writable repository folder. 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 the definition
Open Workflows, then open a workflow row or select New workflow from the definitions view. Enter a name and description, set runtime defaults, and build the steps in the designer.
Drafts autosave while you build. A draft can stay incomplete until you select Publish. Publishing runs validation and makes the workflow available from Send to... on matching work items.
Name workflows after the process, not one task. Plan, approve, code, review is reusable. Implement billing export is usually a task title.
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 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: Tasks, 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. |
| Additional instructions | Optional trusted guidance for the step. One Horizon appends it to the agent session prompt after the base work context and any human gate feedback. |
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.
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. |
| Additional instructions | Optional trusted 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.