Workflow Reference

Workflow reference details belong here so the overview, building guide, and running guide can stay focused on decisions and tasks.

Definition model

A workflow definition owns the reusable authoring model.

Field	Description
workflowId	Stable workflow ID. New definitions receive one when first saved.
name	Display name shown in the workflow overview and switcher.
description	Optional description for people choosing or maintaining the workflow.
icon, iconColor, iconShade	Optional visual identity shown in workflow lists and launch menus.
status	draft, active, or archived.
supportedEntityTypes	Task, bug, and/or initiative types that can launch this workflow from a detail page.
startStepId	Step where the workflow begins. Defaults to the first step when omitted.
steps	Ordered step definitions, including layout positions and routes.
runtime	Portable runtime defaults for workflow-backed sessions, including code isolation and One Horizon PR/MR creation.

Each step can store:

• stepId, name, type, and sortOrder.
• positionX and positionY for saved layout.
• Agent fields: agentId, taskMode, targetWorkerId, targetGroupId, expected inputs, expected outputs, and additionalInstructions.
• Review fields: reviewer assignments, approval policy, reassignment policy, and additionalInstructions.
• Routes for success, approve, feedback, or reject outcomes.

The saved Workflow record wraps the definition with workspace ownership, validation status, created and updated metadata, archive metadata, and hydrated steps used by the dashboard.

Execution model

Execution is choreography, not a central job runner. One Horizon starts the run, creates sessions for launch and human-gate routes, validates delegated sessions, records events, and manages human gates. When one agent step routes to another, the next session comes from the current agent's delegation event.

Launching copies the definition onto the run so later edits do not rewrite in-progress history. The run records the active step, active agent session, active step-session attempt, branch name, review feedback, reviewer assignment, stalled reason, and timestamps as execution moves forward.

Direct assignment to an agent still creates a single-step system workflow run around the queued session. Direct agent work and multi-step workflow work share the same durable run history.

Step types

A run can route through two step types.

Step type	What happens
Agent	Creates or accepts a delegated agent session for the configured agent profile, task mode, and agent target. The agent still polls, claims, heartbeats, reports activity, and finishes the session.
Human review	Pauses the run in waiting_for_review until an assigned reviewer approves, rejects, sends feedback, or reassigns the gate.

Agent steps can target a specific agent or an agent group. When one agent step routes to another agent step, the next step must have targetWorkerId or targetGroupId. Completing the current agent session without delegating to that target stalls the run.

Human review steps require approve, feedback, and reject routes. Feedback is stored on the run, routed back to the configured earlier step, and injected into the next agent session. Reassignment moves review responsibility to another user or team without losing the run history.

Task modes and branches

Agent steps run in plan, code, or review. If an agent step omits taskMode, it defaults to code.

Task mode	Agent instruction
plan	Produce an implementation plan document in ONE_WORKER_DOCUMENTS_DIR. Do not modify product code unless inspection is needed.
code	Implement the approved work, keep a concise nontechnical summary, and let the runtime publish the workflow branch before any cross-agent handoff.
review	Inspect the workflow branch in a disposable review workspace, make an approve, feedback, or reject judgement, and produce findings in a review document. Do not keep review-only code changes.

Review-mode agent steps use the same route outcomes as human review steps. The agent must finish with exactly one review verdict. Missing or unknown verdicts stall the run so the workflow does not silently continue through a failed review.

The workflow branch is the shared handoff state. When a handoff crosses agent or group targets, the parent session must report workflowPushConfirmed before the delegated session can continue. Missing confirmation stalls the run with workflow branch was not pushed before cross-agent handoff.

Workflow artifact documents

Workflow agents read and write structured documents through the agent runtime. Each linked task keeps at most one canonical document per workflow artifact type:

Artifact type	Agent file	Document type	Typical step
Plan document	plan.md	Task	Plan
Review document	review.md	Review	Review
Result summary	code-summary.md	Spec	Code

Lookup uses the linked task plus artifact type, not task mode or workflow run ID on the document row. The same plan or review document is reused across runs on that task so feedback loops keep one durable record.

Run and session provenance is stored separately. A workflow run or agent session can record which run wrote or read an artifact, but that provenance does not change how the document is found.

Agents sync these files from ONE_WORKER_DOCUMENTS_DIR. Custom agents should use the document APIs to create or update the document body and then link it to the task with the matching workflowArtifactType. See Documents for the workspace document model and the API reference for list, save, and update calls.

Document blocks

Workflow artifact documents are markdown files with addressable document-block:v1 sections. Agents edit blocks through document tools such as append_document_block, load_document_blocks, and update_document_block_metadata. They should not rewrite whole workflow documents by hand or commit plan.md or review.md into the product repository.

Each block has a type and optional status in YAML metadata inside the block comment. Status applies to the block, not the whole document file.

Plan document blocks

Plan steps usually write blocks such as:

Block type	Role	Common statuses
goal	States the outcome the work should achieve	Often accepted once drafted
requirement	States a concrete requirement the implementation must satisfy	proposed, accepted, dropped, superseded, or obsolete
implementation_task	Breaks work into executable tasks	todo, in_progress, done, blocked, or skipped
decision, risk, open_question	Supporting planning context	Optional status

Requirements can reference tasks with related.tasks. Later steps use these IDs when they need to trace work back to the plan.

Review document blocks

Review steps write review_finding blocks with IDs such as REV-001. Each finding should include severity and a status.

Status	Meaning
open	The finding still needs a fix
fixed_pending_review	The coder believes the issue is fixed and is waiting for re-review
verified_fixed	The reviewer confirmed the fix
reopened	The reviewer checked the fix and the issue is still present
wont_fix_requested, accepted_wont_fix, obsolete	Exception paths for disputed or stale findings

Findings can point back to plan requirements with qualified refs such as doc-plan:PLAN-REQ-002 in related.requirements.

Result summary blocks

When a code step declares Summary as an expected output, the agent can record implementation notes on code-summary.md using block types such as implementation_note, fixed_finding, or blocker. A fixed_finding block can reference the review finding and commits that addressed it.

This is the normal handoff when a build step needs to show what changed without editing the review document directly. The agent can read review findings when the review document is declared as an expected input, but it can only write review findings when the review document is declared as an expected output on that step.

Review feedback loop

Agent review has two layers:

Layer	What it controls	Example
Review finding blocks	Durable issue list in the review document	REV-001 with status: open and severity: blocker
Review verdict	Workflow routing for the current review step	approve, feedback, or reject on the agent session

The workflow routes on the review verdict. It does not automatically block approve when open findings remain, so agents should only approve when the declared inputs are acceptable.

Add multiple review steps in a row when different checks need different agents, models, skills, or instructions. For example, one reviewer can focus on security, another on architecture, and another on UI reuse. Each review step can route feedback back to the same Code step so the fix stays in one run.

A typical loop:

1. Plan writes goal and requirement blocks to the plan document.
2. Review reads declared inputs, loads workflow document blocks as needed, appends review_finding blocks, and finishes with a review verdict.
3. Code reads the plan and any declared review or summary inputs, implements the work on the workflow branch, and records fixed_finding or implementation_note blocks on the result summary when that output is declared.
4. Review again loads prior findings, updates finding status to verified_fixed or reopened, and returns a new review verdict.

Human review steps use the same approve, feedback, and reject routes, but reviewers decide from the inbox and task context. They do not edit REV-* blocks in the workflow designer. Agent-written findings remain the durable review record unless a later agent step updates them.

Agent responsibilities

Workflows do not replace the agent session and claim lifecycle. They add trusted workflow context to sessions agents already execute. Workflow-backed sessions resolve the workflow runtime at claim time. Direct assignments keep the agent runtime.

Agent queue in the main menu groups active workflow runs by workflow name and linked task. Each group shows run status, step progress, and sessions in that run. Direct agent sessions appear below the workflow groups.

The Overview page also lists recent workflow runs so you can inspect activity without opening the queue.

Custom agents should still follow Agent Sessions: poll or wake from webhooks, claim before running, include the active claimId in updates, heartbeat while active, emit useful activity, and end every session with complete, fail, or release.

For agent-to-agent routes, the agent must create a delegated child session for the configured next target. Finishing the current session is not enough to advance to another agent step. If the agent cannot delegate, cannot confirm the branch handoff, or receives an invalid target, it should report a blocker instead of hiding the stall.

For local execution, see Build a Local Agent. For shared services, see Build a Cloud Agent. To choose between apps, local agents, and custom agents, start with choosing how agents run.