playbook.md

A Playbook is a folder of markdown files, and playbook.md is the one every Playbook has. It carries the front matter that declares what this Playbook is, and a body with the prose that binds every step.

Required

Four fields, and a Playbook without them is not one.

• name: what it is called.
• slug: its identifier, which is also its folder.
• version: an integer.
• category: which shelf it belongs on.

Always written

Two more are written on every save, empty if there is nothing to say.

• required_connectors: the tools this Playbook needs. A bare name means the operator's own access satisfies it; the longer form can say otherwise. See Playbook scope and Runtime scope.
• references: the reference files it reads.

Optional, and what absence means

Each of these can be left out, and leaving it out is not the same as leaving it blank: the absence has a defined meaning.

• outcome: the promise, in one line.
• intake: how it collects what it needs. Absent means a form.
• artifact: what kind of thing it produces. Absent means a document.
• delivery: where the outcome goes. Absent means both in the app and by email. See Delivery, which explains what this declaration does and does not control.
• type and trigger: whether it recurs, and what starts it.
• cadence and default_schedule: the human phrasing, and the actual schedule. Only the second one makes anything run.
• final_output_stage: which step produces the deliverable. Absent means the last one.
• outputs: named outputs, when one document is not enough.
• template: whether this is a template others may copy.
• default_retry: the retry policy for its steps.

The body

Three sections, and they are the ones you edit as prose: ## Goal, ## Persona and ## Rules.

Goal is what a run delivers. Persona is who the work reads as coming from. Rules are the absolutes. Persona and Rules apply to every step at run time, which is why a rule is worth more than an instruction: written once, enforced everywhere.

Everything else you might expect to see in the body is a projection of the front matter or of the other files rather than something you write twice.

Where the rest lives

The ordered steps are separate files. See Play files. The input contract is inputs.md, which declares each input's key, label, type and whether it is asked every run or set once. There is no per-Playbook connectors file: the list is the front matter field above.