feat: add competitive swarm pattern and adding-swarm-patterns skill

.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

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
 

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

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