Build the governed system, step by step

This tutorial takes you from an ungoverned product to a working adaptive-brand system: your commitments written down, your brand compiled into every generation, your riskiest behavior under contract, and a cadence that keeps it all honest. Plan on one week alongside normal work. Most steps are under an hour.

It assumes you already design in code with an agent. If you do not, run the playbook tutorial first; it gets you from a blank folder to a live URL in twelve steps. This tutorial starts where that one ends. And if your product has no runtime AI yet, everything here still pays off at design time; the runtime half is ready the day you need it.

Kyle Cooney, Head of Product Design · The full article · The 14-slide brief

---

One idea drives everything below: generate every surface, govern one system. Two machines produce what your customers see: the agent that builds your screens and the model that writes your product's sentences. Both are fluent, neither knows what your product must never say, and no reviewer will see most of what they produce. So you are going to write the knowing down, in files both machines read, with checks that fire whether or not anyone remembers to run them.

Concretely, twelve steps from now your repo will have grown this:

skills/
  commitments.md      what must always be true      (step 2)
  brand.md            taste as constraints          (step 3)
  evals.md            taste as tests                (step 9)
  decisions.md        why, at every convergence     (step 10)
behaviors/            the named verbs of your UI    (step 5)
contracts/            bounds on the risky ones      (step 6)
templates/            the plain fallbacks           (step 7)
AGENTS.md + hooks     briefs the agent, every time  (step 8)

Every one of these is a plain file in git. No platform, no vendor, nothing to subscribe to. That is the point: the system is the files, and both machines read them. The full worked versions live in the article's Appendix B, The Artifacts.

Run the threshold check

Before building anything, size the problem. The full system is overkill for a portfolio site and negligent to skip for a fintech chat product. The threshold is two numbers multiplied: the cost of a wrong sentence, and the number of surfaces that can produce one. Ask your agent to run the interview:

Interview me, one question at a time: what does this product
do, what is the most expensive wrong sentence it could
generate (legal, financial, trust), and how many surfaces can
generate one (screens, chat, email, voice, per language)?

Then recommend a rung on this ladder and say why:
1 brand file only, 2 + tokens, 3 + named behaviors,
4 + contracts on risky behaviors, 5 + evals, 6 + traces.

Whatever rung it recommends, this tutorial builds to rung five, and each step is useful without the ones after it. Stop where your exposure stops. A product that does not have a coherence problem yet is buying insurance against a fire that is not burning.

Go deeperChapter 3, The Adoption Threshold covers the full ladder, the exit conditions, and why the answer is usually a system, not a second designer.

Write the commitments file

A commitment is anything that must stay true no matter which machine is writing: what you always disclose, what you never claim, whose consent you collect and when. This is the one file everything else enforces, so it comes first. Have the agent interview you:

Interview me to draft /skills/commitments.md. One question
at a time: what must this product always disclose (fees,
estimates, limitations)? What may it never claim (guarantees,
speed promises, advice we are not licensed to give)? Which
actions need explicit consent, and what counts as explicit?

Write the file with three sections: Always disclose,
Never claim, Consent. One line each, no adjectives,
each line checkable by a machine.

Push for checkable. "Be honest about fees" is a wish. "The all-in fee appears before any confirm control" is a commitment: a machine can verify it, which means in step 9 a machine will.

Go deeperChapter 1 is the argument for why this file exists; the Air Canada ruling is what happens without it.

Rewrite the brand as constraints

You probably have a brand file already; the playbook tutorial writes one. This step upgrades it from adjectives to constraints, because "warm but professional" means nothing to a model at three in the morning. Three additions turn a style guide into governed context:

Read /skills/brand.md and /skills/commitments.md. Upgrade
brand.md with three sections:

## Tone by context
For each: delay/error, success, money amounts, first-time
user. One rule each, phrased as a constraint ("lead with
what is true now, then the next step; never open with
an apology").

## Sentence shapes
Concrete rules a validator could check: max sentence length
near numbers, no exclamation points within two sentences of
an amount, one idea per message in chat.

## Never say
Merge the never-claim list from commitments.md, then add the
brand-level entries: words we do not use, joke registers we
do not enter, comparisons we do not make.

Then test it the only way that matters, with generations:

Write the message a user sees when their [core action] fails,
three ways: once following brand.md, once deliberately
violating the tone rules, once deliberately violating the
never-say list. Label which is which only after I guess.

If you cannot tell the compliant one from the violations, the rules are too soft. Tighten and rerun.

Go deeperChapter 6, Brand as Governed Context has the full worked brand file and the two-halves model: the brand file teaches the generator, the contract checks its work.

Collapse the visual truth to tokens

If you followed the playbook tutorial you have tokens already. This step makes them the only visual truth, because a generator that can reach around the token layer will, eventually, at scale. Run the sweep:

Search every screen and component for hardcoded colors,
spacing, radii, and font sizes. Replace each with the right
semantic token from /styles/tokens.css. Where no semantic
token fits, propose one; do not invent component-level
exceptions without flagging them.

Then list every place a generated screen could acquire
styling outside the token layer, and close each one.

The three-layer rule keeps this durable: primitives name what exists, semantic tokens name what things mean, and component tokens are exceptions whose scarcity you should defend. Generators touch only the middle layer. That is how a rebrand stays an afternoon and how a thousand generated screens stay siblings.

Go deeperChapter 4, One Source of Truth explains the layer discipline and who the design system is really for now.

Name your behaviors

Your product already has behaviors; nobody has named them yet. A behavior is what a moment is for, independent of any surface: Explain, Clarify, Confirm, Compare, Recommend, Repair, Warn. Naming them gives both machines a shared vocabulary. Start with an audit:

Walk every screen and message in the [main] flow. For each,
classify the interaction: Explain, Clarify, Confirm, Compare,
Recommend, Repair, or Warn. Flag anything that is two
behaviors fused (an Explain hiding inside a Confirm) and
anything that is none of them.

Then write /behaviors/[name].md for the three most frequent:
intent (one line), required facts, allowed actions,
forbidden claims, and which repair behavior handles failure.

Name for function, never for appearance. A TransferSummary survives a redesign; a BlueFeeCard does not. And expect the audit to surface fused behaviors; unfusing them (the disclosure that was folded into the success message, the warning demoted to a tooltip) is where most of this hour goes.

Go deeperChapter 5, Semantic Components covers the full vocabulary and why the second flow, not the first, is the extraction moment.

Bind the riskiest behavior to a contract

Take the behavior your threshold check pointed at, usually the one that touches money, health, or consent, and put it under contract. A contract is the machine-checkable boundary on what a behavior may say:

Read /skills/commitments.md and /behaviors/. Write
/contracts/[behavior].ts for the riskiest behavior:

- allowedFacts: the fields it may state, from the real data
  shape, nothing invented
- requiredDisclosures: from commitments.md
- forbiddenClaims: from commitments.md and brand.md
- outputShape: what a valid rendering contains, in order
  (the disclosure before the consent control)
- onValidationFailure: "degrade-to-template" for speech,
  "block" for consequential actions

The failure behavior is the design decision that matters most. When validation fails, required disclosures degrade to a plain template, because a stiff but accurate sentence beats a fluent omission. Consequential actions block, full stop.

Go deeperChapter 6 pairs the contract with the brand file; Chapter 9 shows a contract riding through a whole week of work.

Give every channel a fallback

Cross-platform coherence is not the same layout squeezed onto every screen; it is the same promise wearing different clothes. Two artifacts deliver it. The renderer contract states what every channel must guarantee, in terms of placement and reachability, not mere presence. The fallback is the plain, deterministic rendering that ships when the generative path fails or fails validation:

For [behavior], write the renderer contract: the guarantees
every channel must honor (the fee is visible before the
confirm control is reachable; cancel is one step away;
warning salience scales with the amount).

Then build /templates/[behavior]-plain: a deterministic
rendering that satisfies the contract with zero generation.
One for screen, one for chat text.

The fallback will be ugly. It will also be correct, and correct-but-plain is the right floor for anything that moves money or collects consent.

Go deeperChapter 7, Every Surface, One Promise adds behavior localization: pacing, directness, and formality as profile, not translation.

Brief the agent, bind the model

Now wire the files into both machines. The design-time half is your instruction file plus hooks. The rule that decides where each rule goes: an instruction can be forgotten; a hook fires every time. Preferences go in the instructions, invariants go in the machinery:

Update AGENTS.md: before generating any screen or copy, read
/skills/commitments.md, /skills/brand.md, /behaviors/, and
/skills/decisions.md.

Then add hooks that fire on every change: block any diff that
hardcodes a color outside tokens.css, and block any diff that
adds a file to /behaviors/ without a matching eval binding.

One thing to expect: the second hook will complain about the behaviors you wrote in step 5, because none of them have eval bindings yet. Good. That is the hook doing its job; step 9 satisfies it. A hook that never fires on you is a hook you should distrust.

The runtime half is the same files reaching the model. If your product calls a model today, make the call site compile brand.md and the contract into the system context, and run the validator on the output before it renders. If it does not yet, you are done anyway: the file structure is the runtime integration, waiting.

Go deeperChapter 8, The Control Plane, Twice maps every design-time component to its runtime counterpart.

Write your first eval

An eval is taste written down and made executable: a rubric attached to a behavior, checkable across a hundred generated variants, which is the only scale at which checking now matters. Start with the contracted behavior from step 6:

Write /skills/evals.md with two entries for [behavior]:

## [behavior] / [commitment-check]
Fail if [the disclosure] is not stated before [the consent
control], in any phrasing.

## [behavior] / [tone-check]
Fail if the first sentence [violates a tone-by-context rule
from brand.md], in any phrasing.

Then generate 20 variants of the behavior's rendering and
run both evals. Report pass/fail per variant with the
failing sentence quoted.

Expect a few failures; they are the point. Every failure is a decision: tighten the contract, sharpen the brand rule, or accept the variant and loosen the eval. Whichever you choose, the fix lands in a file, not in a conversation.

Go deeperChapter 10, Evaluation-Driven Design: metrics decide winners, evals decide entrants, and the rubric is now a first-class design deliverable.

Start the decision log

Every design decision of consequence gets made once, forgotten, and made again by someone else, slightly differently. The countermeasure costs two sentences at the moment of convergence:

Create /skills/decisions.md with this format:

### [date] — [decision in one line]
Chose X. Rejected Y because [reason]. Sign-off: [who].
Revisit if [condition].

Add a standing instruction to AGENTS.md: whenever I choose
between options you generated, draft the log entry for my
approval before moving on.

Write the first entry right now, about something you decided in this tutorial: why that behavior got the first contract, why the fallback is a template and not a block. Six months of these entries is institutional memory no thread can match, and the agent reads it before every generation.

Go deeperChapter 11, The Memory of the System: the log as onboarding, and ownership by artifact, not by tool.

Run the failure drill

Do not wait for the real failure to find out whether the system works. Break it on purpose, the way Chapter 12 does: with a chain of individually defensible decisions.

Simulate this incident: create a variant of [behavior] under
a new name, without registering it in /behaviors/ or binding
an eval. Make it move the disclosure below the consent
control. Then tell me: which of our checks catches this,
at what moment, and which would have missed it?

The answer you want has three parts: the hook from step 8 blocks the unregistered behavior at commit time; if it somehow landed, the weekly audit in step 12 walks the screens and catches the placement; and the fix is one file. If the agent finds a path through, you have found a real gap. Close it with a hook, not a promise to be careful.

Go deeperChapter 12, Breaking It on Purpose runs the full eleven-day incident and its postmortem.

Set the cadence

The system decays without a rhythm. Two recurring blocks keep it honest. Every Friday, thirty minutes:

1. Run the eval suite against fresh generations of every contracted behavior.
2. Ask the agent to walk the week's changed screens against brand.md and the renderer contracts, with screenshots.
3. Sweep for hardcoded values and unregistered behavior variants.
4. Have the agent draft the changelog from the git log, and update the status section of AGENTS.md.

And every quarter, one hour for the sunset review. For each piece of scaffolding, ask: is the limitation this compensates for still real? When a plain instruction holds across a million generations, retire the contract that duplicates it. Keep the commitments; they were never scaffolding. Feel no sentimentality when a layer comes down.

Go deeperChapter 13, The Case Against is the full argument for retiring your own scaffolding on schedule.

---

When it goes sideways

Four problems account for most stuck moments. The two-line fix for each:

• The agent keeps ignoring the commitments. They are in an instruction, and instructions can be forgotten. Move the check into a hook or a validator; machinery does not forget.
• The contract blocks everything. Your forbiddenClaims are matching too broadly. Make each entry concrete enough to quote a violating sentence, and add the borderline cases to the eval instead, where failure is a report, not a block.
• The evals feel arbitrary. Each entry is missing its why. Rewrite every eval as "fail if X, because [commitment or brand rule]." An eval that cannot cite its source is an opinion, and opinions belong in the decision log until they earn a rule.
• The team keeps relitigating settled decisions. The decision log exists but nobody queries it. Add the standing instruction: before proposing a direction, the agent checks decisions.md and says "this was decided on [date] because [reason]; overturn it?"

---

Where this tutorial ends and the article begins

This tutorial is the hands. The full article is the argument: why the bottleneck is gone, what the control plane is, and the case against the whole framework, steelmanned. Here is the map.

Tutorial step	Article chapter	What the article adds
1. Threshold	Ch 3, The Adoption Threshold	The full ladder, exit conditions, and the do-not-hire argument
2. Commitments	Ch 1, The Bottleneck Was the Brand	Why coherence became architecture; the Air Canada precedent
3. Brand	Ch 6, Brand as Governed Context	The worked brand file; contracts as the enforcement half
4. Tokens	Ch 4, One Source of Truth	The three-layer discipline; the system as agent context
5. Behaviors	Ch 5, Semantic Components	The full vocabulary; extraction at the second flow
6. Contract	Ch 6, Ch 9, A Flow, End to End	A contract riding through one full week of work
7. Fallbacks	Ch 7, Every Surface, One Promise	Renderer contracts as accessibility; behavior localization
8. Both machines	Ch 8, The Control Plane, Twice	The full design-time-to-runtime mapping table
9. Evals	Ch 10, Evaluation-Driven Design	The critique made continuous; the rubric as deliverable
10. Decision log	Ch 11, The Memory of the System	Governance, ownership by artifact, onboarding as docs
11. Failure drill	Ch 12, Breaking It on Purpose	The eleven-day incident, in full, with the postmortem
12. Cadence	Ch 13, The Case Against, Ch 14, The Discipline	The sunset protocol; what survives model progress
The artifacts	Appendix B, The Artifacts	Every file from this tutorial, worked and trimmed to its load-bearing lines

Read the full article for the argument. Send the 14-slide brief to the stakeholder who needs convincing. And run step 11 before your product does it for you.