The record · v0.1.0 · Apache-2.0

@flashyos/playbook

A way organisations work together, as a document rather than code

playbook/1 — a way two or more organisations work together, as a published document rather than code. Named roles, ordered steps, and an evidence kind per step. Authored by an org, served at its own domain, adopted by reference.

npm install @flashyos/playbooknpm ↗source ↗

Why it exists

The ways two organisations could collaborate used to be compiled into our API — seven of them, as an array in a TypeScript file. Adding an eighth meant a code review and a deploy, and no organisation could describe how it works with partners. Social posts, press releases, research, sales, shared leads, events, integrations: “everything” is not a list anybody finishes writing, so the list stopped being code.

What it refuses to do

A playbook describes work; it never creates it. Instantiating one produces a proposal, and every participating organisation’s human consents before any of it becomes real — there is no flag that skips that.

How it works

`playbook/1` is a published document: named roles, ordered steps, and a kind of evidence per step. An organisation authors it, serves it beside its other machine surfaces, and anyone adopts it by reference — the id carries the authoring org, which is what makes it attributable once it has been copied into somebody else’s proposal.

Roles, not sides. The shape it replaces carried a comment conceding that “a” and “b” are meaningless past two organisations. `bindRoles` makes the old two-sided case fall out of the general model, and a step owed by `each` produces one task per participant — which is how a three-party collaboration works as naturally as a two-party one.

Four evidence kinds, and only one is a link. Requiring a public URL is right for an article and wrong for a closed deal, where it asks two companies to publish a customer in order to prove they served one. A countersigned step publishes nothing about the work, only the agreement that it happened.

`instantiate` returns steps rather than writing rows: it touches no database, so a proposal can be previewed before anybody consents to it.

Related concepts

IntentMesh agentic autonomous organization machine-readable organizational trust AI agent trust register

Use it

Adopt a playbook from another organisation’s domain

import { assertPlaybook, bindRoles, instantiate } from '@flashyos/playbook'

const doc = await fetch('https://gda.group/.well-known/playbooks/quarterly-brief.json').then((r) => r.json())
assertPlaybook(doc)

const work = instantiate(doc, bindRoles(doc, [proposer, partner]))

In practice

Describe how your organisation works with partners

A firm writes its own playbook — the roles, the steps, what closes each one — serves it at its own domain, and partners adopt it by URL. Nothing is filed with us and no code changes anywhere.

Express work that cannot be published

A shared pipeline or a closed lead completes on a countersignature rather than a link, so the record shows the work happened without either company publishing a customer to prove it.

How it stays honest

The seven playbooks FlashyOS publishes are generated from the in-code templates they replace, and a differential test runs both engines over the same organisations and asserts the tasks come out identical — titles, briefs, owners and order. A snapshot test would pass the day somebody regenerates a wrong playbook; this one caught a real defect the hour it was written, where a placeholder rotated the wrong way and asked an organisation to publish about itself.

Questions

What is playbook/1?

A published document describing how organisations work together: named roles, ordered steps, and a kind of evidence per step. Authored by an organisation, served at its own domain, and adopted by reference rather than filed with anybody.

Why are there four kinds of evidence?

Because requiring a public URL is right for an article and wrong for a closed deal. A step can close on a fetched page, a sealed commit, a live endpoint, or the counterparty’s countersignature — which publishes nothing about the work itself.

Can a playbook start work on its own?

No. Instantiating one produces a proposal and nothing more. Every participating organisation’s human approves before any of it becomes real, which is the same consent rule the rest of the record follows.

How do I check a playbook I did not write?

Call validate() and it returns every problem at once rather than the first — the author is on another domain and cannot be asked a follow-up question. A JSON Schema ships alongside for readers who are not on JavaScript.

The licence

Apache-2.0, read from the package’s own manifest. Embed it in anything, including closed software — that is what makes a spec adoptable and a verifier worth running. FlashyOS’s server side is AGPL-3.0-only instead, and a test in the monorepo asserts the direction between them: AGPL code may consume this, this may never consume AGPL code.

Keep reading

The standard Machine surfaces

Also in the record

@flashyos/canon @flashyos/directory @flashyos/backlog @flashyos/shiplog @flashyos/checkpoint @flashyos/delivery @flashyos/frontdoor