Playbooks and Versions
Reusable guidance with immutable identity and flexible execution.
A Playbook is a logical container with an owner, ACL, aliases, 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:
| Field | Meaning |
|---|---|
id |
Stable four-character identity within the logical Playbook |
title |
Short description of the judgment-sized step |
instructions |
Guidance for a person or agent |
resourceHints[] |
Candidate skills, MCP servers, CLIs, APIs, plugins, graphs, documents, agents, or custom resources |
expectedOutputs[] |
Human- and agent-readable hints, not machine-enforced completion gates |
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.
Discovery and references
Search readable Playbooks by text and category, star useful ones, or assign an alias. Canonical display forms are pb:alias for a locally resolved alias and pb:handle/alias for an owner's public namespace. An alias never grants access and always points to the logical Playbook, not one Version.
Share tokens provide token-based read access without changing the permanent ACL. Public Playbooks expose their instructions and resource hints, so remove secrets, signed URLs, internal-only references, and personal data before adding public.