Inter-Agent Communication Protocol

Author: Wadsworth 📋
Date: 2026-04-20
Status: Active

The Three Agents

Communication Channels

1. Shared Workspace (Async — Primary)

The shared/ directory is the canonical async channel between agents.

shared/
  api-specs/       ← Socrates writes, Daedalus reads. API contracts.
  design-tokens/   ← Daedalus writes, Socrates reads. Visual specs.
  project-docs/    ← Both read/write. Onboarding, roadmaps, briefings.

Rules:
- Write to your domain directory only
- Read from others' directories freely
- Announce changes in the Board group when significant
- Never write to another agent's workspace (workspace-daedalus/, workspace-socrates/, etc.)

2. sessions_send (Synchronous — Preferred)

When another agent has an active session, use sessions_send to message them directly with full context.

Workflow:
1. sessions_list — find the target agent's session key
2. sessions_send — send a message into their session
3. They receive it as a user message and can respond in context

Advantages over raw Telegram:
- Full session context is preserved
- Proper agent identity (no confusion about who sent the message)
- Response comes back through the normal agent flow

3. Board Group Chat (Announcements)

The Hoffmann Board (-5296734042) is for team-wide announcements and @mention conversations.

Rules:
- @mention only — never respond unprompted
- Keep replies boardroom-appropriate: decisions, alignment, action items
- Deep work happens in DMs

4. NEVER: Raw Telegram Bot API

Do not use curl to the Telegram Bot API to send messages through another bot's token. This:
- Drops text without session context
- Confuses the receiving agent (no conversation history, no system prompt)
- Bypasses OpenClaw's routing entirely
- Creates orphan messages the agent can't reference

Contract-First Workflow

When building features:

1. Socrates writes the API spec → shared/api-specs/
2. Daedalus builds the UI against that spec
3. Matt approves the design
4. Socrates wires real data to the endpoint
5. Wadsworth tracks progress, routes blockers, coordinates testing

Single source of truth per domain:
- API specs → Socrates owns
- Design tokens → Daedalus owns
- Project coordination → Wadsworth owns

Session Routing

Each agent's session is bound to their Telegram bot account:

If routing breaks, check openclaw.json bindings and agents.list first.