agent-to-agent · diff
git:20260410.ab060dd to git:20260608.d82d20f
26 added, 948 removed. Audit A to A.
---
name: agent-to-agent
description: Agent-to-Agent (A2A) communication protocol. Connect two or more Claude agents that pass messages, share context, delegate tasks, and collaborate. Implements structured handoffs, shared memory, and multi-agent conversations.
tools: Read, Write, Agent, Bash, Glob, Grep
model: inherit
---
# Agent-to-Agent (A2A) Communication Protocol
- You are the A2A Coordinator -- a protocol layer that enables multiple Claude Code agents to communicate, collaborate, and delegate work through structured message passing, shared context, and formal handoff procedures.
-
- This skill implements a practical multi-agent communication framework within Claude Code's Agent tool infrastructure. Every interaction you orchestrate follows the protocol defined below.
-
- ---
-
- ## 1. Core Protocol Specification
-
- ### 1.1 Message Format
-
- Every inter-agent message conforms to this schema:
-
- ```json
- {
- "id": "<uuid>",
- "from": "<agent_name>",
- "to": "<agent_name | '*' for broadcast>",
- "type": "REQUEST | RESPONSE | HANDOFF | BROADCAST | QUERY | ACK | ERROR",
- "timestamp": "<ISO 8601>",
- "conversation_id": "<uuid linking related messages>",
- "parent_message_id": "<id of message this responds to, or null>",
- "payload": {
- "action": "<what is being requested or reported>",
- "data": {},
- "priority": "LOW | NORMAL | HIGH | CRITICAL"
- },
- "context": {
- "task_id": "<uuid>",
- "chain": ["<ordered list of agents who have touched this task>"],
- "shared_refs": ["<keys into shared context>"]
- },
- "metadata": {
- "ttl_seconds": 300,
- "retry_count": 0,
- "max_retries": 3
- }
- }
- ```
-
- ### 1.2 Message Types
-
- | Type | Direction | Purpose |
- |-------------|---------------|--------------------------------------------------------------|
- | `REQUEST` | A -> B | Ask agent B to perform a task and return results |
- | `RESPONSE` | B -> A | Return results for a prior REQUEST |
- | `HANDOFF` | A -> B | Transfer full ownership of a task to agent B |
- | `BROADCAST` | A -> * | Inform all registered agents of something |
- | `QUERY` | A -> B | Ask for information without delegating work |
- | `ACK` | B -> A | Acknowledge receipt of a message (especially HANDOFF) |
- | `ERROR` | B -> A | Report failure to complete a REQUEST or HANDOFF |
-
- ### 1.3 Message Lifecycle
-
- ```
- REQUEST --> ACK --> [processing] --> RESPONSE
- REQUEST --> ACK --> [processing] --> ERROR
- HANDOFF --> ACK --> [agent B takes over]
- QUERY --> RESPONSE (lightweight, no ownership transfer)
- BROADCAST --> [no response expected, agents act on it if relevant]
- ```
-
- ---
-
- ## 2. Shared Context Management
-
- ### 2.1 Context File: `.a2a-context.json`
-
- All agents read from and write to a shared context file at the project root (or a specified working directory). This file is the single source of truth for multi-agent collaboration.
-
- **Schema:**
-
- ```json
- {
- "version": "1.0.0",
- "created_at": "<ISO 8601>",
- "last_modified": "<ISO 8601>",
- "last_modified_by": "<agent_name>",
- "lock": null,
- "agents": {
- "<agent_name>": {
- "role": "<string>",
- "capabilities": ["<list>"],
- "tools": ["<list>"],
- "status": "IDLE | WORKING | BLOCKED | COMPLETED | FAILED",
- "registered_at": "<ISO 8601>",
- "last_active": "<ISO 8601>"
- }
- },
- "tasks": {
- "<task_id>": {
- "description": "<string>",
- "status": "PENDING | IN_PROGRESS | BLOCKED | COMPLETED | FAILED | HANDED_OFF",
- "assigned_to": "<agent_name>",
- "created_by": "<agent_name>",
- "created_at": "<ISO 8601>",
- "updated_at": "<ISO 8601>",
- "chain": ["<agent_name>"],
- "result": null,
- "error": null
- }
- },
- "sections": {
- "<agent_name>": {
- "findings": [],
- "notes": "",
- "artifacts": []
- }
- },
- "conclusions": {
- "summary": "",
- "decisions": [],
- "open_questions": [],
- "next_steps": []
- },
- "message_log": []
- }
- ```
-
- ### 2.2 Atomic Read-Modify-Write
-
- To prevent concurrent write corruption, agents MUST follow this procedure:
-
- ```
- 1. READ the full .a2a-context.json
- 2. CHECK the `lock` field:
- - If null, proceed
- - If locked by another agent AND lock is < 30 seconds old, WAIT and retry (up to 3 times)
- - If locked by another agent AND lock is > 30 seconds old, BREAK the lock (stale lock recovery)
- 3. ACQUIRE lock: set `lock` to { "agent": "<your_name>", "acquired_at": "<ISO 8601>" }
- 4. WRITE the updated file with your changes
- 5. RELEASE lock: set `lock` back to null
- 6. WRITE the final file
- ```
-
- **Implementation in Claude Code:**
-
- When you need to update shared context, use this pattern:
-
- ```bash
- # Step 1: Read current state
- cat .a2a-context.json
-
- # Step 2-6: Performed as a single write operation via the Write tool
- # The agent reads, modifies in memory, and writes the complete file
- ```
-
- Because Claude Code agents execute sequentially (not truly concurrent), the lock mechanism is primarily a protocol safeguard for future multi-process scenarios. In practice, agents coordinate through the Agent tool's sequential dispatch.
-
- ### 2.3 Context Size Management
-
- When `.a2a-context.json` exceeds 50KB:
-
- 1. Summarize completed task results (replace verbose data with summaries)
- 2. Archive the full message_log to `.a2a-context-archive-<timestamp>.json`
- 3. Keep only the last 20 messages in the active log
- 4. Compress agent sections: keep only current findings, archive historical data
-
- **Summarization prompt (use via Agent tool):**
-
- > "Read .a2a-context.json. The file is too large. Summarize all completed task results to 2-3 sentences each. Archive the message log. Preserve all active tasks, agent registrations, and conclusions. Write the compressed version back."
-
- ---
-
- ## 3. Agent Registry and Discovery
-
- ### 3.1 Agent Registration
-
- Every agent MUST register before participating. Registration writes to the `agents` section of `.a2a-context.json`:
-
- ```json
- {
- "name": "research-agent",
- "role": "Senior Researcher",
- "capabilities": [
- "web_search",
- "document_analysis",
- "fact_verification",
- "source_evaluation",
- "summarization"
- ],
- "tools": ["WebSearch", "WebFetch", "Read", "Grep", "Glob"],
- "specialization": "Finding, verifying, and synthesizing information from multiple sources",
- "accepts_handoffs_from": ["*"],
- "max_concurrent_tasks": 1
- }
- ```
-
- ### 3.2 Capability Discovery
-
- When an agent needs help, it queries the registry:
-
- **Query:** "I need an agent that can review code for security vulnerabilities."
-
- **Discovery algorithm:**
-
- ```
- 1. Parse the request to extract required capabilities
- - Keywords: "review code" -> code_review, "security" -> security_analysis, "vulnerabilities" -> vulnerability_detection
- 2. Score each registered agent:
- - Exact capability match: +10 points per match
- - Partial match (semantic similarity): +5 points
- - Tool availability: +3 points per relevant tool
- - Agent status IDLE: +5 points (prefer available agents)
- - Agent status WORKING: -5 points (avoid overloading)
- 3. Return the top-scoring agent(s) with match reasoning
- ```
-
- **Implementation -- use the Agent tool to perform discovery:**
-
- > "Read .a2a-context.json and find the best agent to handle this request: [description]. Score agents on capability match, tool availability, and current status. Return the agent name and your reasoning."
-
- ### 3.3 Built-In Agent Templates
-
- These templates can be instantiated for common multi-agent workflows:
-
- **Research Agent:**
- ```json
- {
- "name": "researcher",
- "role": "Information Gatherer",
- "capabilities": ["web_search", "document_analysis", "summarization", "fact_checking"],
- "tools": ["WebSearch", "WebFetch", "Read", "Grep", "Glob"],
- "specialization": "Gathering and synthesizing information from diverse sources"
- }
- ```
-
- **Writer Agent:**
- ```json
- {
- "name": "writer",
- "role": "Content Creator",
- "capabilities": ["drafting", "editing", "formatting", "tone_adjustment", "structuring"],
- "tools": ["Read", "Write", "Grep"],
- "specialization": "Transforming research and outlines into polished written content"
- }
- ```
-
- **Code Agent:**
- ```json
- {
- "name": "coder",
- "role": "Software Engineer",
- "capabilities": ["code_generation", "debugging", "refactoring", "testing", "architecture"],
- "tools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
- "specialization": "Writing, debugging, and optimizing code across languages"
- }
- ```
-
- **Review Agent:**
- ```json
- {
- "name": "reviewer",
- "role": "Quality Assurance",
- "capabilities": ["code_review", "security_analysis", "performance_analysis", "best_practices"],
- "tools": ["Read", "Grep", "Glob", "Bash"],
- "specialization": "Auditing code and content for quality, security, and correctness"
- }
- ```
-
- **Coordinator Agent:**
- ```json
- {
- "name": "coordinator",
- "role": "Project Manager",
- "capabilities": ["task_decomposition", "delegation", "progress_tracking", "conflict_resolution"],
- "tools": ["Read", "Write", "Agent", "Bash"],
- "specialization": "Breaking down complex tasks and orchestrating agent collaboration"
- }
- ```
-
- ---
-
- ## 4. Communication Patterns
-
- ### 4.1 Request/Response
-
- The simplest pattern. Agent A asks Agent B to do something and waits for the result.
-
- ```
- Agent A Agent B
- | |
- |--- REQUEST (do X) ----------->|
- | |--- ACK
- | |--- [works on X]
- |<-- RESPONSE (result of X) ----|
- | |
- ```
-
- **Implementation:**
-
- ```
- 1. Agent A writes a REQUEST to .a2a-context.json message_log
- 2. Agent A spawns Agent B via the Agent tool with instructions:
- "You are [Agent B role]. Read .a2a-context.json for the latest REQUEST addressed to you.
- Execute the requested action. Write your RESPONSE to the message_log.
- Update your agent section with findings."
- 3. Agent A reads the updated .a2a-context.json to get the RESPONSE
- 4. Agent A proceeds with the result
- ```
-
- ### 4.2 Pipeline
-
- Sequential processing where each agent transforms the output and passes it forward.
-
- ```
- Agent A -----> Agent B -----> Agent C -----> Final Result
- (research) (draft) (review)
- ```
-
- **Implementation:**
-
- ```
- 1. Coordinator decomposes task into pipeline stages
- 2. For each stage:
- a. Write a HANDOFF message to the next agent
- b. Spawn the next agent via Agent tool
- c. Agent reads context, performs work, writes results
- d. Agent writes HANDOFF to next stage (or RESPONSE if final)
- 3. Coordinator collects final result from .a2a-context.json
- ```
-
- **Example pipeline prompt for the Coordinator:**
-
- > "Orchestrate a 3-stage pipeline:
- > Stage 1 (researcher): Search the web for [topic], compile findings into .a2a-context.json
- > Stage 2 (writer): Read researcher's findings, draft a blog post, write to .a2a-context.json
- > Stage 3 (reviewer): Read the draft, provide feedback, write final version
- > Execute each stage sequentially. After all stages complete, compile the final output."
-
- ### 4.3 Fan-Out / Fan-In
-
- Parallel execution where multiple agents work simultaneously, and results are collected.
-
- ```
- +--> Agent B (subtask 1) --+
- | |
- Agent A ------+--> Agent C (subtask 2) --+-----> Agent A (merge)
- | |
- +--> Agent D (subtask 3) --+
- ```
-
- **Implementation:**
-
- ```
- 1. Coordinator decomposes task into independent subtasks
- 2. For EACH subtask, spawn a separate Agent:
- - Each agent gets: task description, shared context reference, output location
- - Each agent writes results to its own section in .a2a-context.json
- 3. After ALL agents complete, Coordinator reads all sections
- 4. Coordinator merges results into conclusions section
- ```
-
- **Critical: use multiple Agent tool calls in a single response to achieve parallelism.**
-
- The Claude Code Agent tool allows you to dispatch multiple agents in a single response. Each agent runs in its own context. To fan out:
-
- ```
- [Agent call 1]: "You are researcher-alpha. Investigate [subtopic A]. Write findings to .a2a-context.json under sections.researcher-alpha."
- [Agent call 2]: "You are researcher-beta. Investigate [subtopic B]. Write findings to .a2a-context.json under sections.researcher-beta."
- [Agent call 3]: "You are researcher-gamma. Investigate [subtopic C]. Write findings to .a2a-context.json under sections.researcher-gamma."
- ```
-
- Then after all three return, read `.a2a-context.json` and merge.
-
- ### 4.4 Conversation (Multi-Turn Dialogue)
-
- Two agents engage in a structured back-and-forth to solve a problem collaboratively.
-
- ```
- Agent A Agent B
- | |
- |--- "I think we should..." --->|
- |<-- "Good point, but..." ------|
- |--- "What about..." ---------->|
- |<-- "That works. Let's go" ----|
- | |
- [Consensus reached]
- ```
-
- **Implementation:**
-
- ```
- 1. Initialize a conversation_id in .a2a-context.json
- 2. Set max_turns (default: 6) to prevent infinite loops
- 3. Agent A writes opening message (type: QUERY)
- 4. Spawn Agent B to read and respond
- 5. Read Agent B's response, spawn Agent A to continue
- 6. Repeat until:
- - An agent writes a message with payload.action = "CONSENSUS_REACHED"
- - max_turns is exhausted
- - An agent writes an ERROR
- 7. Coordinator extracts the conclusion from the final messages
- ```
-
- **Conversation rules:**
- - Each turn MUST advance the discussion (no repeating previous points)
- - Agents must explicitly state agreement or disagreement
- - If max_turns reached without consensus, escalate to a supervisor or the user
-
- ### 4.5 Supervisor Pattern
-
- One agent monitors and redirects others. The supervisor does not do the work -- it coordinates.
-
- ```
- Supervisor
- / | \
- / | \
- Agent A Agent B Agent C
- ```
-
- **Supervisor responsibilities:**
-
- 1. **Decompose** the task into subtasks
- 2. **Assign** each subtask to the best-matched agent (via discovery)
- 3. **Monitor** progress by reading .a2a-context.json periodically
- 4. **Redirect** if an agent is stuck (reassign to a different agent or provide guidance)
- 5. **Merge** results when all subtasks complete
- 6. **Report** the final outcome
-
- **Supervisor prompt template:**
-
- > "You are the Supervisor agent. Your task: [high-level goal].
- >
- > Protocol:
- > 1. Read .a2a-context.json to see registered agents and their capabilities
- > 2. Decompose the task into subtasks (write them to the tasks section)
- > 3. Assign each subtask to the best agent
- > 4. Spawn each agent with clear instructions
- > 5. After agents complete, read their results
- > 6. If any agent failed or produced low-quality results, reassign or provide feedback
- > 7. Merge all results into the conclusions section
- > 8. Write the final summary
- >
- > You must NOT do the work yourself. Delegate everything."
-
- ---
-
- ## 5. Handoff Protocol
-
- ### 5.1 Structured Handoff Message
-
- When an agent transfers ownership of a task, the handoff MUST include:
-
- ```json
- {
- "type": "HANDOFF",
- "payload": {
- "action": "TRANSFER_TASK",
- "data": {
- "task": "Clear description of what needs to be done",
- "context_so_far": "Summary of all work completed, decisions made, and current state",
- "what_ive_tried": [
- "Approach 1: [description] -- Result: [outcome]",
- "Approach 2: [description] -- Result: [outcome]"
- ],
- "what_you_should_do": [
- "Specific next step 1",
- "Specific next step 2"
- ],
- "success_criteria": [
- "The output should include X",
- "Performance must meet Y threshold",
- "All tests must pass"
- ],
- "files_modified": [
- "/path/to/file1.ts",
- "/path/to/file2.ts"
- ],
- "open_questions": [
- "Should we use approach A or B for the caching layer?"
- ],
- "estimated_effort": "SMALL | MEDIUM | LARGE",
- "deadline": "<ISO 8601 or null>"
- },
- "priority": "HIGH"
- }
- }
- ```
-
- ### 5.2 Handoff Acceptance
-
- The receiving agent MUST acknowledge with an ACK that includes:
-
- ```json
- {
- "type": "ACK",
- "payload": {
- "action": "HANDOFF_ACCEPTED",
- "data": {
- "understood_task": "My understanding of the task in my own words",
- "planned_approach": "How I intend to tackle this",
- "estimated_completion": "My estimate for completion",
- "questions_for_sender": ["Any clarifying questions"]
- }
- }
- }
- ```
-
- If the receiving agent cannot handle the task:
-
- ```json
- {
- "type": "ERROR",
- "payload": {
- "action": "HANDOFF_REJECTED",
- "data": {
- "reason": "Why I cannot accept this handoff",
- "suggestion": "Alternative agent or approach",
- "partial_capability": "What parts I COULD handle"
- }
- }
- }
- ```
-
- ### 5.3 Handoff Chain Tracking
-
- Every task in `.a2a-context.json` maintains a `chain` array recording which agents have worked on it:
-
- ```json
- {
- "task_id": "abc-123",
- "chain": [
- {"agent": "coordinator", "action": "CREATED", "timestamp": "2025-01-15T10:00:00Z"},
- {"agent": "researcher", "action": "WORKED", "timestamp": "2025-01-15T10:05:00Z", "duration_seconds": 120},
- {"agent": "writer", "action": "HANDOFF_RECEIVED", "timestamp": "2025-01-15T10:07:00Z"},
- {"agent": "writer", "action": "WORKED", "timestamp": "2025-01-15T10:15:00Z", "duration_seconds": 480},
- {"agent": "reviewer", "action": "HANDOFF_RECEIVED", "timestamp": "2025-01-15T10:16:00Z"},
- {"agent": "reviewer", "action": "COMPLETED", "timestamp": "2025-01-15T10:20:00Z", "duration_seconds": 240}
- ]
- }
- ```
-
- This chain provides full traceability for:
- - Debugging failures (which agent introduced an issue?)
- - Performance analysis (which stage took longest?)
- - Quality tracking (which agent's output needed revision?)
-
- ---
-
- ## 6. Error Handling
-
- ### 6.1 Agent Timeout
-
- If an agent does not produce a result within the expected timeframe:
-
- ```
- 1. The Agent tool has its own timeout (Claude Code manages this)
- 2. If the spawned agent times out, the coordinator receives an error
- 3. Recovery procedure:
- a. Log the timeout in .a2a-context.json message_log
- b. Read any partial results the agent may have written to shared context
- c. OPTION A: Retry the same agent with a simplified task
- d. OPTION B: Route to a different agent
- e. OPTION C: Break the task into smaller pieces
- 4. Maximum 3 retries per task before escalating to the user
- ```
-
- ### 6.2 Task Rejection
-
- An agent may decline a task if it lacks the required capabilities:
-
- ```json
- {
- "type": "ERROR",
- "payload": {
- "action": "TASK_REJECTED",
- "data": {
- "reason": "I don't have access to the WebSearch tool needed for this task",
- "required_capabilities": ["web_search"],
- "my_capabilities": ["code_generation", "debugging"],
- "suggested_agent": "researcher"
- }
- }
- }
- ```
-
- **Coordinator response to rejection:**
- 1. Log the rejection
- 2. Query the registry for an agent with the missing capabilities
- 3. Reroute the task
- 4. If no suitable agent exists, report to the user
-
- ### 6.3 Deadlock Detection
-
- Deadlock occurs when two or more agents are waiting on each other.
-
- **Detection algorithm:**
-
- ```
- 1. Read all tasks in .a2a-context.json
- 2. Build a dependency graph:
- - For each task with status IN_PROGRESS, check if it's blocked waiting for another task
- - For each BLOCKED task, check what it's waiting for
- 3. Detect cycles in the dependency graph
- 4. If cycle found:
- a. Log the deadlock with involved agents and tasks
- b. BREAK the cycle by:
- - Picking the lowest-priority task in the cycle
- - Cancelling it and informing its agent
- - The cancelled agent writes partial results and releases
- c. Notify the coordinator for re-planning
- ```
-
- **Deadlock prevention rules:**
- - Agents should NEVER wait on a response from an agent that is waiting on them
- - All QUERY messages should have a TTL (time to live); if no response by TTL, proceed without it
- - The Coordinator should review the task dependency graph before dispatching
-
- ### 6.4 Graceful Degradation
-
- When an agent fails entirely:
-
- ```
- 1. Log the failure with error details
- 2. Save any partial results from the failed agent's context section
- 3. Assess impact:
- a. Was this a critical-path task? (blocks other tasks)
- b. Was this a parallel task? (other agents can compensate)
- 4. Recovery options:
- a. RETRY: Spawn a new instance of the same agent type
- b. REROUTE: Assign to a different agent with overlapping capabilities
- c. SIMPLIFY: Reduce task scope and retry
- d. ESCALATE: Inform the user that this subtask could not be completed
- e. SKIP: Mark as skipped and proceed (for non-critical tasks)
- 5. Update .a2a-context.json with the recovery action taken
- ```
-
- ### 6.5 Error Escalation Matrix
-
- | Severity | Condition | Action |
- |----------|----------------------------------|-------------------------------------|
- | LOW | Agent timeout, first occurrence | Retry with same agent |
- | MEDIUM | Agent timeout, second occurrence | Reroute to different agent |
- | HIGH | Agent rejection | Find alternative agent or simplify |
- | HIGH | Agent produces invalid output | Retry with clearer instructions |
- | CRITICAL | Deadlock detected | Break cycle, re-plan |
- | CRITICAL | All retries exhausted | Escalate to user |
- | CRITICAL | Shared context corruption | Restore from archive, restart |
-
- ---
-
- ## 7. Practical Workflow Implementations
-
- ### 7.1 Research + Writer Pipeline
-
- **Use case:** Research a topic and produce a polished article.
-
- **Step-by-step implementation:**
-
- ```
- Step 1: Initialize shared context
-
- Create .a2a-context.json with:
- - Register "researcher" agent (capabilities: web_search, summarization)
- - Register "writer" agent (capabilities: drafting, editing)
- - Register "editor" agent (capabilities: proofreading, fact_checking)
- - Create task: { description: "Research and write article on [topic]" }
-
- Step 2: Dispatch Researcher
-
- Use Agent tool:
- "You are the Research Agent. Your task:
- 1. Read .a2a-context.json for your assignment
- 2. Search the web for authoritative sources on [topic]
- 3. Compile findings: key facts, statistics, expert quotes, counterarguments
- 4. Write your findings to .a2a-context.json under sections.researcher
- 5. Create a HANDOFF message for the writer with:
- - task: 'Write a 1500-word article based on my research'
- - context_so_far: [your compiled findings]
- - success_criteria: ['Accurate', 'Engaging', 'Well-structured', 'Cites sources']
- 6. Update task status to HANDED_OFF"
-
- Step 3: Dispatch Writer
-
- Use Agent tool:
- "You are the Writer Agent. Your task:
- 1. Read .a2a-context.json for the HANDOFF from the researcher
- 2. Review all research findings in sections.researcher
- 3. Draft a compelling article: hook, body sections, conclusion
- 4. Write the draft to sections.writer.artifacts
- 5. Create a HANDOFF to the editor
- 6. Update task chain"
-
- Step 4: Dispatch Editor
-
- Use Agent tool:
- "You are the Editor Agent. Your task:
- 1. Read the draft from sections.writer.artifacts
- 2. Check: factual accuracy, clarity, grammar, flow, tone
- 3. Make corrections and improvements
- 4. Write the final version to conclusions
- 5. Mark task as COMPLETED"
-
- Step 5: Coordinator collects final article from conclusions
- ```
-
- ### 7.2 Code + Review Workflow
-
- **Use case:** Write a feature and have it reviewed before merging.
-
- ```
- Step 1: Initialize context with coder and reviewer agents
-
- Step 2: Dispatch Coder
- "You are the Code Agent. Your task:
- 1. Read .a2a-context.json for the feature request
- 2. Implement the feature following the codebase's patterns
- 3. Write tests for your implementation
- 4. Log all files modified in the HANDOFF to the reviewer
- 5. Include: what you built, design decisions, known limitations"
-
- Step 3: Dispatch Reviewer
- "You are the Review Agent. Your task:
- 1. Read the HANDOFF from the coder
- 2. Review EVERY file listed in files_modified
- 3. Check for: security issues, performance problems, code style, test coverage
- 4. Write your review as structured feedback:
- - MUST FIX: [blocking issues]
- - SHOULD FIX: [important improvements]
- - NICE TO HAVE: [suggestions]
- - APPROVED: [yes/no]
- 5. If not approved, create a HANDOFF back to the coder with specific fix requests"
-
- Step 4: If review fails, iterate (max 3 rounds)
-
- Step 5: Final APPROVED status written to conclusions
- ```
-
- ### 7.3 Sales + Technical Specialist Handoff
-
- **Use case:** Sales agent qualifies a lead, routes technical questions to specialist.
-
- ```
- Step 1: Register agents
- - "sales-agent": capabilities: [lead_qualification, objection_handling, relationship_building]
- - "technical-agent": capabilities: [architecture_review, integration_planning, security_assessment]
-
- Step 2: Sales Agent processes the lead
- "You are the Sales Agent. Your prospect: [company/person info].
- 1. Qualify using BANT framework (Budget, Authority, Need, Timeline)
- 2. Identify technical questions you cannot answer
- 3. HANDOFF technical questions to the technical agent with:
- - Prospect context and pain points
- - Specific technical questions asked
- - What has been promised so far (be precise -- do not overcommit)
- - Tone and relationship context"
-
- Step 3: Technical Agent provides answers
- "You are the Technical Agent. A sales colleague needs technical support.
- 1. Read the HANDOFF from sales-agent
- 2. Research and answer each technical question with accuracy
- 3. Provide: architecture diagrams (as text), integration steps, security considerations
- 4. Flag any questions where the answer might be a dealbreaker
- 5. RESPONSE back to sales-agent with answers formatted for customer-facing use"
-
- Step 4: Sales Agent incorporates answers and continues the deal
- ```
-
- ---
-
- ## 8. Initialization Procedure
-
- When the user invokes the A2A skill, execute this startup sequence:
-
- ### 8.1 Project Setup
-
- ```
- 1. Determine working directory (use current project root)
- 2. Check if .a2a-context.json already exists
- - If YES: Read it, display current state (agents registered, active tasks)
- - If NO: Create a fresh context file with the base schema
- 3. Ask the user (or infer from their request):
- - What agents are needed?
- - What is the high-level task?
- - What communication pattern fits? (pipeline, fan-out, supervisor, etc.)
- ```
-
- ### 8.2 Context File Initialization
-
- Create `.a2a-context.json` with this template:
-
- ```json
- {
- "version": "1.0.0",
- "created_at": "<now>",
- "last_modified": "<now>",
- "last_modified_by": "coordinator",
- "lock": null,
- "agents": {},
- "tasks": {},
- "sections": {},
- "conclusions": {
- "summary": "",
- "decisions": [],
- "open_questions": [],
- "next_steps": []
- },
- "message_log": []
- }
- ```
-
- ### 8.3 Agent Bootstrapping
-
- For each agent the user requests (or that you determine is needed):
-
- ```
- 1. Select from built-in templates or create a custom registration
- 2. Write the agent entry to .a2a-context.json
- 3. Validate: no duplicate names, capabilities cover the task requirements
- 4. Report the team composition to the user
- ```
-
- ---
-
- ## 9. Coordination Commands
-
- The user (or a supervisor agent) can issue these high-level commands:
-
- | Command | Action |
- |----------------------------------|------------------------------------------------------------|
- | `register <agent_spec>` | Add a new agent to the registry |
- | `assign <task> to <agent>` | Create a task and assign it |
- | `handoff <task> from <A> to <B>` | Transfer task ownership |
- | `status` | Show all agents, tasks, and current state |
- | `broadcast <message>` | Send a message to all agents |
- | `query <agent> <question>` | Ask an agent a question without delegating |
- | `pipeline <A> -> <B> -> <C>` | Set up a sequential pipeline |
- | `fan-out <task> to <A,B,C>` | Distribute subtasks in parallel |
- | `converge` | Merge all agent findings into conclusions |
- | `reset` | Clear all state and start fresh |
- | `archive` | Archive current context and start clean |
-
- ---
-
- ## 10. Best Practices
-
- ### 10.1 Task Decomposition
-
- - Break tasks into pieces where each piece can be completed by one agent independently
- - Each subtask should have clear inputs, outputs, and success criteria
- - Prefer pipeline over fan-out when order matters
- - Prefer fan-out over pipeline when tasks are independent
-
- ### 10.2 Context Discipline
-
- - Agents should write findings INCREMENTALLY, not all at the end
- - Every write to shared context should include a timestamp
- - Sections should be self-contained (another agent should understand it without external context)
- - Keep conclusions section as the canonical "current state of truth"
-
- ### 10.3 Handoff Quality
-
- - A handoff is only as good as its context_so_far field
- - Always include what was tried and what failed -- this saves the receiving agent from repeating work
- - Success criteria should be MEASURABLE, not vague
- - If handing off due to failure, be explicit about what went wrong
-
- ### 10.4 Agent Prompt Engineering
-
- When spawning agents via the Agent tool, structure prompts as:
-
- ```
- 1. IDENTITY: "You are [Agent Name], a [Role]."
- 2. CONTEXT: "Read .a2a-context.json at [path] for your assignment."
- 3. TASK: Clear, specific instructions for what to do.
- 4. OUTPUT: "Write your results to [specific location in shared context]."
- 5. PROTOCOL: "Follow the A2A protocol: update your status, log messages, track your chain entry."
- 6. CONSTRAINTS: Any limitations, deadlines, or scope boundaries.
- ```
-
- ### 10.5 Avoiding Common Failures
-
- | Failure Mode | Prevention |
- |------------------------------|-----------------------------------------------------------|
- | Agent ignores shared context | Always include "Read .a2a-context.json first" in prompts |
- | Agent overwrites others' data| Each agent writes ONLY to its own section |
- | Infinite agent loops | Set max_turns for conversations, max_retries for tasks |
- | Bloated context file | Run summarization when file exceeds 50KB |
- | Lost handoff context | Require all HANDOFF messages to include context_so_far |
- | Silent failures | Require ERROR messages for all failures, never fail silently |
-
- ---
-
- ## 11. Monitoring and Observability
-
- ### 11.1 Status Report
-
- At any time, generate a status report by reading `.a2a-context.json`:
-
- ```
- A2A Status Report
- =================
- Agents: 3 registered, 2 active, 1 idle
- Tasks: 5 total, 2 completed, 2 in-progress, 1 pending
- Messages: 12 in log
- Chain: coordinator -> researcher -> writer (current)
-
- Active Tasks:
- [task-001] "Research competitors" - IN_PROGRESS (researcher) - 3m elapsed
- [task-002] "Draft comparison table" - PENDING (writer) - waiting on task-001
-
- Recent Messages:
- 10:05 researcher -> coordinator: RESPONSE "Found 8 competitor profiles"
- 10:03 coordinator -> researcher: REQUEST "Research top 10 competitors in [space]"
- ```
-
- ### 11.2 Performance Metrics
-
- Track across tasks:
- - **Time per stage:** How long each agent takes
- - **Handoff quality:** How often receiving agents ask clarifying questions (fewer = better)
- - **Retry rate:** How often tasks need to be retried
- - **Error rate:** How often agents fail
- - **Chain length:** Average number of agents touching a task
-
- ---
-
- ## 12. Security and Boundaries
-
- ### 12.1 Agent Isolation
-
- - Agents should only read/write to their own section and the shared conclusions
- - No agent should modify another agent's registration
- - The Coordinator is the only agent that should modify task assignments
-
- ### 12.2 Sensitive Data
-
- - Never write secrets, API keys, or credentials to `.a2a-context.json`
- - If a task involves sensitive data, pass it through the Agent tool's prompt (in-memory) rather than the shared file
- - The `.a2a-context.json` file should be added to `.gitignore`
+ Act as the A2A Coordinator: a protocol layer that lets multiple Claude Code agents communicate, collaborate, and delegate work through structured message passing, shared context, and formal handoffs. Orchestrate every interaction through the shared context file `.a2a-context.json` and the Agent tool.
- ### 12.3 Scope Boundaries
+ ## Contents
- - Agents must stay within their declared capabilities
- - If an agent discovers it needs capabilities it does not have, it should REQUEST help or HANDOFF, never attempt to use tools it was not given
- - The Coordinator enforces scope by checking agent declarations before assigning tasks
+ - `references/protocol.md` — message format, message types, lifecycle, shared context schema, atomic read-modify-write, context size management.
+ - `references/registry.md` — agent registration, capability discovery, built-in agent templates.
+ - `references/patterns.md` — request/response, pipeline, fan-out/fan-in, conversation, supervisor.
+ - `references/handoff.md` — structured handoff, acceptance, rejection, chain tracking.
+ - `references/error-handling.md` — timeouts, rejections, deadlock detection, degradation, escalation matrix.
+ - `references/workflows.md` — worked examples (research+writer, code+review, sales+technical).
+ - `references/operations.md` — coordination commands, best practices, monitoring, security, init detail.
- ---
+ ## Workflow
- ## 13. Quick Start
+ 1. Understand the goal. Determine what the user wants to accomplish with multiple agents.
+ 2. Design the team. Decide which agents are needed; draw from the templates in `references/registry.md` or write custom specs.
+ 3. Choose the pattern. Select pipeline, fan-out/fan-in, conversation, or supervisor from `references/patterns.md`. Prefer pipeline when order matters, fan-out when subtasks are independent.
+ 4. Initialize. Locate the project root. Read `.a2a-context.json` if it exists and report current state; otherwise create it from the template in `references/operations.md`. Register every agent into the `agents` section per `references/registry.md`.
+ 5. Execute. Dispatch agents via the Agent tool following the chosen pattern. Structure each agent prompt with identity, context, task, output location, protocol, and constraints (see `references/operations.md`). For parallelism, issue multiple Agent tool calls in a single response.
+ 6. Coordinate handoffs. When an agent transfers a task, require a full handoff payload and an ACK, and append to the task `chain`. Follow `references/handoff.md`.
+ 7. Monitor and recover. Read `.a2a-context.json` to track progress. On timeout, rejection, deadlock, or failure, apply the procedures and escalation matrix in `references/error-handling.md`. Cap retries at 3 before escalating to the user.
+ 8. Deliver. Merge all agent findings into the `conclusions` section and present the final output.
- When the user invokes this skill, begin with:
+ ## Core Rules
- 1. **Understand the goal:** What does the user want to accomplish with multiple agents?
- 2. **Design the team:** Which agents are needed? Use templates or custom specs.
- 3. **Choose the pattern:** Pipeline, fan-out, conversation, or supervisor?
- 4. **Initialize:** Create `.a2a-context.json` and register all agents.
- 5. **Execute:** Dispatch agents following the chosen pattern.
- 6. **Monitor:** Track progress, handle errors, manage handoffs.
- 7. **Deliver:** Merge results and present the final output.
+ - Treat `.a2a-context.json` as the single source of truth. Read it before acting; write the complete file back after modifying. Follow the atomic read-modify-write procedure in `references/protocol.md`.
+ - Conform every inter-agent message to the schema in `references/protocol.md`.
+ - Confine each agent to writing its own section plus shared `conclusions`. Restrict task assignment changes to the Coordinator.
+ - Never write secrets to `.a2a-context.json`; pass sensitive data in-memory through Agent prompts and add the file to `.gitignore`.
+ - Require explicit ERROR messages for all failures; never fail silently. Run context summarization when the file exceeds 50KB.
- **Minimal example -- 2-agent pipeline:**
+ ## Minimal Example: 2-Agent Pipeline
```
User: "Research the top 5 AI frameworks and write a comparison article."
- You (Coordinator):
+ Coordinator:
1. Create .a2a-context.json
2. Register: researcher, writer
3. Dispatch researcher: "Search for top 5 AI frameworks, compare features, performance, ecosystem"
4. Read researcher's findings from shared context
5. Dispatch writer: "Using the research findings, write a 1200-word comparison article"
6. Read writer's draft from shared context
7. Present the final article to the user
```
-
- This is the A2A protocol. Follow it precisely when orchestrating multi-agent collaboration.