Every Recipe, Now Legible

auto-generated flowcharts for dense recipe YAML

The Problem

Powerful recipes arrive as YAML too dense to read at a glance

Amplifier recipes are real multi-step agent workflows — but they ship as dense YAML. You cannot see the steps, approval gates, or branches without reading every line.

So how bad is it? Look at one recipe.

Proof

2205 lines of YAML collapse to a 62-line flowchart

recipe-to-dot renders the validate-recipes recipe into a compact 62-line DOT flowchart — and it converts all 21 bundled recipes (19 examples + 2 core) to valid DOT deterministically, same input, same output.

Where did this capability come from?

What Shipped

The whole system landed in a single commit — PR #56

Brian Krabach's recipe-to-dot documentation-generation system merged to microsoft/amplifier-bundle-recipes on 2026-03-31: one feature PR, +2840 / -1 lines across 48 files. It was co-authored with Amplifier itself.

At its core sits one small, trustworthy converter.

Mechanism · Deterministic Core

One 700-line pure-Python converter, zero LLM calls

recipe_to_dot.py renders YAML to DOT with no model in the loop — its only imports are hashlib, re, pathlib, and yaml. That is why the flowcharts are trustworthy structure, not a model's guess.

And that structure is color-coded to read instantly.

Mechanism · Color Code

A documented color code makes structure legible at a glance

Every node type gets a consistent shape and color, so you read a recipe's shape without reading its YAML.

Then an optional pass makes the labels human, too.

Mechanism · Accessible Labels

An optional LLM pass rewrites only the labels — never the structure

The enhance step turns terse labels into accessible plain language while preserving everything that defines the diagram — so it stays faithful to the recipe.

And because structure is preserved, the diagram can prove when it's stale.

The Turn · Always Fresh

The flowchart can't go stale — it regenerates itself

Each DOT embeds a SHA-256 source_hash of its structural body. validate-recipes Phase 7 compares the embedded hash against a fresh one and auto-regenerates any stale or missing DOT+PNG — with LLM-enhanced labels by default.

That is what turns a diagram into a living design tool.

  1. 1Embedsource_hash = SHA-256 of the structural DOT body
  2. 2ComparePhase 7 checks embedded vs freshly-computed hash
  3. 3Regeneratestale/missing → rebuilt by default; enhance_diagrams:"false" opts out of the LLM pass
Payoff

Recipe structure is legible by construction — and already in use

A 2205-line recipe now reads as a ~60-line color-coded flowchart that lives beside the YAML and stays fresh automatically. The diagram becomes a design tool, not just documentation — and the dot-docs bundle already ships machine-generated recipe flow diagrams built this way.

Shipped, merged, and consumed downstream.

Sources

Sources & Research Methodology

Feature status: Shipped & merged — in active use downstream

Data as of: HEAD b6ee26d (2026-05-20), microsoft/amplifier-bundle-recipes

Primary source: microsoft/amplifier-bundle-recipes (recipe-to-dot module, generate-recipe-docs recipe, recipe-to-dot skill, validate-recipes Phase 7). Independently re-derived from fresh clones at /tmp/recipes-clone and /tmp/dot-docs-clone.

Research performed:

Primary contributor: Brian Krabach (bkrabach) — author of PRs #56, #57, #58 and all core commits; follow-up AMPLIFIER_PYTHON fix by Salil Das (PR #60). Co-authored-by trailer: Amplifier.

Gaps: The full 33-test pytest suite could not be run locally (package __init__ imports amplifier_core, not vendored); determinism and valid-DOT output were verified by loading recipe_to_dot.py directly. Commit message phrasing "21 example + 2 core" is imprecise — ground-truth examples/*.yaml = 19, so the accurate decomposition is 19 examples + 2 core = 21 recipes. PNG byte sizes were read from git --stat, not re-rendered.

More Amplifier Stories