playbook-a2ml

PLAYBOOK.a2ml

:toc: left :toclevels: 2 :icons: font

Machine-readable executable plans and operational runbooks.

Part of the A2ML Format Family — A2ML (Annotated Markup Language) TOML-like key-value data formats for software engineering workflows.

The A2ML Format Family

Format	Purpose	Repository	Tier
META.a2ml	Architecture decisions, governance	hyperpolymath/meta-a2ml	Primary
STATE.a2ml	Project state, milestones	(companion to META)	Primary
ECOSYSTEM.a2ml	Ecosystem positioning	(companion to META)	Primary
PLAYBOOK.a2ml	Executable plans, runbooks	hyperpolymath/playbook-a2ml	Execution
AGENTIC.a2ml	AI agent gating, safety	hyperpolymath/agentic-a2ml	Execution
NEUROSYM.a2ml	Symbolic semantics	hyperpolymath/neurosym-a2ml	Execution
ANCHOR.a2ml	Project recalibration	hyperpolymath/anchor-a2ml	Intervention

What is PLAYBOOK.a2ml?

PLAYBOOK.a2ml defines how permitted actions are executed, not whether they are permitted (that’s META) or whether they may proceed now (that’s AGENTIC).

PLAYBOOKs are derived from:

• META rules (architectural decisions)

• STATE context (current project phase)

• Validated user intent (explicit present request)

# SPDX-License-Identifier: PMPL-1.0-or-later

[playbook.derivation-source]
type = "derived"
meta-rules = ["adr-001", "adr-015"]
state-context = "beta-phase"
timestamp = "2026-01-03T12:00:00Z"

[playbook.procedures.build]
description = "Build the project"
on-failure = "abort-and-notify"

[[playbook.procedures.build.steps]]
step = 1
action = "deno task build"
timeout = 300

[[playbook.procedures.build.steps]]
step = 2
action = "deno task test"
timeout = 600

[playbook.procedures.deploy]
description = "Deploy to production"
requires-confirmation = true
on-failure = "rollback-and-alert"

[[playbook.procedures.deploy.steps]]
step = 1
action = "backup-current"

[[playbook.procedures.deploy.steps]]
step = 2
action = "push-to-prod"

[[playbook.procedures.deploy.steps]]
step = 3
action = "verify-deployment"

Why PLAYBOOK.a2ml?

Feature	Benefit
Derived Authority	Plans inherit authority from META, cannot introduce new permissions
Gated Execution	All execution is subject to AGENTIC safety controls
Auditable	All executions and failures are recorded in journals
Machine-Readable	Tooling can parse, validate, and execute plans
Rollback-Aware	Failure handling and rollback strategies built-in
Cross-Format	Integrates with META, STATE, AGENTIC, NEUROSYM

Execution Pipeline

PLAYBOOKs execute within a defined order:

1. META validation      -> Constitutional authority check
2. AGENTIC gating       -> Operational safety check
3. NEUROSYM semantics   -> Proof obligations discharge
4. PLAYBOOK derivation  -> Build executable plan
5. Execution            -> Run the plan
6. ECOSYSTEM check      -> Integrity verification
7. STATE update         -> Record success/failure

Core Sections

Derivation Source (derivation-source)

Declares where the PLAYBOOK’s authority comes from:

• type - "derived" (default) or "non-derived" (if META permits)

• meta-rules - Which ADRs authorize this PLAYBOOK

• state-context - Current project phase

• agentic-gate - AGENTIC status at derivation time

Procedures (procedures)

Executable plans with:

• description - Human-readable purpose

• preconditions - Required state before execution

• steps - Ordered actions with timeouts

• postconditions - Expected state after success

• on-failure - Failure handling strategy

Alerts (alerts)

Notification configuration:

• Severity levels (info, medium, high, critical)

• Channels (slack, pager, email)

• Escalation delays

Contacts (contacts)

On-call and escalation contacts.

Getting Started

Create a PLAYBOOK.a2ml File

# SPDX-License-Identifier: PMPL-1.0-or-later
# SPDX-FileCopyrightText: 2026 Your Name
# PLAYBOOK.a2ml -- Operational Runbook

[playbook.derivation-source]
type = "derived"
meta-rules = ["adr-001"]
timestamp = "2026-01-03T00:00:00Z"

[playbook.procedures.build]
description = "Build the project"
on-failure = "abort"

[[playbook.procedures.build.steps]]
step = 1
action = "deno task build"

Specification

The formal specification is in the spec/ directory:

• PLAYBOOK-FORMAT-SPEC.adoc - Complete specification

Examples

See the examples/ directory:

• minimal.scm - Minimal valid PLAYBOOK

• comprehensive.scm - Full-featured example

Conformance Requirements

A PLAYBOOK is conformant if:

1. It is derived from META (or explicitly permitted as non-derived)

2. It does not bypass META or AGENTIC

3. Execution ordering is preserved

4. Failures are properly recorded

Media Type

• MIME Type: application/vnd.playbook+a2ml

• File Extension: .a2ml (conventionally PLAYBOOK.a2ml)

• Encoding: UTF-8

Failure Modes

If PLAYBOOK execution fails:

• The system MUST rollback or branch

• STATE MUST NOT be committed

• The failure MUST be recorded in the journal

• Alerts MUST be triggered

Related Specifications

• META.a2ml - Architecture decisions

• AGENTIC.a2ml - Operational gating

• NEUROSYM.a2ml - Symbolic semantics

License

PMPL-1.0-or-later with Palimpsest philosophical overlay.