Adding a playbook

The library grows from real work. Every time we build a setup with a customer, we ask whether it would help other workspaces in the same sector, and if it would, it becomes a playbook here. A playbook copies structure only: which segments, forms, follow-ups and reports exist, how they connect, and their timings. It never copies a person, a contact detail or anything that identifies the customer.

The process

1. Export the workspace’s setup. After the build, run the export script against the customer’s workspace with an admin’s token (see the export script). It reads segments, forms, templates, follow-ups, teams, reports, saved questions, funnels and dashboards through the admin API, and never reads people, profiles, submissions, team members or message logs. It only reads; nothing in the workspace changes.

2. Strip every identifier. The script does the mechanical part: ids become references ({{ ref.form_card.id }}), the workspace’s id, name and links are removed, sender addresses become {{ params.email_from }}, team names become parameters, and timestamps, counts and authors are dropped. It then lists everything that still looks like an identifier (email addresses, phone-like numbers, URLs, the workspace name and its words) as REVIEW: lines. Clear every one by hand. Words inside templates and task instructions are where names hide: the customer’s name in a sign-off, a pastor’s or manager’s name, a street, a local landmark. Replace them with a parameter or neutral words.

3. Turn workspace values into parameters. Anything another customer would answer differently becomes a parameter: the organisation’s name, team names, delays and due times, report schedules, the sender address, the default phone country, lists like areas or branches. Pick about five to ask (ask: true) and give the rest defaults. Rewrite the text in the sector’s words, and for a base playbook in neutral words (“people”, “contacts”, “teams”). Fill in summary, when_to_use, timings, requires.channels and customer_must: who must join which team, which channels need a verified sender or business verification, what to publish and test.

4. Review, then add it. Save it as public/playbooks/<sector>/<slug>.yaml with source.kind: engagement, the build’s date, and an opaque source.ref (eng-YYYY-MM-<sector>-<letter>, never the customer’s name). Then:

   npm run playbooks:pages   # creates the docs page for a new spec
   npm run playbooks:check   # validates every spec and rebuilds index.json
   npm run build

   Open a pull request. A second person reviews the spec for people data and for anything that would identify the customer before it merges. The mapping from source.ref to the customer lives in the pull request, never in the docs.

No people data, ever

Not in a spec, not in a page, not in a pull request’s example output. If a template only reads well with a real name in it, the playbook isn’t ready. The validator fails on email addresses, phone-like numbers, ws_/usr_ ids, UUIDs, tokens and links outside origamy.io, but it can’t recognise a name: the review step has to.

Writing one without an engagement

For a sector we haven’t built with yet, write the playbook from the base patterns and mark it source.kind: synthesized (no date or ref needed). Keep it to what the product does today, say in customer_must which events the customer’s systems must send, and replace it with an engagement playbook once we’ve built the real thing with a customer.

Write it for the business as it really runs. Most small businesses have no developer, so get the data in through a form, a booking form, a staff form or a synced sheet (see Patterns for small businesses), and fill requires.data_in honestly. Use app_events only when the playbook can’t work without an app, and offer a no-code path next to it where there is one. Messages should sound like the business: short, warm, in the channels its customers use (SMS and WhatsApp first in many markets).

The eval prompt

Every playbook has an eval block: the request a customer would type, in their words, and what a good answer must contain. When the playbook is added, the same prompt is added as a live copilot eval in the data plane (internal/orchestrator/copilot/testdata/evals/NN_<name>.json, with a live block). For an engagement playbook, use the customer’s own request where it names no people or places. Number the evals after the highest one already there.

The export script

ORIGAMY_TOKEN=… npm run playbooks:export -- \
  --api https://app.origamy.io \
  --workspace 42 \
  --sector church \
  --slug first-timer-to-member \
  --out /tmp/first-timer-to-member.yaml

• ORIGAMY_TOKEN is the bearer token of an admin signed in to the workspace. Keep it in the environment; never paste it into a file, a spec or a pull request.
• --api is the dashboard’s origin. The script only sends GET requests to /v1/admin/….
• --out should be outside the repository: the draft still needs the review in step 2.
• Add --only workflows,reports to export some kinds only.

The draft it writes is a starting point, not a playbook: the questions, the wording, the summary and customer_must are yours to write.