@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. | | checkContract(doc, playbook?) | Every contract/1 finding, as { rule, at, message }[]. Empty means valid. | | isContract(doc, playbook?), assertContract(doc, playbook?) | Type guard, and throw with every reason at once. | | contractSubject(doc) | The contract without seal, countersignatures, revisions — what the seal is over. | | derive(doc, { now }) | { inForce, why, expiresInDays }, judged against the now you pass. | | verifyContract(doc, playbook, { hash, verifySignature }) | The injected half: the seal against your hash, each countersignature against your verifier. | | CONTRACT_VERSION, CONTRACT_SINCE, DERIVED_FIELDS | '1'; the version to pin on; the four fields refused by name. |

The four evidence kinds

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

A step declares its kind and a claim must match it — otherwise everything arrives as url, because a link is the cheapest thing to produce.

import { checkClaim, verifyEvidence } from '@flashyos/playbook';

checkClaim(step, { kind: 'attested', statement: 'The introduction arrived.', by: theirOrgId });

attested is the one kind that does not require publishing the work — a closed lead, a shared pipeline, an embargoed finding. What makes it worth anything is that an organisation cannot attest its own step. Without that it is weaker than a link: an org would close its own work by saying it happened.

checkClaim is offline and dependency-free. verifyEvidence takes the fetch, the digest and the signature as functions you supply — a kind with no verifier comes back unverified, never holds, because a checker that silently accepts what it cannot check is indistinguishable from one that really checked.

The thirteen FlashyOS publishes

playbooks/, with src/catalogue.ts saying where each came from.

Seven migrated from the templates that were compiled into the API — co-marketing, content exchange, data pilot, joint research, referral partnership, roadmap collaboration, capability pool. src/parity.test.ts proves each produces exactly the tasks its template did.

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

Six authored for work the two-sided shape refused: joint announcement, shared lead, co-selling, integration, joint event, incident response. Each has to say in the catalogue what it expresses that nothing else did — otherwise "authored" becomes the bucket for anything inconvenient.

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.

contract/1 — when the proposal becomes an agreement

A machine-readable agreement between two organisations is not a new package. It is a playbook, instantiated, that every party's human has consented to, sealed, and countersigned by every other party. Every piece already existed; CONTRACT.md is the profile that composes them, and its one home is here.

Pin @flashyos/playbook at ^0.2.0 if you read contracts. CONTRACT_SINCE is 0.2.0 — the first version with checkContract at all — exported so the figure is read from code rather than remembered, and a test asserts this README and that constant agree.

Two organisations, one playbook, one contract

FlashyOS proposes co-marketing to Brinc. The contract is authored by FlashyOS (its slug is in the id), so Brinc is the one that countersigns.

import { checkContract, contractSubject, derive, playbookFor, verifyContract } from '@flashyos/playbook';

const playbook = playbookFor('co-marketing')!;   // roles: proposer, partner

const contract = {
  contract: '1',
  id: 'contract/flashyos/co-marketing-brinc-2026',
  playbook: playbook.id,
  parties: [
    { role: 'proposer', orgId: 'org_flashyos', orgName: 'FlashyOS', orgSlug: 'flashyos' },
    { role: 'partner',  orgId: 'org_brinc',    orgName: 'Brinc',    orgSlug: 'brinc' },
  ],
  terms: { expires: '2027-09-20T12:00:00Z', notes: 'One piece each, on a channel each controls.' },
  consents: [
    { orgId: 'org_flashyos', by: 'person/michael', at: '2026-09-19T09:00:00Z' },
    { orgId: 'org_brinc',    by: 'person/manav',   at: '2026-09-19T15:30:00Z' },
  ],
  seal: { hash: sealHash, sealedAt: '2026-09-20T12:00:00Z' },
  countersignatures: [
    { orgId: 'org_brinc', kid: 'brinc-2026', sig: brincSignature, over: sealHash },
  ],
};

// Offline, dependency-free, every finding at once. Pass the playbook and the
// parties must bind exactly its roles.
for (const f of checkContract(contract, playbook)) {
  console.log(`[${f.rule}] ${f.at}: ${f.message}`);
}

// Derived, never asserted. `now` is yours to pass — nothing here reads a clock.
const { inForce, why, expiresInDays } = derive(contract, { now: '2027-03-20T12:00:00Z', playbook });

Where sealHash came from is the caller's half: it is the hash of contractSubject(contract) — the document without seal, countersignatures and revisions — through @flashyos/verify's canonicalisation. This package computes no hash and verifies no signature; you inject both, exactly as verifyEvidence takes verifiers:

import { canonicalStringify, hashPayload } from '@flashyos/verify';

const verdict = await verifyContract(contract, playbook, {
  hash: (subject) => hashPayload(canonicalStringify(subject)),
  verifySignature: (sig, over, kid, orgId) => brincKeys.verify(sig, over, kid), // your Ed25519 verifier
});
// { state: 'holds' } | { state: 'unverified', reason } | { state: 'fails', findings }

A missing hash or verifySignature comes back unverified, never holds.

The rules a contract cannot bend

• Consent is by a person. Every consents[].by is a person/<slug>; an agent/… is refused. A party that has not consented makes the contract invalid, not pending. There is no auto-consent.
• An organisation cannot sign its own claim. Every party other than the author countersigns; the author's own countersignature is refused as self-countersign. over must equal seal.hash.
• A derived field is never asserted. status, state, active and inForce are refused by name, at any depth. derive computes them.
• A correction is appended, never edited. Negotiation is revisions[], each { id, at, by: 'person/…', reason (≥ 24 chars), proposes, supersedes? }, in order; out of order, by an agent, or superseding anything but an earlier revision is refused.

Not on JavaScript? schema/contract-1.schema.json is the structural half. CONTRACT.md names the eight relational rules it cannot express.

Versions

0.2.0 (CONTRACT_SINCE) adds contract/1: checkContract, isContract, assertContract, contractSubject, derive, verifyContract, the schema and CONTRACT.md. Nothing about playbook/1 moved; every 0.1.0 export is here unchanged.

0.1.0 is playbook/1: the format, the four evidence kinds, instantiate, and the thirteen published playbooks.

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