Build a Generative Recipe DSL

When many similar artifacts must be generated — icons, badges, diagram nodes, test fixtures — having each generator write bespoke code does not scale: N code paths to review, no uniform validation, no cheap re-render. A recipe DSL inverts this: generator agents emit small JSON documents (recipes), and ONE interpreter renders them all. The interpreter is the single audited code path; the recipes are pure data, gated by a validator before any item counts as done. The pattern is proven at corpus scale: in the originating trading-card glyph project, over a thousand agent-generated recipes render through one ~120-line interpreter in two completely different styles.

This skill is the complement of create-glyph: create-glyph hand-authors ONE glyph as R code with individual craft; generative-recipe-dsl builds the machinery for MANY agent-generated artifacts as data under one interpreter. Reach for create-glyph when a single artifact deserves bespoke attention; reach for this skill when a corpus is coming.

When to Use

• A family of roughly 15 or more similar artifacts must be produced: icons for a skill domain, status badges for a service fleet, node pictograms for a diagram set, fixtures for a test matrix
• Generator agents author the artifacts — small JSON documents can be machine-validated at corpus scale; N bespoke code files cannot be reviewed at corpus scale
• The corpus must render in more than one style (print + screen, mono + color, light + dark), or a future restyle is plausible
• Per-item bespoke code is already multiplying unreviewed code paths for artifacts that share one visual or structural grammar
• Do NOT use for one-off or heterogeneous artifacts whose logic is genuinely unique — hand-author those (for icons, use create-glyph)

Inputs

• Required: Artifact family and expected corpus size (what is being generated, how many now, how many later)
• Required: At least two target render styles (e.g. mono engraving for print + flat color for screen) — two styles are what prove the role slots
• Required: Host toolchain for interpreter and validator (e.g. R/ggplot2, Python/SVG, JavaScript/Canvas)
• Optional: Existing bespoke implementations to mine for the primitive vocabulary
• Optional: Batch driver for wave generation — the companion workflow batch-generate-waves

Procedure

Step 1: Decide — Recipe DSL or Bespoke Code

The DSL pays for itself only above a threshold number of artifacts. Decide explicitly before building anything.

1. Count the artifacts: how many exist today, how many are expected over the corpus lifetime.

2. Apply the threshold:

   Artifact count	Recommendation
   1–3	Bespoke code. A DSL costs more than it saves.
   ~4–15	Gray zone. DSL if the artifacts share one shape grammar and more are expected; bespoke if each needs unique logic.
   15+	Recipe DSL. Reviewing N code paths costs more than one ~120-line interpreter; validation and re-render become uniform.

3. Check the override signals that favor a DSL regardless of count:

   • The generators are agents — emitted data can be gated mechanically; emitted code cannot
   • More than one render style is needed now, or a restyle is plausible later
   • The whole corpus must stay cheaply re-renderable (style tweaks touch one file, not N)
   • Shared conventions must hold corpus-wide (see Step 6)

4. Check the counter-signals: each item genuinely needs unique logic, there is no common primitive vocabulary, or the corpus will never grow. If these dominate, stop here and write bespoke code.

Expected: A written go/no-go decision naming the artifact count, the styles, and which signals tipped it.

On failure: If the decision is unclear, prototype 2–3 artifacts both ways. If the bespoke versions share most of their structure and differ only in data-like parameters, the DSL is viable — that shared structure IS the interpreter.

Step 2: Design the Recipe Schema

A recipe is data, not code: a small JSON document an agent can emit in one shot and a validator can check mechanically. The proven shape is primitives × roles × modifier flags.

1. Enumerate the shape primitives from your prototypes. Keep the set small — the reference implementation shipped with 7 (polygon, ngon, circle, star, arc, zigzag, rect), grew to 8 only when spiral was added centrally after launch, and covered a corpus of over a thousand recipes.
2. Fix a local coordinate frame with a soft convention and a hard limit the validator enforces (reference: content within ±36 units, hard limit ±45, +y is up).
3. Add cheap-leverage modifiers. The highest-value one is bilateral symmetry: a top-level "symmetry": "bilateral" flag duplicates every layer marked "mirror": true x-negated — half of a symmetric artifact's points come for free.
4. Include a free-text _intent field the interpreter ignores: one line stating what the recipe depicts, for human audits and reviewer diffs.

{
  "_intent": "one-line human note: what this artifact depicts",
  "symmetry": "bilateral",
  "layers": [
    {"shape": "rect", "x0": -30, "y0": -20, "x1": 30, "y1": 20, "role": "ground"},
    {"shape": "circle", "cx": 22, "cy": 13, "r": 4, "role": "spark"},
    {"shape": "arc", "cx": 0, "cy": 0, "r": 31, "from": 42, "to": 78, "role": "line", "mirror": true}
  ]
}

Expected: A schema document (one page, kept next to the recipes) listing every primitive with its parameters, the coordinate frame, the modifiers, and the roles from Step 3.

On failure: If prototypes keep demanding new primitives, the family may be too heterogeneous for one DSL — split into two schemas, or return to Step 1. If one primitive is repeatedly requested by generators (the reference implementation added spiral this way), add it centrally through code review, never per-item.

Step 3: Design Roles as Style Slots

Roles are the load-bearing design decision. A role names the layer's FUNCTION in the composition — never its appearance. Each output style then maps every role to concrete aesthetics, so one recipe renders in every style unchanged. The reference implementation renders the same JSON as a mono engraving (ink, paper, hatching) and as flat 8-bit color from exactly this indirection.

1. Define roles by compositional function. The proven six-slot vocabulary:

   Role	Function in the composition	Mono engraving style	Color style
   ground	large backdrop mass	paper fill + ink outline + 45° hatch	base fill + frame outline
   mass	primary solid body	solid ink	body fill + frame outline
   accent	secondary textured region	paper fill + ink outline + 135° hatch	highlight fill + frame outline
   spark	small highlight marks	solid ink	signal fill, no outline
   detail	cutout on a solid (eyes, keyholes)	solid paper	signal fill, no outline
   line	stroked path, no fill	soft ink path	highlight path

   How a style separates two roles is the style's choice, not the schema's: the mono column shows the reference mapping (accent hatches at 135° vs ground's 45°), while the worked badge example in references/EXAMPLES.md separates accent from ground by tighter hatch spacing at the same angle. Both are valid slot mappings — the distinction lives in the style, never in a recipe.

2. Apply the litmus test: propose a hypothetical third style (say, blueprint linework). If every role maps cleanly to new aesthetics without touching any recipe, the slots are functional. If a role only makes sense in one style, it is an appearance name in disguise — rename it by function.

3. Encode substrate interactions as conventions, not new roles: e.g. spark marks read on hatched/ground bodies; detail cutouts read on solid mass bodies. Pick the mark's role for the body under it.

Expected: A role table mapping each role to concrete aesthetics in EVERY target style; the third-style litmus test passes on paper.

On failure: If two roles map identically in all styles, merge them. If a needed look has no role, first try composing existing roles (outline + hatch = two layers) before adding a seventh slot.

Step 4: Write the Interpreter — One Audited Code Path

The interpreter compiles a recipe into render layers. It is the ONLY code that turns recipes into artifacts — audit it once, and every generated item inherits the audit.

1. Structure it as three small functions plus a loader (the verified reference is ~120 lines total):

# geometry: layer spec -> points; unknown shape is a HARD error, never skipped
badge_layer_geometry <- function(layer) {
  if (layer$shape == "circle") return(poly_regular(layer$cx, layer$cy, layer$r, 48))
  # ... one branch per primitive ...
  stop("dsl: unknown shape '", layer$shape, "'", call. = FALSE)
}

# style slots: (geometry, role, style) -> drawable layers; unknown role is a HARD error
badge_role_layers <- function(geometry, layer, style) { ... }

# compile: recipe -> function(cx, cy, s, style), applying symmetry + placement
badge_from_spec <- function(recipe) { ... }

2. Enforce vocabulary hard: unknown shape or role must stop(), never fall through to a default — silent fallbacks let malformed recipes pass the gate.
3. Keep it deterministic: no RNG, no time dependence. The same recipe must render byte-identically on every run, or corpus-wide re-renders produce untrackable diffs.
4. Freeze the contract: generator agents may never edit the interpreter. Primitive additions go through normal code review as central changes.

See references/EXAMPLES.md for a complete, empirically verified ~170-line interpreter in a non-icon domain (service status badges).

Expected: The interpreter compiles hand-written test recipes into layers in every style; a recipe with an unknown shape or role raises a hard error.

On failure: If the interpreter is growing past ~250 lines, per-item logic is leaking in — push variation back into recipe data or drop a primitive. If styles disagree on layer counts, a role branch is emitting different structure per style; roles must vary aesthetics only.

Step 5: Write the Validator Gate

The validator is what makes agent-authored data trustworthy: no recipe counts as done until it passes. It must end in a REAL render — compile-only checks pass recipes that crash the renderer.

1. Implement the checks in order, per recipe × per style:
   1. Parses — strict JSON, no recovery
   2. Structural floor — e.g. at least 2 layers
   3. Compiles — the interpreter accepts every layer (this catches unknown shapes/roles)
   4. Bounds — all geometry within the hard coordinate limit
   5. Real render — write an actual output file in EVERY style; assert plausible file size
2. Exit nonzero on any failure and print one PASS/FAIL line per recipe — the gate must be usable by agents and CI alike.
3. Add a --fast mode that runs checks 1–4 and skips the render. Rendering is the slow O(N) step: in the reference implementation --fast sweeps a ~1,200-recipe corpus in ~100 seconds where per-item rendering would time out.
4. Fix the usage pattern: full mode gates every new batch; --fast is for corpus-wide sweeps (completion checks, CI on the whole tree) — never the only gate a new recipe sees.

Rscript validate_badges.R message-queue auth-gateway   # named recipes, full gate
Rscript validate_badges.R                              # all recipes, full gate
Rscript validate_badges.R --fast                       # whole corpus: compile + bounds only

Expected: Valid recipes print PASS in both modes; a deliberately broken recipe (unknown role, out-of-bounds point) prints FAIL and the process exits 1.

On failure: If the full gate is too slow even per-batch, render to a throwaway raster at reduced size — but keep a real render. If the validator and interpreter disagree (validator passes what the renderer rejects), the validator is re-implementing rules instead of calling the interpreter; make it call the same compile path.

Step 6: Hand-Author Seed Recipes and Name the Conventions

Seed recipes are the corpus's style anchor. Once the interpreter plus a few seeds exist, conventions hold across hundreds of generated items without per-item steering — the DSL constrains agents into consistency.

1. Hand-author 3–8 seed recipes that together exercise every primitive and every role, and pass the full gate.
2. Start a conventions document next to the recipes. Conventions observed to emerge and hold corpus-wide in the reference implementation:
   • Family motifs: related items share ONE motif elaborated across variants (an evolution line elaborating the same shape; a service family sharing an envelope motif)
   • Owner/variant marks: variants of a base item carry a small shared spark mark and dodge the base item's gesture, so variant ≠ base at a glance
   • Substrate rules: which mark role reads on which body role (Step 3.3)
   • Orientation rules: +y is up; a recipe built y-down still validates but renders upside down — the gate cannot catch it
3. Feed the schema doc, the seeds, and the conventions into every generator prompt.

Expected: All seeds pass the full gate; the conventions document exists and is referenced by the generator prompt.

On failure: If seeds look inconsistent with each other, fix that before generating — agents amplify whatever the seeds do, including their inconsistencies.

Step 7: Generate at Scale

Generator agents emit one recipe per item and gate themselves before returning.

1. Fix the agent contract: read the schema doc + seeds + conventions; emit recipes/<slug>.json per assigned item; run the FULL validator on your own batch; only validated recipes count as done.
2. Derive filenames from one canonical slug function (a single source of truth shared by generators and coverage checks) — ad-hoc slugging orphans items silently.
3. For corpus-scale runs, drive waves with the companion workflow batch-generate-waves (scout the remaining pool → generate a wave, validator-gated → audit). Because recipes land on disk before a wave returns, an interrupted wave loses nothing: validate, commit the survivors, and the next scout pass skips them.
4. Keep the bespoke escape hatch: individually crafted artifacts remain allowed alongside recipes, with a fixed precedence rule (reference: bespoke wins over a recipe of the same name).

Expected: Waves of validated recipes accumulating in recipes/, each wave passing the full gate before merge.

On failure: If an agent's recipes fail the gate repeatedly, its prompt is missing the schema doc or conventions — do not patch the interpreter to accept them. If the scout under-enumerates the remaining pool (observed at low remaining counts), pre-compute the missing list with the slug function and pass it to the wave explicitly.

Step 8: Audit the Corpus

The validator proves renderable, not recognizable. Close the loop with human/agent judgment over real renders.

1. Render proof sheets (paged contact sheets of the whole corpus) in each style.
2. Judge recognizability against each item's _intent and the conventions (orientation, family motifs, variant marks).
3. Track weak items in a backlog file (validates + renders but reads generic) rather than blocking the corpus; schedule a redraw pass.
4. Run a coverage/drift check whenever the item pool changes: every pool item's canonical slug must resolve to exactly one recipe or bespoke artifact; report misses and orphans.

Expected: Proof sheets reviewed in every style; coverage check reports zero missing and zero orphaned items; weak-item backlog exists.

On failure: If many items read generic, the primitive set or seed diversity is too thin — improve the seeds and conventions, then redraw the weak tail; do not hand-tune the interpreter for single items.

Validation

• Go/no-go decision from Step 1 is recorded, with artifact count and style targets
• Schema document exists next to the recipes: primitives + parameters, coordinate frame, modifiers, roles
• Every role maps to concrete aesthetics in EVERY target style; the third-style litmus test passes
• One interpreter is the only render path; unknown shape or role raises a hard error (test with a deliberately broken recipe)
• Validator gate runs compile + bounds + real render in all styles and exits nonzero on any failure
• --fast mode (compile + bounds only) sweeps the full corpus within CI-tolerable time
• 3+ hand-authored seed recipes pass the full gate and exercise every role
• Conventions document exists and is included in generator prompts
• Coverage check: every pool item resolves to exactly one recipe or bespoke artifact

Common Pitfalls

• Roles named by appearance: red_fill or hatched instead of spark or accent breaks every recipe the moment a second style arrives. Name roles by compositional function; let each style map function to look.
• Validator without a real render: compile + bounds proves a recipe is well-formed, not that it renders — device errors, degenerate geometry, and style-mapping bugs only surface in a real render. Keep --fast for corpus sweeps; gate every new batch in full mode.
• Trusting PASS for recognizability: an upside-down or unrecognizable recipe validates fine. The gate checks mechanics; proof-sheet audits check meaning. Budget for both.
• Interpreter creep: generator agents "helpfully" extending the interpreter destroys the single-audited-code-path property. Freeze it; route primitive requests through central code review (the reference added exactly one primitive this way, after it became the most-requested shape across waves).
• One-off schema extensions: a per-item parameter added for one recipe becomes unvalidated dead weight. Express the need with existing primitives, or extend the schema centrally with validator support.
• ID/filename drift: recipes named by ad-hoc slugging silently orphan items from their pool entries. Use one canonical slug function as the single source of truth and run the coverage check after any pool change.

Related Skills

• create-glyph — the complement: ONE hand-authored glyph with individual craft, where this skill generates MANY recipes under one interpreter
• enhance-glyph — the polish pass for individual items flagged weak in the Step 8 audit
• dream — the generative front end: unconstrained exploration produces the concept a recipe then encodes (a dream becomes a recipe becomes a picture)
• stale-proof-rendered-numbers — the sibling data-not-code pattern for rendered figures: numbers substituted from measured data, with the build failing on missing keys
• Companion workflow: batch-generate-waves — the resumable scout → generate → audit batch driver for which this skill defines the canonical per-item generator