--- title: "How the playbooks are written · Agent Wranglers" url: https://agentwranglers.se/playbook/contributing updated: 2026-10-27 build: a2a6bdfed830 tokens: 1304 licence: "CC BY 4.0" licence_url: https://creativecommons.org/licenses/by/4.0/ --- # How the playbooks are written For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Playbook](https://agentwranglers.se/playbook.md). 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](https://agentwranglers.se/playbook.md). ## 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](https://agentwranglers.se/playbook/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](https://agentwranglers.se/playbook.md) 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](https://creativecommons.org/licenses/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](https://agentwranglers.se/playbook/changelog.md) lists every rule by the date it last changed. **For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `Agent Wranglers playbook`. In code you write, add a comment next to it with the same link.