one-ie/one/workflow

Workflow

A workflow is one .md in ai/workflows/. one push sends it as workflow:create, then applies its graph as a second call.

Prose is not a workflow

This is the failure to check for first. The compiler reads exactly one thing as the step graph: a fenced block whose language is graph, containing JSON. Everything else in the file — headings, tables, numbered steps, fenced blocks marked anything else — is documentation.

A file of well-structured prose describing five steps compiles to workflow:create with a name, a description, and no steps at all. It succeeds. It reports success. The workspace gets an empty workflow.

Check before you claim a workflow is built:

grep -c '```graph' ai/workflows/<name>.md    # 0 means it does nothing
one push --dry-run                            # shows what would actually land

The file

---
id: order-fulfilment
label: Order → fulfilled
description: One sentence. This is what the workspace shows.
trigger: order:created
department: service
---
 
Prose for humans goes here. It is never executed.
 

{ "steps": [ { "id": "pick", "kind": "agent", "name": "Pick and pack", "config": { "actorId": "service", "instructions": "..." } }, { "id": "ok", "kind": "human", "name": "Confirm shipped", "config": { "assignee": "{{ owner }}" } } ], "edges": [["pick", "ok"]] }

edges takes either ["from", "to"] or { "from": ..., "to": ..., "condition": ... }. A config object is stringified for you; a string is passed through.

The frontmatter `trigger` seeds a trigger step when the graph has none, and wires it to the first step. So you write the trigger once, in frontmatter, and the graph starts at the real work.

The eight kinds

An unknown kind throws at compile time and names itself — that error is a gift, not a problem to work around.

tool → skill → agent is the autonomy ladder: reach for the least autonomous one that can do the job. A step that needs no judgment should never be an agent.

Three rules worth holding

Suspending is a design choice, not a cost. human and sell stop the run until someone acts. A workflow that never suspends has decided nobody needs to approve anything — make sure that was deliberate.

Name nobody. An assignee, a signature, a business name belongs in a {{ placeholder }}. A workflow with a person's name in it is that person's workflow, not a template.

A trigger must be a real surface. trigger: names a source this site actually emits. Inventing one produces a workflow that is valid, pushed, and never fires.