asymmetric-al Team Communication Protocols
Protocols for effective communication between agent teammates, including message type selection, plan approval workflows, shutdown procedures, and common anti-patterns to avoid.
When to Use This Skill
- Establishing communication norms for a new team
- Choosing between message types (message, broadcast, shutdown_request)
- Handling plan approval workflows
- Managing graceful team shutdown
- Discovering teammate identities and capabilities
Message Type Selection
message (Direct Message) — Default Choice
Send to a single specific teammate:
{
"type": "message",
"recipient": "implementer-1",
"content": "Your API endpoint is ready. You can now build the frontend form.",
"summary": "API endpoint ready for frontend"
}
Use for: Task updates, coordination, questions, integration notifications.
broadcast — Use Sparingly
Send to ALL teammates simultaneously:
{
"type": "broadcast",
"content": "Critical: shared types file has been updated. Pull latest before continuing.",
"summary": "Shared types updated"
}
Use ONLY for: Critical blockers affecting everyone, major changes to shared resources.
Why sparingly?: Each broadcast sends N separate messages (one per teammate), consuming API resources proportional to team size.
shutdown_request — Graceful Termination
Request a teammate to shut down:
{
"type": "shutdown_request",
"recipient": "reviewer-1",
"content": "Review complete, shutting down team."
}
The teammate responds with shutdown_response (approve or reject with reason).
Communication Anti-Patterns
| Anti-Pattern | Problem | Better Approach |
|---|---|---|
| Broadcasting routine updates | Wastes resources, noise | Direct message to affected teammate |
| Sending JSON status messages | Not designed for structured data | Use TaskUpdate to update task status |
| Not communicating at integration points | Teammates build against stale interfaces | Message when your interface is ready |
| Micromanaging via messages | Overwhelms teammates, slows work | Check in at milestones, not every step |
| Using UUIDs instead of names | Hard to read, error-prone | Always use teammate names |
| Ignoring idle teammates | Wasted capacity | Assign new work or shut down |
Plan Approval Workflow
When a teammate is spawned with plan_mode_required:
- Teammate creates a plan using read-only exploration tools
- Teammate calls
ExitPlanModewhich sends aplan_approval_requestto the lead - Lead reviews the plan
- Lead responds with
plan_approval_response:
Approve:
{
"type": "plan_approval_response",
"request_id": "abc-123",
"recipient": "implementer-1",
"approve": true
}
Reject with feedback:
{
"type": "plan_approval_response",
"request_id": "abc-123",
"recipient": "implementer-1",
"approve": false,
"content": "Please add error handling for the API calls"
}
Shutdown Protocol
Graceful Shutdown Sequence
- Lead sends shutdown_request to each teammate
- Teammate receives request as a JSON message with
type: "shutdown_request" - Teammate responds with
shutdown_response:approve: true— Teammate saves state and exitsapprove: false+ reason — Teammate continues working
- Lead handles rejections — Wait for teammate to finish, then retry
- After all teammates shut down — Call
Teammatecleanup
Handling Rejections
If a teammate rejects shutdown:
- Check their reason (usually "still working on task")
- Wait for their current task to complete
- Retry shutdown request
- If urgent, user can force shutdown
Teammate Discovery
Find team members by reading the config file:
Location: ~/.claude/teams/{team-name}/config.json
Structure:
{
"members": [
{
"name": "security-reviewer",
"agentId": "uuid-here",
"agentType": "team-reviewer"
},
{
"name": "perf-reviewer",
"agentId": "uuid-here",
"agentType": "team-reviewer"
}
]
}
Always use name for messaging and task assignment. Never use agentId directly.