Convention for generating DOT flowchart diagrams from Amplifier recipe YAML files
SKILL.md
Recipe-to-DOT Convention
Purpose
Recipe YAML files define multi-step AI agent workflows, but they're hard to understand at a glance. DOT flowchart diagrams make recipes visually understandable. This skill documents the standard mapping from recipe YAML structure to DOT visual elements.
Visual Convention Mapping
Recipe Concept
DOT Shape
Fill Color
Style
Start/End nodes
oval
#e0e0e0 (gray)
filled,rounded
Bash step (type: bash)
box
#bbdefb (blue)
filled,rounded
Agent step (type: agent / default)
box
#c8e6c9 (green)
filled,rounded
Sub-recipe call (type: recipe)
box
#e0e0e0 (gray)
filled,rounded,dashed
Approval gate
diamond
#ffe0b2 (orange)
filled
Condition decision
diamond
#fff9c4 (yellow)
filled
Data/Output
note or cylinder
#e1bee7 (purple)
filled
Graph Structure Rules
Graph flows top-to-bottom (rankdir=TB)
Every diagram has Start and Done nodes
Flat mode: steps flow sequentially, conditions get preceding diamonds
Staged mode: each stage is a cluster subgraph
Approval gates between stages when approval.required=true
Foreach/parallel get annotations on edges or node labels
While loops get dashed loop-back edges
Legend at bottom showing only step types actually used
Auto-labeling
Step IDs are converted to readable labels:
Split on hyphens, title-case each word
3+ words split across 2 lines
Sub-recipe steps append "(sub-recipe)"
File Conventions
Recipe DOT files are co-located next to their source YAML file
Naming: same filename, different extension — .yaml → .dot and .png
The recipe_to_dot Python function in amplifier_module_tool_recipes.recipe_to_dot generates DOT deterministically from YAML:
from amplifier_module_tool_recipes.recipe_to_dot import recipe_to_dot, recipe_dot_hash
# Generate DOT string
dot = recipe_to_dot("path/to/recipe.yaml")
# Get hash for freshness checking
hash = recipe_dot_hash("path/to/recipe.yaml")
Freshness
DOT files embed a source_hash graph attribute that tracks the YAML's structural fingerprint.
The validate-recipes recipe (Phase 7) compares this hash against the current YAML to detect
stale diagrams — even when labels have been LLM-enhanced.
LLM Voice Enhancement (Default)
The standard generation pipeline (generate-recipe-docs recipe) includes an LLM pass that
rewrites node labels so a non-technical person can understand them:
"Read Profile" → "Read Your Settings — What repos do we have?"
"Determine Tiers" → "Check For Changes — Look at git history"
"Structural Validation" → "Validate Structure — Are the YAML files well-formed?"
This is the default stance — visual documentation should be accessible to anyone.
The LLM preserves all structural elements (node IDs, edges, shapes, colors) and only
rewrites label text and the graph title.
To generate or regenerate flow diagrams for a repo:
