Rundown - Executable Runbooks in Markdown

Executable Runbooks from Markdown

Enforce process. Track progress. Resume anytime.

Get Started View on GitHub View Patterns →

Features

📄

Markdown Runbooks

Human-readable runbook definitions in familiar .runbook.md files

💾

State Persistence

Runbook progress survives context clears and session restarts

⚙️

XState Compilation

Runbooks compile to state machines for reliable execution

💻

CLI Control

Simple commands to run, pass, fail, and navigate runbooks

Quick Start

Install the CLI:

npm install -g @rundown/cli

See it in action:

Less More

Runbook

simple.runbook.md

# Simple Runbook

## 1. Create Plan

Create an implementation plan.

- PASS: CONTINUE
- FAIL: STOP

## 2. Implement

Write the code.

- PASS: CONTINUE

## 3. Verify

Run tests.

- PASS: COMPLETE

Output

Terminal

$ rundown run simple.runbook.md

File: simple.runbook.md

State: .claude/rundown/runs/wf-2026-01-09-abc123.json

Action: START

Step: 1/3

## 1. Create Plan

Create an implementation plan.

$ rundown pass

-----

Action: CONTINUE

From: 1/3

Result: PASS

Step: 2/3

## 2. Implement

Write the code.

$ rundown pass

-----

Action: CONTINUE

From: 2/3

Result: PASS

Step: 3/3

## 3. Verify

Run tests.

$ rundown pass

-----

Action: COMPLETE

From: 3/3

Result: PASS

Runbook: COMPLETE

Runbook

review.runbook.md

# Code Review Runbook

## 1. Dispatch reviewer

Run code-review-agent.

- PASS: CONTINUE
- FAIL: RETRY 2

## 2. Categorize issues

Sort as BLOCKING or NON-BLOCKING.

- PASS: CONTINUE
- FAIL: STOP "Review failed"

## 3. Handle blocking

Fix BLOCKING issues first.

- YES: CONTINUE
- NO: GOTO 4

## 4. Address feedback

Implement NON-BLOCKING fixes.

- PASS: COMPLETE

Output

Terminal

$ rundown run review.runbook.md

File: review.runbook.md

State: .claude/rundown/runs/wf-2026-01-09-xyz789.json

Action: START

Step: 1/4

## 1. Dispatch reviewer

Run code-review-agent.

$ rundown fail

-----

Action: RETRY

From: 1/4

Result: FAIL

Attempt: 1/2

Step: 1/4

## 1. Dispatch reviewer

Run code-review-agent.

$ rundown pass

-----

Action: CONTINUE

From: 1/4

Result: PASS

Step: 2/4

## 2. Categorize issues

Sort as BLOCKING or NON-BLOCKING.

$ rundown pass

-----

Action: CONTINUE

From: 2/4

Result: PASS

Step: 3/4

## 3. Handle blocking

Fix BLOCKING issues first.

$ rundown yes

-----

Action: GOTO 4

From: 3/4

Result: YES

Step: 4/4

## 4. Address feedback

Implement NON-BLOCKING fixes.

$ rundown pass

-----

Action: COMPLETE

From: 4/4

Result: PASS

Runbook: COMPLETE

Commands

rd is an alias for rundown

rundown run <file>	Start a runbook
rundown pass	Mark current step as passed
rundown fail	Mark current step as failed
rundown goto <n>	Jump to step number
rundown status	Show current state
rundown stop	Abort runbook
rundown complete	Mark runbook complete
rundown stash	Pause enforcement
rundown pop	Resume enforcement
rundown ls	List active runbooks
rundown check <file>	Validate runbook file