Give steps a style

Give a step a style to decide in one name which harness runs it, which model it uses, how hard it thinks and which persona it speaks as. Set style on the step, on a group of steps, or at the top of the workflow for every step. This guide walks through one plan, implement and review workflow that uses each of them.

styles.toml

version = 3
entry = "steps.plan"
use = ["shared/team.toml"]
style = "balanced"

[styles.careful_review]
extends = "reviewer"
effort = "max"
codex.sandbox_mode = "read-only"

[steps.plan]
style = "planner"
prompt = "Plan a small change that meets this goal: {{ inputs.goal }}. Do not change files."
outputs.plan = "text"
next = "steps.coder.implement"

[steps.coder]
style = ["implementer", "codex"]

[steps.coder.implement]
prompt = "Implement this plan: {{ context.plan }}"
next = "steps.coder.check"

[steps.coder.check]
effort = "low"
prompt = "Run the project's checks and fix what they find."
next = "steps.review"

[steps.review]
style = ["careful_review", "thorough"]
prompt = "Review the change against this plan: {{ context.plan }}. Report what you find. Do not change files."
next = "steps.done"

[steps.done]
kind = "terminal"

Before you start

• Know how to write a workflow. See Write your first workflow.
• Know what styles and personas are. Styles and personas defines them.

Set a base for every step

The top-level style applies to every step that does not choose otherwise:

style = "balanced"

balanced ships with Orbital and sets effort = "medium". Put the settings every step shares here, such as permissions, in a style of your own and name it at the top.

Give a step a style

Only steps that take a turn use styles: agent steps, a fan-in with a prompt, and the write of an action. A command, a wait or a terminal does not.

[steps.plan]
style = "planner"
prompt = "Plan a small change that meets this goal: {{ inputs.goal }}. Do not change files."

plan uses the shipped planner style, so it speaks as the planner persona and thinks at high. Its style beats the workflow’s balanced.

Give a group a style

A table under steps that holds steps is a group. A style on the group reaches every step inside it:

[steps.coder]
style = ["implementer", "codex"]

coder.implement and coder.check both run with the implementer persona, on Codex with gpt-6, because the codex style says so. The list combines two styles, and a later name wins where both set the same key.

Override one key on a step

A key set on the step itself beats every style:

[steps.coder.check]
effort = "low"
prompt = "Run the project's checks and fix what they find."

coder.check thinks at low. It keeps the persona, harness and model it takes from its group.

Combine styles in a list

[steps.review]
style = ["careful_review", "thorough"]

careful_review extends the shipped reviewer, so review speaks as strict_reviewer. thorough comes later in the list, so its effort = "high" wins over the max in careful_review.

Set something for one harness only

[styles.careful_review]
extends = "reviewer"
effort = "max"
codex.sandbox_mode = "read-only"

codex.sandbox_mode applies only when Codex runs the step. review names no harness, so it runs on the harness of the run’s preset: the preset you picked on the Start page, or else the preset in use. On Codex it runs in a read-only sandbox and cannot write to the repository. On any other harness the line does nothing. The claude.*, opencode.* and pi.* sub-tables work the same way, and so does a plugin harness’s sub-table of its own name.

Share styles between workflows

use pulls in style files, with paths relative to the workflow file:

use = ["shared/team.toml"]

shared/team.toml

version = 3

[styles.thorough]
effort = "high"

[styles.codex]
harness = "codex"
model = "gpt-6"
codex.sandbox_mode = "workspace-write"

thorough comes from this file. Orbital also ships a style called codex, which sets only harness = "codex". The app’s style wins on the key it sets, so the file’s model and codex.sandbox_mode still merge in. A style the workflow defines itself beats a style of the same name from a file it uses.

Change a style for every workflow

Presets in Settings > Presets win over styles of the same name in files. Edit the shipped reviewer there, and every workflow that names it follows, including through careful_review, which extends it.

To change a shipped preset for one workflow only, extend it under a new name in that workflow, as careful_review does. A copy called reviewer in the file would lose to your Settings.

1. Open Settings > Presets.

   Open Settings from the sidebar and choose Styles.

2. Edit the style.

   Select a style and change its settings.

3. Undo it if you need to.

   Reset to default returns an edited shipped preset to Orbital’s version. Deleting a shipped preset hides it until you choose Restore.

Choose the run’s preset

Steps that name no harness, such as plan and review, run on the harness of the run’s preset. A run started without a preset follows the preset in use in Settings > Presets, which is claude on a fresh install. To run one run on another style, pick it in the Start page’s preset picker, or pass style to start_run. That pins the run to it. The run’s preset comes after everything the workflow sets, so the coder group still runs on Codex.

Check what a step resolved to

Select a step in the workflow editor. The inspector sums up the settings the step resolves to, such as its persona, harness, model and effort, and says where each comes from: the step itself, one of its styles, a group that holds it, or the workflow. Select a part to open its definition.

Once a run has started, the run page shows the settings each step ran with, and the transcript records the settings of every turn. It is the fastest way to check that your styles did what you meant.

Try the example

The coder group runs on Codex, so sign in to Codex first. Codex refuses to start in a folder that is not a Git repository, so pick a practice project that is one. See plain folders and Git.

1. Download the files.

   Download the files.

2. Unpack them.

   Unpack the download into your workflow library, ~/.orbital/workflows/. Keep every relative path, so the workflow finds shared/team.toml.

3. Check the workflow.

   Run orbital validate ~/.orbital/workflows/styles.toml.

Open the styles workflow in the editor and select each step to see what it resolves to. Then choose New task, pick your practice project, choose the styles workflow and write a goal.

This example changes your folder

coder.implement changes files in the project’s folder itself, because the workflow makes no worktree. Pick a practice project, not one you care about.

Expected behaviour

plan writes a plan without changing files. coder.implement and coder.check run on Codex and change the files. review reports what it finds without changing files. The run page shows the settings each step ran with.

Complete source

Download styles.toml and shared/team.toml, or all the files.

Workflow file describes every key in these files.

Quick reference

To	Do this
Give every step a style	Set style at the top of the workflow.
Give a group of steps a style	Set style on the group’s table.
Give one step a style	Set style on the step.
Combine styles	Give style a list. Later names win.
Change one setting of a step	Set the key on the step, such as effort = "low".
Set something for one harness only	Use a sub-table key, such as codex.sandbox_mode.
Share styles between workflows	Put them in a style file and list it in use.
Change a preset for every workflow	Edit it in Settings > Presets.
Run one run on another preset	Pick it in the Start page’s preset picker.
Change a shipped preset for one workflow	Extend it under a new name with extends.

Related

• Styles and personas: what a style holds and how styles cascade
• Use different models: run steps on different harnesses and models
• Reuse a workflow: how import steps pass styles to the steps inside
• Workflow file: the exact resolution order