Skip to main content

Playbooks in the UI

A playbook is a curated guided template: a named recipe with an intent, a beat sequence, the tools it drives, its parameters, and its durable gotchas. You can browse playbooks, read one in detail, and instantiate it into a runnable test — all in the web UI. (Agents drive the same playbooks over MCP.)

Find it in the sidebar under Platform Testing → Playbooks (/playbooks).

Browse​

The list groups playbooks by category (e.g. CONTRACT_ANCHOR, PERF_FROM_API, PROJECT_SETUP, SECURITY_SWEEP). Each card shows the playbook's name, its intent (the one-line "what this is for"), a short description, and chips for how many tools and gotchas it carries. The search box filters by name, intent, category, or tag.

Click a card to open its detail.

Detail​

The detail page (/playbooks/:id) shows everything the playbook contains:

  • Intent — the outcome it's built to produce.
  • Beats — the guided narrative (the ordered steps a human or agent walks through).
  • Tool Sequence — the platform tools it drives, in order.
  • Parameters — inputs it needs, each with a prompt and default.
  • Triggers — when this playbook is a good fit.
  • Durable Gotchas — see below.

Instantiate​

Instantiate turns the playbook into a runnable artifact (usually an API scenario). Requires ANALYST or ADMIN.

  1. Click Instantiate.
  2. Pick a Project and Environment, and fill in the playbook's parameter values (pre-filled with defaults).
  3. Leave Dry run on to preview — you get the filled YAML back plus a valid/invalid chip, and nothing is created.
  4. Turn Dry run off and click Create Scenario to persist it; the result links straight to the new scenario.

PROJECT_SETUP playbooks are special: instantiating one returns a filled onboarding payload that seeds the Onboard Project wizard rather than a scenario.

Durable Gotchas​

A gotcha is a durable fact about running a playbook — a contract detail, an enum, a required parameter — not a transient bug. Each is either:

  • REQUISITE — a truth the run fails without (shown in red), or
  • ADVISORY — a best practice.

ANALYST/ADMIN can Add or Delete gotchas on a playbook. Add is durability-gated on the server: bug-shaped text (e.g. "currently returns 500", "workaround", "until fixed") is rejected inline with a "file a bug" message — bugs are temporary and don't belong here. VIEWER sees gotchas read-only, and cannot instantiate.