Play files

Each step is its own file, named for its position and its slug, in the Playbook's plays folder: play-01-audit-page.md, then play-02-…, and so on. The front matter declares the contract; everything below it is the instruction.

Required

Six fields. A step file without all six is not valid.

• stage: its position, from 1.
• name: its identifier, referred to by other steps.
• title: the human sentence.
• input: what it expects to be handed.
• output: what it promises to produce.
• tools: the Connectors it may call. This one is required and may be empty, which is deliberate: a step has to state that it calls nothing rather than say nothing.

Optional

• gate: human to pause for approval before proceeding. Absent means no gate. See Approvals.
• references: the reference files this step reads.
• reads: the earlier steps whose output it takes.
• model: pin a specific model, rather than letting routing choose.
• search: declare that this step searches the web as it works, and with which provider.
• persona: craft text baked into this step alone.
• retry: how many attempts, and how long to wait between them.
• phase: whether it gathers, composes or finishes.
• skill: which library Skill this step was imported from, where it was.

The rule about reads

Absent does not mean "nothing". A step with no reads takes the output of the step immediately before it, which is the ordinary chain. Naming steps in reads is how you say something other than that: take the output of steps one and three, and skip two.

That is the one place in this format where an omission means something specific rather than nothing, so it is worth knowing before you delete the line.

The body

Markdown, conventionally under an ## Instructions heading. Values from the input contract are written as {{inputs.<key>}} and are replaced with the answers before the step runs.

A real one

URL SEO Audit's first step is stage: 1, name: audit-page, titled "Research the page". Its input is the URL from the run inputs; its output is research notes. It declares no tools, no gate, and that it searches with a search provider. Its instruction is one paragraph.