Playbooks and Versions

A Playbook is a logical container with an implicit owner, visibility, explicit editors, an optional official alias, latest Version, and archive state. Its actual content lives in immutable Versions, so a title or Step change always creates a new historical fact instead of rewriting the definition used by past work.

Definition

A Version contains schemaVersion, title, description, one category, an input schema, and an ordered list of Steps. Categories are productivity, programming, design, sales, marketing, operations, and learning.

The input schema is JSON Schema Draft 2020-12 with an object root. It describes accepted Case input; it does not cause Epismo to execute the Playbook.

Each Step has:

Steps do not have status, assignees, transitions, retry policy, dependencies, or completion timestamps. An agent may skip, combine, reorder, or extend them.

Publishing and identity

Creating a Playbook creates the container and Version 1 atomically. Publishing another Version requires baseVersionId. If the latest Version changed, publication fails with a conflict instead of overwriting concurrent work.

The server normalizes a Definition, stores canonical JSON, and calculates a sha256: digest. Equivalent JSON or YAML formatting produces the same content identity. A Case pinned to a Version stores its Version ID and digest so the guidance it started with remains verifiable.

New Steps omit IDs; the server assigns them. Preserve an existing ID only when the Step is the same logical Step. Removed IDs are not reused.

Archiving Versions

An owner manager can archive a historical Version from its detail page, the CLI, MCP, or the HTTP API. Archived Versions disappear from normal lists, direct reads, and new Case starts. Their numbers are never reused: if Version 2 is archived after Versions 1–3 were published, the visible history is Versions 1 and 3, and the next publication is Version 4.

The latest Version cannot be archived because it remains the Playbook's current definition and the base for Drafts and future publications. Existing Cases keep their pinned Version reference and continue to operate, but the archived Version's content is no longer exposed through normal reads.

Drafts

A Playbook has at most one Draft: mutable, unpublished content that an owner manager can save any number of times without minting a Version. Each save takes the revision last read (0 for a first Draft); a stale revision is rejected, the same discipline as a base-version conflict on publish.

A Draft follows Playbook edit access: editors and owner managers can read and edit it, while public readers and share links cannot. Publishing a Draft mints a new Version from its content and discards the Draft in the same step; discarding it directly leaves the published Version untouched.

Discovery and references

Search readable Playbooks by text and category, or browse the web catalog by resource kind and normalized resource reference. The catalog groups equivalent GitHub and npm URL and provider-specific forms together, while keeping resource kinds separate. Star useful Playbooks or assign an alias in your active namespace. Each personal or managed Workspace namespace can give one alias to a readable Playbook. Canonical display forms are pb:alias for a locally resolved alias and pb:handle/alias for a named namespace. The Playbook owner's alias is displayed and indexed as official. A third-party alias is shown only to its namespace owner as "your alias" and is not indexed. An alias never grants access and always points to the logical Playbook, not one Version.

Share tokens provide token-based read access without changing permanent access. Public Playbooks expose their instructions and resource hints, so remove secrets, signed URLs, internal-only references, and personal data before setting visibility to public.