From f98d0eeaa2d74250cbef15f111ae1bafd84cfa5b Mon Sep 17 00:00:00 2001 From: Agent Relay Date: Thu, 19 Feb 2026 16:52:37 +0000 Subject: [PATCH] feat: add competitive swarm pattern and adding-swarm-patterns skill Add competitive pattern for multiple independent implementations followed by comparison and selection. Useful for exploratory work and architecture decisions where diverse approaches help find optimal solutions. Changes: - Add "competitive" to SwarmPattern type and JSON schema - Create competitive.yaml template with 3 competing teams - Add pattern and template documentation - Create adding-swarm-patterns skill for guidance on future additions Co-Authored-By: Claude Opus 4.5 --- .claude/skills/adding-swarm-patterns/SKILL.md | 174 ++++++++++++++++++ docs/workflows/README.md | 2 + docs/workflows/patterns/competitive.md | 139 ++++++++++++++ docs/workflows/templates/competitive.md | 68 +++++++ .../builtin-templates/competitive.yaml | 103 +++++++++++ packages/broker-sdk/src/workflows/schema.json | 3 +- packages/broker-sdk/src/workflows/types.ts | 3 +- 7 files changed, 490 insertions(+), 2 deletions(-) create mode 100644 .claude/skills/adding-swarm-patterns/SKILL.md create mode 100644 docs/workflows/patterns/competitive.md create mode 100644 docs/workflows/templates/competitive.md create mode 100644 packages/broker-sdk/src/workflows/builtin-templates/competitive.yaml diff --git a/.claude/skills/adding-swarm-patterns/SKILL.md b/.claude/skills/adding-swarm-patterns/SKILL.md new file mode 100644 index 000000000..526d4f689 --- /dev/null +++ b/.claude/skills/adding-swarm-patterns/SKILL.md @@ -0,0 +1,174 @@ +--- +name: adding-swarm-patterns +description: Use when adding new multi-agent coordination patterns to agent-relay - provides checklist for types, schema, templates, and docs updates +tags: agent-relay, swarm, patterns, workflows +--- + +# 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 + +| File | Location | What to Add | +|------|----------|-------------| +| types.ts | `packages/broker-sdk/src/workflows/types.ts` | Add to `SwarmPattern` union type | +| schema.json | `packages/broker-sdk/src/workflows/schema.json` | Add to `SwarmPattern.enum` array | +| template.yaml | `packages/broker-sdk/src/workflows/builtin-templates/` | Create `{pattern}.yaml` | +| pattern.md | `docs/workflows/patterns/` | Create `{pattern}.md` | +| template.md | `docs/workflows/templates/` | Create `{pattern}.md` | +| README.md | `docs/workflows/README.md` | Add to patterns and templates tables | + +## Implementation Checklist + +### 1. Update TypeScript Types + +```typescript +// packages/broker-sdk/src/workflows/types.ts +export type SwarmPattern = + | "fan-out" + | "pipeline" + // ... existing patterns ... + | "your-new-pattern"; // Add here +``` + +### 2. Update JSON Schema + +```json +// packages/broker-sdk/src/workflows/schema.json +"SwarmPattern": { + "type": "string", + "enum": [ + "fan-out", + "pipeline", + // ... existing patterns ... + "your-new-pattern" + ] +} +``` + +### 3. Create YAML Template + +```yaml +# 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 + +```markdown +# 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 + +```markdown +# 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 + +| Mistake | Fix | +|---------|-----| +| Forgetting schema.json | Validation will fail if schema doesn't include the pattern | +| Inconsistent naming | Use same name in types, schema, template filename, and docs | +| Missing verification markers | Each step should have `output_contains` verification | +| Wrong doc links | Use relative paths: `patterns/name.md` not `/docs/workflows/patterns/name.md` | + +## 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 diff --git a/docs/workflows/README.md b/docs/workflows/README.md index 3533a040e..eeb2a11e0 100644 --- a/docs/workflows/README.md +++ b/docs/workflows/README.md @@ -28,6 +28,7 @@ Swarm patterns define how agents coordinate and execute tasks. Choose the patter | [cascade](patterns/cascade.md) | Waterfall with phase gates | Gated release processes | | [debate](patterns/debate.md) | Agents propose and counter-argue | Design exploration, trade-off analysis | | [hierarchical](patterns/hierarchical.md) | Multi-level reporting structure | Large refactors, organizational workflows | +| [competitive](patterns/competitive.md) | Independent parallel builds, then compare | Solution exploration, architecture spikes | ## Built-in Templates @@ -41,6 +42,7 @@ Pre-configured workflows for common development tasks. Each template defines age | [security-audit](templates/security-audit.md) | pipeline | Scan, triage, remediate, and verify security issues | | [refactor](templates/refactor.md) | hierarchical | Analyze, plan, execute, and validate a refactor | | [documentation](templates/documentation.md) | handoff | Research, draft, review, and publish documentation | +| [competitive](templates/competitive.md) | competitive | Independent implementations, compare, select winner | ## Using Templates diff --git a/docs/workflows/patterns/competitive.md b/docs/workflows/patterns/competitive.md new file mode 100644 index 000000000..9a0ce660b --- /dev/null +++ b/docs/workflows/patterns/competitive.md @@ -0,0 +1,139 @@ +# Competitive Pattern + +Multiple agents independently implement solutions to the same problem, then a judge compares outputs and selects the best approach. + +## When to Use + +- **Exploratory problems** where multiple valid solutions exist +- **High-stakes decisions** that benefit from diverse approaches +- **Innovation challenges** where fresh perspectives help +- **Architecture decisions** with significant trade-offs +- **Spike work** to evaluate different technologies + +## Structure + +``` + ┌─────────────────────────────────────┐ + │ Define Spec │ + │ (Lead) │ + └───────────────┬─────────────────────┘ + │ + ┌────────────────┼────────────────┐ + │ │ │ + ▼ ▼ ▼ +┌─────────┐ ┌─────────┐ ┌─────────┐ +│ Team A │ │ Team B │ │ Team C │ +│ Impl │ │ Impl │ │ Impl │ +└────┬────┘ └────┬────┘ └────┬────┘ + │ │ │ + │ ┌─────────┼─────────┐ │ + │ │ │ │ │ + └────┼─────────┴─────────┼────┘ + │ │ + ▼ ▼ + ┌─────────────────────────────────────┐ + │ Compare Solutions │ + │ (Lead) │ + └───────────────┬─────────────────────┘ + │ + ▼ + ┌─────────────────────────────────────┐ + │ Select Winner │ + │ (Lead) │ + └─────────────────────────────────────┘ +``` + +## Key Characteristics + +- **Isolation**: Teams work independently without seeing each other's approach +- **Diversity**: Different CLIs/models encourage varied solutions +- **Objectivity**: Judge evaluates based on predefined rubric +- **Synthesis**: Winner selection can combine best elements from multiple solutions + +## Configuration + +```yaml +swarm: + pattern: competitive + maxConcurrency: 4 + timeoutMs: 5400000 + +agents: + - name: lead + cli: claude + role: "Defines spec, judges implementations, selects winner" + - name: team-alpha + cli: claude + role: "Independent implementation team" + - name: team-beta + cli: codex + role: "Independent implementation team" + - name: team-gamma + cli: gemini + role: "Independent implementation team" + +coordination: + barriers: + - name: implementations-complete + waitFor: [implement-alpha, implement-beta, implement-gamma] + timeoutMs: 3600000 +``` + +## Workflow Steps + +1. **define-spec** — Lead defines requirements and evaluation criteria +2. **implement-*** — Teams build solutions in parallel, isolated from each other +3. **compare-solutions** — Lead reviews all outputs against rubric +4. **select-winner** — Lead chooses best solution or synthesizes hybrid + +## Best Practices + +- **Clear rubric**: Define evaluation criteria upfront (performance, maintainability, simplicity) +- **Team diversity**: Use different CLIs/models to encourage varied approaches +- **Strict isolation**: Teams must not see each other's work until comparison +- **Time boxing**: Set appropriate timeouts to prevent runaway implementations +- **Synthesis option**: Consider combining best elements rather than picking one winner + +## Variations + +### Two-Team Competitive +Simpler variant with only two competing teams: +```yaml +agents: + - name: lead + cli: claude + - name: team-alpha + cli: claude + - name: team-beta + cli: codex +``` + +### Iterative Competitive +Multiple rounds where losing teams can improve: +```yaml +workflows: + - name: round-one + steps: [define-spec, implement-alpha, implement-beta, compare] + - name: round-two + steps: [feedback, re-implement, final-compare, select-winner] +``` + +### Hybrid Selection +Instead of selecting one winner, synthesize the best parts: +```yaml +steps: + - name: select-winner + agent: lead + task: | + Create a hybrid solution combining: + - Architecture from the most scalable approach + - Implementation details from the cleanest code + - Edge case handling from the most thorough solution +``` + +## Example Use Cases + +- **API Design**: Three teams propose different API structures +- **Algorithm Selection**: Compare performance of different approaches +- **Framework Evaluation**: Build same feature with different frameworks +- **Refactoring Strategy**: Multiple approaches to restructure legacy code diff --git a/docs/workflows/templates/competitive.md b/docs/workflows/templates/competitive.md new file mode 100644 index 000000000..105eac076 --- /dev/null +++ b/docs/workflows/templates/competitive.md @@ -0,0 +1,68 @@ +# Competitive Template + +**Pattern:** competitive | **Timeout:** 90 minutes | **Channel:** swarm-competitive + +## Overview + +Multiple agent teams independently implement solutions to the same problem, then a lead compares outputs and selects the best approach. Useful for exploratory work, architecture decisions, and innovation challenges. + +## Agents + +| Agent | CLI | Role | +|-------|-----|------| +| lead | claude | Defines spec, judges implementations, selects winner | +| team-alpha | claude | Independent implementation team A | +| team-beta | codex | Independent implementation team B | +| team-gamma | gemini | Independent implementation team C | + +## Workflow Steps + +``` +define-spec → [implement-alpha, implement-beta, implement-gamma] → compare-solutions → select-winner +``` + +1. **define-spec** (lead) — Define requirements, acceptance criteria, and evaluation rubric +2. **implement-alpha** (team-alpha) — Build solution independently +3. **implement-beta** (team-beta) — Build solution independently +4. **implement-gamma** (team-gamma) — Build solution independently +5. **compare-solutions** (lead) — Review all outputs against rubric +6. **select-winner** (lead) — Choose best solution or synthesize hybrid + +## Usage + +```bash +agent-relay run --template competitive --task "Design caching layer for API" +``` + +```typescript +import { TemplateRegistry, WorkflowRunner } from "@agent-relay/broker-sdk/workflows"; + +const registry = new TemplateRegistry(); +const config = await registry.loadTemplate("competitive"); +const runner = new WorkflowRunner(); + +await runner.execute(config, undefined, { + task: "Design and implement a caching strategy for the user API endpoints", +}); +``` + +## Configuration + +- **maxConcurrency:** 4 (all teams can run in parallel) +- **onError:** fail (implementations should complete for fair comparison) +- **errorStrategy:** continue (allow partial comparison if one team fails) +- **Barrier:** implementations-complete (waits for all teams) + +## Verification Markers + +- `SPEC_COMPLETE` — Requirements defined +- `IMPLEMENTATION_COMPLETE` — Team finished their solution +- `COMPARISON_COMPLETE` — Analysis of all solutions done +- `DONE` — Winner selected + +## Best Practices + +- **Clear rubric**: Define evaluation criteria upfront in the spec step +- **Strict isolation**: Teams must not see each other's work +- **Diverse CLIs**: Use different models to encourage varied approaches +- **Time boxing**: Set appropriate timeouts per team diff --git a/packages/broker-sdk/src/workflows/builtin-templates/competitive.yaml b/packages/broker-sdk/src/workflows/builtin-templates/competitive.yaml new file mode 100644 index 000000000..09c027ccc --- /dev/null +++ b/packages/broker-sdk/src/workflows/builtin-templates/competitive.yaml @@ -0,0 +1,103 @@ +version: "1.0" +name: competitive +description: "Multiple agents independently implement solutions, then compare and select the best approach." +swarm: + pattern: competitive + maxConcurrency: 4 + timeoutMs: 5400000 + channel: swarm-competitive +agents: + - name: lead + cli: claude + role: "Defines spec, judges implementations, and selects winner" + - name: team-alpha + cli: claude + role: "Independent implementation team A" + - name: team-beta + cli: codex + role: "Independent implementation team B" + - name: team-gamma + cli: gemini + role: "Independent implementation team C" +workflows: + - name: competitive-build + description: "Independent parallel implementations followed by comparison and selection." + onError: fail + steps: + - name: define-spec + agent: lead + task: | + Define clear requirements, acceptance criteria, and evaluation rubric: + {{task}} + verification: + type: output_contains + value: SPEC_COMPLETE + - name: implement-alpha + agent: team-alpha + dependsOn: [define-spec] + task: | + Implement solution independently based on spec: + {{steps.define-spec.output}} + + Do not coordinate with other teams. Focus on your best approach. + verification: + type: output_contains + value: IMPLEMENTATION_COMPLETE + - name: implement-beta + agent: team-beta + dependsOn: [define-spec] + task: | + Implement solution independently based on spec: + {{steps.define-spec.output}} + + Do not coordinate with other teams. Focus on your best approach. + verification: + type: output_contains + value: IMPLEMENTATION_COMPLETE + - name: implement-gamma + agent: team-gamma + dependsOn: [define-spec] + task: | + Implement solution independently based on spec: + {{steps.define-spec.output}} + + Do not coordinate with other teams. Focus on your best approach. + verification: + type: output_contains + value: IMPLEMENTATION_COMPLETE + - name: compare-solutions + agent: lead + dependsOn: [implement-alpha, implement-beta, implement-gamma] + task: | + Compare all implementations against the evaluation rubric. + + Team Alpha: {{steps.implement-alpha.output}} + Team Beta: {{steps.implement-beta.output}} + Team Gamma: {{steps.implement-gamma.output}} + + Analyze trade-offs, strengths, and weaknesses of each approach. + verification: + type: output_contains + value: COMPARISON_COMPLETE + - name: select-winner + agent: lead + dependsOn: [compare-solutions] + task: | + Select the winning implementation or synthesize the best elements. + Provide rationale and integration plan. + verification: + type: output_contains + value: DONE +coordination: + barriers: + - name: implementations-complete + waitFor: [implement-alpha, implement-beta, implement-gamma] + timeoutMs: 3600000 + consensusStrategy: majority +state: + backend: memory + ttlMs: 21600000 + namespace: competitive +errorHandling: + strategy: continue + notifyChannel: swarm-competitive diff --git a/packages/broker-sdk/src/workflows/schema.json b/packages/broker-sdk/src/workflows/schema.json index 70f8bcb9b..48b639cbe 100644 --- a/packages/broker-sdk/src/workflows/schema.json +++ b/packages/broker-sdk/src/workflows/schema.json @@ -94,7 +94,8 @@ "saga", "circuit-breaker", "blackboard", - "swarm" + "swarm", + "competitive" ] }, "AgentDefinition": { diff --git a/packages/broker-sdk/src/workflows/types.ts b/packages/broker-sdk/src/workflows/types.ts index fec4bb473..e9406b0d2 100644 --- a/packages/broker-sdk/src/workflows/types.ts +++ b/packages/broker-sdk/src/workflows/types.ts @@ -68,7 +68,8 @@ export type SwarmPattern = | "saga" | "circuit-breaker" | "blackboard" - | "swarm"; + | "swarm" + | "competitive"; // ── Agent definitions ───────────────────────────────────────────────────────