Workflow Reference

This is the current kind: Workflow document used by the Python, TypeScript, and Go runtimes.

Minimal Workflow

apiVersion: edictum/v1
kind: Workflow
metadata:
  name: coding-review

stages:
  - id: read-context
    tools: [Read]
    exit:
      - condition: file_read("TASK.md")
        message: Read the task before editing

  - id: implement
    entry:
      - condition: stage_complete("read-context")
    tools: [Edit, Bash]

  - id: done
    entry:
      - condition: stage_complete("implement")
    terminal: true

Top-Level Fields

Field	Required	Notes
`apiVersion`	Yes	Must be exactly `edictum/v1`
`kind`	Yes	Must be exactly `Workflow`
`metadata`	Yes	Workflow identity
`stages`	Yes	Ordered list of workflow stages

`metadata`

Field	Required	Notes
`name`	Yes	Must match `^[a-z0-9][a-z0-9._-]*$`
`description`	No	Free-form text
`version`	No	Optional version label

`stages[]`

Field	Required	Notes
`id`	Yes	Must match `^[a-z0-9][a-z0-9._-]*$`
`description`	No	Free-form text
`entry`	No	Array of gate objects checked before the stage can start
`tools`	No	Authoritative allowlist for the stage. Entries may be exact tool names or glob patterns like `"mcp__*"`
`checks`	No	Per-call checks while the stage is active
`exit`	No	Array of gate objects checked before the stage can finish
`approval`	No	Pause at the stage boundary until approved
`terminal`	No	Final stage marker. A terminal stage never auto-advances past itself

Gate Objects

entry and exit gates use this shape:

entry:
  - condition: stage_complete("read-context")
  - condition: file_read("TASK.md")
    message: Read the task before editing

Field	Required	Notes
`condition`	Yes	One supported workflow condition
`message`	No	Block message shown when the gate fails

Supported Conditions

Condition	What it checks
`stage_complete("stage-id")`	Whether an earlier stage already completed
`file_read("path")`	Whether successful read evidence recorded that path
`approval()`	Whether the current stage was approved
`approval("stage-id")`	Whether a named stage was approved
`command_matches("regex")`	Whether command evidence for the stage matches the regex
`command_not_matches("regex")`	Whether command evidence for the stage does not match the regex
`exec("cmd", exit_code=0)`	Whether a trusted local command exits with the expected code
`mcp_result_matches("tool", "field", "value")`	Whether recorded MCP result evidence for that tool matches one exact field/value pair

exec(...) requires explicit runtime opt-in.

Checks

Checks are structured objects, not condition: strings:

checks:
  - command_matches: "^pytest$"
    message: Run pytest before leaving this stage
  - command_not_matches: "^git push origin main$"
    message: Never push to main

Field	Required	Notes
`command_matches`	Exactly one of the two	Regex that must match command evidence
`command_not_matches`	Exactly one of the two	Regex that must not match command evidence
`message`	Yes	Failure message

Approval

approval:
  message: Human review required before continuing

approval.message is required whenever approval is present.

Runtime Semantics

Stages are ordered and forward-only during normal execution.
State is persisted per session and per workflow name.
tools is authoritative when present.
Omitting tools makes a non-terminal stage unrestricted.
A terminal stage with no tools blocks all later tool calls once that stage is active.
A terminal stage with tools may still allow matching tools, but never auto-advances past itself.
Successful Read calls record evidence for file_read(...).
Successful Bash calls record evidence for command_matches(...) and command_not_matches(...).
Approved stages satisfy approval(...).
MCP-backed runs can record structured result evidence for mcp_result_matches(...).
evaluate() and other dry-run paths do not replace real runtime state progression.

Validation Rules

The current runtimes reject workflow YAML when any of these are false:

apiVersion is edictum/v1
kind is Workflow
metadata.name matches ^[a-z0-9][a-z0-9._-]*$
stages contains at least one item
every stage.id matches ^[a-z0-9][a-z0-9._-]*$
every stage.id is unique
every tools entry is a valid tool name or glob pattern
every gate condition is supported and non-empty
every checks entry sets exactly one of command_matches or command_not_matches
every checks entry has message
approval.message is present when approval is defined
terminal: true only appears on the last stage

On this page