Compilation rules between IDD decompositions and Amplifier recipe YAML. Template expressions, foreach, while/break_when, parallel execution, approval gates, bidirectional compilation. Use when compiling decompositions to recipes or understanding the mapping.
This document specifies how IDD (Intent-Driven Design) markdown compiles to Amplifier recipe YAML and how YAML decompiles back to IDD markdown. These rules form the deterministic bridge between the human-readable design layer and the machine-executable workflow layer.
IDD markdown is the human-readable design layer -- the Grammar in document form. It uses natural language with structured conventions. It is NOT freeform prose. It is a constrained natural language format that maps deterministically to YAML. Think of it as the "source code" that compiles to recipes.
An IDD markdown document contains one section per primitive, expressed in natural language but structured enough to parse unambiguously. Each section heading corresponds to a Grammar primitive (Intent, Agents, Context, Behaviors, Triggers), and the content within each section follows conventions that the compiler can translate without guessing.
## Intent
Reduce employee onboarding drop-off from 40% to under 20%.
Success criteria: drop-off below 20%, completion time under 15 minutes, AA accessibility.
Scope: sign-up flow, first-day checklist, welcome sequence.
Out of scope: admin dashboard, payroll integration.
Values: accessibility over aesthetics, simplicity over features.
## Agents
- UX Designer: creates wireframes and prototypes
- UX Researcher: conducts usability studies and heuristic analysis
- Frontend Engineer: implements the designs
- QA Tester: validates against success criteria
## Context
- Current onboarding flow and drop-off metrics
- Design system component library
- Accessibility guidelines (WCAG 2.1)
## Behaviors
- Mobile-first design approach
- Present three options before committing
- TDD for all implementation work
## Triggers
- Activation: user requests onboarding redesign
- Confirmation: human approval required before implementation begins
- Sequence: design and research in parallel; implementation after design approval; QA after implementation
Every keyword in this document has a defined compilation target. The next section enumerates those mappings.
The following table defines the exhaustive set of mappings from IDD markdown elements to recipe YAML fields. These rules are applied top-down during compilation and reversed during decompilation.
| IDD Element | YAML Field | Compilation Rule |
|---|---|---|
| Intent goal statement | intent: top-level key | Direct map -- the goal sentence becomes the recipe intent string |
| Success criteria list | success_criteria: list | Each criterion becomes a YAML list item |
| Scope items | scope: list | Each scope item becomes a list entry |
| Out of scope items | constraints: list | Negative-scope items become constraint entries |
| Values ranking | values: list | Each "X over Y" pair becomes a values entry |
| Agent definition | steps[].agent: | Agent name maps to an agent reference path |
| Agent responsibility | steps[].instruction: | The role description becomes the step instruction |
| Context items | context: list | Each context source becomes a context entry |
| Behavior rules | behaviors: list | Each behavior becomes a behavioral constraint |
| "in parallel" / "and" / "simultaneously" | No depends_on | Steps without ordering keywords receive no depends_on field |
| "after X" / "once X completes" | depends_on: [X] | Dependency keywords generate depends_on references |
| "reviews against criteria" | while: / break_when: | Review-loop phrasing compiles to a convergence loop |
| "for each" / "iterate over" | foreach: | Collection iteration compiles to a foreach block |
| Confirmation: "human" | approval: required | Human confirmation triggers an approval gate on the stage |
| Confirmation: "auto" | (no gate) | Step executes without pause |
| Activation trigger | trigger: top-level key | The activation condition becomes the recipe trigger |
These rules are intentionally unambiguous. If an IDD markdown element does not match any row in this table, compilation fails with a diagnostic error rather than guessing.
The following demonstrates a complete compilation from the onboarding redesign IDD markdown to its equivalent recipe YAML.
## Intent
Reduce onboarding drop-off to under 20%.
Success criteria: drop-off below 20%, completion under 15 min, AA accessibility.
## Agents
- UX Designer: creates wireframes and prototypes
- UX Researcher: conducts usability studies
- Frontend Engineer: implements designs
- QA Tester: validates against criteria
## Sequence
Design and research run in parallel.
Implementation begins after design review approval.
QA reviews implementation against success criteria.
Iterate until all criteria pass.