Documentation Index

Fetch the complete documentation index at: https://docs.runmaestro.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Local Manifest for Custom Playbooks

​

Overview

• File Location: <userData>/local-manifest.json (same directory as marketplace-cache.json)
• Format: Same structure as the official manifest.json from GitHub
• Optional: If the file doesn’t exist, Maestro works normally with official playbooks only
• Hot Reload: Changes to local-manifest.json automatically refresh the Playbook Exchange

​

Use Cases

​

1. Bespoke Playbooks

• Internal tools and workflows
• Proprietary processes
• Environment-specific automation
• Company-specific security policies

​

2. Playbook Development

• Test playbook structure and documents
• Refine prompts and loop behavior
• Validate asset bundling
• Preview in the UI before publishing

​

How It Works

​

Merge Semantics

1. Override: Local playbooks with the same id as official ones override the official version
2. Append: Local playbooks with unique ids are added to the catalog
3. Source Tagging: All playbooks are tagged with source: 'official' | 'local' for UI distinction

Official playbooks: [A, B, C]
Local playbooks:    [B_custom, D]
Merged result:      [A, B_custom, C, D]
                         ↑ override   ↑ append

​

Path Resolution

• Absolute paths: /Users/me/.maestro/custom-playbooks/security
• Tilde paths: ~/maestro-playbooks/security
• Import behavior: Files are copied from the local path instead of fetched from GitHub

​

Schema

​

Required Fields

• id - Unique identifier (use same ID as official to override)
• title - Display name
• description - Short description for search and tiles
• category - Top-level category
• author - Creator name
• lastUpdated - Date in YYYY-MM-DD format
• path - Local filesystem path or GitHub path
• documents - Array of document entries with filename and resetOnCompletion
• loopEnabled - Whether to loop through documents
• prompt - Custom prompt or null for Maestro default

​

Optional Fields

• subcategory - Nested category
• authorLink - URL to author’s website
• tags - Searchable keyword array
• maxLoops - Maximum loop iterations (null for unlimited)
• assets - Asset files from assets/ subfolder

​

Creating a Local Playbook

​

Step 1: Create Playbook Files

~/my-playbooks/security-audit/
├── 1_SCAN.md
├── 2_ANALYZE.md
├── 3_REPORT.md
├── README.md (optional)
└── assets/
    ├── config.yaml
    └── rules.json

​

Step 2: Create local-manifest.json

{
	"lastUpdated": "2026-01-17",
	"playbooks": [
		{
			"id": "security-audit-internal",
			"title": "Internal Security Audit",
			"description": "Custom security audit for our infrastructure",
			"category": "Security",
			"author": "Security Team",
			"lastUpdated": "2026-01-17",
			"path": "~/my-playbooks/security-audit",
			"documents": [
				{ "filename": "1_SCAN", "resetOnCompletion": false },
				{ "filename": "2_ANALYZE", "resetOnCompletion": true },
				{ "filename": "3_REPORT", "resetOnCompletion": false }
			],
			"loopEnabled": false,
			"prompt": null,
			"assets": ["config.yaml", "rules.json"]
		}
	]
}

​

Step 3: Open Playbook Exchange

​

Step 4: Import and Use

​

Hot Reload

1. Edit your local manifest
2. Save the file
3. The Playbook Exchange automatically reloads (500ms debounce)
4. No need to restart Maestro

​

Error Handling

​

Invalid JSON

​

Missing Required Fields

​

Local Path Doesn’t Exist

​

File Watch Errors

​

UI Indicators

• Badge: Blue “Local” badge next to category
• Tooltip: “Custom local playbook” on hover
• Search: Works across both official and local playbooks
• Categories: New categories from local playbooks appear in filters

​

Development Workflow

​

Testing Before Publishing

1. Create your playbook files locally
2. Add to local-manifest.json
3. Test import and execution in Maestro
4. Refine documents and prompts
5. When ready, submit a PR to Maestro-Playbooks
6. Remove from local manifest once published

​

Overriding Official Playbooks

{
  "id": "development-security",  // Same as official
  "title": "Dev Security (Custom)",
  "path": "~/my-version/dev-security",
  ...
}

• Add custom documents
• Modify prompts
• Change loop behavior
• Test improvements before contributing

​

Troubleshooting

​

Playbook Doesn’t Appear

1. Check JSON syntax in local-manifest.json
2. Verify all required fields are present
3. Look for warnings in console logs
4. Ensure path field is set correctly

​

Import Fails

1. Verify the local path exists
2. Check file permissions on playbook directory
3. Ensure documents have .md extension
4. Verify assets exist in assets/ subfolder

​

Hot Reload Not Working

1. Check console for file watcher errors
2. Verify local-manifest.json path is correct
3. Try restarting Maestro
4. Check file system permissions

​

Related Files

• Manifest types: src/shared/marketplace-types.ts
• Marketplace handlers: src/main/ipc/handlers/marketplace.ts
• Import logic: marketplace:importPlaybook handler
• UI component: src/renderer/components/MarketplaceModal.tsx
• React hook: src/renderer/hooks/batch/useMarketplace.ts

​

Security Considerations

• Local manifest is not synced or shared
• Paths are validated before file operations
• Local-only playbooks remain private
• No network requests for local paths
• File watching is non-blocking and fails gracefully

​

Future Enhancements

• JSON schema validation
• Visual editor for local manifest
• UI controls to manage local playbooks
• Relative paths from Auto Run directory
• Local manifest templates
• Import/export for sharing local manifests