Workflows

A workflow is one DOT file that Orbital can load, validate and run. It declares a version, an entry node, the nodes themselves and the edges between them. Orbital calls a loaded workflow a graph, and the two words mean the same thing here. The simple example is the smallest complete one: a graph attribute line, one agent and one terminal.

Keep the file in your project’s .orbital/ folder. Give every node a stable ID, because the run transcript, visit counts and manual jumps all address nodes by ID. Write each prompt for someone arriving without prior conversation: state the expected result and the allowed actions.

Validate before you run

orbital validate .orbital/hello.dot

Validation reads the file, resolves imports and prompt sidecars, and checks routing without calling an agent. Fix errors before adding more nodes. Warnings identify unreachable nodes, unused inputs and other suspicious but loadable declarations.

Add one decision at a time. A choice output with two explicit weighted routes is easier to inspect than a prompt that silently decides whether to publish. Validate again after editing imports and prompt files, because those are separate files that the graph only names.

Where Orbital looks for a workflow

Discovery searches custom graphs saved in the browser first, then the primary project folder and remaining folders, the operator library, and the graphs shipped with Orbital. A name collision selects the first match, so a custom graph named hello shadows a file named hello.dot. Use a distinct name while experimenting, and pass an explicit path to orbital validate when diagnosing a collision.

The browser graph library also creates and edits custom graphs. Saving validates them. Inspect the selected graph before starting a run.

Declared inputs

inputs="work,notes?" requires work and makes notes optional. goal is built in. Starting a run requires the goal and every required input, so a workflow states its own contract rather than relying on the operator to remember it. Context covers what happens to those values once the run starts.

Continue with nodes, or copy the simple example and change it.