Workflows (forgeflows CLI)

A ForgeFlow is a declarative multi-stage agent pipeline written in RON. Saved flows live under .wayland/workflows/ and run as sub-agent stages over the same provider and spawner the main agent loop uses. The workflow subcommand (alias forgeflows) is how you check, find, and run them.

Where flows are found

The engine looks for .wayland/workflows/*.ron, resolving the project root by walking up from the current directory to the nearest existing .wayland directory. A flow’s name is the file stem: nightly-audit.ron is run as nightly-audit.

Validate before you run

validate parses a single .ron file and prints a summary without executing anything. No provider is contacted.

wayland-core workflow validate .wayland/workflows/nightly-audit.ron

On success it prints the flow name, node count, and an estimated agent count walked from the IR. On failure it prints the typed parse error with a field pointer and exits non-zero, so it fits in CI.

List saved flows

wayland-core workflow list

Each line shows the flow name, an estimated agent count, and its description, drawn from the flow’s metadata and the cost estimator. Files that fail to parse are skipped with a warning rather than aborting the list.

Run a flow

wayland-core workflow run nightly-audit

This resolves nightly-audit to .wayland/workflows/nightly-audit.ron, parses it, and executes it through the workflow runner over a real provider. The same flows surface in-app as the Workflow tool, so a flow you validate here behaves the same when an agent calls it.

The forgeflows alias is interchangeable:

wayland-core forgeflows list

Writing a flow

A flow declares meta, schemas, and phases, with topologies such as pipeline and fan-out. For the grammar and authoring patterns, see the ForgeFlow authoring reference. Start by validating early and often: the parse error pointer is the fastest way to find a mistake.