jason-hchsieh/runbook-register

Register Runbook

You are registering a new automated runbook that will execute a sequence of actions when a trigger condition is met.

Runbook File

Runbooks are persisted in .claude/runbooks.json in the project root. Create the file and parent directory if they don't exist.

Schema

{
  "runbooks": {
    "<runbook-name>": {
      "trigger": "<trigger-type>",
      "mode": "auto|ask",
      "enabled": true,
      "description": "<what this runbook does>",
      "actions": [
        { "type": "shell", "command": "<shell command>" },
        { "type": "prompt", "instruction": "<instruction for Claude to follow>" }
      ]
    }
  }
}

Supported Triggers

| Trigger | When it fires | |---------|---------------| | task_complete | After Claude finishes a task (via Stop hook) | | manual | Only when explicitly invoked with /runbook-run |

Execution Modes

| Mode | Behavior | |------|----------| | auto | Execute actions immediately without asking the user | | ask | Show the user what will run and ask for confirmation before executing |

Default mode is ask — safer for new runbooks. Use auto for trusted, well-tested runbooks.

Supported Action Types

| Type | Format | Example | When to use | |------|--------|---------|-------------| | prompt | { "type": "prompt", "instruction": "..." } | { "type": "prompt", "instruction": "Run /bump to update the version" } | Default. For invoking skills, multi-step workflows, or anything Claude should reason about | | shell | { "type": "shell", "command": "..." } | { "type": "shell", "command": "git push" } | For simple, deterministic commands that need no judgment |

Prompt actions are instructions that Claude follows directly. They can reference skills (e.g., "Run /bump"), describe multi-step workflows, or include conditional logic. Claude uses its judgment to execute them — invoking skills, running commands, or making decisions as needed.

Shell actions are raw commands executed via Bash. Use these only for simple, single-purpose commands where Claude's reasoning isn't needed.

Detecting action type from user input

When the user describes actions:

• References to skills (/bump, /commit, /deploy), natural language instructions ("check if tests pass then deploy"), or conditional logic → use prompt type
• Simple shell commands (git push, npm test, docker restart) → use shell type
• When in doubt → use prompt type (it's more flexible)

Template Variables

Actions support these template variables (replaced at execution time):

• {{task_description}} — brief description of what was just completed
• {{date}} — current date in YYYY-MM-DD format
• {{branch}} — current git branch name

Instructions

1. Parse arguments: The user provides a runbook name and optionally inline trigger/actions, e.g.:

   • /runbook-register auto-commit — then ask for trigger and actions
   • /runbook-register auto-version-commit trigger:task_complete actions: /bump, /commit-and-push

2. If trigger/actions not provided, ask the user:

   • What trigger? (task_complete or manual)
   • What mode? (auto or ask, default: ask)
   • What actions? (list of instructions or commands to run in order)
   • Optional description

3. Classify each action as prompt or shell based on the detection rules above

4. Read existing runbooks: Read .claude/runbooks.json if it exists, otherwise start with { "runbooks": {} }

5. Show the user exactly what will be registered:

   Runbook "auto-version-commit":
     Trigger: task_complete
     Mode: auto
     Actions:
       1. [prompt] Run /bump to update the version
       2. [prompt] Run /commit-and-push to commit and push all changes
     Status: enabled
   

6. Add the new runbook to the JSON object and write to .claude/runbooks.json

7. Confirm registration with the summary above

Safety

• Warn the user if a task_complete runbook contains destructive shell commands (force push, rm -rf, etc.)
• If a runbook with the same name exists, ask before overwriting
• Always show the user exactly what will be registered before writing