Skip to main content

​
What are Playbooks?

Playbooks are reusable Auto Run configurations that define a sequence of markdown documents with tasks for AI agents to execute. They enable you to:
  • Automate repetitive workflows across projects
  • Create looping task sequences for continuous integration
  • Share workflows with your team
  • Build complex multi-document automation pipelines

​
Playbook Structure

A playbook consists of:
1

Document Queue

An ordered list of markdown files containing task checkboxes
2

Configuration

Settings like loop mode, reset behavior, and prompt templates
3

Worktree Settings

Optional git worktree integration for isolated execution

​
Playbook Data Model

Playbooks are stored as JSON files in ~/.config/maestro/playbooks/ (or equivalent on your platform): 
interface Playbook {
  id: string;
  name: string;
  createdAt: number;
  updatedAt: number;
  documents: PlaybookDocumentEntry[];
  loopEnabled: boolean;
  maxLoops?: number | null;
  prompt: string;
  worktreeSettings?: {
    branchNameTemplate: string;
    createPROnCompletion: boolean;
    prTargetBranch?: string;
  };
}

interface PlaybookDocumentEntry {
  filename: string;
  resetOnCompletion: boolean;
}

​
Creating a Basic Playbook

1

Create task documents

Create markdown files with checkboxes in your Auto Run folder:
# Feature Implementation

- [ ] Implement user authentication
- [ ] Add unit tests for login flow
- [ ] Update API documentation
Press Cmd+L (Mac) or Ctrl+L (Windows/Linux) to quickly insert checkboxes.
2

Configure the run

  1. Open the Auto Run tab (Cmd+Shift+1)
  2. Click Run to open the configuration modal
  3. Click + Add Docs to add documents to the queue
  4. Drag documents to reorder them
  5. Configure per-document options:
    • Reset on Completion - Creates working copies instead of modifying originals
    • Duplicate - Add the same document multiple times
3

Save as playbook

  1. Click Save as Playbook
  2. Enter a descriptive name (e.g., “Security Audit Workflow”)
  3. The playbook is saved and appears in the Load Playbook dropdown

​
Playbook Configuration Options

​
Loop Mode

Enable Loop Mode to cycle back to the first document after completing the last one: 
# Continuous Integration Loop

- [ ] Run test suite
- [ ] Check for security vulnerabilities
- [ ] Update dependency versions
- [ ] Commit changes if tests pass
With loop mode enabled, this playbook runs indefinitely until you stop it. 
{
  "loopEnabled": true,
  "maxLoops": null  // Run forever
}

​
Reset on Completion

When enabled for a document:
  • Creates a working copy in Runs/ subfolder
  • Original document is never modified
  • Working copies serve as audit logs (e.g., TASK-1735192800000-loop-1.md)
  • Critical for looping playbooks to maintain clean state each iteration
Each task executes in a completely fresh AI session with its own unique session ID. No conversation history bleeds between tasks, ensuring predictable behavior across loop iterations.

​
Custom Prompts

The prompt is prepended to each task when sent to the AI agent. Use template variables for dynamic content: 
You are working on {{AGENT_PATH}} as part of the {{PLAYBOOK_NAME}} workflow.
Current date: {{DATE}}
Git branch: {{GIT_BRANCH}}

Complete the following task:
See Slash Commands for all available template variables.

​
Advanced Patterns

​
Multi-Phase Workflows

Organize documents by phase for complex projects: 
auto-run-docs/
├── 01-planning.md
├── 02-implementation.md
├── 03-testing.md
├── 04-documentation.md
└── 05-deployment.md
Configure the playbook to run these sequentially, with reset enabled on all documents for audit trails.

​
Worktree Integration

Dispatch playbooks to git worktrees for isolated execution:
1

Enable worktree mode

In the run configuration modal, toggle Dispatch to a separate worktree
2

Configure worktree

  • Base Branch: Branch to base the worktree on (e.g., main)
  • Worktree Branch Name: Name for the new branch
  • Automatically create PR: Opens a PR when the run completes
3

Save in playbook

Worktree settings are saved in the playbook’s worktreeSettings field
Example Worktree Settings
{
  "worktreeSettings": {
    "branchNameTemplate": "autorun/{{DATE}}-security-audit",
    "createPROnCompletion": true,
    "prTargetBranch": "main"
  }
}
Worktree playbooks require your project to be a git repository with at least one commit.

​
Playbook Management

​
Loading Playbooks

  1. Open the Auto Run panel
  2. Click the Load Playbook dropdown
  3. Select a saved playbook
  4. Configuration is loaded (documents, loop settings, prompt)

​
Updating Playbooks

After loading a playbook:
  1. Modify documents, order, or settings
  2. Click Update Playbook to save changes
  3. Or click Discard Changes to revert to saved version

​
Sharing Playbooks

Playbooks are stored per-session in: 
# macOS
~/Library/Application Support/maestro/playbooks/<session-id>.json

# Linux
~/.config/maestro/playbooks/<session-id>.json

# Windows
%APPDATA%/maestro/playbooks/<session-id>.json
To share a playbook:
  1. Locate the playbook JSON file
  2. Copy to another agent’s playbook directory
  3. Or use the Playbook Exchange for community playbooks

​
Using the Inline Wizard

Generate playbooks from conversational descriptions:
1

Start the wizard

Type /wizard in any AI tab or click the Wizard button in Auto Run
2

Describe your project

Have a natural conversation about your goals:
“I want to build a REST API for user management with authentication, CRUD operations, and rate limiting.”
3

Build confidence

Watch the confidence gauge build as the AI understands requirements (80%+ triggers generation)
4

Generate documents

The AI creates detailed Auto Run documents in a subfolder under your Auto Run folder
The wizard uses these system prompts:
  • src/prompts/wizard-inline-new.md - Initial conversation
  • src/prompts/wizard-inline-iterate.md - Refining requirements
  • src/prompts/wizard-document-generation.md - Document creation

​
Playbook Best Practices

Each checkbox should be a single, verifiable action. Avoid compound tasks like “Implement authentication and add tests” — split into two checkboxes.
Name playbooks clearly: “Weekly Security Audit” instead of “Audit” or “Security Workflow v2” instead of “v2”.
Always use Reset on Completion for documents in looping playbooks to maintain clean state.
Run a playbook once in non-loop mode to verify all tasks work correctly before enabling loop mode.
Make prompts dynamic with {{DATE}}, {{GIT_BRANCH}}, {{AGENT_PATH}} for context-aware execution.

​
Troubleshooting

Playbook not appearing in dropdown Playbooks are session-specific. Ensure you’re viewing the dropdown in the correct agent session. Tasks not completing Check that checkboxes use the correct markdown syntax: - [ ] with a space between brackets. Working copies not created Verify “Reset on Completion” is enabled for the document and the Runs/ subfolder has write permissions. Worktree creation fails Ensure:
  • Your project is a git repository
  • The base branch exists
  • The worktree branch name is valid (no spaces or special characters)
  • You have write permissions in the project directory

Build docs developers (and LLMs) love

Get started for freeTalk to us