---
name: playbook-format
description: Defines the contract for LolaCore Playbook files — frontmatter, body structure, and size limits.
domain: core
type: system
version: 1.0.1
min_lolacore_version: 1.9.0
---

## Purpose

A **playbook** is curated, bounded domain context that Lola (an LLM agent) consults when working in a specific area. Unlike memory (what happened) or skills (how to act), playbooks describe **what exists and which rules apply** in a domain — plugin APIs, FSE anatomy, brand guidelines, etc.

Playbooks are **not** raw document dumps. They are distilled, actionable reference material sized to fit in a single prompt delivery. **Audience: downstream LLM agents, not human readers.** Write dense, operational content (definitions, routing, constraints) — not tutorial prose or marketing copy.

## Key concepts

### Frontmatter (hard contract)

Every playbook is a Markdown file with YAML frontmatter between `---` delimiters, followed by the body.

| Field | Required | Type | Notes |
|---|---|---|---|
| `name` | Yes | string (kebab-case) | Unique slug; sanitized with `sanitize_title` |
| `description` | Yes | string ≤ 200 chars | Short summary for listings |
| `domain` | Yes | string | e.g. `fse`, `acf`, `core`, `brand` |
| `type` | No | `system` \| `project` | Default `system` for files, `project` for DB |
| `ability_prefixes` | No | string[] | Triggers delivery when matching abilities run |
| `triggers.keywords` | No | string[] | Hints for model-adaptive delivery |
| `version` | No | semver | e.g. `1.0.0` |
| `min_lolacore_version` | No | semver | Minimum core version required |

### Body (soft contract)

Recommended sections:

- `## Purpose` — domain boundary and when this playbook applies
- `## Key concepts` — terminology maps, routing tables, lifecycles (agent-oriented, not end-user docs)
- `## Rules` — MUST/SHOULD constraints the agent enforces at runtime
- `## Examples` — optional compact SPEC_TEMPLATES

Missing sections produce warnings, not rejections. The body **must** stay within the size limit.

### Size limit

Maximum body size: **~1,500 tokens** (~6,000 characters). Playbooks that exceed this are rejected at validation. Curate aggressively — one focused manual beats a wiki paste.

## Rules

**Do include:**

- Actionable domain knowledge Lola needs at execution time
- Clear rules and constraints ("always use X", "never do Y")
- Terminology maps for the domain
- Version-specific behaviour when relevant

**Do not include:**

- Raw document dumps or unedited exports
- Marketing copy or defensive negations ("this is not…", "we don't support…")
- Content that belongs in memory (site-specific facts) or skills (behavioural protocols)
- Secrets, API keys, or credentials

## Examples

Minimal valid playbook:

```markdown
---
name: example-domain
description: Short summary under 200 characters.
domain: example
type: system
---

## Purpose
What this playbook covers.

## Key concepts
- Term A: definition
- Term B: definition

## Rules
1. Always verify before writing.
2. Prefer reversible actions.
```

When creating playbooks via chat, MCP, or the admin upload flow, format the full markdown (frontmatter + body) and pass it to `create_playbook`. The store validates every write regardless of origin.

The upload distiller system prompt includes a **reference output** few-shot (`PlaybookDistillTemplate::referenceOutputExample`) on a non-domain topic (`brand`) to demonstrate LLM-to-LLM density without colliding with the source topic. Large sources trigger a minimum body-size quality gate and extraction priorities (DECISION tables, STATE lifecycles, checklist rules).
