choosing-swarm-patterns

What it does

The skill instructs an AI agent to pick an appropriate swarm pattern for coordinating multiple agents using Agent Relay's workflow engine. It documents 24 swarm patterns via a single swarm.pattern field and emphasizes using the simplest pattern that solves the problem, adding complexity only when necessary. It provides both YAML and fluent-builder methods to run a pattern, plus a Quick Decision Framework to decide which pattern to use. It includes detailed Pattern Reference (Core 10) and description examples for each pattern, as well as an extended set of 14 additional patterns and structured guidance for squad reviews and verification signals.

How it works

• It explains two execution modes: YAML (portable) and Fluent Builder (programmatic), showing code snippets for each method to set pattern, channels, agents, steps, and run the workflow.
• It presents a decision framework: asks a series of Boolean-style questions to determine the appropriate pattern (fan-out, pipeline, hub-spoke, consensus, mesh, handoff, cascade, dag, debate, hierarchical, plus additional role-driven patterns).
• It lists the Core 10 patterns in a table with topology and best use cases, and adds notes on structural nuances (e.g., hierarchical resolves to hub-spoke topology in current implementation).
• It provides concrete blocks of code or YAML for representative patterns (fan-out, pipeline, hub-spoke, consensus, mesh, handoff, cascade, dag, debate, hierarchical) and several structured examples for each.
• It covers verification and completion signals, detailing how an agent step may complete via verification types and values.

When to use it

• Use when coordinating multiple AI agents with Agent Relay’s workflow engine and you need to pick the right orchestration pattern.
• Consult the Quick Decision Framework to determine if the task is independent per agent, whether outputs depend on previous steps, whether a coordinating agent must stay alive, whether the task involves decision-making, and other criteria to select patterns such as fan-out, pipeline, hub-spoke, consensus, mesh, handoff, cascade, dag, debate, or hierarchical.

What it can touch

• It references the declarative YAML and programmatic workflow builder via @relayflows/core, including runWorkflow and workflow() usage:
  • runWorkflow('workflows/feature-dev.yaml', { vars: { task: 'Add OAuth login' } })
  • workflow('feature-dev').pattern('hub-spoke').channel('swarm-feature-dev')... .run()
• It uses the swarm.pattern field to select patterns and describes the supported topologies and steps for each pattern.

Caveats

• Hierarchical pattern structurally mirrors hub-spoke in current implementation; multi-level trees are not implemented. Use the pattern name for intent, but expect the same runtime graph.
• The description notes that there are no standalone helper functions like fanOut(...) or hubAndSpoke(...); patterns are configured declaratively via YAML or the workflow() fluent builder.
• License indicated: Apache-2.0.