Cookwala Recipe Format: recipes that work with Missions

A recipe in Cookwala isn't a list of instructions. It's portable cooking knowledge that a planner compiles against a specific Mission (household, robots, appliances, energy, budget, health, timing) into an executable plan. The robot then runs that plan, adapting through contingencies and playbooks when reality changes.

Schema: [recipe.schema.json](../schemas/recipe.schema.json). Full worked example: [examples/shakshuka.cookwala.json](../examples/shakshuka.cookwala.json).

1. Four layers (adapted from the WHO SMART Guidelines approach) #

Like source code and a compiler: the recipe is portable intermediate representation (R3 + R2). The Mission is the target machine. That's what keeps recipes valid as robots and AI change: a better planner produces a better R4 from the same recipe.

2. What each section does in a Mission #

3. Example: one step with everything attached #

{
  "id": "n7", "op": "cw.op.simmer",
  "inputs": ["aromatic_base", "tomato", "salt", "blackpepper"], "output": "sauce",
  "params": { "heat": "medium_low", "lid": "off", "target": { "sensor": "cw.sense.liquid_temp", "value": 94, "unit": "degC", "tolerance": 3 } },
  "until": { "any": [ { "sensor": "cw.sense.mass_loss_ratio", "gte": 0.25 }, { "vision": "cw.sense.sauce_coats_spoon" } ],
             "minTime": "PT10M", "maxTime": "PT18M" },
  "onTimeout": "extend",
  "pause": { "pausable": true, "safeState": ["heat_hold_low", "lid_ajar"], "maxPause": "PT45M", "onExceeded": "reheat_then_resume" },
  "failureModes": [
    { "incident": "cw.incident.too_salty", "likelihood": "low", "playbook": "cw.pb.too_salty_liquid" },
    { "incident": "cw.incident.too_thin", "likelihood": "medium", "playbook": "cw.pb.sauce_too_thin" } ],
  "alternatives": [ { "id": "gas", "op": "cw.op.simmer", "when": ["gas_only"], "timeFactor": 1.0, "quality": "same" } ],
  "hazards": ["hz_splatter", "hz_steam"], "attention": "monitor"
}

4. Compiling a recipe for a Mission (what the planner does) #

1. Select the variant: diet, texture (IDDSI), equipment, energy and mode pick from alternatives. Identity essentials must survive.
2. Scale: from formula and the servings, portions per person (HEALTH.md), the limiting ingredient, or a ration horizon. Spices sub-linearly, time by mass exponent.
3. Substitute within roles, respecting identity.neverAdd, allergens, dietary packs and inventory.
4. Prepare the environment: compare prep with the Mission's space facets (sink full? hob occupied? board dirty?) and add tidy, wash, dry and stage tasks. Schedule advanceTasks (soak, thaw, marinate, preheat).
5. Bind: assign each node to robots, appliances or humans by affordances and capabilities. Lease burners, vessels and zones. Attach monitors (smart pot, delivery ETA, smoke detector).
6. Schedule back from the serve time, honoring pause budgets, battery and energy limits, household quiet hours and kitchen-sharing windows.
7. Attach contingencies: each node's failureModes and pause rules, plus the Mission's global policies (interruptions, child or pet near the hob, stove watchdog, spoilage watch).
8. Verify: schema + semantic checks, policy packs, CCP coverage, simulator dry-run, priority-stack invariants (PROTOCOL §7.2).
9. Emit R4 into the Mission's plan, sign it, and hand it to the robot.

5. Authoring and converting #

• From fifi.cooking: the EXPORT-FIFI pipeline generates R1 + R2 + R3. The new sections (identity, sensory, formula, prep, service, pause, failureModes, affordances) are generated by local models from the existing text and checked by validators and sampled human review.
• From the web: cookwala convert --from schema-org → R1/R2 (V0), then the same enrichment.
• To other formats: schema.org Recipe (R1/R2 for search engines), Cooklang (human editing), PDDL or temporal logic (research planners) can all be generated from R3.
• By hand: cookwala init recipe scaffolds all layers; cookwala validate and cookwala simulate check them.
• Versioning: revisions are immutable and hashed. Forks record meta.derivedFrom. Recipe patches (from playbooks or feedback) are proposed as diffs and promoted only after review and evidence.

6. Language of the step text #

Step sentences are written for a person first and parsed by a machine second. The Arabic step text in the example recipes uses the feminine imperative (قطّعي، سخّني), which is the common Egyptian cookbook convention; it is a deliberate choice, not an oversight, and a publisher may use the gender-neutral passive (تُقطَّع البصلة) instead. The op, params and until fields carry the meaning; the sentence is for the cook.

7. Why this stays future-proof #

• Recipes describe food outcomes and constraints, not motions. New robots and new AI produce better R4 plans from the same R3.
• All new sections are optional and additive. A V0 recipe (R1 only) still works for guided human cooking; each layer added unlocks more automation.
• Unknown x- fields pass through. Vendors, chefs and health bodies can extend recipes without breaking anyone.
• Acceptance checks let any executor, human or robot, prove the dish came out right, which is how recipes climb to V3 with field evidence.