A human-readable workflow format for complex work involving humans, agents, and software systems.
Readable without tools. Executable with tools.
steps.sh is a markdown-based specification for describing workflows. It lets you document how work happens in a structured format that humans can read and tools can execute.
It is designed to:
- Document how work happens -- capture roles, artifacts, steps, and dependencies in plain markdown
- Serve as an execution plan -- not just documentation, but a runnable description of work
- Support parallel work without DAG complexity -- linear to read, parallel to run
- Evolve incrementally toward automation -- start with humans, add agents over time
A steps.sh file looks like this:
# Podcast production
## Goal
Produce and publish a podcast episode.
## Roles
- producer[Producer]
- editor[Editor]
- transcription[Transcription]
- show_notes[Show Notes]
- clip_extraction[Clip Extraction]
## Step 1: Transcription
**Owner:** transcription
**Output:** transcript
## Step 2: Rough Cut
**Owner:** editor
**Input:** transcript
**Output:** rough_cut
## Parallel Group: Post-Production
**Mode:** parallel
### Step 3a: Show Notes Draft
**Owner:** show_notes
**Input:** transcript
**Output:** show_notes_draft
### Step 3b: Clip Extraction
**Owner:** clip_extraction
**Input:** rough_cut
**Output:** clips
## Step 4: Publish
**Owner:** producer
**Wait for:** Post-Production- Markdown is the interface -- no proprietary formats, just
.mdfiles - Linear to read, parallel to run -- document order is reading order; parallel groups handle concurrency
- Humans and agents are first-class -- any role can be a person or a software agent
- Order expresses intent -- the sequence of steps matters
- Explicit joins -- parallel groups require explicit join steps
The full spec covers headers, roles, artifacts, constraints, steps, parallel groups, revision loops, and exception handling. Read it at steps.sh or browse the /docs page.
An example workflow is included to demonstrate the format:
| Example | Highlights |
|---|---|
| Podcast production | Transcription, parallel post-production, revision loop, exception handling |
Paste or write a steps.sh file and get real-time validation with line-by-line error highlighting:
- Step format and numbering
- Role and artifact reference checks
- Parallel group syntax
- Wait condition validation
- Loop reference checks
- Auto-fix suggestions
Convert any steps.sh file into an interactive workflow diagram. The visualizer parses the markdown and renders sequential steps, parallel groups, join steps, and loops as a flowchart.
Install the steps.sh Agent Skills so your AI assistant can write, validate, and convert workflows to steps.md:
npx github:supermix-dev/steps.shThis installs two skills into your project:
- steps-sh -- Write and validate
steps.mdfiles from scratch - convert-to-steps -- Convert existing workflow documents (SOPs, runbooks, process docs) into
steps.mdformat
- Node.js (v18+)
- npm
git clone https://github.com/supermix-dev/steps.sh.git
cd steps.sh
npm installnpm run devOpen http://localhost:3000 to view the site.
npm run build
npm run startsteps-sh/
├── app/ # Next.js app router pages
│ ├── docs/ # Specification documentation
│ ├── examples/ # Example listing and detail pages
│ │ └── [slug]/ # Dynamic routes for each example
│ └── tools/
│ ├── lint/ # Linter tool
│ └── visualize/ # Visualizer tool
├── components/ # React components
│ └── ui/ # shadcn/ui primitives
├── lib/
│ ├── content/ # Spec content, examples, and constants
│ │ └── examples/ # Example .md files
│ └── tools/ # Linter and visualizer logic
│ ├── lint.ts # Validation rules
│ ├── visualize.ts # Layout engine
│ └── visualize-parse.ts # steps.sh parser
└── public/ # Static assets
- Next.js 16 (App Router)
- React 19
- TypeScript
- Tailwind CSS
- shadcn/ui + Radix UI
- React Flow for workflow visualization