Choosing Swarm Patterns

swarm: { pattern: handoff }
agents:
  - { name: triage, cli: claude }
  - { name: billing, cli: claude }
  - { name: tech, cli: claude }
workflows:
  - name: support
    steps:
      - { name: triage, agent: triage, task: 'Triage: {{request}}' }
      - { name: billing, agent: billing, dependsOn: [triage], task: 'Handle billing' }
      - { name: tech, agent: tech, dependsOn: [triage], task: 'Handle tech issues' }

swarm: { pattern: cascade }
agents:
  - { name: haiku, cli: claude, model: claude-haiku-4-5-20251001 }
  - { name: sonnet, cli: claude, model: claude-sonnet-4-6 }
  - { name: opus, cli: claude, model: claude-opus-4-7 }
workflows:
  - name: answer
    steps:
      - { name: try-haiku, agent: haiku, task: '{{question}}' }
      - name: try-sonnet
        agent: sonnet
        dependsOn: [try-haiku]
        task: "If this is a complete answer, echo it verbatim. Otherwise answer anew:\n{{steps.try-haiku.output}}"
      - name: try-opus
        agent: opus
        dependsOn: [try-sonnet]
        task: "Final-tier answer, using prior attempts for context:\n{{steps.try-sonnet.output}}"

swarm:
  pattern: dag
  maxConcurrency: 3
agents:
  - { name: dev, cli: codex, role: worker }
workflows:
  - name: fullstack
    steps:
      - { name: scaffold, agent: dev, task: 'Create project scaffold' }
      - { name: frontend, agent: dev, task: 'Build React UI', dependsOn: [scaffold] }
      - { name: backend, agent: dev, task: 'Build API', dependsOn: [scaffold] }
      - { name: integrate, agent: dev, task: 'Wire together', dependsOn: [frontend, backend] }

swarm: { pattern: debate }
agents:
  - { name: pro, cli: claude, role: debater, task: 'Argue FOR monorepo' }
  - { name: con, cli: claude, role: debater, task: 'Argue FOR polyrepo' }
  - { name: judge, cli: claude, role: judge, task: 'Decide after 3 rounds' }
coordination:
  barriers:
    - { name: debate-done, waitFor: [pro-round-3, con-round-3] }

swarm: { pattern: hierarchical }
agents:
  - { name: lead, cli: claude, role: lead }
  - { name: fe-coord, cli: claude, role: coordinator }
  - { name: be-coord, cli: claude, role: coordinator }
  - { name: fe-dev, cli: codex, role: worker, interactive: false }
  - { name: be-dev, cli: codex, role: worker, interactive: false }
workflows:
  - name: large-team
    steps:
      - { name: plan, agent: lead, task: 'Coordinate full-stack app' }
      - { name: fe-plan, agent: fe-coord, task: 'Manage frontend', dependsOn: [plan] }
      - { name: be-plan, agent: be-coord, task: 'Manage backend', dependsOn: [plan] }
      - { name: fe-impl, agent: fe-dev, task: 'Build components', dependsOn: [fe-plan] }
      - { name: be-impl, agent: be-dev, task: 'Build API', dependsOn: [be-plan] }

verification:
  type: output_contains # or: exit_code | file_exists | custom
  value: DONE # or: PLAN_COMPLETE, IMPLEMENTATION_COMPLETE, REVIEW_COMPLETE

trajectories:
  enabled: true
  reflectOnBarriers: true # config flag exists but runner does NOT currently invoke this path
  reflectOnConverge: true # fires at parallel convergence points (runner.ts:2762-2779)
  autoDecisions: true # record retry/skip/fail decisions

// Resume a failed run:
await runWorkflow('feature-dev.yaml', { resume: '<runId>' });
// Skip ahead, re-using cached outputs from an earlier run:
await runWorkflow('feature-dev.yaml', {
  startFrom: 'review',
  previousRunId: '<runId>',
});

version: '1.0'
name: feature-dev
description: 'Blueprint-style feature development with quality gates.'
swarm:
  pattern: hub-spoke
  maxConcurrency: 2
  timeoutMs: 3600000
  channel: swarm-feature-dev
  idleNudge: { nudgeAfterMs: 120000, escalateAfterMs: 120000, maxNudges: 1 }
agents:
  - { name: lead, cli: claude, role: lead, permissions: { access: full } }
  - { name: planner, cli: codex, role: planner, interactive: false, permissions: { access: readonly } }
  - { name: developer, cli: codex, role: worker, interactive: false, permissions: { access: readwrite } }
  - { name: reviewer, cli: claude, role: reviewer, permissions: { access: readonly } }
workflows:
  - name: feature-delivery
    onError: retry
    preflight:
      - { command: 'git status --porcelain', failIf: non-empty, description: 'Clean worktree' }
    steps:
      - name: plan
        agent: planner
        task: 'Plan: {{task}}'
        verification: { type: output_contains, value: PLAN_COMPLETE }
      - name: implement
        agent: developer
        dependsOn: [plan]
        task: 'Implement: {{steps.plan.output}}'
        verification: { type: output_contains, value: IMPLEMENTATION_COMPLETE }
      - name: test
        type: deterministic
        dependsOn: [implement]
        command: npm test
      - name: review
        agent: reviewer
        dependsOn: [test]
        task: 'Review implementation'
        verification: { type: output_contains, value: REVIEW_COMPLETE }
coordination:
  barriers:
    - { name: delivery-ready, waitFor: [plan, implement, review], timeoutMs: 900000 }
trajectories:
  enabled: true
  reflectOnBarriers: true
  reflectOnConverge: true
errorHandling:
  strategy: retry
  maxRetries: 2
  retryDelayMs: 5000