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. This repo also has skills for an older, unrelated engine that is also casually called "Relayflow" (singular), @relayflows/core's WorkflowBuilder, a chained builder (workflow('name').pattern('dag').agent(...).step(...).run()). That's writing-agent-relay-workflows and migrating-persona-to-relayflow's territory. 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're in the other engine, stop and use one of those skills instead.

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).
• Wiring up cli/model for an agent or llm step, in either language.
• Debugging a REFUSED [...] message from flows check or flows run.
• Choosing between TypeScript and YAML for a given flow.

The ladder

Three step verbs, one per rung, never more (packages/sdk/src/spec.ts, export type StepType = 'deterministic' | 'llm' | 'agent';):

1. run / deterministic, a shell command. No model. Implicit gate is exit_code == 0.
2. llm / llm, a bare model call. Prompt in, verified output out. No workspace, no tool use.
3. agent / agent, a harnessed coding agent in a workspace. Returns { summary, artifacts }, not raw text.