Add monkey swarm skill and mailbox protocol

monkey-swarm/MAILBOX.md

@@ -0,0 +1,116 @@
+# Mailbox Protocol
+
+The mailbox is the file-based communication system for the monkey swarm. It enables agents to send messages to each other and the orchestrator without shared memory or a live connection.
+
+## Directory Structure
+
+```
+mail/
+  dir/          ← agent directory (registry of active agents)
+  <agent-id>/
+    inbox/      ← messages received by this agent
+    drafts/     ← messages composed by this agent (staging area)
+```
+
+Each agent has its own mailbox under `mail/<agent-id>/`. The orchestrator typically uses `orchestrator` as its ID.
+
+## Agent Directory (`mail/dir/`)
+
+`mail/dir/` is the registry of active swarm agents. Every agent writes its own entry when it starts, so other agents (and the orchestrator) can discover who is running and how to reach them.
+
+### Registering
+
+When an agent starts, it writes a file to `mail/dir/`:
+
+```
+cat > mail/dir/<agent-id>.txt << 'EOF'
+id: <agent-id>
+role: <short role name>
+archetype: <specialist|surveyor|researcher|planner|interfacer>
+task: <one-line description>
+EOF
+```
+
+Example — `mail/dir/monkey-a3f7.txt`:
+
+```
+id: monkey-a3f7
+role: API integration specialist
+archetype: specialist
+task: Implement OAuth2 flow in auth module
+```
+
+### Discovering Agents
+
+Agents can scan `mail/dir/` to find who else is in the swarm:
+
+```bash
+ls mail/dir/
+cat mail/dir/monkey-a3f7.txt
+```
+
+Use this to find the right recipient when you need to send mail but don't know which agent ID handles a given role.
+
+### Cleanup
+
+When an agent finishes its work, it removes its own entry:
+
+```
+rm mail/dir/<agent-id>.txt
+```
+
+The orchestrator can also clean up stale entries when a swarm run is complete.
+
+## Sending Mail
+
+To send a message to another agent:
+
+1. **Write a draft** — create the message in your drafts folder:
+
+   ```
+   mail/<your-id>/drafts/01_subject-line.txt
+   ```
+
+   The prefix number (`01_`) gives ordering; use sequential numbers for related messages.
+
+2. **Move it to the target's inbox** — atomically deliver by renaming:
+
+   ```
+   mv mail/<your-id>/drafts/01_subject-line.txt \
+      mail/<target-id>/inbox/01_subject-line_<hash>.txt
+   ```
+
+   The trailing `<hash>` is a short random suffix (e.g. `a3f7`) to avoid filename collisions.
+
+3. **Use `mv` not copy** — a message is either in your drafts or in the target's inbox, never both. This avoids duplicate reads.
+
+## Receiving Mail
+
+- **Check inbox at startup** — read all files in `mail/<your-id>/inbox/` when you begin.
+- **Check inbox between work units** — scan for new files after completing a logical step.
+- **Process all pending mail** — read every file in the inbox in filename order.
+- **Archive after reading** — move processed mail to `mail/<your-id>/sent/` or leave it; the orchestrator can clean up.
+
+## Mail Format
+
+Each `.txt` file is a single message with a simple format:
+
+```
+To: <recipient-id>
+From: <sender-id>
+Subject: <brief description>
+---
+<message body>
+```
+
+The `---` separator distinguishes headers from the body. The body can be any plain text, code, file paths, or structured data.
+
+## Rules
+
+- **Register before you work.** Write your entry to `mail/dir/` as one of your first actions so others can find you.
+- **Unregister when done.** Remove your `mail/dir/` entry before you exit so stale agents don't linger.
+- **Your inbox is your signal channel.** The orchestrator uses it to redirect you, cancel work, or provide new context mid-run.
+- **Keep messages short.** If you have a lot to say, write a file and send a pointer in the mail.
+- **Always move, never copy.** A message in your drafts is a work-in-progress. Once moved, it's delivered.
+- **Don't read other agents' inboxes.** Only read your own. If you need to share data with another agent, send it to them — don't peek at their conversations.
+- **Check before and between.** The inbox is how you learn you've been redirected. Missing mail = missing orders.