writing-relayflows
Use when authoring a Relayflows flow (@relayflows/surface / @relayflows/sdk, the journal-based v2 engine — the CLI is `flows`, package versions 2.0.x) in TypeScript or YAML/JSON. Covers the three-rung ladder (run/llm/agent), the resident verbs (human/dispatch/done), verification gates, TypeScript vs YAML authoring, per-step cli/model selection and its resolution order, flows.json, and `flows check`/`run`/`resume` with their real refusal shapes and exit codes. Not for the older, unrelated `@relayflows/core` WorkflowBuilder engine (`.pattern('dag')`/.agent()/.step() chains) that `writing-agent-relay-workflows` and `migrating-persona-to-relayflow` cover — that's a different product despite the similar name.
AgentWorkforce · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add AgentWorkforce/relay --skill writing-relayflowsAbout this skill
name: writing-relayflows
description: Use when authoring a Relayflows flow (@relayflows/surface / @relayflows/sdk, the journal-based v2 engine — the CLI is flows, package versions 2.0.x) in TypeScript or YAML/JSON. Covers the three-rung ladder (run/llm/agent), the resident verbs (human/dispatch/done), verification gates, TypeScript vs YAML authoring, per-step cli/model selection and its resolution order, flows.json, and flows check/run/resume with their real refusal shapes and exit codes. Not for the older, unrelated @relayflows/core WorkflowBuilder engine (.pattern('dag')/.agent()/.step() chains) that writing-agent-relay-workflows and migrating-persona-to-relayflow cover — that's a different product despite the similar name.
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.tsor.flow.yaml/.flow.jsonfor theflowsCLI (package@relayflows/sdk, binary nameflows). - Deciding whether a step needs
run(shell),llm(bare model call), oragent(harnessed coding agent in a workspace). - Wiring up
cli/modelfor anagentorllmstep, in either language. - Debugging a
REFUSED [...]message fromflows checkorflows 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';):
run/deterministic— a shell command. No model. Implicit gate isexit_code == 0.llm/llm— a bare model call. Prompt in, verified output out. No workspace, no tool use.agent/agent— a harnessed coding agent in a workspace. Returns{ summary, artifacts }, not raw text.
Plus four resident verbs that aren't ladder rungs: human (durable approval), dispatch (hand off to a child flow), done (typed finish), and in YAML, on/triggers (event entry points — out of scope for this skill).
Most flows only need run and llm. Climb to agent once a step needs hands on a real workspace.
Two ways to author the same thing
TypeScript
import { flow } from '@relayflows/surface';
export default flow('hello', async (f) => {
const greeting = await f.run('echo "Hello from Relayflows"');
console.log(greeting.trim());
const answer = await f.agent('greeter', {
task: 'Reply with one short hello sentence. Do not use tools or modify files.',
cli: 'claude',
model: 'claude-sonnet-4-6',
});
console.log(answer.summary);
f.done('success');
});
YAML
version: '0.1.0'
name: hello
steps:
- id: greeting
type: deterministic
command: 'echo "Hello from Relayflows"'
- id: greeter
type: agent
dependsOn: [greeting]
instruction: 'Reply with one short hello sentence. Do not use tools or modify files.'
cli: claude
model: claude-sonnet-4-6
The real Ctx contract (TypeScript)
packages/surface/src/context.ts, current as of origin/main@86a2ec2:
export interface AgentResult {
summary: string;
artifacts: string[];
}
export interface AgentOptions {
task: string;
workspace?: string;
cli?: string;
model?: string;
}
export interface Ctx {
run(command: string): Step<string>;
llm(strings: TemplateStringsArray, ...values: unknown[]): Step<string>;
llm(
prompt: string,
options: { output: Record<string, unknown>; cli?: string; model?: string }
): Step<unknown>;
agent(name: string, options: AgentOptions): Step<AgentResult>;
human(question: string, options: { to: string }): Promise<boolean>;
dispatch<T>(flow: string, input: unknown): Promise<T>;
done(reason: RunCompletionReason): void;
cloud: CloudHelper;
slack: SlackHelper;
}
The real step shapes (YAML/JSON, packages/sdk/src/spec.ts)
```ts
interface DeterministicStepSpec {
type: 'deterministic';
id: string;
command: string;
dependsOn?: string[];
timeoutMs?: number;
verification?: VerificationSpec; // omit for implicit exit_code
}
interface LlmStepSpec {
type: 'llm';
id: string;
prompt: string;
dependsOn?: string[];
verification?: OutputVerificationSpec;
model?: string;
cli?: string;
}
interface AgentStepSpec {
type: 'agent';
id: string;
instruction: string;
dependsOn?: string[];
verification?: OutputVerificationSpec;
agent?: string; // selects a named FlowSpec.agents entry
cli?: string;
model?: string;
surfaces?: { workspace?: { surface: string }[]; streams?: { stream: string }[]; external?: string[] };
recoveryMode?: 'reset' | 'inspect' | 'manual'; // default 'reset'
permissions?: {
fileGlobs?: string[];
networkAllowlist?: string[];
accessPreset?: 'readonly' | 'readwrite';
};
}
interface FlowSpec {
version: string; // required, e.g. '0.1.0' — not optional
name?: string;
cli?: string; // flow-level CLI default
agents?: Record<string, { cli: string; model: string }>; // both fields required
steps: StepSpec[];
budget?: { maxTokensIn?: number; maxTokensOut?: numbe
Read the complete source ↗