# Workflows

Workflows turn a repeatable process into a reusable graph of actions and
control steps. Use them when work needs more structure than sending one
scheduled message—for example, a decision, approval, wait, loop, parallel
branch, or several dependent Agent actions.

## The Product Model

- **Workflow**: the reusable definition and its input contract.
- **Schedule**: a saved configuration that starts one Workflow on a schedule.
- **Run**: one execution of an exact published Workflow version.

A scheduled collaboration message and a Workflow Schedule are different
features. The former sends one saved message later; the latter starts a
published multi-step Workflow.

## Navigate Workflows

Open **Workflows** from the workspace rail to land on **Overview**. The module
keeps four tabs in one place: **Overview**, **Workflows**, **Schedules**, and
**Runs**. Overview shows yesterday, today, and tomorrow as chronological day
columns, combining accepted Runs with upcoming Schedule occurrences. Use the
scope control to see the whole workspace or only Workflows created by you or
your Agents, and use the arrow controls to move through past or future windows
three days at a time or return to today. Select the displayed date range to
choose the middle day of any three-day window from the month calendar. The
dashboard beside it summarizes Run health for the same window and lists recent
Runs. Longer Runs use a
taller capped card and show their elapsed duration without expanding in direct
proportion to runtime. Recent runs shows the latest ten Runs of any status in
descending start-time order and scrolls independently; select a row to open
that Run.

## Create and Edit a Workflow

Open **Workflows** and create one from a template. The visual canvas and YAML
view edit the same draft. Turn on **Auto layout** when Loop should keep node
positions organized; nodes stay fixed while the mode is on. Turn it off to
preserve the current positions and drag nodes manually. Choose **Save** when
the draft is ready; Loop validates it and creates the saved version used by
future Runs.

Use **Add step**, then choose what should happen next from the task-oriented
categories. Adding a step selects and centers it, then opens its core
configuration. The adjacent step finder selects and centers an existing step
by its name, ID, or type. Hover or select an eligible ordinary connection to
insert a message or wait step. Loop keeps this shortcut hidden wherever an
insertion could change data, an approval decision, or control flow; use graph
or AI edit there instead.

The right panel shows Workflow information, the selected step or connection,
and AI edit. Select an ordinary step and choose **Edit** to change its
configuration with typed controls. The action's core settings appear before
its canvas name and input contract. **Apply** updates the local draft; use
**Save** when you are ready to persist it. Fields that change connected
branches or ports stay read-only and offer **Edit with AI** instead. The form
keeps optional and conditional settings out of the way until they apply, while
preserving any configured or invalid value so you can repair it. Fixed
protocol details remain available in the step summary instead of appearing as
inactive fields. If you leave a step form with unfinished changes, Loop asks
before discarding them. After applying a change, Loop offers **Save and leave**
or **Leave without saving** before navigation would discard an unsaved draft.

The canvas toolbar shows **Auto run** separately from **Run**. A Workflow is
only a definition: it does not run automatically until it has an enabled
Schedule. The status distinguishes not configured, off, and on, while the
Workflow information panel offers the applicable create or management action.

Choose **AI edit** when the change spans the graph or is easier to describe:

1. Select one of your Agents.
2. Describe the change in plain language, or insert a common instruction and
   adapt its placeholders.
3. Optionally select a node or connection to attach that context.
4. Send the request.

The composer keeps typed text and its attached canvas item together. Selecting
another node does not silently retarget a non-empty draft; an explicit handoff
lets you keep the current context or use the selected node. Clearing the
attachment explicitly returns to Workflow-level context. The attachment helps
the Agent understand the request; it does not limit which part of the draft the
Agent may need to update.

After one attributable Agent update, **AI updated the draft** appears in the
same panel. Review the marked nodes and grouped configuration or layout
changes on the existing canvas. Choose **Finish review** to keep the updated
draft, or **Undo this change** to restore the saved baseline when no newer
Draft update has occurred. This comparison and one-click undo are available
only in the current uninterrupted page session.
If the Agent finishes without changing the saved draft, the same panel says so
without opening a change review, and your next request remains available in the
existing composer.

## Review Published Versions

Open the latest-publish summary after the Workflow description to see the five
most recent versions. Choose one to open that snapshot, or choose **View all
published versions** to open history at the latest version. The selected
version appears read-only in the same visual canvas or YAML view, while the
right panel lists published versions. **Latest published** and **Default run**
are separate roles.

Choose a version row to preview it. From the row menu, eligible versions can be
set as the default run version or republished as a new version. Setting the
default affects later runs that do not specify a version; it does not change
existing Schedules or Runs that have already started. Republishing creates a
new immutable version without changing the current draft, prior versions, or
existing Schedules.

Choose **Back to current draft** or press Escape to leave the read-only
preview. Your draft changes, canvas position, and selection remain as they were
before opening history.

## Run Now

Choose **Run** on Workflow detail to start the default published version.
The compact attached menu offers separate **Add schedule** and
**Manage schedules** actions. The primary button always starts an immediate
Run and does not change after a menu action. Loop builds the form from that
version's input schema:

- choices use selectors;
- channels, members, Agents, and collaboration spaces use accessible workspace
  resources;
- numbers, dates, durations, lists, and structured values use controls that
  match their declared type.

Use **Show workflow preview** to expand the graph. Hovering or focusing an
input emphasizes the nodes that consume it. If validation or invocation fails,
the dialog keeps the values you entered so you can correct and retry them.

## Create a Schedule

From Workflow detail, open **Schedules** and choose **New schedule** to keep the
current Workflow preselected. You can also open the main **Schedules** list and
choose **New**. Loop uses the Workflow's latest published version automatically;
set the timing, then provide the fields required by that Workflow. Completed
sections collapse into summaries but remain editable. Changing an earlier
answer only reopens or invalidates the sections affected by that change.

When no active published Workflow is available, the Workflow selector offers
a direct route back to the Workflow list instead of becoming a disabled
control.

## Inspect a Run

The main **Runs** list groups records by local calendar day, newest first. Open
or collapse a day, then select anywhere on a Run row to inspect it. Each row
shows the start time, Workflow name, elapsed time when available, source, and
status. Status appears once as the leading icon; manual and scheduled source
Badges use different icons.

Run history provides two primary views:

- **Graph** shows executed nodes, status, attempts, and branch information.
- **YAML** shows the pinned Workflow source used by that Run.

Workflow, Schedule, and Run details provide a leading back action to their
owning list. A Run opened from Overview returns to Overview instead.

Use **More actions → Debug data** to inspect the raw run input, current state,
output, and error data. For an active Run, **Cancel run** is the final action in
the same menu and asks for confirmation before stopping the Run.

The detail panel links back to the related Workflow and Schedule when one
started the Run. Active Runs refresh while open; a transient refresh failure
does not discard the current view.

## Practical Guidance

- Give inputs user-facing labels and descriptions in the Workflow schema.
- Use a choice, channel, member, Agent, or scope type when free text is not
  valid.
- Publish a new version for executable changes; existing Runs stay pinned to
  their original version.
- Test important branches with **Run** before enabling a Schedule.