Writing Relayflows

Overview

Relayflows turns a coding-agent task into steps a journal can inspect, verify, and resume. A flow is data (YAML/JSON) or code (TypeScript) that compiles to the same journal-backed kernel spec. Every effect is journaled before it's treated as real — a journal write that fails fails the step, with no silent fallback.

Name collision warning. An older, unrelated engine is also casually called "Relayflow" (singular): @relayflows/core's WorkflowBuilder, a chained builder (workflow('name').pattern('dag').agent(...).step(...).run()). This skill is the v2 engine: @relayflows/surface's flow() function and the YAML/JSON dialect compiled by @relayflows/sdk. If you see .pattern(, .agent( as a chained builder call, or ctx.workflow.run(), you are looking at legacy code. Do not use that syntax for new work; keep v2 guidance inside this skill.

When to use this skill

• Writing a new .flow.ts or .flow.yaml/.flow.json for the flows CLI (package @relayflows/sdk, binary name flows).
• Deciding whether a step needs run (shell), llm (bare model call), or agent (harnessed coding agent in a workspace).
• Choosing a verification gate that will actually run — a wrong choice here compiles fine and fails at flows run time, not authoring time.
• Wiring up cli/model for an agent or llm step, in either language.
• Debugging a REFUSED [...] message from flows check or flows run.
• Deciding between running a flow locally, deploying it to listen for tickets, or scheduling it on a cron.

Inputs and hosted authoring