# 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](https://bun.sh)
- A Runbook API key and organization ID
- Conductor on macOS, Cursor, Claude Code, or another MCP client

Install dependencies and link the `rb` command:

```bash
bun run setup
rb --help
```

Copy the MCP example:

```bash
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.

## Authoring flow

1. Read [workflow-guide.md](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`:

```bash
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

```text
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](LICENSE).