Playbook Builder

A playbook is the standing answer to "how do we work here", written so an agent can act on it. This skill produces one by reading the repository first and asking the user only what the repository cannot tell you.

Why most playbooks fail, and what to do differently. Teams write a long document of preferences, and agents ignore it. Three causes, each with a fix that shapes this whole process:

1. It restates what tooling already enforces. If the formatter sets quote style, writing "use single quotes" adds nothing and buys a maintenance liability. Fix: never write a rule a tool can enforce. Automate it instead and say so (§3).
2. Rules have no trigger. "Prefer composition" cannot be applied, because nothing says when. Fix: every rule names the situation that invokes it (§4).
3. Rules have no reason. An agent given an unexplained rule cannot tell a case the rule was built for from a case where it does harm, so it either over-applies or abandons it. Fix: every non-obvious rule carries its cost or consequence (§4).

The target is 20 to 40 real rules, not 200. A playbook competes for attention with the task itself, and length is the enemy of being followed.

When this is the wrong tool

Say so rather than building something nobody needs:

• Fewer than about ten rules. Put them directly in CLAUDE.md. A playbook is overhead until there is enough to organize. This is not in tension with the placement guidance in §5: that section describes how to split a playbook once it is large enough to need splitting, and a small repo arriving at §5 with a dozen rules should put all of them in CLAUDE.md and stop.
• The user wants one specific thing fixed now. Fix it. A playbook is for recurring decisions.
• Generic best practices with nothing team-specific. Point them at the frontend-practices, backend-practices, database-practices, security-practices and git-practices skills, which already cover the general case. This skill is for what makes their repo different.

The process

Detect, classify each decision as determined, inferable or must-ask, ask only the last of those, merge with whatever instructions already exist, draft the gate pipeline with every guess marked, place it, then test it on real work. Do not skip detection: the interview is short and credible only because detection did the boring half first, and asking a user for their test command when package.json states it reads as not having looked.

1. Detect

Run detection before asking anything. references/detection.md holds the commands, grouped by ecosystem and opening with topology. Work through it there rather than improvising; this section covers only how to read what comes back.

Start with topology, because it decides where the playbook can live and how many pull requests one task produces, and every later answer depends on it. Then four things in order: what already instructs agents here, the stack and its real verification commands, what tooling already enforces, and the conventions as practised rather than as claimed.

Read the commit log for what is practised. If 80% of subjects carry a fix: prefix, that is the convention whatever anyone says. If the log is a wall of "update", that is a finding worth raising, not a convention to encode.

When detection comes up empty. Documentation repos, config and infrastructure repos, design systems, content sites and fresh projects have no manifest, no test runner and no linter, so most of the commands above return nothing. That is itself the most useful finding: a repo with no mechanical enforcement has every convention living in someone's head, which is the strongest possible case for writing them down and for §3's advice to convert them into checks. Fall back to three sources that always exist:

• The commit log, which shows subject style, body discipline, granularity and whether work goes through branches. In a repo with no tooling this is the only written record of how the team operates.
• Churn, which shows what the work actually consists of. A repo where every commit touches the same four documents has a different shape from one spread across fifty files.
• The artifacts themselves. Read two or three of the files the repo exists to produce and infer the house style directly: how rules are phrased, how sections are structured, what the author clearly refuses to do. A convention visible in every file is a real convention.

Check whether the repo follows the standards it already ships or cites. If it contains or links a style guide, a contributing document, a set of practice rules or a published policy, verify a sample of those claims against reality: does main have the protection its own guide demands, does CI run what its own README promises, do the files follow the conventions they document? Divergence here is high-value, because a repo that visibly ignores its own rules teaches every reader, human or agent, that the rules are decorative. Either the practice or the rule needs to change, and the user is the one who decides which.

Then report what you found and ask for correction, in a few lines. "Your last 200 commits are 85% Conventional Commits, tests live beside sources as *.test.ts, Biome and a pre-commit hook already enforce formatting, and CI runs typecheck plus unit plus e2e. Correct anything wrong here." Confirming beats interrogating, and it surfaces the gap between the intended convention and the practised one, which is often the most useful thing the exercise produces.

2. Ask only what you cannot infer

Resist interviewing first. People answer abstract questions about how they want to work poorly and correct a concrete artifact well, so a draft built from inference and marked with its guesses gets further in one round than a questionnaire gets in two.

Classify every architectural decision before asking anything. Each one is in exactly one of three states, and only the third earns a question:

Both conditions are required for the third. Something the evidence is silent on but cheap to get wrong is an assumption, not a question: the draft surfaces it and the user corrects it in a sentence. Something the evidence settles is not a question even if it feels important.

In practice this collapses most of the architecture interview:

• Determined by detection: topology, which tracker is reachable, what CI enforces, what tooling exists, the commit and branch conventions as practised.
• Inferable from evidence: isolation (a repo with no branches in its history wants a single tree), execution model (native with delegated exploration suits almost everyone until they have seen it go wrong), plan gating (scale it to blast radius: a prose repo is light, a payments service is not), review (whatever tooling already exists), triage criteria (derive them from what the repo actually contains, then show them).
• Genuinely must ask: the authority to commit and push, because a repository's history cannot tell you what its owner wants an agent doing unsupervised; the human half of the definition of done, because CI shows the mechanical half and nothing shows whether a changelog entry is expected; and anything where the evidence contradicts itself, such as a repo whose own standards demand branch protection that it does not have.

That is usually two or three questions, not eight. references/workflow-interview.md holds the full question bank with the reasoning behind each, to consult when a decision lands in the third state or when a draft gets pushed back on.

Scale the ceremony to what is at stake. A five-file prose repository does not warrant the same interview as a payments service, and asking as though it does reads as process for its own sake. Let the size of the repository, the blast radius of its changes and the number of contributors set how much you ask.

Then draft, with every guess visible. Produce the complete playbook plus a short list in the form "I assumed X, because Y, change it if wrong". A marked assumption costs one sentence to fix and nothing to accept; an unmarked one becomes a rule nobody agreed to. Never hide an inference in the prose as though it were established.

Topology first, whatever else you skip, because a task spanning two repositories produces two pull requests that must merge in order, which changes what every later gate means.

Then the standards. Same rule: infer what the code shows, ask what it cannot. The starred items below are the ones worth a question even on a small repo.

Definition of done. ★ What has to be true before a task counts as finished? Tests passing, new tests written, types checked, docs or changelog updated, a migration tried against a copy, a screenshot, a manual check somewhere? This is the highest-value answer in the interview, because nearly every disagreement about agent work is a disagreement about what finished meant.

Stop conditions and autonomy. ★ Ask these together, in one exchange, because they are two ends of the same question and answering one half-answers the other. How far does an agent's authority run: edit the working tree, commit, push a branch, open a pull request, merge? And where does it stop and ask instead of deciding: adding a dependency, changing a schema, altering a public API or response shape, touching auth or permissions, anything involving money or personal data, a change spanning more than some number of files? Then the hard limits, which are worth stating separately in the output: what it may never do without a human, such as pushing to a protected branch, running a migration against live data, editing production config, or rotating a credential. Being explicit prevents both timid agents that stop short of useful work and bold ones that push to main.

Watch for answers that contradict a rule the playbook is about to state. A team that wants an agent pushing directly to main has chosen a workflow that branch-protection advice forbids; that is a legitimate choice for a small repo, but it has to be recorded as a deliberate deviation with its reason (§4), or the playbook will contradict itself and lose credibility.

The shape of a task. Where does work arrive from, and in what format? Branch from what, named how? Is there a required sequence from issue to merge, and who or what reviews? Agents are good at following a stated pipeline and bad at inferring one.

Scope discipline. When an agent notices an unrelated problem mid-task, what should it do: fix it, mention it, open an issue, or leave it alone? Is drive-by refactoring welcome or unwelcome? Teams differ sharply here and the wrong guess is irritating in both directions.

The dangerous parts. Which areas of this codebase are riskiest to change, and why? What mistake do new contributors reliably make? Is there anything that looks wrong but is deliberate? That last question is worth real weight: it is the only reliable way to stop an agent confidently "fixing" an intentional oddity, and the answer is never in the code.

Verification. The exact commands to build, test, lint and typecheck, roughly how long each takes, and anything that cannot be checked locally at all. Duration matters: an agent that knows the suite takes twelve minutes will scope what it runs, and one that does not will either skip testing or stall.

Taste that recurs. Any library or pattern deliberately banned, and what to use instead? Any module the team considers exemplary and worth imitating? A pointer to one good example teaches more than a paragraph of description.

Corrections you have already had to make. ★ Ask directly: what have you had to tell an agent, or a new colleague, more than once? What did the last review of agent-written work change? This is the single most productive question in the interview and the one most often skipped, because those corrections are the conventions that matter most and the ones least likely to be written anywhere. They exist only in chat logs and reviewers' memory, and they vanish when the session ends, which is exactly the problem a playbook solves. If you are running this skill inside a session where the user has already corrected you, mine that: those corrections are evidence, and they belong in the playbook whether or not the user thinks to mention them.

3. What earns a place

Admit a rule only if all three hold. This filter is what keeps the result worth reading:

1. It recurs. It will come up again. A one-off is a code comment, not a rule.

2. Getting it wrong has a real cost. Broken production, a security hole, data loss, a painful revert, a repeated argument. Aesthetic preferences with no consequence are not rules.

3. No tool enforces it. If a linter, formatter, type checker, test, CI gate or database constraint can enforce it, that is strictly better than a written rule, because it cannot be forgotten or ignored. When you find such a rule, say so and offer to add the check instead. A playbook should shrink as enforcement grows.

   scripts/validate-playbook.py in this skill is a working scaffold for exactly that. Copy it into the repository, usually as scripts/validate-playbook.py, and replace its example CHECKS with the project's own. It composes checks from factories for forbidden text, required text, file existence, link resolution, commit subjects and bodies, and a shell escape hatch that delegates to tooling the project already owns rather than reimplementing it. Prefer that escape hatch where a real linter exists: wrapping pnpm lint keeps the check honest, while reimplementing its rules guarantees drift.

   Then prove the checks can fail. Run python3 scripts/validate-playbook.py --self-test, which writes a synthetic violation for each check and confirms it fires. A check that cannot fail is worse than no check, because it reports success forever and nobody looks at it again. Do this every time you add or edit one; it catches inverted conditions and patterns that never match, and it takes a second. Anything reported as unverified needs a sample violation declared before you trust it.

   Expect the first real run to fail on things that are fine. That is the scaffold's defaults meeting the project's actual choices, and each failure is a question worth asking: is this a rule the project wants, or a default to delete? Resolve every one before wiring it to CI, because a validator that is known to cry wolf gets disabled within a week.

Also exclude: anything already obvious from the code, anything covered by the five general practice skills unless this team deliberately differs from them, and anything nobody actually follows. An aspirational rule that is routinely violated teaches an agent that the playbook is decorative.

4. Write it

Merging with what is already there

Most repositories that want a playbook already have something: a CLAUDE.md, an AGENTS.md, a .cursorrules, a CONTRIBUTING.md, or conventions scattered through docs/. Treat every one of these as content to restructure, never as a draft to replace. It accumulated because somebody hit a problem and wrote down what they learned, and most of what it contains cannot be re-derived by reading the code. Overwriting it destroys the most valuable thing in the repository, and the user will not notice what went missing until an agent makes the mistake the deleted paragraph existed to prevent.

Read the existing file completely before writing anything. Then sort its contents, because the categories have different fates:

Check whether the file is generated before editing a word of it. Some frameworks ship a command that writes and rewrites an instruction file: Laravel Boost produces a CLAUDE.md and AGENTS.md, and other ecosystems do the same. An edit there survives until the generator next runs and then disappears without a trace, which is worse than being refused, because nobody learns it happened. Check how often that is: generators are often wired into a package manager's post-install hook, so the file can regenerate on every dependency install rather than only when someone deliberately asks. Three signals, any one close to conclusive:

# Two names, identical bytes: no person wrote both.
cmp -s CLAUDE.md AGENTS.md && echo "generated: identical twins"
# Machine-authored openings: a wrapper tag, a banner, a do-not-edit notice.
head -10 CLAUDE.md | grep -iE '^<[a-z-]+>|generated|do not edit|guidelines'
# The generator itself, and whether it runs on install.
grep -riE 'boost|agents?-?(md|rules)|post-autoload|postinstall' \
  package.json composer.json pyproject.toml 2>/dev/null | head

Two files with different names and identical bytes were not written by a person. When you find one, leave it exactly as it is and work around it: put your rules in a file you own, usually a root CLAUDE.md, point at the generated one for what it covers, and where you need to override it say so explicitly, because the generated file cannot say it for you. Tell the user what you found, since they may not know the file regenerates either.

Three rules govern the merge itself:

• Show the mapping before you write. A short list saying where each existing section lands: kept as is, moved under a gate, rewritten, or proposed for removal with a reason. This is the consent step for an operation that is otherwise hard to review, because a rewritten file diffs as one enormous change in which a quietly dropped paragraph is invisible.
• Never drop anything silently. Removal is a proposal with a reason attached, every time. The user knows why a line is there and you usually do not.
• Keep their vocabulary, their paths and their examples. If the file says "tenant", do not switch to "organization" because the template used that word. Their terminology is part of the content.

Their structure might be better than the template's. If the existing file is already well organized and the only thing missing is a gated pipeline, add the pipeline and leave the rest alone. The template in references/template.md is a default for a blank page, not a shape to force existing content into.

Then verify nothing was lost. Before presenting the result, check mechanically that every heading and every concrete fact in the old file, meaning each path, command, flag and named rule, appears either in the new file or in your proposed-removals list. A diff of the two files is enough, and it reliably catches a paragraph dropped by accident during restructuring. If the old file was committed, git already holds it; if it was not, say so before touching it, because that is the one case where a mistake is unrecoverable.

The two halves

Two halves. The gate pipeline says how a task travels from arrival to done. Standards say what good work looks like here. Most teams have some of the second written down somewhere and almost none of the first, and the pipeline is the half agents most need, so write it first and give it the most care.

The gate pipeline

Write the workflow as numbered gates that close in order, not as a list of steps. The difference is enforcement: "write tests" is advice an agent weighs against the situation, while "Gate 4 does not open until Gate 3 is approved" is a thing an agent either did or did not do. Numbered gates also give the user something to point at when work goes wrong: "you skipped Gate 5" is a precise complaint that a prose workflow cannot express.

Four properties make a gate a gate, and a step missing any of them is a suggestion wearing a gate's name:

1. An entry condition, usually that the previous gate closed.
2. A definite action naming the real tool, skill or command, never a description of one.
3. An exit condition that can be checked. "Plan approved", "every review finding resolved or dismissed with a reason", "issue moved to In Review and PR attached". Never "done properly".
4. A stated behaviour when it cannot close. The tracker is down, the user has not given a go-ahead, a finding cannot be fixed. The common failure is a gate that silently evaporates when its precondition fails, so write down what happens instead.

Number from 0, so a tracking gate can sit ahead of triage without renumbering the rest.

Put the authority boundary in its own gate and make it loud. Whether an agent may commit, push and open a pull request is the decision users most regret leaving implicit, and the one agents most often read generously. If the answer is "ask first", the gate has to say that permission is per-step, that it does not carry to the next task, that a clean review and a green build are not permission, and that it overrides any skill which commits as part of its own flow. Without that last clause an agent following a test-driven-development skill will commit on every green test and be correct to, because that skill told it to.

A pipeline is a cost. Eight gates on a repo that ships a typo fix a day will be routed around within a week. Triage exists to stop that: define a short flow, say exactly which gates it still runs, and make the tiebreaker explicit, because "short flow" with vague boundaries becomes "no flow".

Referencing general practice skills

A playbook sits alongside whatever general standards are already available, including the frontend-practices, backend-practices, database-practices, security-practices and git-practices skills in this plugin. The obvious approach, pointing at them everywhere, is wrong: each already carries a description saying when it applies, and that description is what loads it. Reference one only where the playbook changes what would otherwise happen, and write the reference so the rule survives the skill being absent.

references/referencing-skills.md has the four cases that earn a reference, the area table format, and the degradation pattern.

Standards

Write every standards rule in this form:

Imperative claim. The trigger or situation, then the reason or cost.

- **Never query the warehouse from a request handler.** Warehouse queries take seconds to
  minutes, and one blocking call occupies a worker for the duration. Read from the replica, or
  move it to a job and return a job id.

That carries a trigger (a request handler), an instruction, and a consequence that lets a reader judge when an exception is legitimate. Compare "avoid slow queries", which carries none.

Conventions that make the output usable:

• Order by how often it applies, not by topic neatness. The rule that fires every task goes first.
• State the real command, not a description of it. pnpm test -- --filter=api beats "run the relevant tests".
• Name files and directories explicitly. "Handlers live in src/api/routes/, one file per resource" is actionable; "keep the structure consistent" is not.
• Record the reason for anything surprising, especially deliberate oddities. This is the content with the longest useful life, because the code cannot express it.
• Mark hard limits as hard. Separate "stop and ask" items visually from preferences. An agent needs to distinguish a guardrail from a nicety.
• Match the repo's own vocabulary. If the team says "tenant", never silently switch to "organization".

Use references/template.md for the skeleton and worked fragments, and references/workflow-interview.md for the questions that decide which gates exist.

5. Place it

The gate pipeline belongs in CLAUDE.md, always. It governs every task, so it has to be loaded before the agent decides what to do, and a pipeline that loads only when something triggers it has already been bypassed by the time it arrives. The same is true of the authority boundary: a stop condition that loads conditionally is a stop condition that fails.

Recommend the split for everything else. Put the pipeline and the universal rules in CLAUDE.md, and move per-area depth into skills that the relevant gate points at. Put domain depth in skills, where it costs nothing until relevant. The common failure is cramming everything into CLAUDE.md, which taxes every session and buries the critical rules in bulk.

When writing a skill, the frontmatter description is the entire triggering mechanism, so it must state both what the skill covers and the situations that should invoke it. A skill with a vague description never fires and its content may as well not exist.

6. Test it on real work

A playbook is a hypothesis until a task runs through it. Finish by taking one real task, ideally one that previously went wrong, and running it under the new playbook. Then look for:

• Silence: a decision the agent had to make that the playbook did not cover. Add it.
• Friction: a rule that made the work worse or was overridden for good reason. Fix or delete it. A rule reasonable people violate is wrong or badly explained.
• Dead weight: rules that never came up. Leave them if they are real guardrails; cut them if they were speculative.

Say this to the user explicitly, because it is what turns the document into something load bearing instead of a one-time artifact.

Keep it true. A stale playbook is worse than none, since agents follow wrong rules with confidence. Set a trigger for revisiting it: whenever a rule is overridden twice, whenever the stack changes, and whenever a postmortem names a missing rule. Prefer deleting a rule to leaving one nobody believes.

Anti-patterns

• A playbook restating what the linter, formatter, type checker or CI already enforces.
• Rules with no trigger ("write clean code", "prefer composition").
• Rules with no reason, which an agent cannot apply judgment to.
• Aspirational rules the team does not actually follow.
• Everything in CLAUDE.md, so critical guardrails sit buried in context every session.
• A skill whose description is too vague to trigger, making its content unreachable.
• Interviewing the user for facts the repository plainly states.
• A playbook long enough that reading it costs more than the mistakes it prevents.
• Interviewing before drafting, which asks someone to answer in the abstract what they could correct in a second if they were looking at it.
• Asking a question the evidence already answers, or one whose wrong answer costs nothing.
• An inference presented as established fact rather than a marked assumption, which turns a guess into a rule nobody agreed to.
• The same weight of process on a five-file repository as on a payments service.
• Overwriting an existing instruction file instead of restructuring it, which destroys the tacit knowledge that is the one thing in the repository nobody can re-derive.
• Dropping a rule during a rewrite without proposing it, so the loss is invisible in a diff that already changes every line.
• Editing an instruction file that its own tooling regenerates, where the change survives until someone runs the generator and then vanishes with no trace.
• Restating a skill's own trigger conditions, which duplicates the mechanism that already loads it and rots the moment the skill is renamed.
• Pointing at a general skill without saying what the team does differently, which leaves the one genuinely local piece of information unwritten.
• A workflow written as prose steps rather than gates, so nothing says when one is skipped.
• Treating separate repositories under one parent folder as a monorepo, which hides the merge ordering problem until a client ships against an endpoint that does not exist yet.
• A playbook written into a parent folder that is not itself a repository, so nobody else ever sees it.
• A gate with no stated behaviour for when it cannot close, which makes skipping it the default.
• Commit and push authority left implicit, or stated without overriding the skills that commit on their own.
• A full pipeline with no short flow, which gets routed around rather than followed.
• Hardcoded tracker status names, which break silently when a team renames a column.
• Writing it once and never revisiting it after a rule proves wrong.