commit 16cb791d259a801d5f48bb1386fc60fe8e469dbc Author: charles Date: Thu Jun 18 22:04:23 2026 -0700 Add monkey swarm skill and mailbox protocol diff --git a/monkey-swarm/MAILBOX.md b/monkey-swarm/MAILBOX.md new file mode 100644 index 0000000..10ac9a2 --- /dev/null +++ b/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) + / + inbox/ ← messages received by this agent + drafts/ ← messages composed by this agent (staging area) +``` + +Each agent has its own mailbox under `mail//`. 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/.txt << 'EOF' +id: +role: +archetype: +task: +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/.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//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//drafts/01_subject-line.txt \ + mail//inbox/01_subject-line_.txt + ``` + + The trailing `` 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//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//sent/` or leave it; the orchestrator can clean up. + +## Mail Format + +Each `.txt` file is a single message with a simple format: + +``` +To: +From: +Subject: +--- + +``` + +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. diff --git a/monkey-swarm/SKILL.md b/monkey-swarm/SKILL.md new file mode 100644 index 0000000..2463119 --- /dev/null +++ b/monkey-swarm/SKILL.md @@ -0,0 +1,81 @@ +# Monkey Swarm + +When the user mentions needing help from the team, monkeys, or swarm — or asks you to delegate work — invoke the monkey swarm. The swarm keeps your context clean by offloading work to specialized sub-agents. + +## Trigger + +Activate this skill whenever the user mentions any of: + +- "monkey", "monkeys", "monkey swarm", "the swarm" +- "ask the monkeys", "have the monkeys", "send a monkey" +- "spawn", "delegate" (when referring to offloading a subtask) +- Requests that imply parallel or specialized work that would benefit from a dedicated agent + +## How It Works + +The swarm does **not** spawn agents with fixed roles. Instead, it spawns agents with **archetypes** — broad behavioral profiles. An "HR monkey" then translates the archetype into a concrete persona tailored to the immediate need. + +### Archetypes + +| Archetype | Purpose | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **specialist** | Dives deep into a very specific task. Use when the work is narrow, technical, and requires focused expertise. | +| **surveyor** | Explores a large space superficially. Use when you need breadth over depth — scanning a codebase, exploring a directory tree, or surveying a set of options. | +| **researcher** | Distills information from the work done by others. Use when multiple sources of information need to be synthesized into a coherent summary or recommendation. | +| **planner** | Looks at the current state of the project and proposes next steps. Use when you need a high-level plan, decomposition of work, or prioritization. | +| **interfacer** | Comes up with a set of questions for the user. Use when the problem is underspecified and you need more input before proceeding. | + +### Agent Identity and Mailbox + +When spawning a monkey agent: + +1. **Generate an agent ID** — a short random hex string like `monkey-a3f7`. Pass it to the agent in its prompt. +2. **Create the mailbox structure** — ensure `mail//inbox/` and `mail//drafts/` exist before the agent starts. +3. **Pass the orchestrator's ID** — tell the agent the orchestrator's agent ID (e.g. `orchestrator`) so it can send status updates or questions back. +4. **Register in the directory** — the agent writes its role, archetype, and task to `mail/dir/.txt` so other agents can discover it. The orchestrator can scan `mail/dir/` to see who's running. +5. **Tell the agent to use the mailbox protocol** — reference the `MAILBOX.md` file below. + +The mailbox is the communication channel between swarm agents and the orchestrator. It lives in `mail/` at the repo root. Agents read their inbox at the start of a run and check for new mail between work units. The `mail/dir/` registry keeps track of active agents and their roles. + +### Spawning a Monkey + +When spawning a monkey agent: + +1. **Identify the archetype** based on what's needed. +2. **Generate a persona** — briefly describe the exact role this agent should play, including its scope, goals, and deliverables. Be specific about what "done" looks like. +3. **Generate an agent ID** and create its mailbox directories. +4. **Include all context** — the agent does not see your conversation history. Provide file paths, requirements, constraints, any relevant background, and its agent ID. +5. **Tell the agent to follow the mailbox protocol** (see `MAILBOX.md`). +6. **Use `spawn_agent`** to launch the sub-agent with the persona as its label and the full prompt as its message. + +### Persona Template + +When generating a persona, fill in: + +``` +You are a [ROLE NAME], a [ARCHETYPE] monkey in the swarm. + +## Your Role +[2-3 sentences describing what you do and why you exist for this task.] + +## Scope +- [What you're responsible for] +- [What you're NOT responsible for] + +## Deliverables +- [Concrete output expected — file, summary, plan, questions, etc.] + +## Context +[All background the agent needs: project structure, relevant files, constraints, etc.] + +## Instructions +[Step-by-step or high-level guidance on how to approach the work.] +``` + +### Practical Rules + +- **Keep your context clean.** Offload work whenever a task can be completed by a sub-agent. The orchestrator's job is coordination, not doing everything. +- **Parallel when possible.** If multiple independent monkeys can work at once, spawn them in parallel. +- **Match archetype to need.** Don't send a specialist to explore — send a surveyor. Don't send a planner to implement — send a specialist. +- **Chain when needed.** A surveyor's findings can feed into a researcher's synthesis, which can feed into a planner's proposal. +- **The HR monkey is implicit.** You don't need to spawn a separate HR agent — you generate the persona yourself before spawning.