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. See how the app surfaces workflows

Section titled “5. See how the app surfaces workflows”

The desktop surfaces workflows too. Open the Workflows library, search the 107 bundled workflows, and open a detail modal to read a flow’s body and the skills it depends on.

The workflows library grouped by category

The library also has a Build a workflow button. Note what it does and does not do: it opens a modal where you write (or describe and let the model draft) a plain-language workflow body in Markdown, then saves it to your library. It is not a RON editor. There is no visual ForgeFlow builder in the desktop; RON ForgeFlows like the one in this tutorial are authored by hand and run through the wayland-core CLI or the inline Workflow tool.

To run a RON ForgeFlow, the model can call the built-in Workflow tool mid-conversation 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 how the desktop surfaces the bundled workflows.

Next

Section titled “Next”