Playbook
Domain-specific operational patterns expressed in Markdown
What is a Playbook?
Playbooks are domain-specific operational patterns expressed in Markdown. They define how Spry processes and emits content for specific use cases.
A Spry Playbook is:
Human-readable
Written in standard Markdown that anyone can read and understand
Machine-actionable
Axiom rules turn it into an executable graph
Service-specific
Projection and emitters tailored for specific domains
Deterministic
Produces reproducible outputs every time
Composable
Supports imports, partials, and reusable behaviors
The Playbook Pipeline
Every playbook follows the same conceptual flow:
graph LR
A[Markdown] --> B[Parse]
B --> C[Analyze]
C --> D[Project]
D --> E[Emit]Define
Author Markdown with fenced blocks, frontmatter, decorators, and attributes.
Parse
remark parses Markdown into an AST (mdast).
Analyze
Axiom rules establish structural edges, semantic decorators, dependency relationships, and cell classifications.
Project
A specialized projection interprets the graph for the target domain.
Emit
Concrete artifacts are produced: SQL files, HTML pages, JSON data, or execution steps.
Available Playbooks
SQLPage Playbook
Build complete web applications using SQL and Markdown.
Use case: Data dashboards, admin panels, internal tools
Artifacts:
.sqlfiles for SQLPagesqlpage_filestable entries- Route forests and breadcrumbs
- Configuration files
Example:
---
sqlpage-conf:
database_url: sqlite://app.db
port: 9227
---
# My Application
```sql index.sql { route: { caption: "Home" } }
SELECT 'card' AS component, 'Welcome' AS title;
```Commands:
spry sp spc --fs dev-src.auto --conf sqlpage/sqlpage.jsonspry sp spc --package | sqlite3 app.dbRunbook Playbook
Automate operational procedures with executable documentation.
Use case: DevOps, deployments, maintenance tasks
Artifacts:
- Executable shell tasks
- Task DAG execution
- Execution reports
- JSON summaries
Example:
---
runbook:
name: Deployment
---
# Deployment Runbook
```bash check --descr "Pre-flight checks"
./preflight.sh
```
```bash deploy --depends check --descr "Deploy application"
./deploy.sh
```Commands:
# List all tasks
spry rb ls
# Run with verbose output
spry rb run --verbose rich
# Run specific task
spry rb task deployData Quality Playbook
Define and execute data validation rules.
Use case: Data pipelines, ETL validation, quality assurance
Artifacts:
- DQ tests and suites
- SQL validation checks
- JSON assertions
- Provenance documents
Example:
# Data Quality Checks
@dataset users
## Users Table
@expect row_count > 0
```sql check-users-exist
SELECT COUNT(*) as count FROM users;
```
@expect no_nulls email
```sql check-emails
SELECT COUNT(*) FROM users WHERE email IS NULL;
```Data Quality Playbooks help ensure data integrity throughout your pipelines with automated validation checks.
Compliance Playbook
Document policies and generate compliance evidence.
Use case: Audit preparation, policy documentation, evidence collection
Artifacts:
- Control mappings
- Evidence documents
- Audit trails
- Status reports
Example:
---
doc-classify:
role: evidence
framework: SOC2
control: CC6.1
---
# Access Control Verification
```bash verify-access -C ./evidence/access-check.json
./audit-access.sh
```Playbook Components
Frontmatter
Configure the playbook behavior using YAML frontmatter:
---
sqlpage-conf:
database_url: ${env.SPRY_DB}
web_root: ./dev-src.auto
playbook:
name: My Playbook
version: 1.0
---Environment variables can be referenced using ${env.VARIABLE_NAME} syntax in frontmatter.
Executable Cells
Code that runs during execution:
```bash task-name --descr "Description"
./script.sh
```Materializable Cells
Content that becomes output files:
```sql page.sql
SELECT 'text' AS component;
```Directives
Control how content is processed:
```sql PARTIAL layout.sql --inject **/*
SELECT 'shell' AS component;
```Decorators
Attach metadata to sections:
@id my-section
## My SectionCreating Custom Playbooks
For advanced users, custom playbooks can be created by:
Define a projection
Create a projection that interprets the graph for your specific domain
Create emitters
Build emitters that produce your target artifacts
Build CLI commands
Implement CLI commands to interact with your playbook
See Plugin Development Guide for detailed instructions.
Playbook Selection
Spry determines the playbook based on:
Command used
rb for runbook, sp for SQLPage
Frontmatter
Configuration keys indicate type
File content
Cell types and directives
Best Practices
Single Responsibility
Each Spryfile should focus on one playbook type:
# App Dashboard
---
sqlpage-conf:
database_url: sqlite://app.db
---
```sql index.sql
SELECT 'card' AS component;
```Focused on SQLPage with clear configuration
# Mixed Playbook
---
sqlpage-conf:
database_url: sqlite://app.db
runbook:
name: Deployment
---Mixing multiple playbook types causes confusion
Clear Documentation
Document the playbook's purpose at the top:
# Server Maintenance Runbook
This runbook performs routine server maintenance:
1. Check server health
2. Backup databases
3. Apply updates
4. Verify services
## Prerequisites
- SSH access to servers
- Database credentials in environmentGood documentation helps team members understand what a playbook does and how to use it safely.
Reusable Components
Use PARTIAL and imports for shared content:
```sql PARTIAL nav.sql --inject **/*.sql
SELECT 'shell' AS component, 'App' AS title;
```
```import --base ./shared
sql helpers.sql TAIL
```Version Control
Include version information in frontmatter:
---
playbook:
name: Deployment Pipeline
version: 2.1.0
updated: 2025-01-15
---Related Topics
Spryfiles
Learn about document structure and syntax
Code Cells
Understand cell syntax and attributes
Architecture
Explore Spry's internal design
Plugin Development
Build custom extensions
Next Steps
Choose a playbook type
Decide which playbook best fits your use case
Create your first Spryfile
Follow the examples above to create a basic playbook
Test execution
Run your playbook and verify the output
Iterate and refine
Add more cells, dependencies, and documentation
How is this guide?
Last updated on