# Writing a recipe

Write a recipe when a kind of job keeps coming back and the built-ins don't fit it: a video rendered with one tool, a
release checklist, a migration your repository does the same way every time. A recipe is a prompt template plus the
settings for where the run works and what it hands back. Owners and admins edit recipes. For what the built-ins do and
how a card gets its recipe, see [Recipes](https://andon-docs.pages.dev/guide/recipes.md).

## Make a recipe

1. Search Settings for **Recipes**. The page is off Settings' menu.
2. Press **New recipe**, give it a **Name**, and press **Create recipe**. Or open a built-in to change it.
3. Fill in the editor's sections, below. **Preview** beside the prompt shows it filled in for an example card.
4. Press **Save recipe**.
5. A machine on the default Open preset runs it at once. A machine on Standard or Locked runs a new or edited recipe
   only after `andon policy approve <slug>` there ([machine policy](https://andon-docs.pages.dev/reference/policy.md)). In the desktop app,
   **Approve** on Settings → Machines does this for the computer it runs on.

Editing a built-in has the same cost on Standard and Locked machines: each must approve it again.

## The editor

### Name and icon

The **icon**, **Name** and **Description** at the top of the editor: what people see when they pick a recipe for a
card.

### Prompt

**Prompt template** is what the run is told. Write it as you would brief a person: the job, how to check it, what to
hand back. The [tags](#template-tags) below fill in the card. If the template holds literal `\n` characters (pasted
from JSON, say), the editor warns you, and **Make them line breaks** fixes them.

### How it runs

| Setting | Choices |
|---|---|
| **Workspace** | **New worktree**: a new branch of the team's repository, ending in a pull request. **A workspace you pick**: an existing branch or folder. **Scratch workspace**: a folder for work that isn't code, with no pull request. **New repository**. **Card's workspace**: the workspace the card already has, or a new worktree when it has none. |
| **Mode** | **Interactive (you can chat)**: a session you can watch and reply to. **Background**: runs to the end on its own. |
| **Permissions** | The most the agent may do without asking, from **Plan only** to **Auto (classifier decides)**. Each machine's policy can lower it. |
| **Required connectors** | MCP servers, tools or machine tags a machine must have, such as `effectcraft` or `gpu`. Only a machine with all of them connected takes the card. |
| **Output files** | Globs for the files the run produces, such as `renders/**/*.mp4`. They show on the card and are reviewed when review is on. |

### When it finishes

| Switch | What it does |
|---|---|
| **Review outputs** | A person approves or rejects the output files. |
| **Done on approve** | Approving the outputs moves the card to Done. |
| **Revise on reject** | Rejecting sends your reason back to the same session to try again. |
| **Done on merge** | When the run's pull request merges, the card moves to Done. |
| **Done on report** | When the agent reports the task done and nothing is pending, the card moves to Done, with 10 minutes to undo. |

### Card inputs

Fields a card fills in when it uses this recipe, such as an aspect ratio or a target environment. Each has a **Key**,
**Label**, **Type**, a **Default** and **Required**. The prompt reads one as `{{inputs.<key>}}`. **Add input** adds
one; **Edit as JSON** edits them all as JSON. On the card, a recipe's inputs come first on the **Fields** tab.

### Advanced

- **Allowed tools**: for background runs, the tools allowed without asking, such as `Read Bash(git:*)`. A machine's
  policy caps them.
- **System prompt addition**: text added to the agent's system prompt rather than the task.

## Template tags

A tag is replaced by the card's value when the run starts. Unknown tags become empty text; nothing is evaluated.

| Tag | Places |
|---|---|
| `{{title}}` | the card's title |
| `{{notes}}` | the card's notes. For a PR group's run, every card's title, notes, links, sub-tasks and files, in order |
| `{{workspace}}` | the path the run works in |
| `{{inputs.<key>}}` | one of the recipe's card inputs |
| `{{links}}` | the card's linked issues and pull requests |
| `{{attachments}}` | the card's files, with their paths in the run's `context/` folder; short text files inline |
| `{{fields}}` | every [custom field](https://andon-docs.pages.dev/guide/fields.md) with a value |
| `{{fields.<key>}}` | one custom field's value |
| `{{comments}}` | the latest 20 [comments](https://andon-docs.pages.dev/guide/comments.md), oldest first, with authors and replies |
| `{{card_context}}` | the card's parent, its [sub-tasks](https://andon-docs.pages.dev/guide/subtasks-and-relations.md) and the cards blocking it |
| `{{memory}}` | the repository's memory entries that match the card ([Memory](https://andon-docs.pages.dev/guide/memory.md)) |
| `{{knowledge}}` | the project's plan, the PR group's plan, and the matching knowledge notes |
| `{{upstream}}` | for a workstream step, what the earlier steps did |
| `{{review}}` | for the Code review recipe, the pull request under review |

Everything a tag places from the card is marked as data, not instructions, so text in a card can't take over the run.

**A template without some tags still gets them.** `{{links}}`, `{{attachments}}`, `{{memory}}`, `{{knowledge}}` and
`{{upstream}}` are added after the prompt, and `{{review}}` before it, when the template doesn't place them. Leave
them out only if the end of the prompt is the right place.

**Others reach the run only through their tag.** `{{fields}}`, `{{comments}}` and `{{card_context}}` are never added
on their own: a recipe that doesn't name them never sends them. The built-ins don't carry `{{comments}}`; add it to a
recipe whose runs should read what people said on the card.

### Memory and knowledge

Put `{{memory}}` and `{{knowledge}}` where you want the run to read them: before the task for a code change (the
conventions first, then the work), after `{{review}}` for a review (the diff first, then what the repository says
about it). The run gets one line per entry or note and reads the full text from files beside the prompt, within the
team's memory size.

`{{memory kinds="gotcha,how-to"}}` places only those kinds: `convention`, `decision`, `gotcha`, `how-to`,
`glossary`. You can place different kinds in different spots with several tags.

To have runs record what the next run should know, end the prompt with a line asking for it, as the built-in code
recipes do: the run proposes entries with the `remember` tool and edits notes with `knowledge`, at most five entries a
run. See [Memory](https://andon-docs.pages.dev/guide/memory.md#how-runs-learn-on-their-own).

### Review on the preview

To let people mark up a run's work, say so in the prompt, as the built-in New app and Image assets recipes do: the
person may annotate a frame of the preview (share a web app with the `preview` tool, a native app with
`preview_screen`) or the images, and the notes come back as the run's next message. See
[Previews and annotations](https://andon-docs.pages.dev/guide/previews-and-annotate.md).

## A recipe that needs a tool on one machine

For a job that needs a tool only some machines have (an image generator, a video renderer, a design tool), connect
the tool as an MCP server in that machine's Claude Code, then:

1. Under **Required connectors**, add the connector's name. Only machines where it is connected take the card; the
   others never claim it, and the card says why it waits.
2. In the prompt, tell the agent how to use the tool: render commands, file layout, known traps. Keep that in the
   recipe; the agent itself stays generic.
3. Set **Output files** so the deliverables are collected, and turn on **Review outputs** to approve them.
4. For background runs, add `mcp__<connector>__*` to **Allowed tools**, and ask the machine's owner to allow it in the
   machine's policy: `andon policy tools "<list>"`.

Each machine lists the connectors it has under **Settings → Machines**, with the reason when one isn't available.

### Example: a motion-graphics video

A recipe for a machine whose Claude Code has an `effectcraft` MCP server connected:

- **Name** `Video (EffectCraft)`
- **Workspace** Scratch workspace · **Mode** Background · **Required connectors** `effectcraft` (and `gpu`, if you
  tag a machine that way)
- **Output files** `renders/**/*.mp4`, `renders/**/*.mov`, `renders/**/*.webm`, `renders/**/*.png` · **Review
  outputs** on
- **Card inputs**, as JSON:

  ```json
  [{"key":"aspect","label":"Aspect","type":"select","options":["16:9","9:16","1:1"],"default":"16:9","required":true},
   {"key":"duration_s","label":"Duration (s)","type":"number","default":10,"required":true},
   {"key":"style","label":"Style","type":"text"},
   {"key":"source_media","label":"Source media (paths on the machine)","type":"text"}]
  ```

- **Prompt template**:

  ```
  You are producing a motion-graphics video with EffectCraft via its MCP tools.
  Brief: {{title}}
  {{notes}}
  Format: {{inputs.aspect}} · {{inputs.duration_s}}s · style: {{inputs.style}}
  Source media: {{inputs.source_media}}

  Work in small steps: make one edit, render a verification frame (render_frame), check it, then continue.
  Import media with paths RELATIVE to this workspace (copy source media in first). Save the project to
  ./project.ecproj.

  The MCP server has no full-render tool. When the project is ready, render with the CLI:
  1. effectcraft-cli exec footage.check --project project.ecproj --params '{"wait":true}' --save --json
     If "missing" is not 0, stop and say which media is missing: an absolute or broken media path renders
     black frames and still exits 0.
  2. effectcraft-cli render --project project.ecproj --comp <your comp> --out renders/final.mp4 --format h264 --json
     Add --gpu only for heavy comps (it costs ~28 s of start-up).
  When done, call andon.publish_output for each deliverable with a short label.
  {{attachments}}
  {{links}}
  ```

On that machine, start the MCP server with `--automation-read-root <dir> --automation-write-root <dir>` so it touches
only files under those folders, and never expose its live-control (`--bridge`) port beyond localhost.
