> For the index of every page in Orbital's docs, read https://docs.beta.runorbital.dev/llms.txt.

# Give steps a style

> Choose each step's harness, model, effort and persona with styles

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.

![plan leads to coder.implement, coder.implement leads to coder.check, coder.check leads to review, and review reaches done.](/styles.svg?v=061c1b9c45)

```toml title="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](/workflows/write-a-workflow/).
- Know what styles and personas are. [Styles and personas](/styles/) defines them.

## Set a base for every step

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

```toml
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.

```toml
[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:

```toml
[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:

```toml
[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

```toml
[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

```toml
[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:

```toml
use = ["shared/team.toml"]
```

```toml title="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](/projects/#plain-folders-and-git).

1. **Download the files.**

   [Download the files](/styles.zip).

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.

:::caution[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](/examples/styles/styles.toml) and [shared/team.toml](/examples/styles/shared/team.toml), or [all the files](/styles.zip).

[Workflow file](/reference/workflow-file/#styles) 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](/styles/): what a style holds and how styles cascade
- [Use different models](/harnesses/use-different-models/): run steps on different harnesses and models
- [Reuse a workflow](/workflows/reuse-a-workflow/): how import steps pass styles to the steps inside
- [Workflow file](/reference/workflow-file/#how-a-steps-settings-resolve): the exact resolution order