Concept
Runbooks
A runbook is a reusable task blueprint. Instead of rebuilding a task from scratch every time, a runbook encodes the operational pattern — intent, execution mode, command or prompt, approval requirements, and constraints — so it can be instantiated with a single action.
Blueprint, not execution
A runbook defines what to do but doesn't execute anything itself. It creates a task when instantiated.
Repeatable
The same runbook can be instantiated many times. Each instantiation creates a fresh task with a new ID and full audit trail.
Governance-aware
Runbooks carry approval requirements. When instantiated, the approval class from the blueprint flows into the task.
What a runbook contains
| Field | Purpose |
|---|---|
| name | Unique display name within the organization |
| intentTemplate | Template for the task intent (what to do) |
| mode | Execution mode: command, prompt, or investigate |
| command | Shell command to execute (for command mode) |
| promptText | AI prompt to send (for prompt/investigate mode) |
| approvalClass | Required approval level: none, sensitive_write, or production_mutation |
| defaultPlan | Default task plan (can be overridden at instantiation) |
| defaultConstraints | Default execution constraints (tags, limits) |
| successCriteria | Expected outcomes for validation |
| status | active, draft, or archived |
Instantiation
Instantiatinga runbook creates a new task from its blueprint. The process merges the runbook's defaults with any overrides provided at instantiation time.
Runbook: "Deploy health check" │ mode: command │ command: "curl -sf https://api.example.com/health" │ approvalClass: none │ ▼ instantiateRunbook(targets: [prod-1, prod-2]) │ Task created: ├─ intent: "Deploy health check" ├─ mode: command ├─ command: "curl -sf https://api.example.com/health" ├─ targets: [prod-1, prod-2] ├─ plan.runbookId: "abc-123" ├─ plan.runbookName: "Deploy health check" └─ planStatus: approved (auto-approved for runbook instantiations)
The created task stores plan.runbookId and plan.runbookName for audit traceability — you can always trace a task back to the runbook that created it.
Common use cases
Health checks
Periodic verification that services are responding correctly across all target workstations.
Deploy verification
Post-deploy smoke tests that run the same validation script on staging and production.
Security audits
Standardized prompts for AI agents to review code for specific vulnerability patterns.
Incident response
Pre-defined diagnostic steps for common failure modes, linked to investigations.
Runbooks and investigations
Runbooks and investigations work together naturally. When instantiating a runbook, you can pass an investigationId to link the created task to an ongoing investigation. This makes it easy to run standardized diagnostic steps as part of a structured analysis.
For example, an "Incident Response" runbook can be instantiated multiple times within the same investigation, targeting different workstations, with each execution contributing evidence to the investigation's artifact collection.
MCP tools and resources
| Tool | Scope | Description |
|---|---|---|
| list_runbooks | mcp:read | List runbooks with execution statistics |
| get_runbook | mcp:read | Full runbook blueprint with recent task history |
Resources
tanjiren://runbooks/{id}Runbook blueprint with defaults and success criteria