START HERE - Playbook Guide

THIS IS REQUIRED READING. Read this playbook FIRST before starting ANY task.

Read playbooks: systemprompt core playbooks show <playbook_id>

How SystemPrompt Works

The Flow

+------------------------------------------------------------------+
|                         USER                                      |
|                           |                                       |
|                           v                                       |
|                    +-------------+                                |
|                    |  PLAYBOOK   |  <-- User reads playbook       |
|                    +------+------+      to learn how to           |
|                           |             interact with agent       |
|                           v                                       |
|                    +-------------+                                |
|                    |    CLI      |  <-- User sends task           |
|                    +------+------+      via CLI to agent          |
|                           |                                       |
|                           v                                       |
|  +------------------------------------------------------------+  |
|  |                       AGENT                                 |  |
|  |                         |                                   |  |
|  |           +-------------+-------------+                     |  |
|  |           v             v             v                     |  |
|  |      +--------+   +----------+   +---------+               |  |
|  |      | SKILLS |   | MCP      |   | TOOLS   |               |  |
|  |      |        |   | SERVERS  |   |         |               |  |
|  |      +--------+   +----------+   +---------+               |  |
+------------------------------------------------------------------+

1. Agents Execute Tasks

Agents are AI workers that perform tasks using:

• Skills - Reusable capabilities (e.g., "write blog post", "analyze code")
• MCP Servers - External tools and integrations
• Tools - Built-in functions available to the agent

2. Users Interact via CLI + Playbooks

Users should NOT guess how to interact with agents. Instead:

1. Find the agent's playbook - Each agent has a corresponding playbook
2. Read the playbook - Learn the correct commands and workflow
3. Use the CLI - Send tasks to agents following the playbook

IMPORTANT: Interacting with Agents

If you are asked to interact with an agent, you MUST:

1. Find the playbook for that agent:

   systemprompt core playbooks list --category content   # For content agents
   systemprompt core playbooks list                      # List all playbooks
   

2. Read the playbook:

   systemprompt core playbooks show <playbook_id>
   

3. Follow the playbook instructions - The playbook contains:

   • How to send messages to the agent
   • Required parameters and format
   • Expected responses
   • Error handling

4. Use the CLI to interact (example from playbook):

   systemprompt admin agents message <agent_name> -m "Your task here" --blocking
   

DO NOT improvise agent interactions. The playbook has the correct commands.

3. Edit & Update via CLI

Skills, agent instructions, and playbooks can all be edited using the CLI:

# AGENTS - Edit agent configuration and instructions
systemprompt admin agents list                    # List all agents
systemprompt admin agents show <name>             # View agent config
systemprompt admin agents edit <name>             # Edit agent config
systemprompt admin agents create                  # Create new agent

# SKILLS - Edit skill definitions
systemprompt core skills list                     # List all skills
systemprompt core skills show <name>              # View skill details
systemprompt core skills edit <name>              # Edit skill
systemprompt core skills create                   # Create new skill
systemprompt core skills sync --direction to-db -y  # Sync to database

# PLAYBOOKS - Edit playbook instructions
systemprompt core playbooks list                  # List all playbooks
systemprompt core playbooks show <id>             # View playbook
# Edit playbook files directly in: services/playbook/
systemprompt core playbooks sync --direction to-db -y  # Sync to database

File Locations

MANDATORY: Read Before Any Task

Agents MUST follow this workflow for EVERY task:

1. Read this playbook first - systemprompt core playbooks show guide_start
2. Identify the task domain - Find the relevant playbook below
3. Read the domain playbook - systemprompt core playbooks show <playbook_id>
4. Follow the playbook steps exactly - Do not improvise
5. Verify success - Use the playbook's verification steps

DO NOT skip steps. DO NOT guess commands. ALWAYS use playbooks. ALWAYS fix playbooks immediately if bugs are encountered

Guide Pathways

Guides link to detailed playbooks. Start with the appropriate guide for your task.

guide_start (this playbook)
    |
    +-> CLI Operations
    |       +-> cli_session, cli_agents, cli_services, cli_database...
    |
    +-> Building Code
    |       +-> guide_coding-standards
    |               +-> build_rust-standards (Rust patterns)
    |               +-> build_extension-checklist (Extensions)
    |               +-> build_mcp-checklist (MCP servers)
    |
    +-> Content Creation
    |       +-> content_blog, content_linkedin, content_twitter...
    |
    +-> Discord Integration
    |       +-> guide_discord
    |               +-> cli_discord (CLI commands)
    |               +-> cli_jobs (Gateway job)
    |
    +-> Writing Playbooks
            +-> guide_playbook
                    +-> guide_documentation

Master Playbook Index

Guide (Start Here)

CLI Operations

Build & Development

Content Creation

Domain Operations

How to Use Playbooks

# List all available playbooks
systemprompt core playbooks list

# Read a specific playbook (full content)
systemprompt core playbooks show guide_start
systemprompt core playbooks show cli_session
systemprompt core playbooks show build_architecture

# Raw markdown output (for piping)
systemprompt core playbooks show cli_agents --raw

# Filter list by category
systemprompt core playbooks list --category cli
systemprompt core playbooks list --category build
systemprompt core playbooks list --category content

Task to Playbook Quick Reference

Playbook Structure

Every playbook contains:

• Title & Description - What the playbook does
• Prerequisites - Required setup (e.g., active session)
• Step-by-step commands - Exact commands to run
• Verification - How to confirm success
• Troubleshooting - Common issues and fixes
• Quick Reference - Command summary table

Rules for Agents

1. ALWAYS read guide_start first - This playbook
2. ALWAYS read the domain playbook - Before executing any task
3. NEVER guess commands - Only use commands from playbooks
4. NEVER skip steps - Follow playbooks in order
5. ALWAYS verify - Use verification steps from playbooks
6. Self-repair playbooks - If a playbook is wrong, fix it before continuing

MANDATORY: Self-Repair

If a playbook command fails or doesn't match CLI behavior, you MUST fix the playbook BEFORE continuing with your task.

When to Self-Repair

• A command in the playbook returns an error
• The CLI syntax has changed
• A command flag doesn't exist
• The playbook references outdated behavior

Self-Repair Workflow

1. Stop your current task - Do not continue with broken instructions
2. Verify the correct CLI syntax:

   systemprompt <domain> <subcommand> --help
   

3. Edit the playbook file directly - Playbooks are in services/playbook/
4. Sync the updated playbook:

   systemprompt core playbooks sync --direction to-db -y
   

5. Verify the fix:

   systemprompt core playbooks show <playbook_id>
   

6. Resume your task - Now using the corrected playbook

Playbook File Locations

services/playbook/
├── guide/          # guide_* playbooks (onboarding, meta)
├── cli/            # cli_* playbooks (all CLI operations)
├── build/          # build_* playbooks (development standards)
└── content/        # content_* playbooks (content creation)

Example: Fixing a Broken Command

# 1. Command in playbook fails
systemprompt admin agents list --verbose
# Error: unknown flag --verbose

# 2. Check correct syntax
systemprompt admin agents list --help

# 3. Edit the playbook file
# Edit: services/playbook/cli/agents.md
# Change: --verbose -> -v (or remove if not supported)

# 4. Sync changes
systemprompt core playbooks sync --direction to-db -y

# 5. Verify fix
systemprompt core playbooks show cli_agents

# 6. Resume task with corrected command

DO NOT continue with a broken playbook. Fix it first.

Sync Playbooks

If playbooks are missing or outdated:

# Sync from disk to database
systemprompt core playbooks sync --direction to-db -y

# Verify sync
systemprompt core playbooks list