# Recipes

A recipe is how a card runs: what the agent is told, where it works (a new branch, a scratch folder), what it hands
back, and what happens when it finishes. Every card has one. Most of the time Andon picks it for you; you change it
when a card is a different kind of job, such as a question to study instead of code to write.

To write or change a recipe, see [Writing a recipe](https://andon-docs.pages.dev/guide/writing-a-recipe.md).

## The built-in recipes

| Recipe | For | Where it works | Ends in |
|---|---|---|---|
| **Code change** (`code-change`) | changing an existing app | a new branch in a worktree | a pull request |
| **Bug** (`bug`) | fixing a reported bug: reproduce it, find the cause, fix it, add a regression test. It reads the report from the card's notes, files and links, so an imported issue runs as it is | a new branch | a pull request |
| **New app** (`app-new`) | building an app in a fresh repository | a new repository | a pull request |
| **Image assets** (`image-assets`) | generating images for you to review | a scratch folder | output files to review |
| **Study** (`study`) | answering a question rather than doing a task. It never pushes or opens a pull request. See [Studies](https://andon-docs.pages.dev/guide/studies.md) | the card's workspace, committing nothing | a proposal: findings and cards |
| **Plan a workstream** (`plan`) | splitting a card into steps that then run on their own. See [Workstreams](https://andon-docs.pages.dev/guide/workstreams.md) | the card's workspace, read-only | proposed steps to approve |
| **Generic** (`generic`) | anything else | depends on the card | depends on the card |
| **Code review** (`code-review`) | reviewing a pull request. Andon runs it for review rounds; you don't pick it for a card | the pull request's branch | review findings |

An admin can add more recipes, such as one that renders a video with a tool on one machine.

## How a card gets its recipe

1. A card you make on the board takes its team's **default recipe**.
2. A card made without one (quick add, a capture, an import, the phone) has its recipe **picked by a model**: it reads
   the card, its team and project and the org's recipes, and answers with a recipe and a reason. When it is sure
   enough, the card takes that recipe. The card's **Recipe** field says who picked it, such as *Picked by Claude*, and
   why.
3. When the model isn't sure, says none fits, or can't answer, the card takes the default recipe: the team's, else the
   workspace's, else Code change. The Recipe field then reads *Default recipe* and, when the model had a guess,
   *Suggested: …* with **Use it**.

A recipe you pick by hand always wins, even while a pick is on its way.

Which model picks: with a Claude (Anthropic), Gemini or Vercel AI Gateway key, the workspace's or the server's, the pick follows the
workspace's **AI backend** ([AI backends](https://andon-docs.pages.dev/machines/ai-backends.md)). With no key at all, a machine's own Claude or
Codex picks, when the card has a machine that can answer. Each org gets at most 120 picks an hour per service. The
keys are under **Settings → Connections**, **Advanced** ([Integrations](https://andon-docs.pages.dev/guide/integrations.md#ai-keys)). A machine's owner
can keep it out of picking with `andon policy recipe-detect off` ([machine policy](https://andon-docs.pages.dev/reference/policy.md)).

## Change a card's recipe

Open the card and pick another in its **Recipe** field, or right-click the card on the board and choose the recipe.
The next run uses it; a run already going keeps its own.

## Set a default recipe

- **For the workspace**: search Settings for **Recipes**, then set **Default recipe** at the top of the page.
  Follow-up cards get it, and a card waiting for a recipe offers it, unless its team has its own default.
- **For one team**: search Settings for **Default recipe** and pick the team. A new card in the team takes it.

## What a recipe changes about a run

### Where the run can go

A recipe can require a connector (an MCP server such as an image generator) or a machine tag. Then only a machine
that has it connected right now takes the card. While none can, the card says why it waits:

- *waiting for <machine> (offline)*
- *<connector> needs authentication on <machine>*: connect it in that machine's Claude Code
- *no machine with <connector>*
- *update the agent on <machine>*
- *waiting for a free slot*: every machine that could take it is at its **Runs at once** limit

After five minutes the reason also shows on the board's andon strip. A machine with **Takes queued work** off only
runs cards someone started by hand.

A machine set up with the default answer (the Open preset) runs any recipe from the org, edited ones included. A
machine on the Standard or Locked preset runs only the recipes approved on it: after an admin edits a recipe, each of
those machines needs it approved again with `andon policy approve <slug>`, or switched to trusting the org with
`andon policy trust-org` ([machine policy](https://andon-docs.pages.dev/reference/policy.md)).

### Pull requests

A recipe that works on a new branch ends in a pull request into the repository's default branch. To send a team's
pull requests to another branch (`staging`, say), open **Settings → Teams**, pick the team, and under **Repository**
set **PRs into** on the repository's row. Each team sets its own.

When the team's repository isn't on GitHub, there is no pull request. The team's **Overrides** section then shows
**Finished work**:

- **Merge into <branch>**: when the run reports the task done, Andon brings the base branch into the card's branch,
  merges the card's branch into the base, and pushes it when the repository has a remote. It never force-pushes. A
  merge conflict goes back to the run, at most twice, then to you as an attention item with **Resolve merge
  conflicts**.
- **Leave it on its branch**: the work stays on the card's branch for you to merge.
- **Automatic** (the default): merge when the repository has no remote, leave the branch when it has one.

Andon's merge here is an auto merge, held back as a pull request's would be: when the card's branch changes a
never-auto-merge path (a migration, the CI config, a lockfile, `.env` files, `.andon/settings.json` or the team's own
additions), or the machine's policy doesn't allow auto merge, the work stays on the branch for you to look at and merge.

A run that reports the task done moves its card to Done only once the work has landed. When Andon leaves the work on
the branch (the team leaves it there, the machine's policy has auto-push or auto merge off, or the branch changes
never-auto-merge paths) or a merge fails, the card stays where
it is, with an attention item naming the branch to merge. Merge it, or push it for review, then move the card to Done. A branch that
has been pushed to a remote for review counts as landed.

Several cards can ship in one pull request as a PR group. A group runs one recipe: Code change and Bug cards can mix
(the group runs Code change), and any other recipe needs every card in the group to share it. Study, Plan a
workstream, Image assets and Generic in a scratch folder never join a group.

### Scratch-folder recipes

Image assets and other non-code recipes work in a folder and never open a pull request. On a team with a repository,
the folder is a worktree on that repository; otherwise it is a folder under the machine's scratch folder. Its outputs
are the files the run made. When the card reaches Done, the folder goes to the Trash. **Continue** can't bring it back:
start the card over instead.

### Pages

A run can hand back a **page**: one self-contained `.html` file, reviewed like any other output (**Approve**, or
**Reject with note** to send it back). The board shows it in a sealed frame: its scripts run, but it can't reach the
board, your session or the network, and links open in a new tab. A page can be at most 5 MB, with its styles, scripts
and images inline; one that loads anything from elsewhere is refused. A page with dark styles follows the board's
theme. Studies hand back their proposal this way.

## See also

- [Writing a recipe](https://andon-docs.pages.dev/guide/writing-a-recipe.md): the editor, the prompt's tags and a worked example.
- [Studies](https://andon-docs.pages.dev/guide/studies.md): the Study recipe from question to project.
- [Previews and annotations](https://andon-docs.pages.dev/guide/previews-and-annotate.md): open a run's app, and annotate it.
