Playbooks

Playbooks give the agent your team's runbooks — durable, version-controlled markdown files the agent loads when relevant keywords appear in a user message.

Playbooks vs Apps — quick disambiguation. A Playbook is a single markdown file the agent reads as context (think: "how we do X"). An App (§15 bundle) is a deployable unit with a UI form, a workflow, and a versioned package — what you scaffold with /app create and run with /app run or the headless insightworker app run <slug>. Playbooks shape how the agent thinks; Apps define what the agent runs end-to-end. They compose — an App's plan.md is essentially the playbook for that App, and a global playbook can apply across many Apps.

Where they live

Scope	Path
Per-workspace (recommended)	`<workspace>/.insightworker/playbooks/<name>.md`
Global (your machine)	`~/.insightworker/playbooks/<name>.md`

Per-workspace files are typically committed to the project's git repo so the whole team gets the same agent behavior.

What playbooks are good for

Team conventions — "our git app is squash-and-rebase, never merge"
Domain rules — "for property submissions, always check the SOV against COPE data before quoting"
Reusable instructions — "when generating sprint digests, always use these section colors and order"
Mappings — "when a broker says 'Type IV construction', map to ISO Class 3"

If a teammate would benefit from knowing it, write a playbook. If only the current session benefits, let memory handle it.

Anatomy

---
triggers: [email, draft, reply, broker]
---

# Email Style — Property Underwriting Team

## Salutations
- External brokers: "Hi <FirstName>" (never "Dear")
- Internal teammates: First name only, no greeting line
- Senior leadership: "Hi <FirstName>," with comma

## Sign-offs
- Default: "Best,\nSarah"
- When declining: "Thanks for the look — Sarah"
- When asking for more info: "Appreciated — Sarah"

## Tone
- Direct, never flowery. No "I hope this email finds you well."
- Use contractions when emailing brokers (you're, we'll). NOT in formal coverage letters.
- Bullet point action items when there are 2+ asks. Otherwise prose.

The triggers: frontmatter array tells the resolver which keywords activate this playbook. When the user says "draft a reply to the broker", the agent loads this file into context.

How matching works

Triggers match against the user's message in a case-insensitive substring sense. To control matching:

Multiple triggers — any single hit activates the playbook (OR semantics)
Phrases — use "phrase trigger" if you want a multi-word match: triggers: ["weekly digest", "sprint review"]
Conflicts — if two playbooks both match, both are loaded (concatenated in alphabetical filename order)

To inspect what got loaded for a given prompt:

insightworker -c "/debug context for: 'draft a reply to the broker'"

Playbooks vs memory

	Playbooks	Memory
Lifetime	Permanent	Per-conversation, gradually persistent
Authored by	Humans	The agent (it writes its own memories)
Scope	Team-shared via git	Per-machine, per-workspace
Format	Markdown with frontmatter	Markdown with frontmatter
When to use	Conventions everyone should follow	"Remember this for next time" details from one conversation

Both are plain markdown — easy to read, easy to fork.

Examples — common playbook shapes

Code style playbook

---
triggers: [code, refactor, lint, format]
---

# Code Style

- TypeScript strict mode is non-negotiable
- Prefer `const` over `let`; never `var`
- Avoid default exports — named exports only
- Tests live next to source: `foo.ts` + `foo.test.ts`
- ESM imports, no CommonJS

Domain mapping playbook

---
triggers: [construction, ISO, property]
---

# Construction Class Mappings

| Broker term | ISO Class |
|---|---|
| Frame | 1 |
| Joisted Masonry | 2 |
| Non-Combustible | 3 |
| Masonry Non-Combustible | 4 |
| Modified Fire Resistive | 5 |
| Fire Resistive | 6 |

App override playbook

---
triggers: [migration, dag, airflow]
---

# Airflow → ADW Migration Conventions

When generating Oracle ADW SQL from Airflow DAGs:
- Always use `MERGE INTO` for upserts (not Postgres `INSERT ... ON CONFLICT`)
- Wrap CTAS in `EXECUTE IMMEDIATE` blocks for redeploy idempotency
- Schema names map: `prod_redshift.<x>` → `MIGRATED.<X>` (uppercase)

Versioning

Treat playbooks as code. Commit them to your project's git repo, review them in PRs, version them. The team that maintains the agent's behavior maintains these files.