runbook-workflows

Minimal CLI, MCP server, and authoring guide for building workflows for the Runbook workflow engine.

This public template contains no customer workflows, backtesting, harvesting, analytics, dashboards, or autofix tooling.

Setup

You need:

• Bun

• A Runbook API key and organization ID

• Conductor on macOS, Cursor, Claude Code, or another MCP client

Install dependencies and link the rb command:

bun run setup
rb --help

Copy the MCP example:

cp .cursor/mcp.example.json .cursor/mcp.json

Edit .cursor/mcp.json and set RUNBOOK_ENV_SLUG, RUNBOOK_API_URL, RUNBOOK_API_KEY, and RUNBOOK_ORG_ID. The file is gitignored. Do not commit real credentials or organization IDs.

• RUNBOOK_API_KEY: in the Runbook dashboard, click the user icon (top right) → Manage account → API keys, then create or copy a key.

• RUNBOOK_ORG_ID: click the organization dropdown (top left) → Manage → Info to find the organization ID.

The committed .conductor/settings.toml installs dependencies, links rb, and copies local MCP settings into each worktree. Shared Conductor settings take effect after they are merged into the remote default branch.

Related MCP server: MCP Workflow Server

Authoring flow

1. Read workflow-guide.md.

2. Run rb workflow create or call the create_workflow MCP tool.

3. Edit the scaffold under workflow-definitions/<env>/workflows/<slug>/.

4. Validate with validate_workflow or rb sync on a linked branch.

5. Push a draft with the MCP server or the rb review-branch flow.

6. Simulate the draft before publishing it from the Runbook UI.

rb CLI

Install the local command with bun run setup, or use ./bin/rb directly.

In a plain clone on main:

rb workflow set <env>/<workflow>
rb checkout <branch>
rb sync
rb commit -m "Build workflow"
rb push
rb prepare-publish

In a Conductor worktree or any branch created for you, use rb adopt instead of rb checkout.

rb prepare-publish creates a draft on the default branch. A person still publishes the draft from the Runbook UI.

Workflow layout

workflow-definitions/<env>/
├── registry.json
└── workflows/<slug>/
    ├── workflow.json
    ├── agents/<agentId>/
    │   ├── agent.json
    │   └── prompt.md
    ├── toolsProviders/
    ├── connections/
    ├── skills/           # optional
    └── memory/           # optional

Core MCP tools

• Workflow authoring: list_workflows, create_workflow, validate_workflow, push_workflow.

• Branches: list_branches, create_branch, archive_branch.

• Platform discovery: list_models, list_providers, list_provider_actions, list_provider_event_types, list_connections, get_connection.

• Simulation: simulate_run, simulate_event, simulate_action_response, simulate_tool_result, wait_for_next_intercepted_call, fork_run.

• Run inspection: list_runs, get_run_logs, send_user_message.

Integration skill

The included add-integration skill covers Slack, Microsoft Teams, Outlook, Google Sheets, and scheduler connections, triggers, and actions. It is shared by Claude Code and Cursor through .claude/skills and .cursor/skills.

License

MIT — see LICENSE.