Skip to content
bucker

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_template or org_skill families: 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

  1. An agent calls playbooks_propose with a slug, a title and a definition. The first call is an ask (input_required) with the approval card. playbook.propose carries the registry's ask floor: no policy row, earned rung or review mode makes it apply by itself.
  2. A person with configure_playbooks decides it. The yes is bound to the plan digest.
  3. 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_CHANGED and nothing is stored. A replayed answer buys nothing.
  4. 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 http entry on the organization's egress allow-list (egress.host.add is human-only). An empty list does not mean "anything goes" for a template.
  • action_template.create stores 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 least disruptive) 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 a branch after the step may read only status, http_status, ok, bytes and truncated. 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.run asks 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