82 lines
5.0 KiB
Markdown
82 lines
5.0 KiB
Markdown
|
# 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.
|