Skip to content
PLAYBOOK.md Docs

Extensions

The PLAYBOOK.md specification is designed to be extensible. This page collects the extension points and future considerations documented across the v0.1.0 spec.

Design Principles for Extensions

Extensions to the spec should follow these principles:

  • Backwards compatible — existing playbooks must remain valid when new features are added
  • Gracefully degradable — implementations that don’t support an extension should skip it with a warning, not fail
  • Markdown-native — new syntax should feel natural within a markdown document

Planned Extension Areas

Branching Enhancements

The current branching model supports == and != string comparison only. Future versions may add:

  • Logical combinators (AND, OR) for compound conditions
  • Numeric operators (>, <, >=, <=) with type coercion
  • Nested branching within sub-steps
  • Pattern matching (contains, startsWith, regex)

See Branching for the current specification.

Artifact Enhancements

The artifacts system currently supports a single type declaration. Future versions may add:

  • Multiple artifacts — a playbook could declare multiple output artifacts from different steps
  • Custom types — implementation-specific artifact types beyond the standard set
  • Schema validation — for json artifacts, an optional JSON Schema could validate output structure

See Artifacts for the current specification.

Additional Directive Types

The current directive set (@output, @elicit, @prompt, @tool) covers the core execution patterns. Future directives may address:

  • Retry logic — automatic retry with backoff for failed steps
  • Parallel execution — running independent steps concurrently
  • Conditional directives — directives that activate based on conditions

Conformance Levels

Implementations may support the spec at different levels:

LevelRequirements
ParseCan parse a playbook document into a structured representation. Reports fatal errors and warnings per spec.
Execute (Basic)Parse + can execute linear playbooks (no branching, no directives). Steps run sequentially with context accumulation.
Execute (Full)Basic + branching, all directives (@output, @elicit, @prompt, @tool), pause/resume.
StreamFull + real-time token streaming during step execution.

Contributing

The PLAYBOOK.md specification is open and community-driven. If you have proposals for extensions, open an issue or discussion on the playbook-spec repository.