Playbooks

A playbook is a recipe for a kind of work. When a request needs a multi-step plan, the planner sees the names, descriptions and selection conditions of the available playbooks, reads the one that matches, and plans from it. Without a matching playbook it plans from the roster of enabled agents.

A playbook is guidance, not an executable workflow language. The coordinator itself sees neither playbook names nor the agent roster. Only the planner does.

Note

Playbooks belong to the coordinator, which turns a request into a workflow of steps run by agents. The coordinator has its own switch for new workflows under Governance → General.

Layout

• Directoryplaybooks/

  • Directorysoftware-development/

    • PLAYBOOK.md

An organisation deployment layer can provide playbooks/<name>/PLAYBOOK.md, and plugins use the same layout, with an optional playbooks path in the manifest. A file in a playbook folder that is not named PLAYBOOK.md is skipped with a warning.

PLAYBOOK.md

playbooks/software-development/PLAYBOOK.md

---
name: software-development
description: Changes to an application or service
when: Build, change or fix software
---

1. architect: design the approach.
2. designer, when the user interface changes: prepare mockups and ask for sign-off.
3. coder: implement on a branch and run tests.
4. reviewer: review until approved, at most three rounds.
5. coder: open the pull request and post its link.

Done when: the reviewed pull request is open and its link is posted.

Field	Required	Limit
name	Yes in a plugin. A deployment-layer file defaults to the folder name	Lowercase letters, digits, hyphen or underscore, starting with a letter or digit, up to 64 characters
description	Yes	Up to 400 characters
when	Yes	The condition for choosing this playbook, up to 1,000 characters
Markdown body	Yes	The recipe, up to 64 KiB

Write each step as work to do, such as “design the approach” rather than “agree the approach”, which reads as asking the person first. Put a sign-off gate after the work it approves, never on the first step.

The older allow_automatic_progression key is ignored. Other unknown frontmatter keys are ignored with a warning.

Manage playbooks

Open Capabilities → Playbooks to create, edit or switch playbooks at the organisation or a team. Playbooks support on and off switches and organisation locks like other capabilities. Plugin-owned playbooks are read-only: edit the source repository and re-sync. An organisation lock overrides lower-scope switches.