# Inter-Agent Communication Protocol

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

---

## The Three Agents

| Agent | Bot | Telegram | Domain |
|-------|-----|----------|--------|
| Wadsworth 📋 | HoffmannButlerBot | @hoffmann_butler_bot | Chief of Staff — routing, scheduling, general assistance |
| Socrates 🧠 | Socrates | @HoffDeskSocratesBot | Backend architect — APIs, pipelines, infrastructure |
| Daedalus 🎨 | Daedalus | @Daedalus89Bot | Frontend architect — UI/UX, design system, mobile |

---

## 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:

| Binding | Bot Account | Agent | Workspace |
|---------|-------------|-------|-----------|
| default → main | @hoffmann_butler_bot | Wadsworth | `~/.openclaw/workspace/` |
| daedalus → daedalus | @Daedalus89Bot | Daedalus | `~/.openclaw/workspace-daedalus/` |
| socrates → socrates | @HoffDeskSocratesBot | Socrates | `~/.openclaw/workspace-socrates/` |

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