Skip to content
Wayland Docs

Author and Ship a ForgeFlow

A ForgeFlow is a declarative, multi-stage agent pipeline written in RON. Instead of asking the model to orchestrate stages turn by turn, you describe a fan-out, pipeline, or verify topology once and run it as a coordinated set of sub-agents. This tutorial writes a small ForgeFlow, validates it, runs it, and shows the in-app equivalent. You will use the wayland-core CLI. See Install Wayland Core if you do not have it yet.

1. Understand the shape

Section titled “1. Understand the shape”

A ForgeFlow is a single Workflow(...) root document. The brand is ForgeFlows, but the grammar keyword stays Workflow(. It has three parts: meta, an optional schemas table, and an ordered list of phases. Each phase holds steps, and there are three step kinds: Agent, Pipeline, and Parallel. See the ForgeFlow (RON) Authoring Reference for the full grammar.

2. Author the file

Section titled “2. Author the file”

Saved ForgeFlows live in <project-root>/.wayland/workflows/*.ron, where the project root is the nearest ancestor of the current directory that contains a .wayland directory. Create the file:

Terminal window
mkdir -p .wayland/workflows
$EDITOR .wayland/workflows/review-changes.ron

Write a flow that scans changed files in a pipeline, then verifies in parallel and summarizes:

Workflow(
    meta: (name: "review-changes", description: "review a diff end to end"),
    phases: [
        Phase(
            title: "verify",
            steps: [
                Parallel(id: "verdict", branches: [
                    (id: "lint",  prompt: "lint the diff and return findings"),
                    (id: "audit", prompt: "audit the diff for risk"),
                ], join: Collect),
                Agent((id: "summarize", prompt: "summarize the verdict", input: Some("verdict"))),
            ],
        ),
    ],
)

A Parallel step needs at least two branches; one is rejected as degenerate. The summarize agent reads the collected verdict array by naming it in input.

3. Validate before running

Section titled “3. Validate before running”

Validation parses the file and reports problems without contacting a provider:

Terminal window
wayland-core workflow validate .wayland/workflows/review-changes.ron

On success it prints OK: review-changes with the node count and the estimated agent count. The estimate comes from walking the lowered graph, not from any est_agents hint you write in meta. On a problem, such as a duplicate node id, a dangling input ref, or an unknown schema, it prints a typed error with a field pointer and exits non-zero. Fix the file and validate again until it is clean.

4. List and run

Section titled “4. List and run”

List the saved ForgeFlows in the project:

Terminal window
wayland-core workflow list

Each line shows the name, an estimated agent count, and the description. Unparseable files are skipped with a warning rather than aborting the list.

Run the flow by name:

Terminal window
wayland-core workflow run review-changes

The run path resolves the name, parses it, builds a provider and spawner from your normal config, prints a pre-execution estimate to stderr, executes through the workflow runner, and prints the structured outcome as JSON: the per-stage records plus the final state. Because you opted in by invoking run, there is no extra confirm gate at the flow level. Each inner tool call a stage makes still keeps its own approval gate.

The subcommand has the alias forgeflows, so wayland-core forgeflows run review-changes works too.

5. Build the same thing in the app

Section titled “5. Build the same thing in the app”

The desktop surfaces ForgeFlows as well. Open the Workflows library, search the 176 bundled workflows, and open a detail modal to read a flow’s body and the skills it depends on. To author your own, use the Build Workflow modal, which writes the same RON shape you wrote by hand.

The workflows library grouped by category

The model can also run a ForgeFlow mid-conversation through the built-in Workflow tool by passing an inline RON string. Note that the tool and the CLI run path both start with an empty initial state, so a Pipeline(over: ...) that needs a starting collection should produce it in an earlier stage.

What you built

Section titled “What you built”

You authored a ForgeFlow in RON, validated it without spending tokens, ran it as a coordinated set of sub-agents, read the structured outcome, and saw the same construct in the app.

Next

Section titled “Next”