Coordination and delegation protocols for sub-agent specialist assignments
Load this skill before invoking ANY sub-agent (master-orchestrator, specialists, validators).
Every sub-agent prompt MUST include four components:
"USER'S ORIGINAL REQUEST: [verbatim user prompt - MANDATORY]
[COMPREHENSIVE CONTEXT]
- Project: [overall goal and current state]
- Background: [why this matters, how it fits]
- Dependencies: [what this builds on or integrates with]
TASK ASSIGNMENT:
[Detailed, specific requirements with clear scope and boundaries]
CONTEXT REFERENCES:
- Session: [path and what to extract]
- Skills: [relevant skills to load]
- Examples: [similar existing implementations]
Think hard and provide [thoroughness level] analysis/implementation.
DELIVERABLES:
[Exact format, success criteria, validation requirements]"
Sub-Agent Context Principle: Sub-agents have temporary windows—maximize their context collection. Over-collection is safe; under-collection causes failures.
| Bad | Good |
|---|---|
| "Fix authentication" | "Fix OAuth redirect loop where successful login redirects to /login instead of /dashboard" |
| "Add tests" | "Add tests for user profile editing (session Phase 2) covering avatar upload, validation, error handling" |
| "Implement feature X" | "Implement feature X following patterns from Y, integrating with Z API, referencing session-current.md Phase 3" |
| Scenario | Approach |
|---|---|
| Multi-phase feature, 5+ files, architectural | Auto-invoke /team-plan → user approval → /build |
| Cross-domain integration, agents need coordination | /team-plan → user approval → /team-build (Agent Teams) |
| Simple file edit, pattern search, single-component | Direct sub-agent delegation |
| Ambiguous scope, needs planning | Gather context → /team-plan → user approval → /build |
| Clear scope, bounded execution | Direct delegation |
| High-reliability task, production changes | /team-plan with Specialist + Quality Engineer validation |
| Research/exploration only | Direct Explore agent or deep-researcher |
/build vs /team-build Decision:
/build: Tasks are independent, sub-agents don't need to communicate, cost-sensitive (1x tokens)/team-build: Agents need peer-to-peer coordination, cross-domain interfaces, contract-first spawning (2-4x tokens)Central AI auto-invokes /team-plan + /build (or /team-build) for complex work. This is the standard operating procedure for all non-trivial implementation.
Auto-invoke /team-plan immediately when:
Gather info first, then invoke when:
Don't invoke (direct execution) when:
Step 1 - Plan:
Skill({ skill: "team-plan", args: "<comprehensive prompt with all context>" })
Step 2 - Pause:
Present the plan summary to the user. Wait for approval ("go", /build, /team-build, or feedback).
Step 3 - Execute (after user approval):
For isolated sub-agent execution (default):
Skill({ skill: "build", args: ".claude/tasks/<plan-file>.md" })
For collaborative Agent Teams execution (when agents need peer-to-peer coordination):
Skill({ skill: "team-build", args: ".claude/tasks/<plan-file>.md" })
Use /team-build when the plan involves cross-domain integration where agents need to share contracts (schemas, API specs, interfaces) and coordinate in real-time. Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
When composing the prompt for /team-plan, Central AI should include:
AskUserQuestionExample auto-invocation:
Skill({
skill: "team-plan",
args: "Build a new models section for the blog with 11 model profile pages. User wants: chronological model pages from Claude 3 through Opus 4.6, a models index page, and cross-links to existing posts. Existing blog structure is in apps/web/src/content/blog/blog-structure.ts. Content style should match existing guide posts. Use content-writer agents for parallel page creation."
})
Invoke multiple agents using multiple Task tool calls in ONE message.
| Pattern | Agents | Use Case |
|---|---|---|
| Domain Parallel | frontend + backend + database | Independent feature development |
| Validation Parallel | security + performance + quality | Comprehensive validation |
| Debug Parallel | debugger-detective + deep-researcher | Complex issue investigation |
Use parallel dispatch when ALL conditions met:
Use serial dispatch when ANY condition present:
Parallel Agent Output Rule: When dispatching agents in parallel, instruct them to write their work to files (edits, creations) rather than returning lengthy responses in the terminal. All work is version controlled, so file-based output is preferred. This prevents context bloat from multiple agents returning verbose terminal output simultaneously.
The high-reliability pattern: specialist agents build, quality-engineer validates. Use when incorrect output has high cost.
Specialist agents serve as builders. Use the appropriate specialist for the domain: frontend-specialist, backend-engineer, supabase-specialist, security-auditor, performance-optimizer, or general-purpose for cross-domain work. Each specialist focuses on ONE task and reports completion via TaskUpdate.
Quality engineer serves as validator. When dispatched in validation mode, the quality-engineer inspects completed work without modifying files and produces a structured pass/fail report.
Validation prompt template:
"You are operating in VALIDATION MODE. Verify the completed work against acceptance criteria.
TASK TO VALIDATE: [task description and acceptance criteria]
SPECIALIST'S WORK: [files to inspect, expected changes]
WORKFLOW:
1. Read the task requirements and acceptance criteria
2. Inspect all files the specialist changed
3. Run validation commands (tests, type checks, compilation)
4. Report PASS or FAIL with specific evidence using the Validation Report format
CONSTRAINT: Do NOT modify any files. Inspect and report only. If issues are found, report them for the specialist to fix."
Dependency pattern for specialist/validation chains:
TaskCreate: "Build feature X" -> Task #1 (assigned to specialist)
TaskCreate: "Validate feature X" -> Task #2 (assigned to quality-engineer)
TaskUpdate: Task #2 addBlockedBy: ["1"] // Validation waits for build
// Multiple specialists can run in parallel:
TaskCreate: "Build component A" -> Task #1 (frontend-specialist)
TaskCreate: "Build component B" -> Task #2 (backend-engineer)
TaskCreate: "Validate all" -> Task #3 (quality-engineer), addBlockedBy: ["1", "2"]
Store agent IDs to continue work with preserved context:
// First deployment
Task({ prompt: "Build X...", subagent_type: "general-purpose" })
// Returns: agentId "abc123"
// Later - resume with full prior context
Task({ prompt: "Now add tests...", resume: "abc123" })
Use resume when: continuing related work, agent needs prior context. Use fresh when: unrelated task, clean slate preferred.
| Chain | Reasoning |
|---|---|
| Schema → API → Frontend | Data structure must exist before interfaces |
| Core → Enhancement | Foundation before optimization |
| Build → Validate → Integrate | Build, verify, then connect |
| Research → Planning → Execution | Understand, plan, implement |
| Domain | Agent | Handles |
|---|---|---|
| Frontend | frontend-specialist | React, UI, state, forms, responsive design |
| Backend | backend-engineer | Server actions, APIs, business logic, auth |
| Database | supabase-specialist | Schema, migrations, RLS, real-time |
| Testing/Validation | quality-engineer | Unit, integration, E2E, coverage, task validation |
| Security | security-auditor | Auth security, RLS validation, vulnerabilities |
| Performance | performance-optimizer | Core Web Vitals, bundle analysis, monitoring |