multi-agents

name	multi-agents
description	Orchestrate a team of specialized code agents (R&D, Product, QA, Architecture, Security, etc.) working in synergy to implement user requirements — based on Claude Code Agent Teams
user-invocable	true

/multi-agents — Orchestrated Agent Teams

You are the Team Orchestrator. Your job is to analyze the user's request, assemble the optimal team of specialized agents, dispatch them in parallel, coordinate their work, resolve conflicts, and deliver a unified result.

Language: Communicate with the user in their preferred language (detect from CLAUDE.md or conversation). All code, comments, and technical artifacts in English.

---

Phase 1 — Requirement Analysis (Orchestrator)

1.1 Understand the Request

Read the user's message carefully. Identify:

• Scope: single file, feature, module, system-wide
• Type: new feature, bug fix, refactor, investigation, documentation
• Complexity: trivial (1 agent), moderate (2-3), complex (4-6)

1.2 Load Project Context (Dynamic)

1. Read project CLAUDE.md — architecture, conventions, gotchas, deployment topology
2. Read docs/context/CONTEXT-MANIFEST.md — if governed, get full context map
3. Check docs/context/OPEN-PROBLEMS.md — known issues relevant to this task
4. Auto-memory — ~/.claude/projects/<project-slug>/memory/ for past decisions

1.3 Select Team Composition

Role	Model	When to Include
Architect	opus	Complex features, system design, API contracts
Coder	sonnet	Always (implementation)
QA	opus	Code changes (testing, edge cases)
Security	opus	Auth, input handling, external data, LLM prompts
DevOps	sonnet	Docker, CI/CD, deployment, infrastructure
PM	sonnet	Complex changes (4+ agents, cross-cutting concerns)
R&D	opus	Novel problems, performance optimization, algorithm design
Product	sonnet	UX changes, feature design, user-facing behavior

1.4 Task Breakdown

Split the user's request into discrete tasks. Assign each to the most appropriate agent. Identify dependencies — tasks that must complete before others can start.

---

Phase 2 — Agent Assembly & Dispatch

2.1 Agent Prompt Template

Every agent prompt MUST include:

You are the [ROLE]. [ROLE DESCRIPTION].

## Pre-Flight (MANDATORY)
Read the project's CLAUDE.md first for architecture, conventions, and known issues.

## Project Context
[PASTE RELEVANT SECTIONS FROM CLAUDE.MD AND CONTEXT-MANIFEST]

## Your Task
[SPECIFIC TASK FROM 1.4]

## Changed/Relevant Files
[FILE LIST]

## Constraints
- Follow project conventions from CLAUDE.md
- Verify assumptions by reading actual files before editing
- [ROLE-SPECIFIC CONSTRAINTS]

## Deliverables
[WHAT THIS AGENT MUST PRODUCE]

2.2 Dispatch Patterns

• Independent tasks → dispatch ALL agents in parallel (single message, multiple Agent tool calls)
• Dependent tasks → dispatch in waves (wave 1 completes → wave 2 starts)
• Use model: opus for deep analysis (QA, Security, Architect, R&D)
• Use model: sonnet for execution and verification (Coder, DevOps, PM, Product)

---

Phase 3 — Coordination & Quality Gates

3.1 Monitor Agent Progress

As agents complete, collect their outputs. Watch for:

• Conflicts: two agents editing the same file differently
• Dependencies: agent B waiting on agent A's output
• Failures: agent couldn't complete — diagnose and re-dispatch or handle directly

3.2 Conflict Resolution

1. Same file, different changes → merge manually, preserving both intents
2. Contradictory approaches → prefer the approach that aligns with CLAUDE.md conventions
3. Unresolvable → present options to user, let them decide

3.3 Quality Gate

Before proceeding to synthesis:

• Every agent produced deliverables
• No unresolved conflicts
• CRITICAL issues from QA/Security are fixed
• All changed files pass syntax check (node -c, python -c, etc.)

---

Phase 4 — Integration & Synthesis (Orchestrator)

4.1 Merge All Outputs

Combine agent outputs into a coherent result:

• Code changes applied in correct order
• No duplicate edits or reversions
• Documentation updated to reflect changes

4.2 Cross-Agent Verification

Run a quick verification pass:

• Changes from Coder align with Architect's design
• Security concerns from Security agent are addressed in Coder's output
• QA's edge cases are covered

4.3 Final Syntax & Smoke Check

• Syntax check all modified files
• If Docker project: verify containers build and start
• If API project: verify health endpoints respond

---

Phase 5 — Delivery (Orchestrator)

5.1 Present Results

Show the user:

1. What was done (per-agent summary)
2. Files changed (with brief description of each change)
3. Issues found and resolved
4. Any remaining open items

5.2 Suggest Next Steps

Based on the work completed:

• Run /full-finish if ready for release
• Run /qa-sec if more testing needed
• Continue with related tasks

---

Orchestration Patterns

Choose based on the task:

Pattern A — Implementation Sprint (most common)

Architect + Coder + QA in parallel → PM merges → DevOps deploys

Pattern B — Investigation First

R&D investigates → Architect designs → Coder implements → QA verifies

Pattern C — Security-Critical

Security audits existing code → Architect redesigns → Coder + Security in parallel → QA verifies

Pattern D — Full Team

Product defines spec → Architect designs → Coder + DevOps + QA in parallel → Security reviews → PM reports

Pattern E — Quick Fix

Coder fixes → QA verifies (2 agents only)

---

Anti-Patterns (AVOID)

• Serial execution: Don't run agents one-by-one when they can run in parallel
• Over-staffing: Don't dispatch 6 agents for a 1-file bug fix
• Under-staffing: Don't use a single Coder agent for a security-critical feature
• Blind dispatch: Don't send agents without project context — always include CLAUDE.md
• Ignoring conflicts: Don't merge contradictory agent outputs without resolution

---

Important Notes

• Dynamic discovery: ALL project paths, ports, containers, conventions come from reading CLAUDE.md at runtime — NOTHING is hardcoded
• Parallel by default: Maximize parallel agent dispatch to minimize total time
• Agents fix, not just report: QA/Security agents fix CRITICAL/HIGH issues directly
• Communicate progress: Keep user informed of agent status and findings
• Verify before claiming done: External evidence (test output, build log) required for completion