AI Skill Report Card
Orchestrating Multi Agent Swarms
Quick Start13 / 15
For any non-trivial engineering task, don't run a single monolithic agent — decompose into a swarm with explicit roles:
YAMLswarm: topology: hierarchical # mesh | hierarchical | star agents: - role: architect # plans task decomposition model: claude-opus - role: coder # implements model: claude-sonnet - role: reviewer # critiques diffs model: gpt-4o - role: tester # writes/runs tests model: claude-haiku # cheap, high-volume - role: security-auditor # final gate model: claude-sonnet consensus: quorum # majority vote before merge routing: cost-optimized # route simple subtasks to cheap/local models
Run the architect first to produce a task graph, fan work out to specialized agents in parallel where there are no dependencies, and gate merges behind reviewer + security-auditor consensus.
Recommendation▾
Add a concrete code/output example showing actual agent outputs (e.g., sample task graph JSON, actual diff/review exchange) rather than only narrative descriptions of what happens
Workflow13 / 15
Progress:
- Step 1: Decompose the task into subtasks with a dependency graph
- Step 2: Assign agent roles based on subtask type (coding, review, test, security, docs)
- Step 3: Choose topology (mesh for exploratory/research, hierarchical for structured delivery, star for single-coordinator simple tasks)
- Step 4: Route each subtask to the cheapest capable model (use Agent Booster / lightweight models for boilerplate, reserve frontier models for architecture/security decisions)
- Step 5: Execute agents in parallel where independent; serialize dependent chains
- Step 6: Apply consensus mechanism (quorum/unanimous) before accepting output that touches shared state (merges, deploys, schema changes)
- Step 7: Run fault-tolerance checks — if an agent fails or produces low-confidence output, retry with a different model or escalate to a stronger one
- Step 8: Collect metrics (token usage, latency, consensus disagreements) and feed back into routing decisions for future runs (self-optimization loop)
Role Decomposition Pattern
Default agent roster for software tasks:
- Architect — breaks requirements into subtasks, defines interfaces/contracts
- Coder(s) — one per independent module/subtask, implements against the contract
- Reviewer — checks diffs against contract and style/correctness
- Tester — generates and runs tests, reports coverage/failures
- Security auditor — scans for vulnerabilities, secrets, unsafe patterns
- Integrator — merges validated outputs, resolves conflicts
Scale agent count to task complexity — trivial tasks need architect + coder only; don't spin up a full swarm for a one-line fix.
Recommendation▾
Include a 'bad outcome' example (e.g., swarm without consensus leading to a bad merge) to contrast with good outcomes per grading best practices
Examples13 / 20
Example 1: Input: "Add rate limiting middleware to the API and ensure it's secure and tested." Output:
- Architect agent defines the interface (
RateLimitermiddleware contract, config schema) - Coder agent (sonnet) implements middleware
- Tester agent (haiku, cheap/high-volume) writes unit + load tests
- Security auditor (sonnet) checks for bypasses (e.g., header spoofing, race conditions)
- Reviewer agent approves; quorum consensus (2/2 approvals) required before merge
- Routing report: 70% of tokens spent on coder, 15% tester, 15% security — flagged as optimal cost split
Example 2: Input: "Refactor a 10k-line legacy module with unclear ownership boundaries." Output: Use mesh topology (not hierarchical) since subtask boundaries are unclear — spawn exploratory agents to map module dependencies first, converge on an architect-proposed decomposition once boundaries emerge, then switch to hierarchical execution for the actual refactor.
Recommendation▾
Clarify how routing/consensus mechanics actually work technically (e.g., how quorum vote is computed, how agents communicate) since this is somewhat abstract/conceptual without implementation specifics
Best Practices
- Match topology to task shape: hierarchical for well-defined delivery pipelines, mesh for exploration/research, star for simple single-coordinator jobs.
- Route by capability, not preference — use cheap/local models for boilerplate, formatting, and simple tests; reserve frontier models for architecture, security, and ambiguous judgment calls.
- Always gate shared-state changes (merges, deploys, migrations) behind multi-agent consensus, never a single agent's output.
- Keep a security-auditor agent independent from the coder agent (different model or explicit adversarial prompt) to avoid shared blind spots.
- Track token/latency metrics per agent role and feed them back into routing — this is the self-optimization loop, not a one-time setup.
- Fail toward escalation: if a cheap model produces low-confidence or inconsistent output, retry with a stronger model rather than accepting it.
Common Pitfalls
- Don't spawn a full swarm for trivial tasks — orchestration overhead exceeds the value for single-file, low-risk changes.
- Don't let the coder and reviewer be the same model instance/context — defeats the purpose of independent review.
- Don't skip consensus on merge/deploy steps to save time — this is where fault-tolerance matters most.
- Don't route security-critical subtasks to the cheapest model purely for cost savings.
- Don't ignore dependency graphs and parallelize everything — race conditions and conflicting edits will cost more time than sequential execution would have.