Skip to content
Wayland Docs

ForgeFlow (RON) Authoring Reference

A ForgeFlow is a declarative, multi-stage agent pipeline written in RON (Rusty Object Notation). This page is the reference for the format. The authoritative source is docs/workflows.md in the engine repository.

The shape of a document

Section titled “The shape of a document”

A ForgeFlow is a single Workflow(...) value with three parts:

Workflow(
  meta: ( /* identity and defaults */ ),
  schemas: { /* named structured-output schemas */ },
  phases: [ /* the ordered stages */ ],
)

meta

Section titled “meta”

meta carries the workflow’s identity and defaults: its name, a description, run-level settings, and est_agents (a hand-written estimate of how many sub-agents the flow spawns). The name is how the CLI and the Workflow tool resolve and list it.

schemas

Section titled “schemas”

schemas defines named structured-output shapes a step can require, so a stage returns validated data rather than free text. A later stage consumes that data by name.

phases and steps

Section titled “phases and steps”

phases is the ordered list of stages. Each phase contains one or more steps. A step describes a unit of agent work and how it runs:

  • A plain step runs one agent task.
  • A fan-out step runs the same task across many inputs.
  • A pipeline step streams items through stages without a barrier between them, so an item can move to the next stage as soon as it is ready rather than waiting for the whole batch.

Agent fields

Section titled “Agent fields”

Each step’s agent carries fields such as its id, its prompt, the schema it must satisfy, an optional model, and its input. The CLI’s reported agent count does not read est_agents: the estimator walks the lowered execution graph and counts the agents it actually produces.

Data flow between stages

Section titled “Data flow between stages”

Output from one stage feeds the next. Stages reference prior results so a pipeline composes: discover, then transform each item, then verify. Verification steps run as their own stage so a finding is checked before it is accepted.

Validation

Section titled “Validation”

ForgeFlows are validated at parse time, before any provider call. Run the validator to catch grammar and reference errors without executing anything:

Terminal window
wayland-core workflow validate path/to/flow.ron

How it runs

Section titled “How it runs”

A ForgeFlow lowers to an execution-graph intermediate representation and runs over the Delegate (sub-agent) path. It is surfaced three ways: as the Workflow LLM tool the agent can call, as the wayland-core workflow CLI (alias forgeflows) over files in .wayland/workflows/, and through shadow-mode detection (off by default).

Next

Section titled “Next”