@flashyos/playbook

playbook/1 — a way organisations work together, as a published document.

A playbook names the roles in a collaboration, the steps each role owes, and the kind of evidence that closes each one. An organisation authors it, serves it at its own domain, and anyone can adopt it by reference.

npm install @flashyos/playbook

Apache-2.0, so you can embed it. No account, no key, no service to call.

Why

The ways two organisations could collaborate used to be compiled into the FlashyOS API — seven of them, as a TypeScript array. Adding an eighth meant a code review and a deploy, and no organisation could describe how it works with partners.

Social posts, press releases, R&D, sales, shared leads, events, devops, integrations: "everything" is not a list anybody finishes writing. So the list stopped being code.

SPEC.md is the format and the reasoning.

Use it

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

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

// Throws with every reason at once — the author is on another domain and
// cannot be asked a follow-up question.
assertPlaybook(doc);

const work = instantiate(doc, bindRoles(doc, [
  { id: 'org_1', name: 'GDA Capital', slug: 'gda-capital' },
  { id: 'org_2', name: 'Brinc', slug: 'brinc' },
]));

for (const step of work) {
  console.log(step.orgId, '·', step.title, '·', step.evidence);
}

instantiate returns steps, not rows. It writes nothing and touches no database — which is what lets the parity test run both engines side by side, and what lets you preview a proposal before anybody consents to it.

Check one without adopting it

import { validate } from '@flashyos/playbook';

for (const finding of validate(doc)) {
  console.log(`[${finding.rule}] ${finding.at}: ${finding.message}`);
}

Not on JavaScript? schema/playbook-1.schema.json is the structural half. SPEC.md names the four relational rules it cannot express, so you know exactly what a schema-only check is not doing for you.

API

| Export | What it does | |---|---| | validate(doc) | Every finding, as { rule, at, message }[]. Empty means valid. | | isPlaybook(doc) | Type guard. | | assertPlaybook(doc) | Throws with every reason at once. | | bindRoles(playbook, orgs) | Binds organisations to roles positionally — the proposer first. | | instantiate(playbook, bindings) | The work: one InstantiatedStep per task. | | fill(template, ctx) | Placeholder substitution on its own. | | EVIDENCE_KINDS, EVERY_ROLE | The vocabulary, declared once. |

The four evidence kinds

| Kind | Claims | Checked by | |---|---|---| | url | A public artefact exists | Fetching it | | sealed | A specific commit shipped | Recomputing a shipped/1 digest offline | | endpoint | A contract holds right now | Calling it and asserting the response | | attested | The counterparty agrees it happened | Ed25519 countersignature |

attested is the one that does not require publishing the work — a closed lead, a shared pipeline, an embargoed finding. Nothing about the thing becomes public, only the agreement that it occurred.

The seven FlashyOS publishes

playbooks/ — co-marketing, content exchange, data pilot, joint research, referral partnership, roadmap collaboration, capability pool.

They are generated from the recipe canon they replace, and src/parity.test.ts proves both produce identical tasks. Regenerate and check for drift:

node scripts/from-recipes.mjs           # write
node scripts/from-recipes.mjs --check   # fail if they drifted

What it will not do

A playbook describes work; it never creates it. Instantiating one produces a proposal, and every participating organisation's human consents before anything becomes real. Agents suggest; humans consent.

Part of the FlashyOS mesh, beside @flashyos/directory, @flashyos/backlog, @flashyos/shiplog and @flashyos/countersign.