@alexgabbia/role-dispatcher 1.2.0 → 1.3.0

package/README.md

@@ -28,7 +28,7 @@ Instead of a one-size-fits-all response, you get answers from the **actual profe
 | | Without Role Dispatcher | With Role Dispatcher |
 |---|---|---|
 | **Expertise** | Generic AI response | Specialist-grade from 209+ roles |
-| **Multi-domain tasks** | You manage context yourself | Auto-dispatches 1-3 agents that collaborate |
+| **Multi-domain tasks** | You manage context yourself | Auto-dispatches the right number of agents that collaborate |
 | **Quality control** | Hope for the best | Confidence scoring + Review Agent validation |
 | **Model selection** | One size fits all | Right model (Haiku/Sonnet/Opus) per task complexity |
 | **Your control** | Take what you get | Propose & Confirm — change roles or model before dispatch |
@@ -121,9 +121,9 @@ Proceed? You can:
 
 1. **Analyze** — Detects your language, scans request against keyword index + semantic inference
 2. **Match** — Identifies relevant categories from the 14 available
-3. **Select** — Picks 1-3 specialist roles using Key Skills matching, determines optimal model
-4. **Propose & Confirm** — Shows proposed roles (with key skills) and model, waits for your approval or changes
-5. **Dispatch** — Launches agents with structured prompts including expertise profiles and behavioral guidelines
+3. **Select** — Picks N specialist roles using Key Skills matching, determines optimal model and dispatch mode
+4. **Propose & Confirm** — Shows proposed roles (with key skills), model, and dispatch mode, waits for your approval or changes
+5. **Dispatch** — Launches agents via subagents (1-4) or Agent Teams (5+) with structured prompts
 6. **Review** — (2+ agents) Validates completeness, detects conflicts, verifies integration
 7. **Synthesize** — Merges outputs into a single coherent answer with aggregate confidence
 
@@ -195,6 +195,22 @@ You: "yes"
   -> Architecture -> Implementation plan -> Deployment strategy
 ```
 
+### Large-Scale: SaaS Platform (Agent Team)
+```
+You: "Build a complete SaaS project management tool with auth, real-time
+     collaboration, Stripe billing, and admin dashboard"
+
+Dispatcher proposes:
+  Agents: Software Architect + Backend Dev + Frontend Dev + UX/UI Designer
+          + DevOps Engineer + Security Engineer + Payment Specialist
+  Dispatch mode: Agent Team (7 agents, deep collaboration)
+  Model: Opus
+
+You: "yes"
+  -> Creates team, Software Architect leads, teammates self-coordinate
+  -> Delivers unified architecture + implementation plan
+```
+
 ### User Override
 ```
 You: "Set up a CI/CD pipeline for our Node.js monorepo"
@@ -209,6 +225,38 @@ You: "use only DevOps Engineer with haiku"
 
 ---
 
+## Agent Teams (Experimental)
+
+For large-scale tasks (5+ agents) or when agents need to discuss and challenge each other, the dispatcher uses **Agent Teams** — a Claude Code experimental feature that enables real inter-agent collaboration.
+
+### How it differs from subagents
+
+| | Subagents | Agent Teams |
+|---|---|---|
+| **Communication** | Through dispatcher only | Direct messaging between teammates |
+| **Coordination** | Dispatcher orchestrates | Team self-coordinates via shared task list |
+| **Best for** | 1-4 focused, independent agents | 5+ agents or deep collaboration needs |
+| **Overhead** | Low | Higher, but enables richer collaboration |
+
+### Enable Agent Teams
+
+Add to your `.claude/settings.json`:
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+### Override dispatch mode
+
+During the Propose & Confirm step, you can force a specific mode:
+- **"use team"** — Forces Agent Team mode even for 2-4 agents
+- **"use subagents"** — Forces subagent mode even for 5+ agents
+
+---
+
 ## File Structure
 
 ```
@@ -219,7 +267,7 @@ skill/role-dispatcher/
     prompt-templates.md             # Structured agent prompt templates
     collaboration-protocol.md       # Multi-agent coordination protocol
     model-selection-guide.md        # Model selection decision matrix
-    examples.md                     # 4 complete dispatching scenarios
+    examples.md                     # 6 complete dispatching scenarios
   assets/roles/
     01-software-development.md      # 13 roles
     02-design-ux.md                 # 11 roles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexgabbia/role-dispatcher",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Turn your AI coding tool into a team of 209+ IT specialists. Skill for Claude Code, Codex CLI, and OpenCode.",
   "bin": {
     "role-dispatcher": "bin/install.js"

package/skill/role-dispatcher/SKILL.md

@@ -48,21 +48,37 @@ Within the matched category files, select the best role(s) by comparing the requ
 | Complexity | Agents | Review Agent | Signal |
 |------------|--------|-------------|--------|
 | Single domain, clear deliverable | 1 | No | "Write a React component", "Optimize this query" |
-| Two domains with integration points | 2 | Yes | "Build API + frontend", "Design and deploy" |
-| Multi-domain, architectural scope | 3 | Yes | "Design a secure e-commerce platform" |
+| Two domains with integration points | 2-3 | Yes | "Build API + frontend", "Design and deploy" |
+| Multi-domain, architectural scope | 3-5 | Yes | "Design a secure e-commerce platform" |
+| Large-scale project, cross-layer work | 5-10+ | Yes (or Team Lead) | "Build a complete SaaS platform", "Full security audit of microservices" |
 
-**Max 3 agents.** If more domains are involved, group related competencies into a composite role (e.g., "Full-Stack Developer" covers both frontend and backend rather than dispatching two separate agents).
+**Scale agents to actual complexity.** Match the number of agents to the number of genuinely distinct roles needed. Don't inflate for the sake of it, don't compress when more specialists would help. If a single "Full-Stack Developer" genuinely covers the request, use one agent. If a project spans frontend, backend, database, security, DevOps, and design — use six.
 
 **Role selection heuristic**: Pick the most specialized role that covers the request. "Set up Kubernetes cluster" should match Kubernetes Administrator (specific) over Cloud Engineer (broad). Use the Key Skills column to break ties between similar roles.
 
-## Step 4: Classify Dependencies
+## Step 4: Classify Dependencies & Select Dispatch Mode
 
-Read `references/collaboration-protocol.md` for the full protocol. Quick reference:
+Read `references/collaboration-protocol.md` for the full protocol.
+
+### Dependency Classification
 
 - **INDEPENDENT**: No data flow between agents -> run in **parallel**
 - **DEPENDENT**: Output of one feeds another -> run **sequentially**, pass handoff notes
 - **MIXED**: Parallel first, then sequential for dependent parts
 
+### Dispatch Mode Selection
+
+| Agents | Collaboration needed? | Mode | Why |
+|--------|----------------------|------|-----|
+| 1 | N/A | **Single subagent** | Simple, focused task |
+| 2-4, independent | No | **Parallel subagents** | Fast, low overhead |
+| 2-4, dependent | Minimal (handoff notes) | **Sequential subagents** | One feeds the next, dispatcher coordinates |
+| 5+ OR agents need to discuss/challenge each other | Yes | **Agent Team** (TeamCreate) | Shared tasks, direct messaging, self-coordination |
+
+**User override**: "use a team" forces Agent Team mode even for 2 agents. "use subagents" forces subagent mode even for 5+.
+
+**Note**: Agent Teams require the experimental flag `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `.claude/settings.json`.
+
 ## Step 5: Select Model
 
 Read `references/model-selection-guide.md` for the full matrix. Quick reference:
@@ -86,19 +102,25 @@ Present the dispatch plan and **wait for user confirmation** before proceeding.
 
 **Model:** {model} ({complexity} complexity)
 **Execution:** {INDEPENDENT | DEPENDENT | MIXED}
+**Dispatch mode:** {Subagents | Agent Team} — {reason}
 
 Proceed? You can:
 - **yes** to proceed as proposed
 - **Change roles**: e.g. "use Security Engineer instead of Backend Developer"
 - **Change model**: e.g. "use opus" or "use haiku"
-- **Both**: e.g. "use only Frontend Developer with sonnet"
+- **use team** / **use subagents**: override the dispatch mode
+- **Combine**: e.g. "use only Frontend Developer with sonnet"
 ```
 
-If the user modifies roles or model, adjust and proceed. If they confirm, proceed with the original proposal.
+If the user modifies roles, model, or dispatch mode, adjust and proceed. If they confirm, proceed with the original proposal.
 
 ## Step 7: Dispatch Agents
 
-Read `references/prompt-templates.md` for the full template. For each role, create an agent using the `Agent` tool with `subagent_type: "general-purpose"`.
+Read `references/prompt-templates.md` for the full template.
+
+### Path A: Subagent Dispatch (default for 1-4 agents)
+
+For each role, create an agent using the `Agent` tool with `subagent_type: "general-purpose"`.
 
 Each agent prompt MUST include:
 1. **Role identity**: Name, description, and key skills from the role file
@@ -110,28 +132,50 @@ Each agent prompt MUST include:
 
 **Parallel dispatch**: Launch all INDEPENDENT agents in a single message with multiple Agent tool calls. For DEPENDENT agents, wait for each to complete before dispatching the next with handoff notes.
 
+### Path B: Agent Team Dispatch (for 5+ agents or when deep collaboration is needed)
+
+Use the `TeamCreate` tool to create a team, then spawn teammates via the `Agent` tool with `team_name`.
+
+1. **Create the team**: `TeamCreate` with a descriptive team name and the overall goal
+2. **Spawn teammates**: For each role, use `Agent` tool with `team_name` set to the created team. Use the **Teammate Template** from `references/prompt-templates.md`
+3. **Team Lead**: The first agent spawned acts as Team Lead. Use the **Team Lead Template**. The Team Lead:
+   - Creates shared tasks via the task list for the team to work on
+   - Coordinates work assignment among teammates
+   - Acts as the Review Agent (synthesizes final output)
+   - Sends direct messages to teammates when needed
+4. **Self-coordination**: Teammates claim tasks, communicate via messaging, and deliver their parts. The dispatcher does NOT need to manually orchestrate — the team self-coordinates
+5. **Completion**: The Team Lead synthesizes all contributions and delivers the final result
+
 ## Step 8: Review & Synthesize
 
 **Single agent**: Present the result directly. If confidence is LOW, flag it to the user.
 
-**Multi-agent**: Apply the Review Agent protocol from `references/collaboration-protocol.md`:
+**Multi-agent (Subagent mode)**: Apply the Review Agent protocol from `references/collaboration-protocol.md`:
 1. Check completeness against the original request
 2. Detect conflicts between agent outputs
 3. Verify integration (pieces fit together)
 4. Compute aggregate confidence = minimum of individual confidences
 5. Decision: APPROVE / NEEDS_REVISION / ESCALATE
 
+**Multi-agent (Agent Team mode)**: The Team Lead acts as Review Agent:
+1. Collects all teammate contributions via the shared task list
+2. Applies the same review protocol (completeness, conflicts, integration, confidence)
+3. Synthesizes the final response
+4. The dispatcher presents the Team Lead's synthesis to the user
+
 If **ESCALATE**: Present conflicting perspectives with pros/cons. Let the user decide.
 If **APPROVE**: Synthesize into a single coherent response in `{RESPONSE_LANGUAGE}`.
 
 ## Rules
 
 - Respond in the user's detected language
-- Max 3 agents per request
+- Scale agent count to match task complexity — no artificial limit
 - All file paths are relative to this skill directory (use `assets/roles/` and `references/`)
 - For detailed examples, read `references/examples.md`
-- Use `Agent` tool with `subagent_type: "general-purpose"` for each agent
+- **Subagent mode**: Use `Agent` tool with `subagent_type: "general-purpose"` for each agent
+- **Agent Team mode**: Use `TeamCreate` then `Agent` with `team_name` — requires experimental flag `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
 - Agents run in parallel when INDEPENDENT, sequentially when DEPENDENT
 - LOW confidence from any agent triggers automatic ESCALATE
 - Always wait for user confirmation in Step 6 before dispatching agents
 - Prefer the most specialized role over a generalist one when both could apply
+- User can override dispatch mode with "use team" or "use subagents"

package/skill/role-dispatcher/references/collaboration-protocol.md

@@ -10,9 +10,63 @@ Before dispatching agents, classify the task:
 | **DEPENDENT** | One agent's output feeds into another's input | Sequential | "Design schema, then build API on it" |
 | **MIXED** | Some parts independent, some dependent | Parallel first, then sequential | "Research + design (parallel), then implement (sequential)" |
 
-## 2. Review Agent Protocol
+## 2. Dispatch Mode Selection
 
-**When required**: Always when 2+ agents are dispatched.
+Choose the dispatch mechanism based on agent count and collaboration needs:
+
+| Agents | Collaboration needed? | Mode | Why |
+|--------|----------------------|------|-----|
+| 1 | N/A | **Single subagent** | Simple, focused task |
+| 2-4, independent | No | **Parallel subagents** | Fast, low overhead, results return to dispatcher |
+| 2-4, dependent | Minimal (handoff notes) | **Sequential subagents** | One feeds the next, dispatcher coordinates |
+| 5+ OR agents need to discuss/challenge each other | Yes | **Agent Team** (TeamCreate) | Shared tasks, direct messaging, self-coordination |
+
+**User overrides always take priority:**
+- "use a team" → Agent Team mode, even for 2 agents
+- "use subagents" → Subagent mode, even for 5+ agents
+
+### When to prefer Agent Teams even with fewer agents
+
+- Agents need to **debate or challenge** each other's assumptions (e.g., competing architecture proposals)
+- The task requires **iterative refinement** where agents build on each other's work in multiple rounds
+- Cross-cutting concerns where every agent needs visibility into every other agent's output
+
+## 3. Agent Team Coordination
+
+### Team Creation
+
+1. Use `TeamCreate` with a descriptive name (e.g., "SaaS Platform Team") and the overall project goal
+2. Spawn the **Team Lead** first — this agent orchestrates the others
+3. Spawn remaining **teammates** with their role-specific prompts
+
+### Team Lead Responsibilities
+
+- Creates tasks in the shared task list for each work area
+- Assigns or lets teammates claim tasks based on their expertise
+- Monitors progress and sends messages to unblock teammates
+- Resolves conflicts between teammates
+- Acts as the **Review Agent** — synthesizes the final deliverable
+- Delivers the unified result back to the dispatcher
+
+### Teammate Coordination
+
+- **Claim tasks** from the shared task list that match their expertise
+- **Send messages** to other teammates when they need input or have dependencies
+- **Broadcast** important decisions that affect multiple teammates
+- **Mark tasks complete** with their deliverables attached
+- Stay within their role's domain — flag cross-cutting concerns to the Team Lead
+
+### When to Message vs. Broadcast
+
+| Action | Use |
+|--------|-----|
+| **Direct message** | One teammate needs specific info from another |
+| **Broadcast** | A decision affects the whole team (e.g., "we're using PostgreSQL, not MongoDB") |
+| **Task update** | Delivering a completed work item |
+
+## 4. Review Agent Protocol
+
+**When required**: Always when 2+ agents are dispatched (subagent mode). In Agent Team mode, the Team Lead fulfills this role.
 
 The Review Agent activates AFTER all specialist agents complete. Its responsibilities:
 
@@ -29,7 +83,7 @@ The Review Agent activates AFTER all specialist agents complete. Its responsibil
 | **NEEDS_REVISION** | Minor gaps or inconsistencies | Request specific agent to revise |
 | **ESCALATE** | Critical conflicts or LOW confidence | Present both perspectives with pros/cons, let user decide |
 
-## 3. Conflict Resolution
+## 5. Conflict Resolution
 
 When agents disagree:
 
@@ -52,7 +106,7 @@ The agents provided different recommendations on [topic]:
 Which approach do you prefer?
 ```
 
-## 4. Confidence Scoring
+## 6. Confidence Scoring
 
 ### Individual Agent Confidence
 
@@ -69,7 +123,7 @@ Which approach do you prefer?
 - If all HIGH -> high confidence in the synthesized answer
 - Mixed HIGH/MEDIUM -> proceed with medium confidence, note limitations
 
-## 5. Handoff Protocol
+## 7. Handoff Protocol (Subagent Mode)
 
 When agents need to pass information:
 
@@ -86,7 +140,7 @@ When agents need to pass information:
    Consider these inputs when working on your task.
    ```
 
-## 6. Escalation Triggers
+## 8. Escalation Triggers
 
 Automatically escalate to user when:
 - Any agent reports LOW confidence

package/skill/role-dispatcher/references/examples.md

@@ -144,3 +144,108 @@ Proceed? You can:
 **User**: "use only DevOps Engineer with haiku"
 
 -> Dispatcher adjusts: 1 agent (DevOps Engineer), model changed to Haiku, no review agent needed.
+
+---
+
+## Example 5: Large-Scale Project (Agent Team)
+
+**User request**: "Build a complete SaaS project management tool with user auth, team workspaces, real-time collaboration, Stripe billing, email notifications, and an admin dashboard"
+
+### Dispatch Decision
+- **Categories**: Software Development + Design & UX + Infrastructure & Ops + Cybersecurity + E-commerce
+- **Roles**: Software Architect, Backend Developer, Frontend Developer, UX/UI Designer, DevOps Engineer, Security Engineer, Payment Integration Specialist
+- **Independence**: Highly interdependent — architecture drives all layers, security cross-cuts everything
+- **Agents**: 7 (Agent Team mode — too many agents for subagent coordination, deep collaboration needed)
+- **Model**: Opus (large-scale architecture + multi-agent coordination)
+
+### Propose & Confirm
+
+```
+**Proposed dispatch:**
+- Software Architect: system architecture, service boundaries, data models
+  Key skills: system design, microservices, event-driven architecture
+- Backend Developer: API design, auth, real-time WebSocket layer
+  Key skills: Node.js, Python, REST, GraphQL, WebSockets
+- Frontend Developer: React app, real-time UI, responsive design
+  Key skills: React, TypeScript, state management, WebSocket clients
+- UX/UI Designer: user flows, wireframes, design system
+  Key skills: Figma, design systems, user research, accessibility
+- DevOps Engineer: CI/CD, cloud infrastructure, monitoring
+  Key skills: Docker, Kubernetes, Terraform, GitHub Actions
+- Security Engineer: auth architecture, data protection, compliance
+  Key skills: OAuth, RBAC, encryption, OWASP, GDPR
+- Payment Integration Specialist: Stripe billing, subscription management
+  Key skills: Stripe API, recurring billing, webhook handling
+
+**Model:** claude-opus-4-6 (high complexity)
+**Execution:** MIXED (architecture first, then parallel implementation)
+**Dispatch mode:** Agent Team — 7 agents with cross-cutting dependencies need shared coordination
+
+Proceed? You can:
+- **yes** to proceed as proposed
+- **Change roles**: e.g. "remove UX/UI Designer"
+- **Change model**: e.g. "use sonnet"
+- **use subagents**: force subagent mode instead of team
+- **Combine**: e.g. "remove Payment Specialist, use sonnet"
+```
+
+**User**: "yes"
+-> Dispatcher creates team via TeamCreate, spawns Software Architect as Team Lead, then 6 teammates.
+
+### Team Execution
+1. **Team Lead (Software Architect)** creates tasks: "Define service boundaries", "Design data models", "API contract spec", "Auth architecture", "Deployment strategy", "UI component inventory", "Billing integration spec"
+2. Teammates claim tasks matching their expertise
+3. Security Engineer broadcasts: "All services must use JWT with refresh tokens, RBAC on every endpoint"
+4. Frontend Developer messages Backend Developer: "Need WebSocket event schema for real-time updates"
+5. Team Lead monitors progress, resolves conflicts (e.g., REST vs GraphQL debate)
+6. Team Lead synthesizes all deliverables into a unified architecture document
+
+---
+
+## Example 6: Competing Hypotheses / Debugging (Agent Team)
+
+**User request**: "Our API response times jumped from 50ms to 2s after yesterday's deploy. We changed the ORM, added a new caching layer, and updated the load balancer config. Need to find the root cause."
+
+### Dispatch Decision
+- **Categories**: Infrastructure & Ops + Software Development + QA & Testing
+- **Roles**: Database Administrator, Backend Developer, Performance Tester, SRE, DevOps Engineer
+- **Independence**: INDEPENDENT investigation, but agents need to **challenge each other's hypotheses**
+- **Agents**: 5 (Agent Team mode — competing hypotheses require discussion between agents)
+- **Model**: Opus (complex debugging + multi-agent debate)
+
+### Propose & Confirm
+
+```
+**Proposed dispatch:**
+- Database Administrator: ORM migration analysis, query plan regression
+  Key skills: query optimization, ORM tuning, execution plans
+- Backend Developer: ORM code review, N+1 queries, connection pooling
+  Key skills: ORM patterns, connection management, profiling
+- Performance Tester: load testing, response time profiling, bottleneck isolation
+  Key skills: JMeter, profiling, latency analysis, benchmarking
+- Site Reliability Engineer: load balancer config review, traffic patterns
+  Key skills: load balancing, traffic analysis, monitoring, alerting
+- DevOps Engineer: deployment diff analysis, infrastructure changes
+  Key skills: deploy pipelines, config management, rollback procedures
+
+**Model:** claude-opus-4-6 (high complexity)
+**Execution:** INDEPENDENT (parallel investigation)
+**Dispatch mode:** Agent Team — competing hypotheses need cross-agent discussion
+
+Proceed? You can:
+- **yes** to proceed as proposed
+- **Change roles**: e.g. "add Security Engineer"
+- **Change model**: e.g. "use sonnet"
+- **use subagents**: force subagent mode instead of team
+```
+
+**User**: "yes"
+-> Dispatcher creates team, spawns DBA as Team Lead (database is primary suspect), then 4 teammates.
+
+### Team Execution
+1. Each agent investigates their hypothesis in parallel
+2. DBA broadcasts: "ORM is generating 3 extra JOINs per query — likely culprit"
+3. Backend Developer responds: "Confirmed N+1 pattern in the new ORM mapping, but connection pool is also misconfigured"
+4. SRE messages: "Load balancer change is clean — no impact on latency"
+5. Performance Tester: "Profiling confirms 80% of latency is in DB layer, 20% in connection pool exhaustion"
+6. Team Lead synthesizes: root cause is ORM migration (N+1 + extra JOINs) compounded by connection pool misconfiguration. Proposes fix with rollback strategy.

package/skill/role-dispatcher/references/model-selection-guide.md

@@ -10,7 +10,8 @@
 | Multi-file feature | 2 | Yes | `claude-sonnet-4-6` | Multiple concerns, needs coordination |
 | Architecture / system design | 2-3 | Yes | `claude-opus-4-6` | Deep reasoning, complex trade-offs |
 | Security audit / review | 1-2 | Yes | `claude-opus-4-6` | Critical accuracy, no room for error |
-| Multi-agent coordination | 3 | Yes | `claude-opus-4-6` | Complex orchestration, synthesis |
+| Multi-agent coordination (subagents) | 3-4 | Yes | `claude-opus-4-6` | Complex orchestration, synthesis |
+| Agent Team coordination | 5+ | Yes (Team Lead) | `claude-opus-4-6` | Large-scale orchestration, team self-coordination |
 
 ## Quick Decision Flow
 
@@ -19,7 +20,7 @@ Is it a simple question or small edit?
   YES -> Haiku
   NO  -> Does it require multi-file changes or 2+ agents?
     NO  -> Sonnet
-    YES -> Is it architecture, security, or 3-agent coordination?
+    YES -> Is it architecture, security, 3+ agent coordination, or Agent Team?
       NO  -> Sonnet
       YES -> Opus
 ```
@@ -34,8 +35,9 @@ Is it a simple question or small edit?
 
 ## Override Rules
 
-- **Always use Opus** for: security-sensitive tasks, system architecture, tasks touching production infrastructure
-- **Never use Haiku** for: multi-file code changes, security analysis, architecture decisions
+- **Always use Opus** for: security-sensitive tasks, system architecture, tasks touching production infrastructure, Agent Team coordination
+- **Never use Haiku** for: multi-file code changes, security analysis, architecture decisions, Agent Team mode
+- **Agent Teams note**: The Team Lead should always use Opus. Individual teammates can use Sonnet for focused implementation tasks if the user requests a lighter model — the Team Lead still coordinates on Opus
 - **User override**: If the user explicitly requests a model, respect their choice regardless of this guide
 
 ## User Override Protocol

package/skill/role-dispatcher/references/prompt-templates.md

@@ -83,11 +83,92 @@ You are reviewing the outputs of {N} specialist agents who worked on the same us
 Provide a synthesized, coherent response that integrates all agents' contributions into a single actionable answer.
 ```
 
+## Team Lead Template
+
+Used when dispatching via Agent Team mode. The Team Lead orchestrates the team and acts as the Review Agent.
+
+```
+## Your Role: Team Lead — {ROLE_NAME}
+
+### Expertise Profile
+- **Domain**: {CATEGORY_NAME}
+- **Core competencies**: {ROLE_DESCRIPTION}
+- **Key skills**: {KEY_SKILLS}
+- **Perspective**: You approach problems as a {ROLE_NAME} with deep expertise in {KEY_SKILLS}
+
+### Team Lead Responsibilities
+You are the **Team Lead** for this project. In addition to your specialist role, you:
+
+1. **Create tasks** in the shared task list — one per work area, clearly scoped
+2. **Coordinate** — assign or let teammates claim tasks, unblock dependencies
+3. **Monitor** — check task progress, send messages to teammates who are stuck
+4. **Resolve conflicts** — when teammates disagree, evaluate trade-offs and decide (or escalate to the user)
+5. **Synthesize** — once all tasks are complete, review all contributions and deliver a unified result
+
+### Project Goal
+{USER_REQUEST}
+
+### Your Team
+{TEAMMATE_LIST}
+
+### Language
+Respond in {RESPONSE_LANGUAGE}
+
+### Output
+When all teammates have delivered, synthesize their work:
+1. **Completeness check**: Every part of the user's request is addressed
+2. **Conflict detection**: Resolve contradictions between teammates
+3. **Integration**: Ensure all pieces fit together
+4. **Confidence**: Aggregate confidence = minimum of individual confidences
+5. **Final deliverable**: One coherent, actionable response
+```
+
+## Teammate Template
+
+Used for non-lead agents in Agent Team mode.
+
+```
+## Your Role: {ROLE_NAME}
+
+### Expertise Profile
+- **Domain**: {CATEGORY_NAME}
+- **Core competencies**: {ROLE_DESCRIPTION}
+- **Key skills**: {KEY_SKILLS}
+- **Perspective**: You approach problems as a {ROLE_NAME} with deep expertise in {KEY_SKILLS}
+
+### Behavioral Guidelines
+- **Communication level**: Adapt to the user's technical level. Default: clear, practical, actionable
+- **Language**: Respond in {RESPONSE_LANGUAGE}
+- **Actionability**: Every recommendation must be concrete and implementable
+- **Scope discipline**: Stay within your role's expertise. Flag anything outside it
+
+### Team Coordination
+- **Claim tasks** from the shared task list that match your expertise
+- **Message teammates** when you need input from them or have a dependency
+- **Broadcast** decisions that affect the whole team
+- **Mark tasks complete** with your deliverables
+- Stay within your domain — flag cross-cutting concerns to the Team Lead
+
+### Project Goal
+{USER_REQUEST}
+
+### Your Focus Area
+{FOCUS_AREA}
+
+### Output Format
+1. **Analysis**: Your assessment from your role's perspective
+2. **Deliverable**: Concrete, actionable output for your focus area
+3. **Confidence**: HIGH / MEDIUM / LOW with brief justification
+4. **Dependencies**: What you need from or provide to other teammates
+```
+
 ## Quick Reference: Template Selection
 
 | Scenario | Template | Notes |
 |----------|----------|-------|
 | 1 agent | Standard | No multi-agent section |
-| 2 agents, independent | Standard + Multi-Agent | Run in parallel |
-| 2-3 agents, dependent | Standard + Multi-Agent | Run sequentially, pass handoff notes |
-| Any multi-agent | Standard + Review Agent | Review agent runs after all others |
+| 2-4 agents, independent (subagents) | Standard + Multi-Agent | Run in parallel |
+| 2-4 agents, dependent (subagents) | Standard + Multi-Agent | Run sequentially, pass handoff notes |
+| Any multi-agent (subagents) | Standard + Review Agent | Review agent runs after all others |
+| 5+ agents or deep collaboration | Team Lead + Teammate | Agent Team mode via TeamCreate |
+| User requests "use team" | Team Lead + Teammate | Agent Team mode regardless of count |