agent-collaboration

What this skill does

# Agent Collaboration

Orchestrate multiple AI models as specialized agents — each assigned to what it does best. One model plans, another codes, another reviews. The planner stays in the loop, re-entering after every phase to evaluate and redirect.

---

## When to Use

- Complex projects requiring planning, implementation, and review
- Tasks where a single model's blind spots are a risk
- When you want adversarial review to catch what self-review cannot
- Research-heavy work requiring web search, synthesis, and validation
- Math or science tasks requiring specialized reasoning
- Any task benefiting from a plan → execute → review → replan loop
- When the user explicitly asks for multi-model collaboration

## When NOT to Use

- One-line fixes, typo corrections, simple questions
- Tasks fully within a single model's strength
- When speed matters more than thoroughness
- Exploratory conversations without a concrete deliverable

---

## Philosophy

**One model cannot be the best at everything.** Benchmarks consistently show different model families excel at different tasks. Claude Opus excels at planning and abstract reasoning. GPT-5.4 leads at code implementation. Gemini 3.1 Pro dominates math, science, and knowledge retrieval. Grok 4 brings contrarian perspective. Combining these as specialized agents outperforms any single model on complex tasks.

**The planner is the conductor.** It decomposes, delegates, evaluates, and replans. Every other agent reports back to the planner. The planner never edits files — it reads code for context and spawns sub-agents, but its authority comes from directing, not doing.

**Adversarial review is not optional.** A different model family reviewing the work catches failure modes that self-review cannot. The adversarial reviewer's job is to find problems, not to be diplomatic.

**Agents are disposable, context is not.** Each agent may be stateless, but the handoff between agents must preserve all relevant context. The planner is responsible for ensuring no information is lost between phases.

---

## The Seven Agents

### 1. Planner

- **Role:** Decompose complex tasks into subtasks, assign each to the right agent, define success criteria, evaluate results, replan when needed
- **Primary model:** Claude Opus 4.6 (extended thinking)
- **Fallback:** Claude Opus 4.5, GPT-5.4 (high reasoning)
- **Why Opus:** #1 Arena overall (1504 Elo), #1 Hard Prompts, best abstract reasoning (ARC-AGI 2: 68.8%). Extended thinking excels at structured decomposition and multi-step planning
- **Tools:** No file edits. The planner reads code, runs read-only shell commands (git log, ls), and spawns sub-agents — but never writes or edits files
- **Output:** Structured plan in YAML with subtask assignments, dependencies, and success criteria

### 2. Coder

- **Role:** Implement code changes, write tests, fix bugs, refactor. Follows the plan exactly
- **Primary model:** GPT-5.4 (high reasoning)
- **Fallback:** Claude Sonnet 4.5, Claude Sonnet 4.6
- **Why GPT-5.4:** Leads Aider coding leaderboard (88%). Fast, precise, excellent at turning plans into working code
- **Why Sonnet 4.5 as fallback:** Leads SWE-bench Verified (82%). Strong at real-world software engineering tasks
- **Tools:** Full file system access — read, write, edit, terminal, package managers
- **Output:** Changed files, test results, implementation summary

### 3. Researcher

- **Role:** Web search, documentation lookup, API exploration, literature review, competitive analysis, summarization
- **Primary model:** Gemini 3.1 Pro
- **Fallback:** Claude Opus 4.6
- **Why Gemini 3.1 Pro:** Leads Humanity's Last Exam (45.8%), top MMMLU (91.8%). Exceptional at finding and synthesizing information across broad knowledge domains
- **Why Opus as fallback:** Best on BrowseComp (web research synthesis). Excels at connecting disparate information
- **Tools:** Web search, web fetch, file read. No file edits — the researcher reports, it doesn't implement
- **Output:** Research summary with source attribution, key findings, decision-relevant tradeoffs

### 4. Scientist

- **Role:** Mathematical reasoning, formal proofs, statistical modeling, data analysis, algorithm verification, scientific computation
- **Primary model:** Gemini 3 Pro
- **Fallback:** GPT 5.2, Claude Opus 4.6
- **Why Gemini 3 Pro:** Scores 100% on AIME 2025, 94.3% GPQA Diamond. Exceptional at step-by-step mathematical reasoning and formal proofs
- **Why GPT 5.2 as fallback:** Also 100% on AIME 2025, 92.4% GPQA Diamond
- **Tools:** Code execution (for computation and verification), file read/write for results. Web access not typically needed
- **Output:** Formal analysis, proofs, computed results with methodology

### 5. Visual Analyst

- **Role:** Image analysis, UI/UX review, diagram interpretation, screenshot analysis, visual regression detection, design system compliance
- **Primary model:** Claude Opus 4.6
- **Fallback:** Gemini 3.1 Pro
- **Why Opus:** ARC-AGI 2: 68.8% (dominant lead in abstract visual reasoning). Strong multimodal understanding with structured output
- **Why Gemini as fallback:** MMMU-Pro 80.5%. Excellent at interpreting complex visual content
- **Tools:** Image reading, screenshot capture, file read. No file edits — reports visual findings
- **Output:** Visual analysis report with specific observations, issues, and recommendations

### 6. Adversarial Reviewer

- **Role:** Find flaws, security vulnerabilities, edge cases, logical errors, incorrect assumptions, race conditions, and performance problems. Challenge every decision. Assume the code is broken until proven otherwise
- **Primary model:** Grok 4
- **Fallback:** Gemini 3.1 Pro, Claude Opus 4.6
- **Why Grok 4:** #4 Arena overall with a direct, contrarian communication style. Using a fundamentally different model family than the coder ensures genuine adversarial perspective, not self-congratulatory review
- **Why a different model family matters:** Models from the same family share similar blind spots. Cross-family review catches what same-family review misses
- **Tools:** Read-only. The adversarial reviewer never edits — it produces a list of issues ranked by severity
- **Output:** Issues list with severity (critical/high/medium/low), reproduction steps, and suggested fixes

### 7. Peer Reviewer

- **Role:** Quality assessment, architecture review, style consistency, best practices, documentation review, maintainability analysis
- **Primary model:** Claude Opus 4.6
- **Fallback:** GPT-4o
- **Why Opus:** Excels at structured, thorough analysis. Balances pragmatism with quality standards
- **Why GPT-4o as fallback:** Shows least positivity bias in peer review (per AI Scientist research, Sakana AI). Honest without being hostile
- **Tools:** Read-only. Produces a review with an explicit verdict: approve, request changes, or reject
- **Output:** Structured review with verdict, praise for good decisions, and specific change requests

---

## How It Works

This is a **manual dispatch workflow** — you (or your primary agent session) are the dispatcher. The agents do not self-orchestrate. You follow the orchestration loop below, invoking each agent as needed and passing context between them using the handoff protocol. The skill provides the workflow patterns, agent definitions, and handoff formats. You provide the judgment calls.

## The Orchestration Loop

Every complex task follows this loop. The planner is always the entry and exit point.

```
┌──────────────────────────────────────────────┐
│                  PLANNER                      │
│           Claude Opus 4.6 (thinking)          │
│                                               │
│  1. Analyze the full task and constraints      │
│  2. Break into concrete subtasks              │
│  3. Assign each subtask to an agent role      │
│  4. Define success criteria per subtask       │
│  5. Specify execution order and dependencies  │
│  6. Identify which subtasks can run parallel  │
└──────────────────┬────