Adding Swarm Patterns

Adding Swarm Patterns

Overview

Add new multi-agent coordination patterns to agent-relay by updating four locations: TypeScript types, JSON schema, YAML template, and markdown docs.

When to Use

• Adding a new swarm pattern (e.g., "competitive", "auction")
• Extending coordination capabilities for multi-agent workflows
• Responding to user requests for new orchestration strategies

Quick Reference

Implementation Checklist

1. Update TypeScript Types

// packages/broker-sdk/src/workflows/types.ts
export type SwarmPattern =
  | 'fan-out'
  | 'pipeline'
  // ... existing patterns ...
  | 'your-new-pattern'; // Add here

2. Update JSON Schema

// packages/broker-sdk/src/workflows/schema.json
"SwarmPattern": {
  "type": "string",
  "enum": [
    "fan-out",
    "pipeline",
    // ... existing patterns ...
    "your-new-pattern"
  ]
}

3. Create YAML Template

# packages/broker-sdk/src/workflows/builtin-templates/{pattern}.yaml
version: '1.0'
name: pattern-name
description: 'One-line description'
swarm:
  pattern: pattern-name
  maxConcurrency: N
  timeoutMs: N
  channel: swarm-pattern-name
agents:
  - name: lead
    cli: claude
    role: 'Role description'
  # ... more agents
workflows:
  - name: workflow-name
    steps:
      - name: step-name
        agent: agent-name
        task: |
          Task description with {{task}} placeholder
        verification:
          type: output_contains
          value: STEP_COMPLETE
coordination:
  barriers:
    - name: barrier-name
      waitFor: [step1, step2]
state:
  backend: memory
  namespace: pattern-name
errorHandling:
  strategy: fail-fast

4. Create Pattern Documentation

# docs/workflows/patterns/{pattern}.md

# Pattern Name

One-sentence description.

## When to Use

- Use case 1
- Use case 2

## Structure

[ASCII diagram showing agent/step flow]

## Configuration

[YAML snippet]

## Best Practices

- Practice 1
- Practice 2

5. Create Template Documentation

# docs/workflows/templates/{pattern}.md

# Pattern Template

**Pattern:** name | **Timeout:** N minutes | **Channel:** swarm-name

## Overview

What this template does.

## Agents

| Agent | CLI | Role |
| ----- | --- | ---- |

## Workflow Steps

1. **step** (agent) — Description

## Usage

[CLI and TypeScript examples]

## Verification Markers

- `MARKER` — Description

6. Update README

Add to both tables in docs/workflows/README.md:

• Patterns table: | [pattern](patterns/pattern.md) | Description | Best For |
• Templates table: | [pattern](templates/pattern.md) | pattern | Description |

Common Mistakes

Pattern Design Guidelines

Good patterns have:

• Clear coordination model (who talks to whom)
• Defined failure handling (what happens if one agent fails)
• Appropriate concurrency (parallel vs sequential)
• Barrier synchronization for convergence points

Pattern categories:

• Parallel: fan-out, competitive, scatter-gather
• Sequential: pipeline, handoff, cascade
• Hierarchical: hub-spoke, hierarchical, supervisor
• Consensus: consensus, debate, auction
• Graph: dag, mesh