{
  "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
  }
}

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]

{
  "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": []
}

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

undefined

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.

{
  "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
}

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

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

Agent A                          Agent B
  |                                |
  |--- REQUEST (do X) ----------->|
  |                                |--- ACK
  |                                |--- [works on X]
  |<-- RESPONSE (result of X) ----|
  |                                |

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

Agent A -----> Agent B -----> Agent C -----> Final Result
(research)    (draft)        (review)

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

              +--> Agent B (subtask 1) --+
              |                          |
Agent A ------+--> Agent C (subtask 2) --+-----> Agent A (merge)
              |                          |
              +--> Agent D (subtask 3) --+

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

[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."

Agent A                          Agent B
  |                                |
  |--- "I think we should..." --->|
  |<-- "Good point, but..." ------|
  |--- "What about..." ---------->|
  |<-- "That works. Let's go" ----|
  |                                |
  [Consensus reached]

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

              Supervisor
             /    |    \
            /     |     \
        Agent A  Agent B  Agent C

{
  "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"
  }
}

{
  "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"]
    }
  }
}

{
  "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"
    }
  }
}

{
  "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}
  ]
}

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

{
  "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"
    }
  }
}

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

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

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

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

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

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.)

{
  "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": []
}

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

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.

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]"

User: "Research the top 5 AI frameworks and write a comparison article."

You (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