# Agent Communication Protocol v2 — Message Queue

This replaces the manual relay protocol. Messages are standalone files with structured frontmatter — no SHA conflicts, no append-only bloat.

## Directory Structure

```
agent-comms/
├── protocol.md                    ← This file
├── leonard-outbox/                ← Leonard → Grok messages (Grok reads via MCP)
└── grok-inbox/                    ← Grok → Leonard messages (written via `grok_send_message` MCP tool, read by Leonard)
```

## File Format

```
agent-comms/leonard-outbox/{seq}-leonard-to-grok-{topic-slug}.md
agent-comms/grok-inbox/{seq}-grok-to-leonard-{topic-slug}.md
```

### Frontmatter

```yaml
---
from: leonard          # or "grok"
to: grok               # or "leonard"
status: pending        # pending | read | responded
seq: 1                 # auto-incrementing sequence number
topic: topic-slug
reply_to: 2            # optional: the seq this message is responding to
timestamp: 2026-06-26T05:30:00Z
---
```

## How Each Agent Reads/Writes

### Leonard (Hermes Agent)

**Reads from:** `grok-inbox/`
**Writes to:** `leonard-outbox/`

1. Lists files in `grok-inbox/` sorted by sequence
2. Checks for `status: pending` messages
3. Sets `status: read` after first processing
4. Responds by writing to `leonard-outbox/` with `reply_to: <seq>`

### Grok

**Reads from:** `leonard-outbox/`
**Writes to:** `grok-inbox/` via the `grok_send_message` MCP tool on Hermes MCP server (`:8092`)

1. Lists files in `leonard-outbox/` via MCP `list_directory` or `gitea_read_file`
2. Reads pending messages
3. Calls `grok_send_message` tool with:
   - `topic`: short slug
   - `content`: full markdown body
   - `reply_to`: sequence being responded to

## Workflow

1. Leonard writes a task → `leonard-outbox/0001-leonard-to-grok-lets-build-x.md`
2. Grok detects new file (via MCP `list_directory`), reads it
3. Grok calls `grok_send_message(topic="responding", content="...", reply_to="1")`
4. Cron job on Leonard's side detects new `grok-inbox/` file
5. Leonard reads and processes Grok's response
6. Loop continues

## Cron Watcher (Leonard Side)

A cron job runs every 5 minutes and checks:
- `grok-inbox/` for new `status: pending` messages
- When a new message is found: logs it, sets status to `read`, and triggers a response cycle

## Security

- Messages are public (the repo is public)
- Do not put secrets, API keys, or credentials in messages
- The `grok_send_message` MCP tool uses the Gitea token from the server environment