Recipe Schema Reference

Complete reference for recipe YAML structure, fields, validation rules, and error handling.

Recipe Structure

Top-Level Fields

Step Types

Agent Step

Spawns an AI sub-agent (default type).

Bash Step

Executes shell command (no LLM overhead).

Recipe Step

Invokes sub-recipe (composition).

Common Fields (All Step Types)

Retry Configuration

retry:
  max_attempts: 5            # Total attempts (default: 1)
  backoff: "exponential"     # exponential, linear, or constant
  initial_delay: 5           # Seconds before first retry
  max_delay: 300             # Max seconds between retries

Backoff Strategies

• exponential: 5s → 10s → 20s → 40s (doubles each time)
• linear: 5s → 10s → 15s → 20s (adds initial_delay)
• constant: 5s → 5s → 5s (same delay)

Foreach Loops

- id: "process-all-files"
  foreach: "{{`{files}`}}"       # Array to iterate over
  foreach_var: "file"        # Variable name in sub-steps
  max_concurrent: 3          # Parallel execution limit
  steps:                     # Sub-steps (run for each item)
    - id: "process"
      prompt: "Process {{`{file}`}}"
      output: "result"
  output: "all_results"      # Array of results

Error Handling

Validation Rules

Before execution, recipes are validated for:

• Structure - Required fields present, types correct
• Variable references - All {{`{variables}`}} defined or will be defined
• Agent availability - Referenced agents exist in bundle
• Step dependencies - No undefined variable access
• Recursion limits - Max depth: 5, max total steps: 100
• Foreach validity - Foreach target is array, sub-steps valid

Session Persistence

Session Directory

~/.amplifier/projects/<project>/recipe-sessions/
  recipe_20260116_143022_a3f2/
    state.json        # Current state and outputs
    recipe.yaml       # Recipe being executed
    events.jsonl      # Execution event log

State Structure

{
  "session_id": "recipe_20260116_143022_a3f2",
  "recipe_name": "code-review-flow",
  "current_step_index": 2,
  "context": {
    "file_path": "src/auth.py",
    "issues": "...",
    "improvements": "..."
  },
  "completed_steps": ["analyze", "suggest-improvements"]
}

Resumption

# Resume from checkpoint
amplifier run "resume recipe session recipe_20260116_143022_a3f2"

# Resumes from step 3 (last checkpoint was after step 2)

Limits and Constraints

Variable Syntax

Template Variables

Access context in prompts/commands:

context:
  file_path: "src/auth.py"
  severity: "high"

steps:
  - prompt: "Scan {{`{file_path}`}} for {{`{severity}`}} issues"
    # Expands to: "Scan src/auth.py for high issues"

Nested Access

# Access object properties
{{`{result.stdout}`}}
{{`{validation.score}`}}
{{`{step.index}`}}

# Access array elements
{{`{files[0]}`}}
{{`{results[2].output}`}}

Built-in Variables

Condition Expressions

Python expressions evaluated before step execution:

Comparison Operators

# Equality
condition: "{{`{status}`}} == 'success'"
condition: "{{`{code}`}} != 0"

# Comparison
condition: "{{`{score}`}} > 80"
condition: "{{`{count}`}} <= 10"

# Logical
condition: "{{`{enabled}`}} and {{`{ready}`}}"
condition: "{{`{failed}`}} or {{`{skipped}`}}"
condition: "not {{`{disabled}`}}"

# Complex
condition: "({{`{score}`}} > 50) and ({{`{status}`}} == 'pass')"

Type Checking

# Check if defined
condition: "{{`{optional_var}`}} is not None"

# Check type
condition: "isinstance({{`{data}`}}, list)"

# String operations
condition: "'error' in {{`{message}`}}"
condition: "{{`{file}`}}.endswith('.py')"

Advanced Features

Agent Config Override

- id: "special-step"
  agent: "foundation:zen-architect"
  agent_config:
    providers:
      - module: "provider-anthropic"
        config:
          model: "claude-opus-4"
          temperature: 0.8
    tools:
      - tool-filesystem
      - tool-bash
  prompt: "..."

Recursion Limits Override

- id: "call-sub-recipe"
  type: "recipe"
  recipe: "complex-workflow.yaml"
  recursion_config:
    max_depth: 10        # Allow deeper nesting
    max_total_steps: 200 # Allow more steps

Troubleshooting

Common Errors

Complete Example

Real-world recipe showing all major features:

name: "comprehensive-workflow"
description: "Demonstrates all recipe features"
version: "1.0.0"
author: "Amplifier Team"
tags: ["example", "comprehensive"]

context:
  target_file: "src/main.py"
  severity_threshold: 5

steps:
  # Step 1: Check preconditions (bash)
  - id: "verify-file-exists"
    type: "bash"
    command: "test -f {{`{target_file}`}}"
    output_exit_code: "file_exists"
    on_error: "continue"

  # Step 2: Conditional abort
  - id: "abort-if-missing"
    condition: "{{`{file_exists}`}} != '0'"
    agent: "foundation:zen-architect"
    prompt: "File {{`{target_file}`}} not found. Recipe cannot continue."
    on_error: "skip_remaining"

  # Step 3: Analysis with retry
  - id: "analyze-code"
    agent: "foundation:bug-hunter"
    prompt: "Analyze {{`{target_file}`}} for bugs and security issues"
    output: "analysis"
    timeout: 600
    retry:
      max_attempts: 3
      backoff: "exponential"

  # Step 4: Approval gate
  - id: "review-gate"
    requires_approval: true
    approval_prompt: |
      Analysis complete: {{`{analysis}`}}

      Proceed with automated fixes?
    on_approval_denied: "skip_remaining"

  # Step 5: Apply fixes (only if approved)
  - id: "apply-fixes"
    agent: "foundation:modular-builder"
    agent_config:
      providers:
        - module: "provider-anthropic"
          config:
            model: "claude-opus-4"
    prompt: "Apply fixes for issues in {{`{analysis}`}}"
    output: "fixes_applied"

  # Step 6: Verify
  - id: "run-tests"
    type: "bash"
    command: "pytest tests/ -v"
    output: "test_results"
    on_error: "continue"  # Optional verification

  # Step 7: Generate report
  - id: "create-report"
    agent: "foundation:modular-builder"
    prompt: |
      Generate final report:

      File: {{`{target_file}`}}
      Analysis: {{`{analysis}`}}
      Fixes: {{`{fixes_applied}`}}
      Tests: {{`{test_results}`}}
    output: "final_report"

Official Documentation

• Complete Schema Reference (2337 lines)
• Best Practices Guide
• Troubleshooting Guide