How the playbooks are written

This guide is for people and agents who write, check or cite the playbooks themselves. To use the rules in your own project, start at the playbook hub.

Every rule has an ID that never changes

• Each rule gets an ID made of its playbook's three-letter prefix and a number, such as PAY-14. The build names the next free number when a rule has none.
• Numbers follow the order rules were written, not their position. A position such as 3.4 shifts when a rule is added above it, so old reports would point at the wrong rule.
• An ID is never changed and never given to another rule. When a rule moves to another playbook, it takes the next free ID there. The published retired-ids.json then maps the old ID to the new one.
• When a rule is deleted, its ID goes into retired-ids.json. The entry gives a short reason, the rule that replaced it, or the page that now holds its substance. The build fails when any number up to a playbook's highest ID is missing from the rules and from both lists.
• Every list an agent reads shows the ID, and /r/PAY-14 opens a rule from its ID. A moved ID leads to its new rule. A retired ID answers 410 Gone with the reason, or leads to its replacement.
• Ask an agent to report each rule by its ID as pass or fail. The report then still points at the right rule a year later.

Every rule has a level

The hub defines the levels. A rule is Required only when breaking it causes harm or breaks a legal duty. The build fails when more than 40% of a playbook is Required. A practice that a law bans is a Required rule titled "Never …", not an Avoid rule. Default exists only in the software choices playbook, for named picks.

Rules from one region's law say so

A rule whose duty comes from the law of one place has a Region line, such as - Region: EU or - Region: US-CA, US-CO. A general engineering rule has no Region, even when a law mentions the topic. The law then stays in its Sources. Each playbook page lists its regional rules by region.

Rules on fast-moving texts carry dates

• Spec version names the version of a specification or store policy the rule was checked against, such as MCP 2025-11-25.
• Review by is the date of the next known change, or at most 12 months ahead. A weekly job lists every rule whose date has passed, and the playbook check prints them too.

Every claim cites its primary source

• A rule that follows a specification, standard or law links to that text in its Sources line, with one to three links.
• Cite the text that binds, such as an IETF RFC, a W3C or WHATWG specification, a law on EUR-Lex or a regulator's own page. Never cite blogs, tutorials, encyclopedias or vendor marketing.
• The hosts allowed as sources live in one list in the code. The build stops on a source from any other host, and on a rule that names an RFC or WCAG without a source.
• Fetch every link before adding it, so no address comes from memory. Link the current version and the exact section where the page has stable anchors.

Code watches the sources

• Once a week a job reads the sources from the built rules and fetches each one. It reports every source that stopped answering, moved to another host or a home page, or was replaced.
• For RFCs, the RFC Editor's metadata lists the RFCs that obsolete each one. "Updated by" is left out, because most updates leave the cited text valid.
• Each alert names every rule that cites the source, so the fix needs no search. Nobody is asked to reread sources on a schedule.
• An agent may reread a flagged rule against the current source. It answers "still correct" or "changed" with a quote from the source, and proposes any edit as a pull request for a person to merge. Cap each run, such as 20 rules, to bound the cost.

Cite the playbooks you use

The playbooks are free under CC BY 4.0, which requires credit with a link. Point agents to the playbook pages for common work from your instructions file. Ask them to add a comment linking the rule next to the code it shaped, so reviewers can check the source. The "For agents" box at the end of every page gives the wording.

Every lesson goes into one rule

A bug, an outage or a review can teach something that helps any project. That lesson goes into the one rule it belongs to, or a new rule with a check. Each limit or time is stated in one rule only, and other rules link to it. The changelog lists every rule by the date it last changed.