What's in a playbook

A playbook is what you pick, what runs, what the bench scores, and what you fork when you disagree with it. It is also small. A playbook is a folder in a public repository with a manifest and a set of instructions. You can read the whole thing in a few minutes. The public set is midkernel/playbooks. This note reads one: asvs/auth-review.

The folder is the unit. The YAML bounds the run. The Markdown tells the agent how to audit.

The manifest

asvs/auth-review audits authentication and session handling against the OWASP Application Security Verification Standard. Its manifest looks like this:

name: asvs/auth-review
version: 3
stacks: [web, api]
tools: [read, grep, run-tests, http]
scope: ["src/**", "api/**", "!**/*.test.*"]
profiles:
  low:      { model: fast,      passes: 1, credits: 3 }
  balanced: { model: leading,   passes: 2, credits: 7,  verify: true }
  max:      { model: strongest, passes: 4, credits: 18, verify: true }
report: { schema: findings/v1, proof: required }

tools is the whole list of things the agent may do. Here it can read files, search them, run the repository's own tests, and make HTTP requests inside the sandbox. It cannot write files. It cannot reach the network beyond what the platform allows. If a playbook needs another host (a package registry, a testnet), it declares it here, and you see it before you run.

scope is what it may look at. This playbook reads source and API directories and skips tests. Narrow scope makes runs cheaper and more focused. A playbook that audits everything says so.

profiles is where depth is set. low makes one pass with a fast model. balanced makes two with a leading model and verifies what it finds. max makes four with the strongest model and verifies everything. The credits integers sit on those same profile lines because they are part of the file. How credits work is on Pricing.

report says what the playbook is allowed to hand back. proof: required means a finding without a reproducing input does not make it into the report. That single line is most of the reason this playbook's reports are short.

The manifest is the fence. The agent does not get a tool, a path, or a network host that is not written here.

The instructions

The second file is Markdown, and it is the part people usually mean by "prompt". It is longer than the manifest and more interesting. For this playbook it does four things.

It sets the frame: what ASVS covers, which chapters apply, what the agent is looking for, and what it is not looking for, so that it does not spend budget reporting missing security headers in an authentication review.

It gives a method: start from every entry point that accepts credentials or tokens, trace each to where the decision is made, list the assumptions the code makes about the caller, and try to violate each one.

It defines proof: for each candidate finding, produce a request that demonstrates it against the running code in the sandbox, or downgrade it to a note. The http and run-tests tools exist for this step.

And it fixes the output: path, root cause, proof, severity with the reason, fix. Every finding, every time, in that order. That is the report you read.

The instructions are why two playbooks that share a model still disagree. One spends the budget on headers. This one spends it on how a session is decided.

Why the shape matters

Because the playbook is text, three things follow. You can read it before you trust it. You can diff version 3 against version 2 and see why its bench score moved. And you can fork it: narrow the scope to one service, add a tool, change what counts as proof, and run your version on Team.

Playbooks live in midkernel/playbooks. Each is curated the same way: declared tools and scope, a passing schema, a clean run on at least one benchmark, no benchmark answers inside, and a maintainer who answers issues. If you have one, the contributing guide is short.

A folder you can read is a playbook you can argue with. That is the point.