┌──────────────────────────────────────────────┐
│                  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  │
└──────────────────────────────────────────────┘

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"

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"

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.

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"

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

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

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

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

Planner → Coder → Adversarial Reviewer → Planner

Planner → [Researcher + Scientist] → Planner → Summary

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.

undefined

undefined

{
  "provider": {
    "anthropic": {
      "api_key": "{env:ANTHROPIC_API_KEY}"
    },
    "openai": {
      "api_key": "{env:OPENAI_API_KEY}"
    },
    "google": {
      "api_key": "{env:GOOGLE_API_KEY}"
    },
    "xai": {
      "api_key": "{env:XAI_API_KEY}"
    },
    "bedrock": {
      "aws_access_key_id": "{env:AWS_ACCESS_KEY_ID}",
      "aws_secret_access_key": "{env:AWS_SECRET_ACCESS_KEY}",
      "aws_region": "{env:AWS_REGION}"
    },
    "azure": {
      "api_key": "{env:AZURE_API_KEY}",
      "resource_name": "{env:AZURE_RESOURCE_NAME}"
    },
    "vertex": {
      "project": "{env:GOOGLE_CLOUD_PROJECT}"
    }
  }
}

undefined

This generates 7 agent `.md` files with the correct OpenCode frontmatter (`model: provider/id`, `permission: edit: deny`) in `.opencode/agents/`.

Each agent uses a different provider/model. OpenCode routes to the correct provider automatically based on the model prefix.

**Default assignments (direct providers):**

| Agent | Model ID | Provider |
|-------|---------|----------|
| Planner | `anthropic/claude-opus-4-6` | Anthropic |
| Coder | `openai/gpt-5.4` | OpenAI |
| Researcher | `google/gemini-3.1-pro` | Google |
| Scientist | `google/gemini-3-pro` | Google |
| Visual Analyst | `anthropic/claude-opus-4-6` | Anthropic |
| Adversarial Reviewer | `xai/grok-4` | xAI |
| Peer Reviewer | `anthropic/claude-opus-4-6` | Anthropic |

**Amazon Bedrock alternatives** — swap the model ID in the agent `.md` file to route through Bedrock instead:

| Agent | Bedrock Model ID |
|-------|-----------------|
| Planner | `bedrock/anthropic.claude-opus-4-6-v1` |
| Coder | `bedrock/anthropic.claude-sonnet-4-5-v1` |
| Researcher | `bedrock/amazon.nova-pro-v1` |
| Scientist | `bedrock/anthropic.claude-opus-4-6-v1` |
| Visual Analyst | `bedrock/anthropic.claude-opus-4-6-v1` |
| Adversarial Reviewer | `bedrock/amazon.nova-pro-v1` |
| Peer Reviewer | `bedrock/anthropic.claude-opus-4-6-v1` |

Note: Bedrock gives you Claude models without a separate Anthropic API key (billed through AWS). Gemini and Grok are not available on Bedrock — use Amazon Nova or Claude as alternatives, or mix Bedrock with direct providers.

**Microsoft Azure OpenAI alternatives** — for organizations on Azure:

| Agent | Azure Model ID |
|-------|---------------|
| Planner | `azure/claude-opus-4-6` |
| Coder | `azure/gpt-5.4` |
| Researcher | `azure/gpt-5.4` |
| Scientist | `azure/gpt-5.4` |
| Visual Analyst | `azure/claude-opus-4-6` |
| Adversarial Reviewer | `azure/gpt-4o` |
| Peer Reviewer | `azure/claude-opus-4-6` |

Note: Azure OpenAI model IDs depend on your deployment names. The IDs above assume deployments matching the model names. Azure gives you GPT and Claude models (via Azure AI Foundry) billed through your Azure subscription. Gemini and Grok are not available on Azure — use GPT-4o or Claude as alternatives, or mix Azure with direct providers.

**Google Vertex AI alternatives** — for organizations on GCP:

| Agent | Vertex AI Model ID |
|-------|-------------------|
| Researcher | `vertex/gemini-3.1-pro` |
| Scientist | `vertex/gemini-3-pro` |
| Visual Analyst | `vertex/gemini-3.1-pro` |

Note: Vertex AI gives you Gemini models billed through GCP. Claude is also available via Vertex AI Model Garden.

**Mixing providers is the recommended approach.** You don't have to pick one cloud — use Bedrock for Claude, Azure for GPT, direct for Gemini and Grok. Just change the model prefix in each agent's `.md` file.

@planner Break down this task: implement user authentication with OAuth2 PKCE

@researcher Find existing auth patterns in this codebase
@coder Implement PKCE flow based on the research findings: [paste context]
@adversarial-reviewer Review this PKCE implementation for security issues: [paste context]
@peer-reviewer Review code quality and architecture: [paste context]

sh agents/setup.sh claude-code

export OPENROUTER_API_KEY="sk-or-..."

mkdir -p .claude/scripts
cat > .claude/scripts/call-model.sh << 'SCRIPT'
#!/bin/bash

**Step 3:** In Claude Code, the orchestrating agent can use this script for cross-provider calls:

```bash

This hybrid approach uses Claude Code's native sub-agents for Anthropic models and the gateway script for other providers.

#!/bin/bash

**Vercel AI Gateway advantages:** Zero token markup, 40+ providers, OIDC auth for Vercel-deployed apps (no key management).

---

---
description: Multi-model agent collaboration workflow
globs: ["**/*"]
---

---

undefined

---

undefined

---

undefined

**What you get:** Claude Opus plans the approach, GPT-5.4 implements the edits. This covers Pattern A (Plan → Code) natively.

**What you don't get:** Review phase. For review, run a separate aider session:

```bash

**Provider support:** Aider uses LiteLLM under the hood, supporting 100+ providers. Any `provider/model-id` format works.

---

undefined

**Best for:** OpenCode (native routing), Aider (LiteLLM routing), any tool where you have direct provider API access.

**Mixing providers is normal.** Use `bedrock/` for Claude (billed through AWS), `azure/` for GPT (billed through Azure), and `google/` or `vertex/` for Gemini directly. Each agent's model ID prefix determines which provider is used — no gateway needed.

export OPENROUTER_API_KEY="sk-or-..."

#!/bin/bash

**Best for:** Claude Code, Codex CLI, Gemini CLI — any tool locked to a single provider that needs cross-provider access via script.

export AI_GATEWAY_API_KEY="..."    # From Vercel Dashboard

import { gateway } from '@ai-sdk/gateway';
import { generateText } from 'ai';

const result = await generateText({
  model: gateway('anthropic/claude-opus-4-6'),
  prompt: 'Plan this task...',
  providerOptions: {
    gateway: {
      order: ['anthropic', 'bedrock'],     // Try Anthropic first, fall back to Bedrock
      caching: 'auto',                     // Automatic provider-appropriate caching
    }
  }
});

#!/bin/bash

**Best for:** Vercel projects, TypeScript codebases using AI SDK, teams wanting managed gateway with no token markup.

---