Inter-Agent Communication Protocol

File-Based Asynchronous Coordination for Claude Agents

Back to AI Review Board Architecture

Agent Hierarchy & Communication Flow

PM Agent Orchestrator ~/.claude/agents/pm.md Architect System Design ADRs, Tech Evaluation Security Network & Auth Traefik, Keycloak Developer Implementation Deploy, Debug File-Based Workspace $HOME/projects/data/claudeagents/ pm/tasks/ architect/decisions/ security/decisions/ developer/notes/ escalations/{target-agent}/{project}/request-{topic}.md Cross-agent escalation requests task-architect.md task-security.md task-developer.md Write ADRs Write configs Write notes Reads design Reads specs Legend Task assignment Reads from

Workspace Directory Structure

$HOME/projects/data/claudeagents/ ├── pm/ │ ├── tasks/ │ │ └── {project-path}/ │ │ ├── task-breakdown.md # Full task breakdown │ │ ├── task-architect.md # Architect assignment │ │ ├── task-security.md # Security assignment │ │ └── task-developer.md # Developer assignment │ ├── reports/ │ │ └── {project-path}/ │ │ └── progress-{date}.md # Progress summaries │ └── notes/ │ └── coordination-{date}.md # Coordination notes │ ├── architect/ │ ├── decisions/ │ │ └── {project-path}/ │ │ ├── architecture.md # ADRs │ │ └── design.md # Design specifications │ ├── notes/ │ │ └── research-{topic}.md # Technology evaluations │ └── reports/ │ └── review.md # Architecture review │ ├── security/ │ ├── decisions/ │ │ └── {project-path}/ │ │ ├── network.md # Network topology │ │ ├── security.md # Security config specs │ │ ├── traefik.md # Traefik routing rules │ │ └── keycloak.md # Authentication setup │ └── notes/ │ └── audit-{date}.md # Security audit findings │ ├── developer/ │ ├── notes/ │ │ └── {project-path}/ │ │ ├── deployment.md # Deployment logs │ │ ├── debug-{issue}.md # Debugging notes │ │ └── implementation.md # Implementation details │ ├── reports/ │ │ └── build.md # Build and test reports │ └── decisions/ │ └── technical.md # Technical decisions │ └── */escalations/ └── {target-agent}/ └── {project-path}/ └── request-{topic}.md # Escalation requests

Task Delegation Patterns

Sequential Pattern (Default)

Architecture -> Security -> Development

PM Create task breakdown

Break down user request into specialist tasks

Architect Design solution

Write ADR with technology choices

Security Configure infrastructure

Network topology, auth, Traefik rules

Developer Implement & deploy

Code, deploy, test, document

Parallel Pattern

Independent research or components

## Parallel Tasks - [ ] Architect: Evaluate technology options - [ ] Architect: Design API contract - [ ] Security: Plan network topology ## Sequential Follow-up - [ ] Developer: Implement chosen solution

Iterative Pattern

Complex projects with feedback loops

## Iteration 1 - [ ] Architect: Initial design - [ ] Developer: Prototype - [ ] Architect: Refine based on feedback ## Iteration 2 - [ ] Security: Full security review - [ ] Developer: Production deployment

Escalation Protocol

Escalate to PM User decisions needed Multi-agent coordination To Architect Architecture gaps Design flaws in prod Performance issues Tech evaluation needed To Security Network topology changes Traefik routing config Keycloak client setup Security review needed To Developer Implementation feedback Runtime testing needed Deploy configurations Collect perf metrics Escalation File Format escalations/{target-agent}/{project-path}/request-{topic}.md Contains: From, To, Project, Priority, Date, Problem, Context, Request, Impact

When to Escalate to PM

  • User decisions or clarifications needed
  • Multi-agent coordination required
  • Project scope changes
  • Priority conflicts between agents
  • Resource allocation decisions
  • Blockers that can't be resolved independently

Escalation File Template

# Escalation: {Topic} **From**: {source-agent} **To**: {target-agent} **Project**: {full-project-path} **Priority**: High | Medium | Low **Date**: {YYYY-MM-DD} ## Problem {Description of the issue} ## Context {Relevant background} ## Request {What you need from target} ## Impact {How this blocks progress}

Best Practices

File Management

  • Use full absolute paths to avoid ambiguity
  • Mirror project structure in workspace directories
  • Complete output files before expecting others to read
  • Keep files updated - mark tasks complete

Communication

  • Clear handoffs - state what's done, what's next
  • Document blockers immediately
  • Check for escalations regularly
  • Be specific - vague requests cause rework

Key Principles

  • File-based communication only
  • Asynchronous by design - no waiting
  • Clear ownership of workspace directories
  • Persistent context across sessions