Tools

PLAYBOOK.md ships a set of developer tools for authoring, validating, and integrating playbook files into your workflow. This page covers everything from the command-line interface to CI/CD automation.

CLI

The playbook CLI is a terminal tool for validating, parsing, inspecting, and scaffolding PLAYBOOK.md files. Built in Go with the Charm ecosystem for styled output.

Install

go install github.com/PLAYBOOK-MD/playbook-cli@latest

Or build from source:

git clone https://github.com/PLAYBOOK-MD/playbook-cli.git
cd playbook-cli
go build -o playbook .

Commands

`playbook validate`

Check one or more playbook files against the spec. Exit code 0 means all files are valid; 1 means one or more have errors.

# Validate a single file
playbook validate my-workflow.playbook.md

# Validate multiple files with a glob
playbook validate *.playbook.md

# JSON output for CI pipelines
playbook validate --json *.playbook.md

# Silent mode (exit code only)
playbook validate --quiet *.playbook.md

`playbook parse`

Parse a playbook into its structured AST representation.

# Pretty-printed AST with styled header
playbook parse my-workflow.playbook.md

# Raw JSON output
playbook parse --json my-workflow.playbook.md

`playbook summary`

Display a compact summary card showing title, description, step list, input/step counts, and feature badges (branching, elicitation, tool calls).

# Styled summary card
playbook summary my-workflow.playbook.md

# "info" is an alias
playbook info my-workflow.playbook.md

`playbook convert`

Convert a playbook to JSON format.

# Output to stdout
playbook convert my-workflow.playbook.md --to json

# Write to a file
playbook convert my-workflow.playbook.md --to json --output workflow.json

`playbook init`

Scaffold a new playbook through an interactive form. Walks you through setting title, description, step count, and optional features (inputs, branching, artifacts), then generates a .playbook.md file.

# Interactive form
playbook init

# Specify output path
playbook init --output my-new-workflow.playbook.md

`playbook setup`

Configure AI coding tools for PLAYBOOK.md support. Auto-detects tools in the current project or lets you choose from a list. Generates MCP server configs and agent instruction files. See Editor Integrations below for details.

# Auto-detect and configure
playbook setup

# Specify a tool directly
playbook setup --tool claude-code

# Preview without writing files
playbook setup --dry-run

`playbook tui`

Launch an interactive terminal UI for browsing and inspecting playbooks in a directory.

# Browse current directory
playbook tui

# Browse a specific directory
playbook tui ./workflows

Repository: PLAYBOOK-MD/playbook-cli

VS Code Extension

Syntax highlighting, real-time validation, CodeLens, hover information, and snippets for .playbook.md files.

Install

The extension is not yet published to the VS Code Marketplace. To install locally:

git clone https://github.com/PLAYBOOK-MD/playbook-vscode.git
cd playbook-vscode
npm install
npm run build
npx @vscode/vsce package
code --install-extension playbook-md-0.1.0.vsix

Features

Syntax highlighting for all PLAYBOOK.md elements — section headers, directives, variable interpolation, input declarations, branching, and fenced code blocks. An injection grammar also highlights PLAYBOOK.md syntax inside standard Markdown files.

Real-time validation runs on open, save, and as you type (500ms debounce). Diagnostics appear in the Problems panel.

Fatal Errors	Description
F1	No `# Title` heading found
F2	No `## STEP N: Title` heading found
F3	Duplicate input names
F4	Document exceeds 200KB
F5	Empty or whitespace-only document

Warnings	Description
W1	Non-sequential step numbers
W2	Malformed input line in INPUTS section
W3	Unknown artifact type
W4	Undeclared branch variable
W5	Invalid elicit type
W6	Undeclared interpolation variable
W7	Output name shadows an input variable

CodeLens annotations appear above key sections for a structural overview:

Title — step count, input count, overall validity
Steps — “Step N of M” with directives used
Inputs — total inputs and how many are required
Artifacts — declared artifact type

Hover information for variables ({{variable}}), directives (@output, @elicit, @tool, @prompt), and step headings. Shows context like input type, source step for outputs, and directive explanations.

Snippets for quickly scaffolding common structures:

Prefix	Description
`pb-playbook`	Full playbook scaffold
`pb-step`	Step with title and output
`pb-input`	Input variable declaration
`pb-inputs`	INPUTS section with examples
`pb-system`	SYSTEM prompt section
`pb-branch`	IF/ELSE branching
`pb-output`	`@output` directive
`pb-artifact`	ARTIFACTS section
`pb-elicit`	`@elicit` directive
`pb-tool`	`@tool` directive

Configuration

Setting	Default	Description
`playbook-md.enableValidation`	`true`	Enable/disable real-time validation
`playbook-md.enableCodeLens`	`true`	Enable/disable CodeLens annotations
`playbook-md.enableHover`	`true`	Enable/disable hover information

Repository: PLAYBOOK-MD/playbook-vscode

GitHub Action

Validate .playbook.md files on pull requests with inline annotations and a summary table.

Basic workflow

name: Validate Playbooks
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: PLAYBOOK-MD/playbook-action@v1

Custom pattern

Validate playbooks in a specific directory:

- uses: PLAYBOOK-MD/playbook-action@v1
  with:
    pattern: 'workflows/**/*.playbook.md'

Strict mode

Treat warnings as errors (fail the check if any warnings are found):

- uses: PLAYBOOK-MD/playbook-action@v1
  with:
    strict: 'true'

Using outputs

Access validation results in subsequent steps:

- uses: PLAYBOOK-MD/playbook-action@v1
  id: validate
- run: |
    echo "Valid: ${{ steps.validate.outputs.valid }}"
    echo "Total: ${{ steps.validate.outputs.total }}"
    echo "Errors: ${{ steps.validate.outputs.errors }}"
    echo "Warnings: ${{ steps.validate.outputs.warnings }}"

Inputs and outputs

Input	Description	Default
`pattern`	Glob pattern for playbook files	`*/.playbook.md`
`strict`	Treat warnings as errors	`false`

Output	Description
`valid`	Whether all playbooks are valid (`true`/`false`)
`total`	Total number of playbooks validated
`errors`	Total number of errors found
`warnings`	Total number of warnings found

Badge

Add a validation badge to your README:

![PLAYBOOK.md Validated](https://img.shields.io/badge/PLAYBOOK.md-validated-FF5F1F)

Repository: PLAYBOOK-MD/playbook-action

Editor Integrations

The playbook setup command configures AI coding tools to understand PLAYBOOK.md files. It generates MCP server configs (so the tool can parse, validate, and convert playbooks) and agent instruction files (so the AI knows the spec rules).

Automatic setup

Run playbook setup in your project root. The CLI auto-detects which tools are present and writes the appropriate config files:

playbook setup

If nothing is detected, an interactive prompt lets you choose from the supported tools. You can also specify a tool directly:

playbook setup --tool claude-code

Supported tools

Files created:

.mcp.json — MCP server config
CLAUDE.md — Agent instructions

{
  "mcpServers": {
    "playbook-md": {
      "command": "npx",
      "args": ["-y", "@playbook-md/mcp"]
    }
  }
}

Run playbooks as Claude Code Routines. Commit the playbook-run skill into .claude/skills/playbook-run/SKILL.md and create a routine at claude.ai/code/routines pointing at your .playbook.md. See Run Playbooks as Claude Code Routines for the full three-step recipe, prompt templates per trigger type, and the compatibility matrix.

Files created:

.codex/config.toml — MCP server config
AGENTS.md — Agent instructions

[mcp_servers.playbook-md]
command = "npx"
args = ["-y", "@playbook-md/mcp"]

Files created:

.opencode.json — MCP server config

{
  "mcp": {
    "playbook-md": {
      "command": "npx",
      "args": ["-y", "@playbook-md/mcp"]
    }
  }
}

Files created:

.continue/config.json — MCP server config

{
  "mcpServers": [
    {
      "name": "playbook-md",
      "command": "npx",
      "args": ["-y", "@playbook-md/mcp"]
    }
  ]
}

Files created:

.vscode/mcp-settings.json — MCP server config

{
  "mcpServers": {
    "playbook-md": {
      "command": "npx",
      "args": ["-y", "@playbook-md/mcp"]
    }
  }
}

Files created:

CONVENTIONS.md — Project conventions

Aider does not support MCP, so the setup writes a conventions file that teaches the agent the PLAYBOOK.md spec rules and validation commands.

All MCP configs point to @playbook-md/mcp, which requires npx (Node.js) on the machine.

Pre-commit Hook

Validate staged .playbook.md files before every commit. The hook automatically detects whether the playbook CLI or npx is available and uses whichever it finds.

Install

Copy the hook from the integrations repo into your project:

curl -o .git/hooks/pre-commit \
  https://raw.githubusercontent.com/PLAYBOOK-MD/playbook-integrations/main/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Or, if you already have the integrations repo cloned:

cp path/to/playbook-integrations/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

{
  "husky": {
    "hooks": {
      "pre-commit": "./hooks/pre-commit"
    }
  }
}

pre-commit:
  commands:
    validate-playbooks:
      run: ./hooks/pre-commit

The hook only runs when staged files matching *.playbook.md are present. If no playbook files are staged, the hook exits immediately with success.

Source: playbook-integrations/hooks/pre-commit