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

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

Workflow 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

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

Workflow 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