New Active

Amplifier Recipes

Recipe DOT Docs

Every recipe now tells its own story — visually.
Automated flowchart documentation for the entire recipe ecosystem.

microsoft/amplifier-bundle-recipes #56 #57 #58 April 2026

The Problem

Recipes are invisible.

Amplifier recipes are powerful multi-step workflows — but they live as dense YAML files. As recipes grow in complexity (stages, approval gates, conditionals, parallel branches), understanding what a recipe actually does requires reading every line.

Pain Points

• New engineers can't tell what a recipe does at a glance
• Reviewers read YAML diffs without structural context
• No visual distinction between step types
• Sub-recipe calls are buried in text
• Approval gates and conditionals are invisible

# What does this recipe do?
# How many steps? What order?
# Where are the approval gates?
name: validate-recipes
version: 2.1.0
stages:
  validation:
    steps:
      - name: structural-validation
        agent: recipe-author
        prompt: |
          Validate all YAML files...
      - name: cross-reference-check
        agent: recipe-author
        depends_on:
          - structural-validation
      - name: convention-compliance
      - name: result-review
        agent: result-validator
      # ... 12 more steps
      # ... across 3 stages
      # ... 340 lines of YAML
                

Can you tell what this recipe does? Where the gates are?

The Solution

Every YAML gets a flowchart.

Automatically. Co-located. Always fresh.

foo.yaml

Recipe source

→

recipe_to_dot.py

695 lines, pure Python

→

foo.dot

Graphviz DOT

→

foo.png

Visual diagram

🔬

Deterministic Core

recipe_to_dot.py — pure-Python module, 33 tests. No LLM needed for structure. Color-coded by step type.

🧠

LLM-Enhanced Labels

generate-recipe-docs recipe rewrites labels so non-technical readers can understand each step.

🔄

Auto-Freshness

Embedded source_hash in every DOT file. Validation detects stale diagrams and regenerates them automatically.

Visual Language

Color-coded by step type.

Every node shape and color carries meaning. At a glance, you can see where humans are needed, which steps call sub-recipes, and where the workflow forks.

Blue Rectangles

Bash / script execution steps

Green Rectangles

AI agent steps (LLM-powered)

Gray Dashed

Sub-recipe calls (delegation)

Orange Diamonds

Human approval gates (staged recipes)

Yellow Diamonds

Conditional branches

Cluster Subgraphs

Stages become labeled clusters with dashed borders, so you can see the high-level flow (validation → review → generation) at a glance.

Stage: Validation

Step 1 → Step 2 → ⬥ Gate

Before & After

From YAML wall to instant clarity.

Before: YAML only

name: simple-analysis
steps:
  - name: gather-context
    agent: analyst
    prompt: |
      Analyze the codebase...
  - name: deep-analysis
    agent: analyst
    depends_on:
      - gather-context
  - name: write-report
    agent: reporter
    depends_on:
      - deep-analysis
  - name: generate-scripts
    agent: scripter
    depends_on:
      - deep-analysis
                

→

After: Auto-generated diagram

Simple analysis recipe flowchart showing 4 steps in a clear dependency chain

simple-analysis-recipe.yaml — the simplest case. It only gets more valuable as complexity grows.

The Real Deal

validate-recipes

A 3-stage, 14-step pipeline with validation, review, and auto-generation phases. Try understanding this from YAML alone.

validate-recipes.png — auto-generated with LLM-enhanced labels

Gallery

Every shape of recipe, visualized.

Staged approvals, parallel branches, sub-recipe calls — the system handles them all. 21 recipes now have auto-generated diagrams.

Code Review

Multi-agent review with parallel analysis tracks

Dependency Upgrade (Staged)

Orange diamonds = human approval gates between stages

Generate Recipe Docs

The diagram-generation pipeline, visualized by itself

Intelligent Labels

LLM rewrites labels for humans.

The deterministic core produces structurally correct diagrams with raw step names. The generate-recipe-docs recipe then passes each DOT through an LLM that rewrites every label into plain English.

Before (raw)

structural-validation
cross-reference-check
convention-compliance

After (LLM-enhanced)

Validate Structure — Are the YAML files well-formed?
Cross-Reference Check — Do agents and steps align?
Convention Compliance — Follow naming standards

Opt out with enhance_diagrams: "false"

The doc-generation pipeline itself

Freshness

Diagrams that never go stale.

Every DOT file embeds a source_hash of the YAML it was generated from. Validation catches drift automatically.

📝

Edit YAML

→

⚠️

Hash mismatch
detected

→

🔄

Phase 7/7b
auto-regenerates

→

✅

Diagram fresh
& committed

Phase 7: Check Freshness

Computes SHA-256 of each YAML and compares against the source_hash embedded in the DOT file comment header. Reports stale and missing diagrams.

Phase 7b: Auto-Regenerate

Runs the full pipeline (DOT generation + LLM label enhancement + PNG render) for any stale or missing diagrams. Enabled by default in validate-recipes.

// Embedded in every .dot file:
// source_hash: a3f2c8e1b9d4...  ← SHA-256 of the .yaml
// generated_by: recipe_to_dot v1.0
// enhanced: true  ← LLM-enhanced labels applied
        

Integration

Five pieces, one system.

⚙️

recipe_to_dot.py

695-line deterministic converter. YAML in, DOT out. 33 tests. No LLM dependency.

📋

generate-recipe-docs recipe

LLM-powered label enhancement pipeline. Turns technical step names into human-readable descriptions.

✅

validate-recipes Phase 7 + 7b

Freshness checking and auto-regeneration integrated into the existing validation pipeline.

📖

recipe-to-dot skill

Documents the convention and freshness model so agents and humans follow the same rules.

🤖

Agent Awareness

recipe-author and result-validator agents now know about the diagram convention. They generate and validate diagrams as part of their normal workflow.

Already Paying Off

Visual Diagrams → Immediate Improvement

While reviewing the newly generated diagram for multi-level-python-code-analysis, it was immediately obvious that several steps could run in parallel — something invisible in 700+ lines of raw YAML. The diagram made it obvious. Result: v1.0.0 → v1.1.0 with 3 parallel fork-join pairs, shipped the same day.

Phase 1 — Fork

hypothesis analysis ‖ exploratory analysis

→ differential analysis (join)

Phase 2 — Fork

architectural analysis ‖ exploratory analysis

→ differential analysis (join)

Phase 4 — Terminal Fork

final report ‖ action scripts

Both terminal — run simultaneously

The takeaway: visual docs aren’t just documentation — they’re a design tool. Seeing the flow surfaced optimization opportunities that were invisible in raw YAML.

multi-level-python-code-analysis flowchart showing 15 steps with 3 parallel fork-join pairs

15 steps, 3 fork-join pairs — spotted in the diagram, invisible in YAML

Velocity

By the numbers.

695

Lines of Python

recipe_to_dot.py

33

Tests

Deterministic converter

21

Recipes Documented

DOT + PNG shipped

3

PRs Merged

#56, #57, #58

PR #56

Core recipe_to_dot.py module, tests, initial DOT generation for all recipes

PR #57

LLM-enhanced label pipeline, generate-recipe-docs recipe, validation integration (Phase 7/7b)

PR #58

Parallelized multi-level-python-code-analysis with depends_on across 15 steps

Repository: microsoft/amplifier-bundle-recipes

Sources & Methodology

How we know what we know.

Data Sources

PR #56, #57, #58 on microsoft/amplifier-bundle-recipes
Line count from recipe_to_dot.py source (695 lines)
Test count from test suite (33 tests)
Recipe count from shipped DOT+PNG pairs in repository (21 files)
Step count in multi-level-python-code-analysis.yaml (15 steps with depends_on)
Version bump recorded in recipe YAML header (v1.0.0 → v1.1.0)

What's Not Claimed

No runtime performance benchmarks — parallelization benefit depends on executor implementation
No user adoption metrics yet — this is a new feature, not a measured improvement
LLM label quality is subjective — examples shown are representative, not guaranteed

Feature Status

Recipe DOT Docs system: Active — integrated into validate-recipes, shipping with all recipes
LLM-enhanced labels: Active — enabled by default, opt-out with enhance_diagrams: "false"
Parallelized code analysis: Active — v1.1.0 shipped

Data as of: April 2026 | All metrics from direct repository inspection

Get Started

Your recipes
deserve diagrams.

Every new recipe gets a flowchart automatically.
Every existing recipe already has one.

Create a recipe

Write your YAML as usual. The recipe-author agent generates the diagram automatically.

Validate

Run validate-recipes. Phase 7 checks freshness. Phase 7b regenerates stale diagrams.

Review visually

Open the PNG next to any recipe. See the flow, the gates, the branches — instantly.

microsoft/amplifier-bundle-recipes

Recipe DOT Docs

Recipes are invisible.

Pain Points

Every YAML gets a flowchart.

Deterministic Core

LLM-Enhanced Labels

Auto-Freshness

Color-coded by step type.

Cluster Subgraphs

From YAML wall to instant clarity.

validate-recipes

Every shape of recipe, visualized.

LLM rewrites labels for humans.

Before (raw)

After (LLM-enhanced)

Diagrams that never go stale.

Phase 7: Check Freshness

Phase 7b: Auto-Regenerate

Five pieces, one system.

recipe_to_dot.py

generate-recipe-docs recipe

validate-recipes Phase 7 + 7b

recipe-to-dot skill

Agent Awareness

Visual Diagrams → Immediate Improvement

By the numbers.

PR #56

PR #57

PR #58

How we know what we know.

Data Sources

What's Not Claimed

Feature Status

Your recipesdeserve diagrams.

Create a recipe

Validate

Review visually

Your recipes
deserve diagrams.