Specification

Document

A workflow is one self-contained document in YAML or JSON. It declares its tasks, their orchestration, and every server the tasks depend on. Nothing is left to the environment.

Each spec version ships three files. The prose specification is normative. The JSON Schema validates structure and cannot express every rule; where the two conflict, the prose wins.

Point an editor's YAML language server at the schema with a modeline:

# yaml-language-server: $schema=https://openawf.org/schemas/0.1.0/schema.json

Workflow fields

Orchestration

Each orchestration key names a task. Its value is one of three transitions.

An edge is a task name, or an object that names the task under task and adds execution policy.

orchestration:
  plan: build                  # edge
  build:
    pass: ship                  # branch on outcomes
    fail:
      task: build               # edge with policy
      retries: 2
      session: resume
  ship: null                    # terminal

task is reserved inside a branch: it marks an edge object, so no outcome is named task.

Tasks

A task is an atomic, reusable unit of work. It is defined once and can be pinned by version in any number of workflows. body is the only required field.

Task files

A task on its own is a Markdown file. The YAML frontmatter holds every field except body and declares openawf. The Markdown after the frontmatter is the body.

---
openawf: 0.1.0
version: 1.2.3
summary: Review a diff against its request.
outcomes: [pass, changes]
---
# Review

Read the diff against the request. Emit `pass` when it is correct and
complete. Otherwise emit `changes` and return a list of review notes.

References

A task entry of the form { $ref: … } points at a task defined in another file. Orchestration edges always name tasks by their key in tasks; $ref only says where a task's definition lives.

A workflow with references is a source split over several files. Bundling inlines each referenced task into tasks and records the reference in its source. Sealing bundles first, so a sealed workflow is one file and holds no $ref.

MCP servers

mcp declares the MCP servers a workflow depends on, keyed by name. Each server names its transport (stdio, http or sse) and the tools the workflow uses from it. "*" grants every tool. A task lists the servers it needs in uses, and the runner exposes only those.

Validation

A conformant validator runs three passes in order: structure against the JSON Schema, then the graph, then the hash. A rule that stops the workflow from running is an error. A rule about something that can never be used is a warning.

Liveness rejects a retry cycle with no exit, which no other check catches.

Sealing

Sealing fixes a document's content and gives it an identity. The sha is computed over a canonical form of the document.

1. Bundle the document, inlining every $ref.
2. Convert the YAML to JSON.
3. Remove the top-level sha and version.
4. Serialize with the JSON Canonicalization Scheme, RFC 8785.
5. Hash with SHA-256 and prefix the algorithm: sha256-<hex>.

Bundling before hashing makes the sha independent of how the source was split across files. A task hashes the same way, with its frontmatter and body as one object.

The version is excluded because it is a label. Two versions with identical content share a sha. A document with sha: null is unsealed and has no provenance.

sha384 and sha512 prefixes are also accepted for verification.

Versioning

Versions are major.minor.patch. A workflow pins each task to an exact version. There are no version ranges and no solver: tasks are leaves, so no dependency graph exists to resolve.

A sealed version never changes. Changing it means writing a new draft and sealing it at a newer version.

Roadmap

These additions are in design for the specification.