Rundown - Executable Workflows in Markdown

Executable Workflows from Markdown Runbooks

Enforce process. Track progress. Resume anytime.

Get Started View on GitHub

Features

📝

Markdown-First

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

💾

Persistent State

Workflow progress survives context clears and session restarts

⚙️

State Machines

Compiles to XState machines for reliable, predictable execution

⌨️

CLI Control

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

Quick Start

Install the CLI:

npm install -g @rundown/cli

See it in action:

Less More

Runbook

simple.runbook.md

# Simple Workflow

## 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

▶ Step 1: Create Plan

Create an implementation plan.

→ rundown pass

▶ Step 2: Implement

Write the code.

→ rundown pass

▶ Step 3: Verify

Run tests.

→ rundown pass

✓ COMPLETE

Runbook

review.runbook.md

# Code Review Workflow

## 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

▶ Step 1: Dispatch reviewer

Run code-review-agent.

→ rundown fail

↻ RETRY (1/2)

→ rundown pass

▶ Step 2: Categorize issues

Sort as BLOCKING or NON-BLOCKING.

→ rundown pass

▶ Step 3: Handle blocking

Fix BLOCKING issues first.

→ rundown yes

↳ GOTO 4

▶ Step 4: Address feedback

Implement NON-BLOCKING fixes.

→ rundown pass

✓ COMPLETE

Commands

rd is an alias for rundown

rundown run <file>	Start a workflow
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 workflow
rundown complete	Mark workflow complete
rundown stash	Pause enforcement
rundown pop	Resume enforcement
rundown ls	List active workflows
rundown check <file>	Validate workflow file