authoring-a-playbook
Use when adding a new case playbook to process/playbooks/, editing an existing one, or reviewing a change to one — covers the required frontmatter, the fixed body sections, the hard rules, and the mat
SKILL.mdskills/authoring-a-playbook/SKILL.md
GitHubAuthoring a Playbook
Overview
A case is a class of work with its own trigger, entry criteria, and agent subset —
greenfield, defect, incident, deprecation. A playbook is the recipe for one case:
which agents and skills it uses, in what order, with which gates and loop-backs.
The division of labour is fixed and worth internalising before you write anything:
| Document | Defines |
|---|---|
process/agent-roster.md |
who the agents are |
process/agent-handoff-protocol.md |
how work moves between them |
process/playbooks/<case>.md |
which of them run, in what order, for this case |
A playbook therefore references; it never redefines. If you find yourself restating an agent's scope or a gate's semantics, you are duplicating a source of truth that will drift.
Adding a case is a drop-in: one file conforming to playbook-schema.md, plus one column in
the matrix. The roster and the protocol never change to add a case.
When to Use
- Adding a case.
- Editing an existing playbook — adding or removing an agent, changing gates or ordering.
- Reviewing a change under
process/playbooks/.
Do NOT use for: adding an agent (use authoring-an-agent; the roster gets the agent
first, as its own change, and only then does a playbook reference it).
Step 1 — Establish that it is a distinct case
A case earns its own playbook when it has a distinct trigger and distinct entry criteria,
not merely a different feel. Test it against the existing cases and the picker in
process/playbooks/README.md. Two useful discriminators:
- What starts it? A packet, a defect report, a page, a removal decision, a question.
- What is its relationship to the canonical baseline?
produces,consumes, ornone.
If a candidate case differs from an existing one only in scope size, it is a variant — document
it inside that playbook rather than forking a near-duplicate. greenfield's increment variant
lived that way legitimately until its divergence justified promotion.
Step 2 — Write the frontmatter
Every field is required. playbook-schema.md §1 is authoritative; this is its working form:
---
case: <slug> # unique; equals the filename stem AND the matrix column
name: <Human Title>
trigger: <the artifact or event that starts a run of this case>
entry_criteria: # what the Orchestrator verifies before issuing handoff 0001
- <precondition>
agents: [01,02,...] # roster IDs, INCLUDING conditional ones
skills: [<skill-name>] # [] if none
gates: [scope, design, release] # ordered slugs; [] if the case has none
baseline: produces # produces | consumes | none
closure: > # one line: what makes a run of this case done
<traceable to handoff-protocol §6.1 or a documented variant>
---
Field rules that carry real weight:
agents— every ID must exist in the roster overview table. Conditional agents belong in this list. A matrix cell marked~and an ID absent fromagents:is the exact contradiction this repository has shipped before.baseline—producesmeans the case promotes requirements/glossary/architecture into canonicaldocs/at its terminal gate;consumesmeans it diffs against them;nonemeans it touches neither.closure— cite the protocol section it derives from. A closure condition nobody can check is not one.
Step 3 — Write the body in the fixed section order
Seven sections, all required, in this order (playbook-schema.md §2). "none yet" is a valid
value; omitting a section is not.
## When to use / when NOT entry test, with explicit pointers to the right case when this is wrong
## Entry criteria expanded preconditions the Orchestrator verifies before 0001
## Run at a glance ASCII phase/agent flow with [H] gate and ↺ loop-back markers
## Phase-by-phase per agent: what it receives and produces IN THIS CASE
## Loop-backs used the subset of the protocol's escalation table this case exercises
## Closure criteria matches the frontmatter `closure`
## Worked example link to ../examples/<case>-<project>.md, or "none yet"
Conventions the existing playbooks share, which yours should too:
- Open with a Purpose paragraph and the
[H]/↺Legend before the first section. - Name agents as
NN-agent-slugin the flow block and as`NN`in prose. - Mark conditional steps
(~)in the flow and Conditional in the phase-by-phase entry, and always say what makes them fire. - Number the phase-by-phase entries continuously across phases. Inserting a step means renumbering the ones after it.
- State a KEY INVARIANT where the case has one.
defecthas "reproduce with a failing test first";brownfield-onboardhas "reconstruct only what exists";deprecationhas "no silent deletion". A case without an invariant is usually a case that has not been thought through. - Document deliberate non-use. Where a case pointedly does not use an agent another case
would, say so and why —
brownfield-onboarddoes this for09and23. Silence reads as an oversight; an explicit "not used" reads as a decision.
Step 4 — Add the matrix column and reconcile it
In process/playbooks/README.md:
- Add the case to the picker and the column-abbreviation legend.
- Add a column to the case × agent matrix — one cell for every one of the 29 agents.
x= used ·–= not used ·~= conditional (opt-in per run). - Add a sentence to the "Reading the columns" paragraph explaining the column's shape.
The matrix header claims "Every column is authoritative — each is taken from the agent set its playbook actually runs." Make that true in both directions:
- Cell is
xor~→ the ID is in that playbook'sagents:list and appears in the body. - Cell is
–→ the ID is not in theagents:list.
Step 5 — Verify
# frontmatter present and ordered
head -20 process/playbooks/<case>.md
# all seven sections, in order
grep -n '^## ' process/playbooks/<case>.md
# every agents: ID exists in the roster
grep '^agents:' process/playbooks/<case>.md
Reconcile the matrix against every playbook mechanically. The check lives in the test suite, not in this skill, so it cannot silently go stale when the matrix grows a column:
uv run pytest tests/test_matrix.py tests/test_playbooks.py # or: just test
test_matrix.py derives the columns from the matrix header and the case list from the
playbook files, fails if it parses zero rows, and fails on any cell where x/~ disagrees
with that playbook's agents: list. CI runs it on every pull request; run it locally before
you push.
Finally, bump the case count in README.md (e.g. "10 cases" → "11 cases") and add the case to the
list in the "What's covered" section.
Hard rules (playbook-schema.md §3)
- Project-agnostic. A playbook describes the case, never a specific project. Project
specifics live in
process/examples/(narrative) andruns/(real artifacts). - References, never redefinitions. Name roster agents by ID; link protocol sections. Never restate an agent's scope or a gate's semantics.
- No time estimates. Ordering reflects dependency only, never duration.
- Drop-in, not rewire. If a case needs an agent the roster lacks, the roster gets the agent first, as its own change.
Conformance checklist
-
caseequals the filename stem and the matrix column header - All nine frontmatter fields present
- Every
agents:ID exists in the roster; conditional agents included - All seven body sections, in the fixed order
- Purpose paragraph and
[H]/↺legend before the first section - Phase-by-phase numbering continuous; every conditional step says what fires it
- Deliberate non-use of an agent is stated, not left silent
- Matrix column added and reconciled in both directions
- Case counts updated in
process/playbooks/README.mdandREADME.md -
closuretraceable to handoff-protocol §6.1 or a documented variant
Reference
process/playbooks/playbook-schema.md— authoritative; this skill is its working formprocess/playbooks/README.md— the picker and the case × agent matrixprocess/agent-roster.md— the agent registryprocess/agent-handoff-protocol.md— §3 gates, §4 loop-backs, §6 closure