Add branches

Send a run to different steps depending on what it has just learned. Put a condition on each edge that leaves the step, and the run follows the first one that matches.

conditional.dot

classify [prompt="If the goal asks for a greeting, choose greet. Otherwise choose explain.", outputs="route:choice"]
classify -> greet [condition="route == 'greet'", weight="2"]
classify -> explain [condition="route == 'explain'", weight="1"]

How conditions choose the next step

Routing lives on edges, not in a decision node. Each edge that leaves a step either carries a condition or is the fallback. A condition compares one context value with a literal, such as verdict == 'pass', or tests a value on its own, such as pr.mergeable.

When a step succeeds, Orbital tries its conditioned edges from the highest weight down and takes the first match. Only then does it consider the fallback. Two conditioned edges from one step cannot share a weight.

You cannot combine conditions or compare two context values, so every route stays readable in the workflow. The condition entry lists every form a condition takes.

Each conditioned edge shows its condition and weight; the dashed else edge is the fallback.

Choose what to branch on

Decide first what produces the value you branch on. The answer changes the cost and the reliability of the branch.

• Use a built-in probe when Orbital already observes the fact. The ticket workflow routes on pull request state without asking an agent whether a merge happened.
• For another exact observation, use a script command with declared bool, number or text facts. Its last line of output must be the JSON object exactly as declared. Keep the script read-only when it only inspects something.
• For judgement, give an agent a choice output. Orbital takes the allowed values from the conditions on the step’s outgoing edges and refuses any other answer. So outputs="verdict:choice" with edges for pass and reject accepts nothing else.

A probe or a script gives an exact answer at no agent cost. The example below branches on judgement, so an agent makes the choice.

Cover every case

A branching step needs a fallback, an edge with no condition, unless its conditions already cover every value of its choice output. A run where no edge matches stops with an error, so validation asks for the fallback before the run starts.

Note

A fallback handles successful results outside your named cases. It never handles a failed step. Route a failure with its own condition, outcome == 'failed', as Add a loop and Error handling explain.

Before you start

You need a harness you have signed in to, and a project in Orbital. Any project works. It does not need to be a Git repository, unless you run the example with Codex, which needs one. See Projects and folders.

1. Download the example

Download the example and unpack it into ~/.orbital/workflows/. Keep every relative path.

conditional.dot

digraph conditional {
  graph [version="1", entry="classify"]
  classify [tool_access="Read only", prompt="If the goal asks for a greeting, choose greet. Otherwise choose explain.", outputs="route:choice"]
  greet [tool_access="Read only", prompt="Write a friendly greeting."]
  explain [tool_access="Read only", prompt="Explain the goal in one sentence."]
  done [shape="Msquare"]
  classify -> greet [condition="route == 'greet'", weight="2"]
  classify -> explain [condition="route == 'explain'", weight="1"]
  greet -> done
  explain -> done
}

classify declares outputs="route:choice". Orbital takes the allowed values, greet and explain, from the conditions on its outgoing edges, and refuses any other answer before it reaches context. The two edges carry different weights, so the higher one is tried first. The conditions cover every allowed value, so this step needs no fallback.

Every step has the Read only tool access, so none of them can change files. Codex can run commands to read files because its read-only sandbox prevents writes.

Download conditional.dot

2. Validate it

orbital validate ~/.orbital/workflows/conditional.dot

3. Run it

Choose New task, pick any project, and choose the conditional workflow and your harness. One project serves every example. Use a greeting as the goal to select greet, or any other goal to select explain.

Exactly one response step runs before done. The run’s Context tab shows each value the run holds and the step that set it.

The Context tab shows which step set each value.

Caution

A later step that reads a value produced on only one branch fails validation. Check Error handling before you join branches back together.

Related

• condition: every form a condition takes, and the fallback rules.
• Add a loop: send rejected work back for repair, with a bound.
• Pass context between steps: the values a condition can read.
• Error handling: what happens when a step fails.