agent-to-agent

# Agent-to-Agent (A2A) Communication Protocol

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.

## Contents

- `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

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.

## Core Rules

- 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

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

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
```