git:20260509.f341463 to git:20260518.cdd78c8

- description: Use when building multi-agent workflows with the relay broker-sdk - covers conversation-shape vs pipeline-shape coordination, the WorkflowBuilder API, DAG step dependencies, agent definitions, step output chaining via {{steps.X.output}}, verification gates, evidence-based completion, owner decisions, dedicated channels, dynamic channel management (subscribe/unsubscribe/mute/unmute), swarm patterns, chat-native coordination recipes (Q/A, broadcast-ack, peer review, standup, hand-off), error handling, event listeners, step sizing rules, authoring best practices, and the lead+workers team pattern for complex steps

- | Shape | What it is | Use when |

- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ----------- |

- | **Conversation** (chat-native) | Interactive agents share a channel; messages, `@-mentions`, and ambient awareness drive coordination. Lead and workers spawn in parallel and self-organize. The relay is the coordination layer, not just transport. | Multi-file work, peer review loops, cross-agent feedback, dynamic re-planning, multi-PR coordination, anything with a human-in-the-loop escape, swarms where workers pick up each other's output. |

- | **Pipeline** (one-shot DAG) | Each step runs as a one-shot subprocess (`claude -p`, `codex exec`); steps hand off via `{{steps.X.output}}` text injection. No agents are alive at the same time; no chat happens. | Linear, well-specified transformations; deterministic data passing; no review loop expected; the work could be expressed as a `bash | bash | bash` pipe. |

- const result = await workflow('my-workflow')

- .description('What this workflow does')

- .pattern('dag') // or 'pipeline', 'fan-out', etc.

- .channel('wf-my-workflow') // dedicated channel (auto-generated if omitted)

- .maxConcurrency(3)

- .timeout(3_600_000) // global timeout (ms)

- .agent('lead', { cli: 'claude', role: 'Architect', retries: 2 })

- .agent('worker', { cli: 'codex', role: 'Implementer', retries: 2 })

- .step('plan', {

- agent: 'lead',

- task: `Analyze the codebase and produce a plan.`,

- retries: 2,

- verification: { type: 'output_contains', value: 'PLAN_COMPLETE' },

- })

- .step('implement', {

- agent: 'worker',

- task: `Implement based on this plan:\n{{steps.plan.output}}`,

- dependsOn: ['plan'],

- verification: { type: 'exit_code' },

- })

- .onError('retry', { maxRetries: 2, retryDelayMs: 10_000 })

- .run({ cwd: process.cwd() });

- console.log('Result:', result.status);

- const result = await workflow('my-workflow')

- .description('Multi-file change with peer review')

- .pattern('dag')

- .channel('wf-my-feature') // dedicated channel — agents share it

- .maxConcurrency(4)

- .timeout(3_600_000)

- // Interactive agents — no preset, they live on the channel

- .agent('lead', {

- cli: 'claude',

- model: ClaudeModels.OPUS,

- role: 'Architect + reviewer. Plans, assigns, reviews, posts feedback.',

- retries: 1,

- })

- .agent('impl-a', {

- cli: 'codex',

- model: CodexModels.GPT_5_4,

- role: 'Implementer. Listens on channel for assignments and feedback.',

- retries: 2,

- })

- .agent('impl-b', {

- cli: 'codex',

- model: CodexModels.GPT_5_4,

- role: 'Implementer. Listens on channel for assignments and feedback.',

- retries: 2,

- })

- // Deterministic context — pre-reads files once, posts to the channel for everyone

- .step('context', {

- type: 'deterministic',

- command: 'git ls-files src/',

- captureOutput: true,

- })

- // Lead and workers all depend on `context` — they start CONCURRENTLY.

- // They coordinate over #wf-my-feature, not via {{steps.X.output}}.

- .step('lead-coordinate', {

- agent: 'lead',

- dependsOn: ['context'],

- task: `You are the lead on #wf-my-feature. Workers: impl-a, impl-b.

- })

- .step('impl-a-work', {

- agent: 'impl-a',

- dependsOn: ['context'], // SAME dep as lead → starts in parallel, no deadlock

- task: `You are impl-a on #wf-my-feature. Wait for the lead's plan.

- })

- .step('impl-b-work', {

- agent: 'impl-b',

- dependsOn: ['context'], // SAME dep as lead

- task: `You are impl-b on #wf-my-feature. Wait for the lead's plan.

- })

- // Downstream gates on the lead — lead exits when satisfied.

- .step('verify', {

- type: 'deterministic',

- dependsOn: ['lead-coordinate'],

- command: 'npm run typecheck && npm test',

- failOnError: true,

- })

- .onError('retry', { maxRetries: 2, retryDelayMs: 10_000 })

- .run({ cwd: process.cwd() });

- import { createGitHubStep } from '@agent-relay/sdk/github';

- await workflow('feature-x')

- // ... your real steps that produce code changes ...

- .step('write-marker', {

- type: 'deterministic',

- command: `echo "fix landed at $(date -u)" >> CHANGELOG.md`,

- })

-

- // Branch off main on the remote.

- .step(

- 'create-branch',

- createGitHubStep({

- dependsOn: ['write-marker'],

- action: 'createBranch',

- repo: REPO,

- params: { branch: BRANCH, source: 'main' },

- )

- // Commit the change to the branch via Contents API.

- .step(

- 'commit-change',

- createGitHubStep({

- dependsOn: ['create-branch'],

- action: 'createFile',

- repo: REPO,

- params: {

- path: 'CHANGELOG.md',

- branch: BRANCH,

- content: '<file body here>',

- message: 'chore: changelog entry',

- },

- })

- )

- // Open the PR. This is the load-bearing step.

- .step(

- 'open-pr',

- createGitHubStep({

- dependsOn: ['commit-change'],

- action: 'createPR',

- repo: REPO,

- params: {

- title: 'feat: ship feature X',

- head: BRANCH,

- base: 'main',

- body: '## Summary\n\n- ...\n\n## Test plan\n\n- [x] ...',

- draft: false,

- },

- output: { mode: 'data', format: 'json', path: 'html_url' },

- })

- )

- .run({ cwd: process.cwd() });

- model: CodexModels.O3,

- model: CodexModels.O3,

- dependsOn: [verify-types]

- dependsOn: [verify-service]

- command: git add src/types.ts src/service.ts && git commit -m "feat: add pending status"

- | Mistake | Fix |

- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ----------- |

- | Treating relay as transport, not as a coordination layer (every step is `preset: 'worker'`, every handoff is `{{steps.X.output}}`) | Default to **Conversation shape** for non-trivial work — interactive agents on a shared channel. Pipeline-shape is only correct when the work could be expressed as a `bash | bash | bash` pipe. |

- | Interactive agents on a channel whose task strings don't tell them to talk to each other | Pick a [Chat-Native Coordination Recipe](#chat-native-coordination-recipes) (Q/A, Broadcast/Ack, Peer Review, Standup, Hand-Off) and bake it into the task prompt — otherwise you're paying for a chat substrate you're not using |

- | All workflows run sequentially | Group independent workflows into parallel waves (4-7x speedup) |

- | Every step depends on the previous one | Only add `dependsOn` when there's a real data dependency |

- | Self-review step with no timeout | Set `timeout: 300_000` (5 min) — Codex hangs in non-interactive review |

- | One giant workflow per feature | Split into smaller workflows that can run in parallel waves |

- | Adding exit instructions to tasks | Runner handles self-termination automatically |

- | Setting `timeoutMs` on agents/steps | Use global `.timeout()` only |

- | Using `general` channel | Set `.channel('wf-name')` for isolation |

- | `{{steps.X.output}}` without `dependsOn: ['X']` | Output won't be available yet |

- | Requiring exact sentinel as only completion gate | Use `exit_code` or `file_exists` verification |

- | Writing 100-line task prompts | Split into lead + workers on a channel |

- | `maxConcurrency: 16` with many parallel steps | Cap at 5-6 |

- | Non-interactive agent reading large files via tools | Pre-read in deterministic step, inject via `{{steps.X.output}}` |

- | Workers depending on lead step (deadlock) | Both depend on shared context step |

- | `fan-out`/`hub-spoke` for simple parallel workers | Use `dag` instead |

- | `pipeline` but expecting auto-supervisor | Only hub patterns auto-harden. Use `.pattern('supervisor')` |

- | Workers without `preset: 'worker'` in one-shot DAG lead+worker flows | Add preset for clean stdout when chaining `{{steps.X.output}}` (not needed for interactive team patterns) |

- | Using `_` in YAML numbers (`timeoutMs: 1_200_000`) | YAML doesn't support `_` separators |

- | Workflow timeout under 30 min for complex workflows | Use `3600000` (1 hour) as default |

- | Using `require()` in ESM projects | Check `package.json` for `"type": "module"` — use `import` if ESM |

- | Wrapping in `async function main()` in ESM | ESM supports top-level `await` — no wrapper needed |

- | Using `createWorkflowRenderer` | Does not exist. Use `.run({ cwd: process.cwd() })` |

- | `export default workflow(...)...build()` | No `.build()`. Chain ends with `.run()` — the file must call `.run()`, not just export config |

- | Relative import `'../workflows/builder.js'` | Use `import { workflow } from '@agent-relay/sdk/workflows'` |

- | Hardcoded model strings (`model: 'opus'`) | Use constants: `import { ClaudeModels } from '@agent-relay/config'` → `model: ClaudeModels.OPUS` |

- | Thinking `agent-relay run` inspects exports | It executes the file as a subprocess. Only `.run()` invocations trigger steps |

- | `pattern('single')` on cloud runner | Not supported — use `dag` |

- | `pattern('supervisor')` with one agent | Same agent is owner + specialist. Use `dag` |

- | Invalid verification type (`type: 'deterministic'`) | Only `exit_code`, `output_contains`, `file_exists`, `custom` are valid |

- | Chaining `{{steps.X.output}}` from interactive agents | PTY output is garbled. Use deterministic steps or `preset: 'worker'` |

- | Single step editing 4+ files | Agents modify 1-2 then exit. Split to one file per step with verify gates |

- | Relying on agents to `git commit` | Agents emit markers without running git. Use deterministic commit step |

- | File-writing steps without `file_exists` verification | `exit_code` auto-passes even if no file written |

- | Manual peer fanout in `handleChannelMessage()` | Use broker-managed channel subscriptions — broker fans out to all subscribers automatically |

- | Client-side `personaNames.has(from)` filtering | Use `relay.subscribe()`/`relay.unsubscribe()` — only subscribed agents receive messages |

- | Agents receiving noisy cross-channel messages during focused work | Use `relay.mute({ agent, channel })` to silence non-primary channels without leaving them |

- | Hardcoding all channels at spawn time | Use `agent.subscribe()` / `agent.unsubscribe()` for dynamic channel membership post-spawn |

- | Using `preset: 'worker'` for Codex in _interactive team_ patterns when coordination is needed | Codex interactive mode works fine with PTY channel injection. Drop the preset for interactive team patterns (keep it for one-shot DAG workers where clean stdout matters) |

- | Separate reviewer agent from lead in interactive team | Merge lead + reviewer into one interactive Claude agent — reviews between rounds, fewer agents |

- | Not printing PR URL after `createGitHubStep({ action: 'createPR' })` | Capture `html_url` with `output: { mode: 'data', format: 'json', path: 'html_url' }` and echo or write it in a final deterministic step |

- | Workflow ending without worktree + PR for cross-repo changes | Add `setup-worktree` at start and `push-and-pr` + `cleanup-worktree` at end |