The Recipe Standard
Version: 1.1 · 2026-09-19 What this answers: what a recipe is, what its file has to carry, and what a reviewer will hold it to. Everything here is checkable, and most of it is checked by a script you can run yourself. Who this is for: somebody outside this house who wants to write a recipe, place one, or publish one. It assumes you have never seen our code and never will.
A recipe is a method somebody has written down properly, so that an agent can run it and a person can run it and both produce the same work. This document is the shape that makes those two the same thing rather than two documents that drift.
Every rule below is followed by the reason it exists. A rule with no reason beside it is a convention, and conventions get argued with. A rule whose reason names the failure it prevents can be agreed with, disagreed with, or measured, which is the only way a standard survives contact with somebody who did not write it.
You can check your own file before anybody reads it. The rules in section 12 are implemented in lib/recipe-validate.ts and run two ways: paste your file at /recipes/validate, or run bun run check:recipe over a directory. The validator refuses and never repairs: it will tell you what is wrong and it will not rewrite your recipe.
1. What a recipe is
A recipe is one job: what goes in, what comes out, how you know it worked, and where it stops and asks a person. Not a workflow, not a prompt, not a policy. One job, with a unit arriving and a different unit leaving.
One drawing, two renderings. The method is written once. It is read twice: by an agent, which needs the instruction in full, and by a person, which needs the tool, the time and the end state. Those are not two artifacts. They are one method rendered for two runners, and the whole point of the format is that neither can drift from the other, because there is only one of them.

| The rendering | Who reads it | What it adds that the other does not |
|---|---|---|
| The skill | An agent | The settings block and the mandatory checklist lines, prepended to the instruction |
| The procedure | A person | How (the tool and where in it), How long, and Done when, on the steps a person holds |
Why one file and not two. A method kept in two files is a method that disagrees with itself within a quarter, and the disagreement is invisible because both copies look finished. Everything that is true of the work lives in the file below; everything that is true only of one runner is a field on a step.
The one recipe that takes nothing: the origin. Every recipe takes something, with one exception. Vision & Strategy is where the business begins, and nothing arrives in it (Craig, 2026-09-23). Its Intake recipes (The owner interview, The business on one page, State the strategy) take nothing and return what every other seat starts from. The library marks each one origin, states its inputs as an empty list, and allows the mark only in Vision & Strategy. Inventing an input for them, such as the owner's time, would draw a way in on the Intake card that no seat feeds. Everything else in this standard applies to them unchanged.
What a recipe is not.
- Not a workflow. A workflow is several jobs joined. A recipe is one, and the joining is the canvas's job. A recipe that does three jobs cannot be placed in one seat, scored against one bar, or refused for one reason.
- Not a prompt. A prompt is instruction. A recipe is instruction plus the checklist that says whether the output may be returned at all, which is the part a prompt has no place to put.
- Not a policy. A policy says what must not happen. A recipe says what happens, and carries its refusals as locked checklist lines, which are enforceable rather than hoped for.
2. The file
One file, SKILL.md, in a folder named for the recipe. Front matter at the top between two --- fences, then the body. The front matter is read by machines and the body is read by whoever runs it.
A recipe written inside this house also carries a second file beside it, recipe.json, which says where its documents, figures and catalog line belong in the house's own paperwork. It is ours, not part of this standard: nothing here reads it, the validator ignores it, and a recipe written anywhere else needs only SKILL.md.
2.1 The front matter, field by field
| Field | Type | Required | What it is |
|---|---|---|---|
name | string | Required | The recipe's own id: lower case, hyphens, no spaces. It is the folder name too |
description | string | Required | What it returns, then when somebody would reach for it |
license | string | Required | Proprietary, or the author's own license, named so a reader can look it up |
metadata.author | string | Required | Who wrote it |
metadata.version | string | Required | A number, a dot and a number, quoted |
metadata.recipe-origin | string | Optional | house, or the practice the recipe came from |
metadata.recipe-author | string | Optional | The practice or person behind the method, where that differs from the author |
metadata.recipe-reviewed | string | Required, may be empty | Who checked it and when. Empty is an answer |
metadata.recipe-evidence | string | Required, may be empty | What it has returned in real businesses. Empty is an answer |
metadata.recipe-yields | string | Required | What one run returns, in the units the canvas uses |
metadata.recipe-gate | string | Required | Where it stops and asks a person, in one sentence |
metadata.recipe-method-id | string | Required | The id of the method this implements |
metadata.recipe-input-label | string | Optional | What the person running it types, in the recipe's own words |
metadata.recipe-regimes | list | Required where the method carries an Act step, and may be empty | Which regimes the recipe's steps can reach, each with a reason and the steps it is reached from. See section 2.3 |
recipe-settings | list | Optional | What a person may turn before a run. See section 4 |
recipe-checklist | list | Required | The lines a run is scored against. See section 5 |
recipe-verdict-pass | string | Optional | The word a clean report opens with. Defaults to PASSED |
recipe-verdict-partly | string | Optional | The word a partly clean report opens with |
recipe-verdict-fail | string | Optional | The word a failed report opens with |
One example each, in the order above:
---
name: discount-control
description: Reads a month of quotes and returns one reading per seller. Use when somebody
asks who is discounting and how much.
license: Proprietary. See LICENSE.txt
metadata:
author: Archetric
version: "1.0"
recipe-origin: house
recipe-author: Archetric
recipe-reviewed: ""
recipe-evidence: ""
recipe-yields: One reading per seller per month, with an eighteen-line checklist scored
recipe-gate: Monitors and publishes. Never sets a ceiling and never approves a discount
recipe-method-id: "convert-discount-control"
recipe-input-label: Every quote sent this month with its list price and its final price
recipe-verdict-pass: DEFENSIBLE
recipe-verdict-partly: PARTLY
recipe-verdict-fail: NOT DEFENSIBLE
---
Why recipe-method-id and not the label. A recipe joins to the method it implements by id, never by name, because a label is a name and names get renamed. A join on the label survives until somebody improves the wording, at which point the recipe silently belongs to nothing.
Why recipe-reviewed and recipe-evidence are required and may be empty. A missing key and an empty one are different claims. Empty says this recipe has not been reviewed, or has not yet run in a real business. Missing says nobody has considered the question. A recipe acts, so an unreviewed one is not the same risk as an unreviewed article, and the field that says so has to be present for its emptiness to mean anything.
Why recipe-evidence is the field worth more than the method. Anybody can copy a method. What a copied recipe cannot carry is what it has actually returned, in whose business, over how long.
2.2 The body
Eight headings, in this order. Others are welcome between them.
| Heading | What goes under it |
|---|---|
## What this does | What arrives, what leaves, and what the recipe refuses to do |
## Ingredients | What the person supplies, what is read off the canvas, and what is answered by naming an absence |
## Method | A numbered list, one kind per step. See section 3 |
## What good looks like | The checklist in prose, numbered to match the front matter |
## Report | The shape of the output, including the roll call. See section 7 |
## Where this stops | The gate, spelled out. See section 6 |
## Edge cases | The cases that break a naive reading, each with the answer |
## How you know it worked | What is observably different six weeks later |
Why the order is fixed and the set is not. A reader who has read one recipe knows where the next one keeps its Report. That is the whole benefit, and it survives extra sections perfectly well: a recipe with a section on its own waterfall is a better recipe for having it. What it does not survive is Edge cases appearing before Where this stops in one recipe and after it in the next.
2.3 The regimes a recipe can reach
A recipe whose method carries an Act step says which regimes those steps can touch. Not which regimes apply to the business running it, which the recipe cannot know, but which are reachable at all given what the recipe does.
metadata:
recipe-regimes:
- id: can-spam
why: step 6 drafts a commercial email and step 7 sends it
steps: [6, 7]
- id: tcpa
why: step 8 offers a text as an alternative channel
steps: [8]
| Part | Rule |
|---|---|
id | One of the ids in the table below. Exact, lower case. A near miss is refused rather than guessed at, for the same reason recipe-method-id is an id and not a label |
why | One line saying what the recipe does that reaches it. A declared regime with no why is refused |
steps | The numbers of the steps it is reached from, and every one of them exists in the method |
The classes a recipe moves. The same block may carry recipe-data-classes: [contact, commercial], a list from the closed set in lib/data-classes.ts (the ten classes of The Compliance Approach section 3.2.3 plus the two its profile question names). It is optional in 1.1: a recipe that moves nothing about a person has nothing to say. Where it is written, rule sixteen reads it at the same level as the regimes: a class the list does not hold is named, a class the product refuses at v1 (card, health, consumer-report, biometric, minor) is named as refused in the three sentences section 8.1 requires, and a regime that attaches to a class (glba to financial, hipaa to health) may not be declared without it.
Empty is an answer. Missing is not. recipe-regimes: [] states that the author has considered the question and no regime is reachable, which is the honest answer for most recipes. A missing key says nobody considered it. This is the same distinction recipe-reviewed and recipe-evidence already make, and it exists for the same reason: requiring a denial of every regime that does not apply is how a declaration stops meaning anything.
What this does not do. It does not decide whether a regime applies to your business. That is the intersection of your own declarations with the recipe's, and it is not built yet. What the declaration does today is make the reachability visible and checkable, so that somebody can read, before they place a recipe, that this one can send commercial email.
The ids, one per regime the house holds:
| Group | Ids |
|---|---|
| Messaging and consent | can-spam, tcpa, casl, gdpr-eprivacy, state-telephone, coppa, ai-disclosure |
| Money, credit and collections | fdcpa-reg-f, state-collection, glba, pci-dss, fcra |
| Data and health | hipaa, state-privacy, automated-decisions, retention |
| Claims, hiring and AI | ftc-act-5, ftc-endorsements, ftc-reviews-rule, rosca-auto-renewal, accessibility, employment-adt, eu-ai-act-50 |
| The professions | professions-limit |
Rule sixteen is a warning in version 1.1 and becomes an error in version 1.2. Every recipe that acts needs a declaration written, and one release is the time to write them. A warning gives a visible count of what is still missing; an error on the day the rule landed would have failed every recipe at once. The release is named here rather than left to a changelog, so that an author can plan for it.
3. The twelve step kinds
A method is a numbered list. Each step names its kind in parentheses, after the step's own sentence. A step that does two things names both: (Score, then Branch).
| Kind | What it does | Takes | Yields |
|---|---|---|---|
| Read | Takes in what the canvas hands this step, and understands it | An ingredient | What it says |
| Look up | Reaches through the wall for something the canvas does not hold | A question | An answer, with its source |
| Research | Starts from a question, weighs several sources, returns a finding with where it came from | A question | A finding, with its sources |
| Calculate | Works a figure out in the open, so a later step can use it | Figures | A figure, with its arithmetic shown |
| Test | Checks it against a rule, in order, and the first failure ends it | The work so far | A pass, or the line it failed |
| Branch | Splits into named verdicts, and every verdict carries its reason | The answers | One verdict, named |
| Score | Walks every line of the bar, sorts them into passed, named and failed, and says the word | A draft | A verdict word and the lines that decided it |
| Draft | Makes the thing, without sending it | What the step before yielded | The thing, as a draft |
| Act | Does the thing outside the business: send, post, create, update | The approved draft | A receipt |
| Record | Writes what was learned where the next run will read it | A finding | A note the next run reads |
| Gate | Stops and asks a person, and nothing goes out until they answer | The drafts | Approved, or held |
| Hand over | Names what each consumer receives, in the units the canvas uses | The approved work | The recipe's own returns |
Why twelve and why no thirteenth. These are the kinds that survived reading every numbered step of the written recipes. A kind that exists because one recipe wanted it is a kind every other author has to learn and never uses, and a rail nobody can hold in their head is a rail people stop reading. If your step does not fit one of the twelve, it is usually two steps.
Why Look up and Research are separate. A look up fetches a known thing from a known place. A research starts from a question and comes back with a finding and its sources. They reach through the same wall and they are not the same reach, and a method that calls both a look up cannot say which of its steps has an answer and which has an opinion with citations.
Why no Wait and no Loop. A hold is a field on a step, not a card, and a loop is a wire back to a step already run. A card with no work in it is a card nobody can say what takes or yields.
3.1 What a step may carry
| Field | Applies to | What it says | Why it is a field and not prose |
|---|---|---|---|
| WHEN | Any step | after a plain duration, or until an event naming a unit or a reply, or both, whichever comes first | A wait written in prose cannot be scheduled, and two places to write it is how they come to disagree |
| ON FAILURE | Any step | Back to a named earlier step, at most so many times, and then a gate to a person or the work handed over as it stands | Without the cap, "rewrite anything that failed and score again" is an instruction to loop forever on a line the ingredients cannot satisfy |
| FOR EACH | Any step | The set this step runs once per item of | Consecutive steps naming the same set are one pass, not three sweeps of the same names |
| STOPS WHEN | The recipe, never a step | The unit whose arrival ends the whole run, from wherever it has got to | A stop that fires from any step, copied onto every card, is one fact stated six times |
Steps a person holds carry three more. How (the tool and where in it), How long (a short phrase), and Done when (the observable end state). An agent needs none of the three, which is exactly why they are required only here: a person asked to do something with no end state written down will either stop too early or not stop at all.
An Act step names its connection and its action. It is the one kind with an effect nobody can undo from inside the canvas, and a step that says "send it" without saying what it sends through is a step whose blast radius nobody can read off the card. An Act step is gated by default, and a business that has decided otherwise says so on the placement, where the decision was actually made, never on the card, where the author would be deciding it for every business that ever places it.
4. Settings
A setting is what a person may turn before a run. Each declares its id, its label, its kind, its default, and what it feeds.
| Key | Required | What it is |
|---|---|---|
id | Required | Stable, lower case, hyphens. A placement stores values against it |
label | Required | What the control says, in the recipe's own words |
kind | Required | number, choice or text. There is no fourth |
default | Required | What a run uses when nobody turns anything |
choices | Required for choice | Every value allowed, in the order the recipe wrote them |
min / max | Optional for number | The range |
feeds | Required | What this setting changes, in the recipe's own words |
recipe-settings:
- id: minimum-quotes
label: The fewest quotes a seller needs before they get a rate at all
kind: number
default: 5
min: 2
max: 30
feeds: Which sellers get a rate, and checklist line 6
Why feeds is required. A setting whose effect is not stated is a preference. A setting that says it feeds the returns count tells whoever is reading that the number is a contract, and a run that ignores it has broken something rather than exercised discretion.
Why a value outside the range is refused rather than clamped. Clamping runs the recipe on settings the person did not choose and then reports the result as theirs.
Why an unknown setting id is dropped rather than refused. A browser open since before the recipe was rewritten should run on today's settings, not fail. The asymmetry is deliberate: a stale key is nobody's decision, and an out of range value is somebody's.
A setting with one value is a real setting. Where a recipe has taken a decision out of the reader's hands, the setting appears anyway, with its single value, so that the reader can see which decisions were taken from them rather than discovering it in the output.
Give the recipe a revision limit. A number setting whose feeds names the revision limit is how many rewrite and rescore passes a run gets before it reports the failure instead of rewriting again. Two is the house default.
5. The checklist
The checklist is what a run is scored against, line by line. It lives in the front matter as data and in ## What good looks like as prose, and the two carry the same numbers.
| Key | Required | What it is |
|---|---|---|
id | Required | Stable and unique within the recipe |
line | Required | Its number. The numbers run 1 to N with no gap and no repeat |
question | Required | Written as a question, with a question mark, so it can be answered |
must | Required | Whether the HOUSE holds this line mandatory when nobody has chosen otherwise |
locked | Optional | Whether nobody may relax it. A locked line is always mandatory |
why | Required on a locked line | The sentence a person is refused with |
recipe-checklist:
- id: line-12-no-causal-claim
line: 12
question: "Does the reading refuse to claim that any discount won any deal?"
must: true
locked: true
why: the causal claim is the sentence everybody in the room wants, no quantity of quotes
contains the counterfactual it rests on, and a monitor that supplies it has justified
discounting using its own output as the evidence
5.1 Mandatory, flexible, locked
| Word | Who decides | What a failure means |
|---|---|---|
| Mandatory | The house sets the default, a placement changes it, one run may change it again for that run only | The output may not be returned as finished. Rewrite and score again |
| Flexible | Same three layers | The failure is reported as it stands, and the work is still returned |
| Locked | Nobody. The author decides once, in the file | The same as mandatory, and a request to relax it is refused in words, naming the line and the reason |
The order is run, then placement, then house, and locked is applied last and unconditionally.
Why the layers, in that order. A person should be able to try something once without changing what their business runs on tomorrow.
Why locked is applied last rather than trusted to the layers above. A record written by hand, restored from a backup, or edited in a console is not a validated input, and the line that stops an invented guarantee should not depend on how the record got here.
Why a locked line needs a why. The lock will be argued with, by somebody who has a deadline and a reason. A lock whose reason nobody can read is a lock people route around.
What to lock. Lock a line where breaking it produces a sentence the business will then rely on: a claim the business cannot substantiate, a number measured against a denominator nobody was asked to pay, a causal claim no quantity of the available data contains. Do not lock a line because it matters. Lock it because relaxing it is a decision nobody should be able to make quietly.
Never report a run as passing with fourteen of eighteen. A failed mandatory line is not one problem among several. It is an output whose arithmetic is over the wrong set, or whose most consequential sentence is unsupported, and the count of the lines that passed beside it is a distraction.
6. The gate
Every recipe names the point where it stops and asks a person. It is stated twice on purpose: once in the front matter as recipe-gate, in one sentence, and once in ## Where this stops, spelled out.
Write the gate as what it will not do, not as what it needs. "Drafts only. A person sends every email" is a gate. "Requires approval" is a category.
Why the gate is stated rather than enforced, and why that is said out loud. A recipe is a written instruction to whatever agent runs it. A recipe pasted into an agent that holds send and payment tools is not prevented from using them. The honest claim, and the only one worth making, is that every recipe NAMES where it stops, on the front of the card and not in the small print. Claiming the enforcement would be the kind of promise this format exists to argue against.
A recipe that names no gate is a recipe claiming it never needs one. That is a real answer for a recipe that reads and reports and touches nothing, and it is written down as that answer rather than left blank.
7. The report
The report is the shape of what one run returns. Write it as a fenced block with the fields named and the values shown as placeholders, so an author reading it knows what will be on the page before anything runs.
Four things every report carries:
- What it read, and when. The window, the system, and the moment it was read. A report with no moment on it is a claim about now that was true at some point, and every figure under it inherits that.
- What came off the pile first, with the reason. Anything excluded before the work began, listed. An exclusion that happens silently is indistinguishable from something the recipe missed.
- The roll call. See below.
- The verdict, with the word first. One word, said once, at the front of the line, then the mandatory lines that decided it. Never a paragraph with the word at the end, and never a fraction.
7.1 The roll call
Every checklist line appears in the report exactly once, by number, with one state and one sentence of reason. Three states and there is no fourth:
| State | What it means | What the reason must carry |
|---|---|---|
| passed | The line was answered in full, including where what it reports is an absence or a complication the line exists to surface | One sentence |
| named | The answer was not available from the ingredients | The missing fact, by name |
| failed | The output breaks the line | The sentence that breaks it, quoted word for word |
CHECKLIST (one entry per line, line1 to lineN, each scored exactly once)
line1 <passed | named | failed> · <one sentence>
line2 <passed | named | failed> · <one sentence> (mandatory, locked)
...
(every line appears once and exactly once. a line nobody scored is not a line that passed.
a `named` reason names the missing fact. a `failed` reason quotes the sentence that breaks it)
Why every line, including the ones that came back clean. A compliance block that only appears when something is wrong teaches a reader that its absence means nothing was checked.
Why a line nobody scored is not a line that passed. An unscored output and an output that scored clean are different facts, and folding them together is how a run comes back positive for the wrong reason. A report carrying no self score at all has not passed anything.
Why a failed reason quotes. A reason in the scorer's own words is an opinion about the output. The sentence, quoted, is checkable by somebody who was not there.
Close with what the run would ask. A thin set of ingredients produces a thin output, and the questions that would have thickened it are worth more than another figure.
8. What good looks like, edge cases, and how you know it worked
Three sections, and each answers a question the other two cannot.
## What good looks like is the checklist in prose, numbered to match the front matter, with the mandatory and locked lines marked. It exists because a person reading the recipe to decide whether to place it will not read a YAML block, and the lines are the recipe's actual argument.
## Edge cases is the list of situations that break a naive reading, each with the answer. Write the ones you have actually seen. The test of an edge case is that somebody could reach it on a real Tuesday: "nothing arrived this month" is an edge case, and the reading that says so, reports the count it did read, and does not go looking for something to flag is the recipe working.
## How you know it worked is what is observably different some weeks later, stated so that it could turn out false. Not a time saved, unless something measured it. And the honest failure mode, stated so it can be watched for. A recipe that names the way it will be misused, and the leading indicator of that misuse, is a recipe somebody can keep running safely; one that names only its successes will be trusted past the point where it is still working.
9. The research document
Optional for a listing. Required for house review.
A recipe with no research document behind it is a guess written confidently. The research document is the source of record, the recipe is derived from it, and the two carry the same version number.
| Kind of source | What it is worth | What it cannot tell you |
|---|---|---|
| Practitioner | Built the method, sold it, watched people fail at it. The failure modes are theirs | Almost nothing they say was measured |
| Researcher | Measured what happens, and often found the opposite of what practitioners assumed | Says nothing about which decision to make on Tuesday morning |
| Operator | Runs the thing at volume and has had to write its rules down | Usually written by the party selling the service |
| Standard or regulator | Binding the moment anything leaves the building automatically | Says nothing about whether the work was any good |
Four rules, each with its reason:
- Name every source, with a URL. A principle whose source cannot be opened is a principle nobody can check, and the first person to check it will be somebody arguing with the output.
- Distill, never copy. The recipe is your method, written from what you read. Reproducing somebody's text is both a legal question and a quality one: a copied passage carries the source's assumptions along with its words, and you will not notice which.
- Quotations stay under fifteen words, in quotation marks, with the source named. Long enough to show what was said, short enough that the document is yours.
- Mark the disagreements. Where two sources contradict each other, say so, say which one the recipe follows, and say why. Say once, in the opening, which kind of source wins where they conflict. A document that resolves a disagreement silently has made the most interesting decision in it invisible.
10. The graded run
Before a recipe is published in the house, it is run on real ingredients and the output is scored against its own checklist, by something other than the thing that wrote it.
| What the run produces | What it is for |
|---|---|
| The output, in full | So a reader can see what the recipe actually returns, not what it promises |
| The roll call, every line scored | So the verdict is derived rather than asserted |
| The verdict word | One word, from the recipe's own three |
| What was proven, and what was only argued | The part everybody skips |
Proven versus argued is the sentence that matters. A graded run walks one branch. Every other branch of the recipe is argued, not proven, and the record says which is which by name. A recipe proven on the branch where no ceiling exists has not been proven on the branch where one does, and saying so is worth more than a second run on the same fixture.
Move the arithmetic out of the recipe. Counts, totals, rates and weighted means are where a model's judgment is right and its bookkeeping is wrong. Hand the figures in, computed, and have the recipe say plainly that it uses them as given and does not re-add them.
The verdict word is derived from the roll call, never written first. A report that says the good word while its own self score admits a mandatory line failed is exactly the run this rule exists to stop.
10.1 What it looks like
Since 2026-09-23, a recipe document written in this house carries a section called What it looks like, right after the section that says what the recipe returns. Craig asked for it: a reader deciding whether to place a recipe should see what it actually hands back before reading why.
| What the section holds | Where it comes from |
|---|---|
| The input, in one short paragraph | The ingredients block of the final graded run, named by label |
| The output, word for word, in a boxed quote | The final graded run, as the owner receives it. Its headings are set in bold, so the document's own outline stays its own |
| A frame of the output in the app's run view | Only where the output renders there from the Example. The run view records a run's steps, timings, cost and verdict word and never its output, so today the section says so and no frame is taken |
Generated, never written. docs-source/build-recipe-samples.mjs reads the section out of the recipe's run document and writes it into the recipe document, and npm run check:docs fails when the two differ. An edit by hand is a sample of a run that did not happen, and the check exists so that it cannot outlive the next regeneration.
Only from a run that passed, and only the final one. A run passed when every mandatory and locked line passed and the verdict word the harness derived agrees with the one the run wrote. A recipe whose final run did not pass shows No passing run yet, names the verdict it ended on, and shows no sample: reaching back for an earlier run that looks better would be the flattering sample this rule exists to prevent. A run whose script derived no verdict at all, because it predates the harness, cannot pass this test either, and says so.
Where the run document cannot be read, the section says that too. It says Sample not extracted and gives the reason, rather than guessing at where the output starts.
How a new recipe gets it. Run node docs-source/build-recipe-samples.mjs on the recipe's own branch after its graded runs are in its run document, then rebuild the recipe document's twin. The run document is found by name, Recipe Run <Name> Example.md beside Recipe-<Name>.md, or named as runDocument in the recipe's recipe.json where it is called something else. Nothing shared is edited.
11. The writing rules
| Rule | Why |
|---|---|
| US spelling | One document, one voice. The word list is the one the repository's own checker runs, so this is enforceable rather than a preference |
| No em dashes | The same reason. A file half of which uses them reads as two authors |
| Units are nouns, never verbs | A unit is the thing that moves. "Nurture lead" is a unit; "nurture return" is an instruction wearing a unit's clothes, and a canvas cannot join a chain on it |
| Never key on email | Every contact or user gets its own generated id. An email address is a mutable attribute, and a record keyed on one loses its history the day somebody changes jobs |
| Name the seat, not the person | A seat is what the canvas models, one of the holders may be an agent, and the moment an output is read as an individual's score the inputs degrade |
| Say the absence by name | Where the ingredients do not answer something, the answer is the missing fact, named. A borrowed industry figure makes the most consequential number in the output the one nobody supplied |
| No invented quantity | A ratio, a conversion rate or a benchmark nobody measured is worse than a blank one, because it gets believed |
12. What the validator checks
Sixteen rules. An error is a recipe the product cannot run correctly. A warning is a recipe that will run and that a reviewer should look at anyway.
| Rule | Level | What it checks |
|---|---|---|
front-matter | error | The file opens with a front matter block and that block closes |
required-fields | error | name, description and license are stated |
version | error | metadata.version is a version string, like 1.0 |
method-id | error | recipe-method-id names a method, and one the catalog holds where a catalog was given |
provenance | error | recipe-reviewed and recipe-evidence are present. Empty is an answer; missing is not |
license | warning | The license line names Proprietary or a license a reader can look up |
settings | error | Every setting carries id, label, kind, default and feeds |
checklist | error | Every line carries id, a question with a question mark, and must; the numbers run 1 to N with no gap and no repeat; a locked line is mandatory and says why |
sections | error | The eight headings are all there, in order |
step-kind | error, or warning | Error where a step names no kind among steps that do. Warning, once, where no step in the method names one |
person-step | error | A step a person holds carries How, How long and Done when |
act-step | warning | An Act step names the connection it reaches through and the action it takes |
em-dash | error | No em dash anywhere |
spelling | error | No British spelling from the house list |
long-quote | warning | No quotation longer than fifteen words |
regimes | warning in 1.1, error in 1.2 | A recipe that carries an Act step declares recipe-regimes. Empty is an answer; missing is not. Every id is one section 2.3 holds, every regime carries a why, and every step it names exists |
Why regimes is a warning now and an error in 1.2. Twelve of the recipes shipped today carry an Act step and none of them carries a declaration, so an error on the day the rule landed would have failed all twelve at once for a field that did not exist when they were written. A warning is one release to write them and a visible count of what is still missing. The release it becomes an error is named here, in 1.1, rather than announced later, because a deprecation whose date only appears in a changelog is a deprecation nobody plans for.
Why step-kind is an error one way and a warning the other. A recipe that names no kind at all is a recipe a reader can still follow, whose method the canvas simply does not draw. A recipe that names a kind on eleven steps and not on the twelfth is a different fact: somebody drew the method and left a card the board cannot place.
Why act-step and long-quote are warnings and not errors. Both are judgments about a recipe that will run correctly either way, and a rule that fires on recipes written to this standard is a rule measuring the wrong thing. Where a warning is calibrated against real recipes and still fires on them, the honest move is to leave it visible as a warning rather than delete it.
What the validator cannot check. Whether the method is any good, whether the sources say what you say they say, whether the gate is in the right place, and whether the recipe does one job or three. Those are what review is for, and no amount of format checking substitutes for them.
13. The license line
Every recipe states its license. Two answers are expected:
- Proprietary, pointing at a license file beside it, which is what the house recipes carry.
- The author's own license, named so that a reader can look it up.
The author warrants that the method is distilled, not copied. Naming a practitioner as a source is right and is encouraged: the failure modes in a good method are usually somebody's, and citing them is honest. Reproducing their text is not the same act, and a recipe that does it puts every business that places it in the same position as the author.
Why the line is required even when the answer is obvious. A recipe travels. It gets placed, exported, pasted into somebody else's agent and forwarded to a third party, and at every one of those steps the only thing that says what may be done with it is the line inside the file.
14. Versions
| What | Where | Rule |
|---|---|---|
| The version | metadata.version | A number, a dot and a number. The research document behind it carries the same one |
| The changelog | A ## Version notes section at the end of the body | What changed, and which of the changes were decisions rather than inheritances |
| What a placement runs | The placement | A placement keeps the version it took until its owner takes the new one |
Why a placement keeps its version. A recipe that upgrades under a business silently changes what that business is doing, in a way that shows up first as an output nobody recognizes. The new version is offered, and taking it is a decision with a date on it.
Bump the minor number for anything that changes the output. A new checklist line, a changed default, a step added or removed. A typo fixed in prose is not a version.
Write the version notes for the next author, not for the changelog. The useful sentences are the ones that say which decisions in this version were choices rather than inheritances, and what a reader should look at first if they disagree with the result.
15. Version notes
| Version | Date | What changed |
|---|---|---|
| 1.1 | 2026-09-19 | recipe-regimes and validator rule sixteen. A recipe whose method carries an Act step declares which regimes those steps can reach, each with a reason and the steps it is reached from. Section 2.3 is the field and the closed list of ids. The rule is a warning in 1.1 and an error in 1.2, which is named here rather than later. Nothing else moved: the other fifteen rules, the eight headings and the twelve step kinds are unchanged, and no recipe written to 1.0 has become invalid |
| 1.0 | 2026-09-18 | The first published standard, with fifteen validator rules |
What was a decision rather than an inheritance, in 1.1. Two things.
The rule is scoped to an Act step rather than to a step that sends. An Act step that reaches a connection can touch a regime that has nothing to do with sending: a lookup against a screening vendor is the consumer reporting rules and money leaving is the financial ones. And whether an action puts a message in front of somebody is a property of the connector rather than of the recipe file, so a rule that had to work it out would be guessing on exactly the recipes where being right matters.
Empty is an allowed answer and it is the expected one. Most recipes reach nothing. A rule that made an author deny each of twenty-four regimes in turn would produce twenty-four denials nobody reads, and the declaration would stop meaning anything within a quarter.