Recipe file reference

Most recipes should be created and maintained in the visual editor. Use a recipe file when the definition must live with a repository, be reviewed as text, or be installed as part of a package.

Locations

Workspace recipes: ~/.cairn/recipes/
Project recipes: .cairn/recipes/

Project recipes travel with the repository. Workspace recipes are available across projects on the same Cairn installation.

Minimal portable recipe

This file represents the walkthrough from the editor. File IDs are readable author-chosen strings; the editor uses generated IDs internally. Positions use x@y, and edges name a node and handle as node@port.

cairnVersion: 1
name: Implement and open PR
description: Implement one issue and open a pull request
trigger: manual
nodes:
  - id: trigger
    type: trigger
    name: Trigger
    position: 60@60
    config:
      triggerType: manual
      scope: issue
  - id: implement
    type: agent
    name: Implement
    position: 60@240
    config:
      agent: build
  - id: pr
    type: pr
    name: PR
    position: 60@430
    config:
      inputSchema:
        name: create-pr
        schema:
          type: object
          properties:
            title: { type: string, description: PR title }
            body: { type: string, description: PR description in Markdown }
          required: [title, body]
edges:
  - { from: trigger@control-out, to: implement@control-in, type: control }
  - { from: trigger@context-out, to: implement@context-in, type: context }
  - { from: implement@control-out, to: pr@control-in, type: control }
  - { from: implement@context-out, to: pr@context-in, type: context }

The agent value is the configured agent's stable name. Control edges determine which step may start. Context edges carry the issue or a typed upstream result. Keep both when a downstream agent or PR needs both ordering and input.

Node types authors use

Type	Use it for
`trigger`	Manual, scheduled, or supported event entry
`agent`	Work performed by a configured agent
`pr`	Opening a pull request from the producing branch
`artifact`	A named, schema-validated agent output; optionally confirmed by a person
`condition`	Choosing one output path from data or a model decision
`checkpoint`	A command gate whose exit status permits or blocks progress
`instruction`	Authored context for downstream work
`action`	A configured custom programmatic action

The editor is the canonical way to discover the controls currently available for each node. This page intentionally does not reproduce the generated schema.

Branch targets

A file may declare branchTargets: [new, base] when launchers need a choice between an isolated change and work on the resolved base branch. new is the default. Under base, PR nodes are removed from the execution, so every PR node must be terminal; validation rejects a recipe that depends on a PR downstream.

Use this only for recipes that genuinely support both operating modes. Branch target selection happens at launch, not in the visual recipe editor.