Playbooks
A playbook is a procedure written as typed data: the steps an on-call person would take, with the edges between them, in a form an agent can propose, a person can read in full, and nothing can run until a person has published its exact digest. There is no code in a playbook, no loop and no nested playbook, so what a run can do is computable from its definition alone.
This page covers the definitions: the grammar, the digest, the proposal and publish path, and the reads. Running a published playbook, its triggers and its budgets are a separate feature (MON-22).
Who may do what
| Act | Who | How |
|---|---|---|
Propose a draft (playbook.propose) |
An agent or a person with configure_playbooks |
playbooks_propose, or POST /orgs/:o/playbooks. Always asked, for the first draft and every further one. |
Retract the newest draft or restore (playbook.update), archive (playbook.archive) |
Same | POST /orgs/:o/playbooks/:slug/change; an agent's own drafts through operation_revert |
Publish a version (playbook.publish) |
A person only: an organization owner, behind a password step-up | POST /orgs/:o/playbooks/:slug/publish, naming the version and its digest |
Delete (playbook.delete) |
A person only | No door yet |
| Read | Any member with org read |
playbooks_list, playbook_get, actions_catalog_list, the REST reads |
A draft does nothing. It is an immutable row that no run can reach until a person publishes it. The agent proposes, a person decides the proposal, and a person publishes: three separate acts by separate people, which is the difference from a system where one permission creates, publishes and runs.
The grammar
A definition has steps (1 to 40), optional typed inputs (at most 10), limits, an optional
runbook, and essential (false: paused while an error budget burns). Every step has an id and
names where it goes next. Edges only point forward, to a later step or to end, so a loop cannot be
written, and every step must be reachable from the first.
| Kind | What it does |
|---|---|
query |
Runs a stored query spec by its digest. The spec is never embedded, and its result is data, never a command. |
governed_action |
One act of one operation family: { family, verb, input }. |
approval |
Asks people: a relation, a quorum of 1 or 2, an expiry of 5 minutes to 24 hours. onApproved, onRejected and onExpired are all required: a decision nobody makes still leads somewhere. |
wait |
Pauses for 1 to 240 minutes. The waits together must fit the run timeout (at most 240 minutes). |
branch |
Follows one of two edges on a typed comparison (eq, neq, gt, lt, in) of an earlier step's result. |
notify |
Tells the inbox or one Slack route, with counts only: there is no message field. |
customer_action |
A step in a customer's own system (MON-35). Refused until that package registers it. |
http_template |
One call from a published action template (DEL-22), named by { template, digest, input }: the slug and the digest of the version a person published. The template (method, https URL, header names, a flat parameter schema) is not in the definition and cannot be changed by it. See "Action templates" below. |
A parameter is a typed literal (at most 200 characters, no control characters) or a whole-string
binding: {{inputs.name}} or {{steps.<id>.<field>}}. Any other {{ is refused: there are no
expressions, no functions and no interpolation. A query result may be compared in a branch and is
never bound into an action's input, because it is data from telemetry.
What a governed_action may name
actions_catalog_list shows every act with its class, ask floor, conditional floors, inverse, TTL and
verification signal as fields, so a client sees before a person approves which steps will stop for one.
The same function decides what the grammar accepts. A step is refused at propose when it names:
- a family or verb that is not in the action registry;
- a human-only act: any publish, delete, ship, merge, enable of a human-only switch, approval-policy
change, or anything else the registry marks
humanOnly. No playbook can carry an act a human must perform; - a dual-control act, or an act whose class is CRITICAL (the infrastructure levers: rollback, scale, restart);
- a verb or object the earned-autonomy ladder forbids (
widen,launch,ship,resume,publish,certify,verify,delete,merge,erase; a host or a credential); - an act that is not an approvals or direct write;
- an act of the
playbook,playbook_run,action_templateororg_skillfamilies: a playbook never writes, publishes or runs a playbook, which keeps "no nested playbooks" true by construction.
A mitigation lever (mitigation.*) keeps its own class: the step always asks a person when a run
reaches it. A draft that carries one is asked for like every other draft.
The grammar is part of the input schema, so a definition that breaks it is refused where it is parsed, before a plan, an operation row, an approval request or an audit row exists. It is judged again when the draft is stored and again at publish, so a family the registry has since made human-only stops a version that was valid when it was proposed.
The digest
A version's digest is the SHA-256 of its parsed definition in canonical JSON (steps, edges, inputs, limits and runbook, with the grammar's defaults filled in) under a domain separator. Key order is not part of a definition. A caller cannot state a digest: the plan computes it, the approver is shown the one the apply writes, and the apply refuses a version that no longer hashes to the digest its plan carried.
A published version is immutable by digest. Publishing names the version and the digest the person
read. A different stored digest is a 409, a stored definition that no longer hashes to its digest is a
409 (digest_tampered), and a definition the grammar would now refuse is a 422. A published version can
never be retracted; a later publish of an older version is the rollback, and the audit row names the
previous digest.
From proposal to publication
- An agent calls
playbooks_proposewith a slug, a title and a definition. The first call is an ask (input_required) with the approval card.playbook.proposecarries the registry's ask floor: no policy row, earned rung or review mode makes it apply by itself. - A person with
configure_playbooksdecides it. The yes is bound to the plan digest. - The agent retries with the same answer. One apply stores an inert, unpublished version against
the revision it was asked on; if the playbook moved in between (a person renamed it, published a
version), the answer is
TARGET_CHANGEDand nothing is stored. A replayed answer buys nothing. - A person reads the playbook (
playbook_get, or the dashboard) and publishes the digest they read.
A further draft of an existing playbook is playbook.propose too, under the same floor: every
definition stored as a version was read by a person first. Retracting the newest unpublished draft and
restoring an archived playbook are playbook.update (asked by default). Archiving a draft is allowed;
archiving a published playbook is asked.
Action templates (DEL-22)
An http_template step calls one action template: an outbound HTTP call a platform team defined, which Bucker sends and never runs as code. A template is data: a method, an https URL template with the host written out (placeholders only in the path or query), the names of the headers it sends, and a flat parameter schema in which no free string is longer than 200 characters. Header values are never stored in a template: they come from a sealed connection credential at call time, and a call whose template names headers with no credential to supply them fails closed.
- The host must already be an active
httpentry on the organization's egress allow-list (egress.host.addis human-only). An empty list does not mean "anything goes" for a template. action_template.createstores a draft (SENSITIVE, asked). A person publishes its digest (action_template.publish, human-only,org:admin, password step-up). A published template is immutable: archive it (action_template.archive) and create a new slug.- The stored class is the declared one (
reversible,disruptive,irreversible) raised by the method (anything but GET is at leastdisruptive) and by the host (an explicit port or an IP literal is one step up). A run that names a template starts at the highest class among its templates. - A step pins the template's slug and digest; a template replaced afterwards stops serving the playbook until the new digest is read and the playbook published again. Publishing a playbook refuses a step whose template is missing, unpublished, at another digest or off the allow-list.
- The answer is untrusted text: the step stores the status, the size and a 300-character excerpt (control characters removed, credential-shaped spans masked, withheld whole if it echoes a header value) labelled
untrusted; no reader of a run is handed the excerpt, and abranchafter the step may read onlystatus,http_status,ok,bytesandtruncated. A non-2xx answer fails the step and the run; nothing retries. - No infrastructure template (restart, scale, roll back) exists until OD-DP-01, and there is no private action runner (OD-DP-09).
Running a playbook
A run starts from a published playbook by its digest: the digest you read (playbook_get) is the one the
run is bound to, so a revision published afterwards does not change what runs. playbooks_preview shows
the run without writing anything: for each governed step the family, the act, the class the registry
gives it and the class this plan derives, whether it will stop for a person, and the blast radius. It is
a separate read, never a flag on the run.
- Starting asks by default.
playbook.runasks a person, and always asks when the playbook carries a mitigation lever. The first call answers with the approval card; the retry that names their yes starts one run. - Each step is decided on its own, by the same engine and for the run's principal, with its own freezes, switches, floors and approvals. A step that asks waits for a person. A freeze or a switch that binds a person's run binds this one.
- A refusal ends the run, and nothing retries by itself. A human-only act is refused at run time, and merging is never a step.
- A run can be cancelled (
playbook_run.cancel), and paused and resumed. Cancelling stops what is left; it does not undo steps already taken, whose inverses are the ordinary operations.
Reads and what is untrusted
The reads share one visibility rule: a member with org read; a project-scoped playbook only for a
caller who can reach its project; an empty proposal never; another organization's playbook never. A
missing playbook, another organization's and an unreachable one are the same "not found".
A playbook's title, the runbook an author attached (text and owner team), every literal
step value and every string a branch compares against are written by members or agents. The tools strip control characters, cut before scanning,
mask credentials, scan and cap them under the register's classes (plan_echo, comment_body,
tag_key) and declare every path untrusted; the dashboard renders them as text, never as markup and
never as a link. A runbook is stored with an owner, a review date and an expiry.
Limits
| Steps per version | 40 |
| Versions per playbook | 50 |
| Playbooks per organization | 200 (and 25 waiting for their first draft) |
| Literal parameter | 200 characters, 16 keys per step |
| Runbook text | 2,000 characters |
| Run timeout | 240 minutes; one wait 240 minutes; one approval 24 hours |