> ## Documentation Index
> Fetch the complete documentation index at: https://www.shipfox.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Step Types Reference: Run Steps and Agent Steps

> Detailed reference for Shipfox's two step types: run steps execute shell commands, agent steps invoke AI models. Covers fields, constraints, and the gate block.

Every Shipfox step is one of two kinds: a **run step** executes a shell command on the runner, or an **agent step** invokes an AI model. The kind is determined by which keys are present — `run` marks a run step; `prompt` (or `model`, `thinking`, or `provider`) marks an agent step. Mixing keys from both kinds on the same step is a validation error.

## Run step

A run step executes a shell command on the job's runner. It has access to environment variables from the workflow, job, and step scopes.

<ParamField body="run" type="string" required>
  The shell command to execute. Must be at least one character.
</ParamField>

<ParamField body="name" type="string">
  Displayed in the dashboard log. Display-only — a step referenced by `restart_from` needs a `key:`, not a `name:`.
</ParamField>

<ParamField body="env" type="object">
  Environment variables for this step. Merged with job-level and workflow-level env; step-level values take the highest precedence. Keys must follow POSIX-style naming (`[A-Za-z_][A-Za-z0-9_]*`). Values may be strings, numbers, or booleans.
</ParamField>

<ParamField body="key" type="string">
  Optional stable identifier for this step. Useful for referencing the step programmatically. Must be at least one character.
</ParamField>

<ParamField body="gate" type="object">
  Gate and retry configuration evaluated after the step completes. See [Gate block](#gate-block) below.
</ParamField>

```yaml theme={null}
- key: test
  run: npm test
  env:
    CI: "true"
  gate:
    success_if: exit_code == 0
    on_failure:
      restart_from: install   # 'install' is an earlier step's key
```

## Agent step

An agent step invokes an AI model with a text prompt. The model reads the repository context and executes the instruction. The recommended pattern is an agent step that produces a change, followed by a run step whose gate judges the result.

<ParamField body="prompt" type="string" required>
  The instruction given to the model. Must be at least one character. Required on any step that also sets `model`, `thinking`, or `provider`.
</ParamField>

<ParamField body="model" type="string">
  Model ID to use (e.g., `claude-opus-4-8`, `gpt-5.5-pro`). Uses the workspace default if omitted. Model catalog checks are performed at runtime, not at parse time.
</ParamField>

<ParamField body="provider" type="string">
  Provider ID for the model (e.g., `anthropic`, `openai`, `deepseek`). Pairing `provider` with `model` lets a step target a specific non-default provider/model combination. Uses the workspace default if omitted.
</ParamField>

<ParamField body="thinking" type="string">
  Reasoning depth for the model. Controls how many tokens the model spends on internal reasoning before producing a response. Accepted values: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Default: `high`.
</ParamField>

<ParamField body="name" type="string">
  Optional step name, displayed in the dashboard log.
</ParamField>

<ParamField body="key" type="string">
  Optional stable identifier for this step. Must be at least one character.
</ParamField>

<ParamField body="gate" type="object">
  Gate and retry configuration. See [Gate block](#gate-block) below.
</ParamField>

```yaml theme={null}
- name: review
  model: claude-opus-4-8
  provider: anthropic
  thinking: high
  prompt: Review the failing test output and fix the code.
```

## Gate block

A gate block is optional on both run steps and agent steps. It must contain at least one of `success_if` or `on_failure`.

<ParamField body="success_if" type="string">
  A CEL expression evaluated after the step completes. The variable `exit_code` (integer) is available. Example: `exit_code == 0`. When omitted, the step's default exit behaviour applies.
</ParamField>

<ParamField body="on_failure.restart_from" type="string">
  The `key` of an earlier step in the same job to restart from when this step fails. The referenced step must have a `key:` and appear before the current step in the job's step list (`name:` is display-only and cannot be referenced).
</ParamField>

<ParamField body="on_failure.output" type="string">
  A message to surface in the run log when this step is considered failed.
</ParamField>

## Constraints table

The following table summarises which fields are valid on each step kind. Mixing fields across kinds on the same step is a validation error.

| Field      | Run step      | Agent step    |
| ---------- | ------------- | ------------- |
| `run`      | ✅ Required    | ❌ Not allowed |
| `prompt`   | ❌ Not allowed | ✅ Required    |
| `model`    | ❌ Not allowed | ✅ Optional    |
| `thinking` | ❌ Not allowed | ✅ Optional    |
| `provider` | ❌ Not allowed | ✅ Optional    |
| `env`      | ✅ Optional    | ❌ Not allowed |
| `name`     | ✅ Optional    | ✅ Optional    |
| `key`      | ✅ Optional    | ✅ Optional    |
| `gate`     | ✅ Optional    | ✅ Optional    |

<Warning>
  The `agent:` key is reserved for a future step kind. Using it today results in a validation error with a clear message. It is not a valid alias or shorthand for an agent step — use `prompt` instead.
</Warning>