Full template

Copy this template and replace placeholders with your workflow.

# Workflow title

## Goal
One sentence describing the intended outcome.

## Owner
role_name

## Version
1.0

## Spec
steps.sh/0.1

## Roles
- role_a[Role A]
- role_b[Role B]

## Artifacts
- artifact_one[Artifact One]
  - type: document
  - description: Primary output of the first step
- artifact_two[Artifact Two]
  - type: dataset
  - description: Processed result from the second step
  - schema: id, name, status

## Constraints
- constraint_name: value

## Step 1: First step
**Owner:** role_a
**Action:** Describe what role_a does in this step
**Output:** artifact_one

## Step 2: Second step
**Owner:** role_b
**Action:** Describe what role_b does in this step
**Input:** artifact_one
**Output:** artifact_two
**Done when:** condition satisfied
**Wait for:** step: 1
**Duration:** 2d–5d (business days only)

## Parallel Group: Group name
**Mode:** parallel

### Step 3a: Parallel step A
**Owner:** role_a
**Action:** Describe parallel step A
**Input:** artifact_one
**Output:** artifact_three

### Step 3b: Parallel step B
**Owner:** role_b
**Action:** Describe parallel step B
**Input:** artifact_one
**Output:** artifact_four

## Step 4: Join: Group complete
**Wait for:** step: 3a, step: 3b
**Output:** artifact_bundle

## Step 5: Revisions
**Owner:** role_a
**Action:** Review and request changes; loop back if needed
**Loop to:** Step 2
**Max loops:** 2

## Exceptions

- If a step fails:
  - Describe handling

### If critical failure
**Trigger:** Condition that triggers the exception
**Affects:** step: 3a, step: 3b
**Action:** Describe the response
**Escalate to:** role_a

## Metadata
- department: team_name
- tracking_id: PROJECT-123

## Execution Notes

- Add non-normative notes here

1. File structure

A steps.md file consists of the following sections, in order:

1. Header & metadata
2. Roles
3. Artifacts
4. Constraints (optional)
5. Steps (including parallel groups)
6. Failure & exception handling (optional)
7. Execution notes (optional)

Only Steps are required. Per the header section, a Title (the # heading), Goal, and Owner are also required.

2. Header & metadata

Metadata can be provided using ## Heading sections or YAML frontmatter. Both formats are valid; frontmatter takes precedence if both are present.

Heading format (steps.sh/0.1)

# Podcast production

## Goal
Produce and publish a podcast episode.

## Owner
producer

## Version
1.0

## Spec
steps.sh/0.1

Frontmatter format (steps.sh/0.2)

---
goal: Produce and publish a podcast episode.
owner: producer
version: "1.0"
spec: steps.sh/0.2
---

# Podcast production

Semantics

• Title (the # heading) — REQUIRED. A short, descriptive noun phrase naming the workflow.
• Goal — REQUIRED. SHOULD be a single sentence describing the intended outcome. May be provided as ## Goal or goal: in frontmatter.
• Owner — REQUIRED. The single accountable role for the file. MUST be one of the roles defined in the Roles section. May be provided as ## Owner or owner: in frontmatter.
• Version — OPTIONAL. User-defined version (not tied to spec version). May be provided as ## Version or version: in frontmatter.
• Spec — OPTIONAL. The spec version the file conforms to. MUST match steps.sh/<version> format (e.g. steps.sh/0.1). May be provided as ## Spec or spec: in frontmatter.

Header fields SHOULD appear in the order shown above: Goal, Owner, Version, Spec.

3. Roles

## Roles
- producer[Producer]
- editor[Editor]
- client[Client]
- transcription[Transcription]
- clip_extraction[Clip Extraction]

Semantics

• Roles are agnostic — any role MAY be fulfilled by a human or an agent. The format does not distinguish between them.
• Roles MUST be stable identifiers — the same string every time the role is referenced within a file and across versions of that file.
• A role MAY appear in multiple steps.

Display labels

A role MAY include an optional display label in square brackets:

- video_editor[Video Editor]

• The identifier (video_editor) is used in **Owner:**, **Escalate to:**, and other references.
• The label (Video Editor) is used for display by tools (diagrams, timelines, dashboards).
• If no label is provided, the identifier is used as-is.

Naming conventions

• Role identifiers SHOULD use snake_case (e.g. producer, site_coordinator, vfx_render).
• Role names MUST match the pattern [a-zA-Z][a-zA-Z0-9_]* — letters, numbers, and underscores; must start with a letter.

4. Artifacts

Artifacts are named, addressable outputs.

## Artifacts
- raw_audio[Raw Audio]
  - type: audio_file
  - description: Unedited recording from the session
- transcript[Transcript]
  - type: document
  - description: Word-for-word text from the recording
  - schema: speaker, timestamp, text
- rough_cut
- clips
- show_notes

Semantics

• Artifacts SHOULD be nouns.
• Steps MUST NOT produce unnamed outputs.
• Artifact versioning is out of scope for v1.

Display labels

An artifact MAY include an optional display label in square brackets:

- raw_audio[Raw Audio]

• The identifier (raw_audio) is used in **Input:**, **Output:**, **Wait for:**, and other references.
• The label (Raw Audio) is used for display by tools (diagrams, timelines, dashboards).
• If no label is provided, the identifier is used as-is.

Sub-properties

An artifact MAY have indented sub-properties beneath it using - key: value format:

- transcript[Transcript]
  - type: document
  - description: Word-for-word text from the recording
  - schema: speaker, timestamp, text

Known sub-property keys

• type — Free-form string describing the artifact's kind (e.g. audio_file, document, dataset, url, image).
• description — Human-readable summary of the artifact's contents or purpose.
• schema — Free-form structure hint describing the artifact's shape (e.g. field names, columns, keys).

Sub-property keys SHOULD match the pattern [a-zA-Z][a-zA-Z0-9_]*.

All sub-properties are OPTIONAL. Bare - artifact_name lines remain valid.

Naming conventions

• Artifact identifiers MUST match the pattern [a-zA-Z0-9_]+ — letters, numbers, and underscores.

5. Constraints (optional)

## Constraints
- turnaround_time: 72h
- max_revisions: 2
- clip_count: 6–10

Semantics

• Each constraint MUST use the format - constraint_name: value.
• Constraint names SHOULD be valid identifiers matching [a-zA-Z0-9_]+.
• Constraints apply globally unless overridden.

6. Steps

6.0 Field syntax

Step fields are written as bold Markdown labels followed by a colon and a space:

**FieldName:** value

• One field per line.
• Field names are case-sensitive.
• Values are plain text unless otherwise specified.

6.1 Step definition

Each step MUST be a second- or third-level heading.

## Step 1: Transcription

A step consists of:

• a heading
• required Action and Owner fields and optional structured fields

6.2 Step fields

**Action:** human-readable description of what the owner should do
**Owner:** producer
**Input:** artifact_name
**Output:** artifact_name

Required fields

• Action — REQUIRED. A human-readable description of what the step owner should do. One per step.
• Owner — REQUIRED. The single role responsible for the step; MUST be one of the Roles. One per step.

Optional fields

• Input
• Output
• Done when — a human-readable condition that MUST be satisfied for the step to be considered complete.
• Wait for — comma-separated list of conditions that MUST be satisfied before the step runs. Each entry is prefixed: step: <id> (that step has completed, e.g. step: 4a); artifact: <name> (that artifact exists, e.g. artifact: transcript).
• Duration — a structured time estimate for planning. MUST start with a valid time token (<number><unit>) where unit is m (minutes), h (hours), d (days), or w (weeks). MAY be a range using en-dash or hyphen (e.g. 2d–5d). MAY be followed by optional prose (e.g. (business days only)).

Examples:

**Done when:** episode live on platform
**Wait for:** step: 4a, step: 4b, artifact: transcript
**Duration:** 4h
**Duration:** 2d–5d (business days only)

6.3 Step semantics

• Steps run in document order, unless grouped.
• A step with Wait for does not run until every entry in the list is satisfied: step: <id> when that step has completed; artifact: <name> when that artifact exists.
• A step MAY block execution.
• A step MAY produce multiple artifacts.
• A step MUST NOT implicitly depend on later steps.
• A step with no Output field produces no artifacts. This is valid for steps that exist solely to review or signal.
• A step is complete when its completion criteria are satisfied. Default behavior:
  • If Done when is present, the step is complete when that condition is satisfied (in addition to any Output artifacts existing).
  • If Done when is absent and Output is present, the step is complete when all output artifacts exist.
  • If neither Done when nor Output is present, the step is complete when the owner signals done.

6.4 Step identifiers

A Step ID is the numeric or alphanumeric token that follows the word "Step" in the heading.

• ## Step 1: Transcription → ID is 1
• ### Step 4a: Show Notes Draft → ID is 4a

Step IDs MUST be unique within a file. References to steps use these IDs (e.g. in Wait for as step: 4a).

7. Parallel Groups

Parallel work is expressed using a Parallel Group, followed by an explicit Join Step.

7.1 Parallel Group definition

## Parallel Group: Post-Production
**Mode:** parallel

Semantics

• Mode is required and MUST be parallel. Future versions may introduce other modes.
• All steps inside the group MAY run concurrently.
• Order inside the group is non-normative.
• The group MUST be followed by a Join Step.

7.2 Steps inside a Parallel Group

### Step 4a: Show Notes Draft
**Owner:** show_notes
**Action:** Draft show notes from the transcript
**Input:** transcript
**Output:** show_notes_draft

Rules:

• Step IDs SHOULD be suffixed (4a, 4b, etc.).
• Steps MUST NOT depend on each other inside the group.
• Steps MUST produce distinct artifacts.

7.3 Join Step (mandatory)

## Step 6: Join: Post-Production Complete
**Wait for:** step: 4a, step: 4b, step: 4c
**Output:** post_production_bundle

Semantics

• A Join Step blocks until all listed conditions in Wait for are satisfied. Join Steps typically list the parallel steps using step: entries. A Join Step MAY also list artifact: conditions.
• A Join Step MAY validate artifact existence.

8. Revision loops

## Step 7: Revisions
**Action:** Review outputs and request changes; loop back if needed
**Loop to:** Step 3
**Max loops:** 2

Semantics

• Revision steps MAY loop backward.
• Loop to specifies the step to return to when a revision is needed.
• Exceeding Max loops SHOULD trigger escalation.

9. Failure & exception handling

## Exceptions

- If a parallel step fails:
  - Pause group execution
  - Notify owner

- If join conditions are unmet:
  - Do not proceed

Failure behavior is advisory but strongly recommended.

Structured exceptions (optional)

For richer tooling support, exceptions MAY use structured fields:

## Exceptions

### If safety signal identified
**Trigger:** Safety officer detects adverse event
**Affects:** step: 4, step: 5a
**Action:** Pause enrollment, notify regulatory
**Escalate to:** sponsor, safety_officer

Fields

• Trigger — Human-readable description of the triggering condition.
• Affects — Comma-separated list of step: <id> references indicating which steps are impacted.
• Action — Human-readable description of the response.
• Escalate to — Comma-separated list of roles to notify. Each MUST be listed in ## Roles.

Structured and free-form exceptions MAY coexist in the same ## Exceptions section.

10. Metadata (optional)

The ## Metadata section provides a place for workflow-specific data that tools should preserve but do not need to interpret.

## Metadata
- department: engineering
- compliance_tier: SOC2
- jira_project: PROJ-123

Semantics

• Each entry MUST use the format - key: value.
• Keys SHOULD be valid identifiers matching [a-zA-Z0-9_]+.
• Values are free-form strings.
• Tools MUST preserve metadata entries but MAY ignore them for execution purposes.

11. Execution model (normative)

1. Steps execute top-to-bottom.
2. Parallel Groups fork execution.
3. Join Steps block until all required steps complete.
4. Failures halt downstream steps unless overridden.
5. A step is complete per its completion criteria (see 6.3).

12. Execution notes (non-normative)

## Execution Notes

- This file is the source of truth
- Tools may visualize or execute it
- Humans may follow it manually