charles/tipsy-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor mailbox protocol and add status tracking

Browse Source 
Move the protocol documentation to references/ and expand
it with read receipts and thread IDs. Update SKILL.md to
reference the new location and add a YAML frontmatter block.
Remove the outdated MAILBOX.md file.
This commit is contained in:
charles
2026-06-18 22:32:11 -07:00
parent 16cb791d25
commit 162ff7a559
3 changed files with 263 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files
monkey-swarm/SKILL.md
+30 -17
View File
@@ -1,3 +1,12 @@
---
name: monkey-swarm
description: >
Delegates work to specialized sub-agents (monkeys) using behavioral archetypes
(specialist, surveyor, researcher, planner, interfacer). Use when the user
mentions monkeys, swarm, delegation, or requests that benefit from parallel
or specialized agent work. Don't use for simple single-step tasks.
---
# 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.
@@ -25,34 +34,26 @@ The swarm does **not** spawn agents with fixed roles. Instead, it spawns agents
| **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
## 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`).
3. **Generate an agent ID** — a short random hex string like `monkey-a3f7`. Pass it to the agent in its prompt.
4. **Set up the mailbox** — read `references/mailbox.md` for the full mailbox protocol. At minimum:
- Ensure `mail/<agent-id>/inbox/`, `mail/<agent-id>/inbox/.read/`, and `mail/<agent-id>/drafts/` exist before the agent starts.
- Pass the orchestrator's ID (e.g. `orchestrator`) so the agent can send status updates or questions back.
- Pass a **thread ID** for this agent's conversation with the orchestrator (e.g. `task-refactor-auth`). All messages between the orchestrator and this agent should use the same thread ID.
- Tell the agent to register in `mail/dir/<agent-id>.txt` with `status: active` and to update its status as it works.
5. **Include all context** — the agent does not see your conversation history. Provide file paths, requirements, constraints, any relevant background, and its agent ID.
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:
```
```text
You are a [ROLE NAME], a [ARCHETYPE] monkey in the swarm.
## Your Role
@@ -72,6 +73,18 @@ You are a [ROLE NAME], a [ARCHETYPE] monkey in the swarm.
[Step-by-step or high-level guidance on how to approach the work.]
```
### Mailbox Protocol
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.
**Key features:**
- **Read receipts** (`inbox/.read/`) — agents only poll unread messages, preventing context bloat.
- **Thread IDs** — group related messages into conversations; the orchestrator and each agent share a thread ID.
- **Agent status** (`status:` in `mail/dir/`) — the orchestrator polls status to know who's working, done, or blocked.
**Load `references/mailbox.md`** for the full protocol: directory structure, registration, sending/receiving rules, mail format, thread protocol, message status, and cleanup.
### 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.