Multi-stage workflows

Most routines are one instruction. Some are not: research, then draft, then package is three jobs, and writing them as one prompt leaves the model to decide how much of each to do.

A workflow makes those stages explicit. Stages run in order inside a single run, each one sees what the earlier ones produced, and each one can be limited to a subset of the routine's tools.

When a workflow earns its keep

Use one when the work has a real seam:

• the output of one part is the input of the next ("research, then write"),
• one part should read and another should write, and you want that boundary enforced rather than described,
• the trace needs to say which part of the job a step belonged to.

Keep a single instruction when the job is one thing. A workflow is more to maintain, and stages add prompt overhead to every run.

Anatomy of a stage

A workflow holds between one and eight stages.

Building one

In the composer, switch Instructions mode to Workflow. Whatever is in the instructions box becomes stage 1, so nothing is lost on the way in.

Each stage card carries its name, its instructions, its tool scope, and controls to move it up or down, add another, or remove it. Underneath, the Summary states the execution order and each stage's tool permissions in plain words — read it before saving; it is the same wording the run page uses.

Switching back to Single instruction flattens the stages into one instruction with ## Stage n of m headings. That conversion is lossless as text but not as behaviour: stage boundaries disappear and every part of the routine runs with every allowed tool again. The composer warns before it does.

Some templates ship stages already. Choosing one opens the builder with them filled in.

What each stage sees

A stage's prompt contains, in order:

1. the workflow outline, with the current stage marked,
2. the stage's own instructions, with variables substituted,
3. the routine's repository, skill, and prefetched material sections,
4. the final output of every earlier stage.

The last stage's output is the run's result — the text that reaches your result destinations and the webhook.

Permissions

A stage can never use a tool the routine itself cannot. The scope is applied on top of the routine's permissions, so:

• attaching a connector still grants its tools to the routine as a whole,
• a stage limited to one connector cannot reach another,
• a stage with nothing selected runs without tools at all.

Approvals, managed-provider policy, and automatic execution are unchanged — see Tool permissions.

The scope picker also offers individually approved tools that are enabled for automatic execution. You do not need to attach their whole connector.

Deleting a connection or revoking an individual tool removes stage selections that no longer have a valid grant. An emptied selection stays model-only. Workflows changed this way return to draft and need a fresh test run before their schedules can be activated again.

Limits and failure

Stages share the run's limits. The idle timeout, the absolute deadline, and the usage budget are all run-level, so a workflow does not buy more execution time than a single-instruction routine — plan stage instructions accordingly.

If a stage fails, the run fails and later stages never start. The error names the stage, for example:

Stage 2 of 3 (Draft) failed: Tool linear__save_issue is not enabled for this routine.

There is no resume: fixing the routine and running it again starts from stage one.

Reading the trace

The run page opens with a Stages panel listing the order and permissions of the workflow that run executed — a snapshot taken when the run was queued, including the variable values used to render its stages. Editing the routine later never rewrites that saved configuration. Tool grants are still checked at execution time, so a saved workflow cannot restore a revoked permission. Each stage boundary appears in the trace as a labelled divider, and every model and tool step below it is tagged with the stage it belongs to.

Runs from before a routine became a workflow, and runs of single-instruction routines, keep their existing flat trace.

Changing a workflow

Editing stages is a material configuration change: the routine returns to draft and needs a fresh successful manual run before its schedule can be activated again. See Routines.