# 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/<agent-id>/inbox/` and `mail/<agent-id>/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/<agent-id>.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.