SAMARITANOperations as Code

Turn YAML operation definitions into reviewable runbooks, then drive them step by step with a complete audit trail.

Runbooks from one source

Define an operation once in YAML and generate Markdown or Confluence manuals for every environment, so the document a reviewer approves is the one an operator follows.

Validation before execution

Catch broken variables, malformed steps and drifted assertions with validate — including shellcheck linting of step commands and regex linting of expect rules.

Interactive execution with evidence

Drive an operation step by step in sidecar mode, capture verification output as evidence, and get a durable JSONL run record plus a Markdown report.

Rollback that is planned, not improvised

Author rollback next to the step it undoes, then run one consolidated recovery — ordered by step dependencies — from any prompt.

What SAMARITAN is

SAMARITAN is a documentation generator, validator, and interactive runner for operational procedures. You describe an operation once in YAML; SAMARITAN renders it into reviewable runbooks, checks it for errors, and walks an operator through it while recording what actually happened.

What it is not

It is not a non-interactive execution engine. SAMARITAN never runs your commands unattended. Even in automatic mode, or with --auto-approve, steps are marked complete rather than executed — an operator is always in the loop. Automatic command execution, automatic evidence collection and external integrations (Jira, Confluence API, Slack) are tracked in ROADMAP.md, not shipped.

Being explicit about this matters: these documents are used during incidents, and a runbook that overstates what the tool does is worse than no runbook.