agent-collaboration

name	agent-collaboration
description	Multi-model agent orchestration using specialized agents for planning, coding, research, math/science, visual analysis, and adversarial review. Use when tasks are complex enough to benefit from different models' strengths, when you want adversarial review to catch blind spots, or when coordinating multi-step workflows across agent roles. Triggers on complex projects, multi-step tasks, architecture decisions, or when explicitly requested.
metadata	{"author":"pascalorg","version":"1.0.0"}

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  │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│             EXECUTION PHASE                   │
│     (parallel where no dependencies)          │
│                                               │
│  ┌──────────┐ ┌───────────┐ ┌──────────┐    │
│  │  Coder   │ │Researcher │ │Scientist │    │
│  │ GPT-5.4  │ │Gemini 3.1 │ │Gemini 3  │    │
│  └────┬─────┘ └─────┬─────┘ └────┬─────┘    │
│       │             │             │           │
│       ▼             ▼             ▼           │
│  ┌────────────────────────────────────────┐  │
│  │       Results + Artifacts               │  │
│  └────────────────────────────────────────┘  │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│              REVIEW PHASE                     │
│  (both reviewers in parallel for Patterns A-D)│
│                                               │
│  ┌───────────────┐  ┌───────────────┐        │
│  │  Adversarial  │  │     Peer      │        │
│  │    Grok 4     │  │  Claude Opus  │        │
│  └───────┬───────┘  └───────┬───────┘        │
│          │                  │                 │
│          ▼                  ▼                 │
│  ┌────────────────────────────────────────┐  │
│  │     Review Verdicts + Issue Lists       │  │
│  └────────────────────────────────────────┘  │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│            PLANNER RE-ENTERS                  │
│                                               │
│  Evaluates all review feedback:               │
│                                               │
│  • All clear → Accept and complete            │
│  • Minor issues → Send back to coder          │
│  • Major issues → Replan from scratch         │
│  • Reviewers disagree → Planner adjudicates   │
│  • New information → Update plan, re-execute  │
└──────────────────────────────────────────────┘

Maximum Iterations

To prevent infinite loops, enforce these limits:

• Code → Review cycles: Maximum 3 iterations. If the coder hasn't satisfied reviewers after 3 rounds, the planner must simplify the approach or escalate to the user
• Full replan: Maximum 2 replans per task. After 2, the planner presents what it has with known issues documented
• Individual agent timeout: If any agent hasn't produced useful output after a reasonable effort, the planner reassigns to fallback model or simplifies the subtask

---

Handoff Protocol

When agents pass work to each other, the handoff must be structured. The planner constructs each handoff — agents don't communicate directly.

Pragmatic note: The YAML formats below are aspirational templates, not strict contracts. Real models will not always output perfect YAML. The planner should extract the relevant information from whatever format the agent produces — structured YAML, markdown, or free text. What matters is that the information flows correctly between phases, not that the formatting is exact. If an agent returns free text instead of YAML, the planner should extract the key fields (status, summary, files changed, issues found) and construct the next handoff manually.

Planner → Execution Agent

handoff:
  to: coder                           # agent role
  task_id: 2
  description: "Implement OAuth2 PKCE flow"
  context: |
    The codebase uses JWT tokens stored in httpOnly cookies.
    Middleware at /api/auth/middleware.ts validates tokens on every request.
    The researcher found 3 existing auth patterns (see research summary below).
    Extend the JWT pattern — do not replace it.
  dependencies_resolved:
    - task_id: 1
      agent: researcher
      summary: "Found JWT, session, and API key auth patterns. JWT is most recent."
      key_files:
        - /api/auth/jwt.ts (lines 1-45)
        - /api/auth/middleware.ts (lines 12-30)
  constraints:
    - "Must extend existing JWT pattern, not replace it"
    - "Must be backward-compatible with existing middleware"
    - "Must include tests"
  success_criteria:
    - "OAuth2 PKCE flow works end-to-end"
    - "Existing auth tests still pass"
    - "New tests cover PKCE-specific scenarios"

Execution Agent → Planner (Result)

result:
  from: coder
  task_id: 2
  status: complete                     # complete | partial | failed | blocked
  summary: "Implemented PKCE flow in 3 files, added 8 tests"
  artifacts:
    files_changed:
      - /api/auth/pkce.ts (new, 120 lines)
      - /api/auth/middleware.ts (modified, added PKCE validation)
      - /api/auth/__tests__/pkce.test.ts (new, 85 lines)
    test_results: "8 passed, 0 failed"
  notes: |
    Used crypto.subtle for code verifier generation (Web Crypto API).
    The middleware change is backward-compatible — existing JWT auth still works.
  concerns:
    - "Code verifier storage uses session — may need Redis for horizontal scaling"

Planner → Review Agent

handoff:
  to: adversarial_reviewer
  task_id: 4
  description: "Security audit of OAuth2 PKCE implementation"
  context: |
    The coder implemented a PKCE flow. Review for security vulnerabilities,
    edge cases, and correctness. Be especially critical of:
    - Cryptographic operations (code verifier, code challenge)
    - Token storage and transmission
    - CSRF and replay attack vectors
    - Error handling in auth flows
  artifacts_to_review:
    - /api/auth/pkce.ts
    - /api/auth/middleware.ts
    - /api/auth/__tests__/pkce.test.ts
  implementation_summary: |
    Uses crypto.subtle for code verifier. Session-based storage.
    Middleware validates PKCE alongside existing JWT.

Review Agent → Planner (Verdict)

verdict:
  from: adversarial_reviewer
  task_id: 4
  decision: request_changes            # approve | request_changes | reject
  critical_issues:
    - severity: high
      location: /api/auth/pkce.ts:45
      issue: "Code verifier stored in plaintext session — if session is compromised, PKCE is defeated"
      suggestion: "Hash the verifier before storage, compare hashes on validation"
    - severity: medium
      location: /api/auth/pkce.ts:78
      issue: "No expiration on code challenge — replay attack window is unlimited"
      suggestion: "Add 10-minute TTL on challenge, clean up expired entries"
  minor_issues:
    - severity: low
      location: /api/auth/__tests__/pkce.test.ts
      issue: "No test for expired challenge scenario"
  positive_observations:
    - "Good use of crypto.subtle over Math.random for verifier generation"
    - "Backward compatibility with existing JWT flow is well-handled"

---

Workflow Patterns

Pattern A: Plan → Code → Review (Default)

The bread-and-butter for most development tasks.

Planner → Coder → [Adversarial + Peer Review] → Planner

Use when: Adding features, fixing bugs, refactoring code. Most tasks start here.

Planner behavior: Produces a single plan with clear subtasks. After review, decides whether to accept, revise, or restart.

Pattern B: Research → Plan → Code → Review

When the task requires understanding before implementation.

Planner → Researcher → Planner (replan) → Coder → [Review] → Planner

Use when: Working with unfamiliar APIs, choosing between architectural approaches, integration tasks, anything where you need information before you can plan.

Planner behavior: First plan is "research phase only." After research completes, planner creates a new, informed implementation plan.

Pattern C: Deep Analysis

For math-heavy, scientific, or visual reasoning tasks.

Planner → [Scientist + Visual Analyst + Researcher] → Planner → Coder → [Review] → Planner

Use when: Data pipelines, ML models, algorithm implementation, visual regression testing, anything requiring formal correctness.

Planner behavior: Gathers analysis from multiple specialist agents before creating the implementation plan. The scientist's output directly constrains what the coder can do.

Pattern D: Full Pipeline

The complete workflow for large, complex tasks.

Planner → Researcher → Planner (replan) → [Coder + Scientist] → Visual Analyst → [Adversarial + Peer Review] → Planner

Use when: Major features, system design, architecture changes, anything high-stakes.

Planner behavior: Multiple replan cycles. Visual analyst checks UI after implementation. Full review before acceptance.

Pattern E: Rapid Iteration

For quick fixes where full review would be overkill.

Planner → Coder → Adversarial Reviewer → Planner

Use when: Small bug fixes, minor refactors, documentation updates. Skip the peer reviewer — the adversarial pass catches security and correctness issues, which is enough for small changes.

Planner behavior: Lightweight plan, single review pass, fast completion.

Pattern F: Research-Only

When you need information, not implementation.

Planner → [Researcher + Scientist] → Planner → Summary

Use when: Technical investigations, feasibility studies, competitive analysis, decision support.

Planner behavior: Synthesizes research and analysis into a decision-ready summary. No code is written.

---

Planner Output Format

The planner produces a structured plan that other agents can follow. Use this format:

plan:
  task: "Description of the overall task"
  pattern: A                             # Which workflow pattern (A-F)
  
  subtasks:
    - id: 1
      description: "Research existing auth patterns in the codebase"
      agent: researcher
      depends_on: []
      success_criteria: "Summary of auth patterns with file locations and recommendations"
    
    - id: 2
      description: "Implement OAuth2 PKCE flow extending existing JWT auth"
      agent: coder
      depends_on: [1]
      success_criteria: "Working OAuth2 PKCE flow with tests passing, backward-compatible"
    
    - id: 3
      description: "Verify cryptographic correctness of PKCE implementation"
      agent: scientist
      depends_on: [2]
      success_criteria: "Formal verification that entropy, hashing, and timing are correct"
    
    - id: 4
      description: "Security audit — find vulnerabilities and edge cases"
      agent: adversarial_reviewer
      depends_on: [2]
      success_criteria: "Security audit with no unaddressed critical or high issues"
    
    - id: 5
      description: "Architecture and quality review"
      agent: peer_reviewer
      depends_on: [2]
      success_criteria: "Approved or specific changes requested"
  
  execution_order:
    - phase: 1
      parallel: [1]
    - phase: 2
      parallel: [2]
    - phase: 3
      parallel: [3, 4, 5]
  
  notes: |
    Subtasks 3, 4, 5 can run in parallel since they all review the same output.
    If review finds critical issues, we loop back to subtask 2 with fixes.

---

Setup by Tool

OpenCode (Recommended for Multi-Provider)

OpenCode natively supports 75+ LLM providers with per-agent model overrides. No gateway needed — OpenCode IS the gateway.

API Keys

Set provider API keys as environment variables. You only need keys for the providers you plan to use — pick the direct providers OR cloud providers (Bedrock/Azure), or mix and match:

# --- Direct providers ---
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."            # or GOOGLE_GENERATIVE_AI_API_KEY
export XAI_API_KEY="..."

# --- Amazon Bedrock (alternative for Claude + other models) ---
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"          # or us-west-2, eu-west-1, etc.

# --- Microsoft Azure OpenAI (alternative for GPT models) ---
export AZURE_API_KEY="..."
export AZURE_RESOURCE_NAME="your-resource"
export AZURE_DEPLOYMENT_NAME="your-deployment"
export AZURE_API_VERSION="2024-12-01-preview"

# --- Google Vertex AI (alternative for Gemini models) ---
export GOOGLE_CLOUD_PROJECT="your-project"