Language design
A workflow should be readable before it runs
Why WOML keeps the structure of a process in markup, puts application logic in JavaScript, and makes the complete workflow reviewable as source code.
A workflow is easier to maintain when its source tells you what happens, in what order, and under which rules. WOML makes that structure explicit in markup while leaving the work inside each step to JavaScript.
The structure is part of the program
A process is more than a collection of functions. It has an entry point, a sequence, decisions, concurrent work, waits, and policies that determine how execution behaves. When those relationships are scattered across framework calls, the reader must reconstruct the workflow before reviewing it.
WOML keeps that shape in one document. Triggers live under <triggers>. Executable work lives under <steps>. Branches, approvals, retries, and runtime policy are visible where they affect the process. The file can be read from top to bottom before anything is executed.
<woml>
<workflow id="welcome-user" name="Welcome User" version="1.0.0">
<triggers>
<manual id="start" />
</triggers>
<steps>
<step id="prepare" name="Prepare greeting">
<script>
return { name: context.payload.name ?? "World" };
</script>
</step>
<step id="greet" name="Build message">
<script>
return { message: `Hello ${context.steps.prepare.name}` };
</script>
</step>
</steps>
</workflow>
</woml>Markup and code have different jobs
Markup describes the durable structure: what starts the workflow, which step follows, where work branches, and which policies apply. JavaScript implements the application-specific behavior inside a step. It can transform data, call a managed service, use Fetch, or invoke an imported module.
This division avoids two weak extremes. Business logic does not have to be squeezed into a configuration expression language, and the workflow shape does not disappear inside ordinary application code.
A reviewer should be able to see both the process and the code that makes each step useful.
Readable source changes the review
A .woml file is ordinary text. A pull request can show that a webhook changed, a retry was added, or an approval moved before an external effect. The workflow can be validated in CI with woml check and discussed using the same names that appear in terminal output and run inspection.
Coding agents benefit from the same constraint. They can generate a structured file, validate it with the compiler, and leave a diff that a person can inspect rather than an opaque runtime graph.
Readable does not mean limited to small workflows
The same source model supports parallel work, exact routing, durable human approval, waits, retries, lifecycle hooks, and runtime policies. When one file becomes too broad, local modules and reusable workflows let the system split along meaningful boundaries.
The goal is not to keep every system in one document. It is to preserve a readable contract at every level as a local task grows into coordinated software.
Topics
- code-first workflows
- WOML
- JavaScript
- workflow design