# Agent steps

> One headless turn that answers in JSON, with a spending cap.

One headless turn through [Claude Code](/docs/claude-code): no terminal, an
answer in JSON, and a cost and a duration written on the run when it is over.
Several can be going at once.

## The form

| Field | What it is |
|---|---|
| **Name** | what the lane and the runs call it |
| **Agent** | one of the [agents](/docs/agents) on your machine, by name. Empty: whichever the account defaults to |
| **Ask** | the prompt. Required |
| **Spending cap (USD)** | the ceiling for this turn. Required |
| **Model** | empty: whatever the account defaults to |
| **The answer must match (JSON Schema)** | empty: any answer will do |
| **Tell it about the card** | which context keys the turn is given |
| **Account** | **Default**, or one of your [profiles](/docs/profiles) |
| **This step has no undo** | "It is never started by a drag alone — you confirm it." |

Your **Ask** is what the turn is sent, with the card's title and description
appended below it. Only the agent this step names is handed over: the whole
catalogue would make every step's behaviour depend on files it never mentions.

<!-- Screenshot — the step form with the agent kind chosen. -->

## The cap is not optional

**Create** stays out of reach until **Spending cap (USD)** is filled, and a
step that reaches the runner without one is refused before it spends anything:
*"this step declares no spending cap, so it does not run"*. An agent with no
ceiling is a bill nobody agreed to. What the turn spent lands on the run, and
on the card.

**The answer must match (JSON Schema)** is checked afterwards. An answer that
does not satisfy it fails the run and the card does not advance; prose where
fields were asked for is the case this catches.

## What it is told about the card

Tick the keys you want: `card`, `cardTitle`, `cardBody`, `branch`, `baseRef`,
`project`, `worktreePath`, `projectPath`. Each reaches the turn as an
environment variable — `DEVPIT_` and the key in capitals, so `cardTitle` is
`DEVPIT_CARD_TITLE`. A key nothing answers is left out rather than sent empty:
an empty variable reads as "there is none of this", a different claim from "we
did not look". An agent step runs in the project itself rather than in the
card's checkout, so `branch` and `worktreePath` have nothing behind them there.

## The verdict, and silence

A step can declare that one field of its answer is its verdict. An answer
asking for the card to be sent back moves it to the lane it came from whatever
the lane's setting is, with the reason written on the card. Any other verdict
is a pass, and what follows is the lane's [setting](/docs/moving-cards).

Silence is never a pass. An answer carrying no verdict — and a step declaring
none, which is every step this form makes — has no opinion, and a card never
advances on an opinion nobody gave.
