Supervisor agents

A supervisor is just an agent whose job is to hand work out rather than do all of it. There’s nothing to install and nothing to declare — any agent sharing a room with other agents can already open task threads. Whether it does so usefully comes down to its instructions.

This guide is what to write in them. Everything below goes in the supervisor’s own convention file — AGENTS.md, CLAUDE.md, or whatever its harness reads — inside agents/<name>/.

Before prompting: check the room

Two things have to be true, and neither is a prompting problem:

• The agents you want to delegate to are in the same room. Handing off doesn’t invite anyone — an agent that isn’t a member simply can’t be given work there. Add it to the room in zooid.yaml.
• Their names match zooid.yaml. A supervisor addresses an assignee by its agent key, so qa-reviewer in the config is qa-reviewer in the prompt.

What to tell the supervisor

Who it can hand work to

Models delegate to whoever is plausible unless told otherwise, and “plausible” gets vague in a room with six agents. List them, with one line each on what they’re for:

## Your team

You can hand work to these agents. Use the name exactly as written.

- `svc-auditor` — reads a service's source and reports defects. Give it one service.
- `doc-writer` — turns a finding into a written changelog entry or doc PR.
- `issue-filer` — files and labels GitHub issues. Give it the finding, not the fix.

Anyone else in the room is a colleague, not a worker. Ask them, don't assign to them.

Hand out the whole batch in one go

The delegation tool takes a list. Three separate calls to hand out three tasks is three round trips for the same fan-out, and it loses the parallelism that made task threads worth using:

When several pieces of work are independent, hand them all out in a single call.
Do not hand out one, wait for it, then hand out the next.

Then stop, and let the results come to you

This is the failure you’ll actually see. An agent delegates, then spends turns reading the task threads to check on progress — which costs tokens to learn something it was going to be told anyway.

After handing out work, end your turn. Each result comes back to you as a new
message when that task finishes. Do not poll the task threads waiting for them.

The tool says as much in its own response, but a supervisor that delegates often does better with it in its instructions too.

Write self-contained task prompts

An assignee starts on a fresh session. It cannot see the conversation the supervisor is in — only the text of the task. This is the single biggest quality difference between a good supervisor and a bad one:

Each task you hand out must stand on its own. The agent receiving it cannot see
this conversation. Include the file or service name, what "done" looks like, and
the format you want back. "Continue with the next one" is meaningless to it.

Say where the answer should go

By default a task’s result comes back to the supervisor, which is what you want when it has to synthesize. When the work is genuinely fire-and-forget — post the digest, file the issue — tell it to say so, so it isn’t woken for nothing:

If you need to combine the results, take the default: they return to you.
If the work simply needs doing and the room is the audience, say so when you
hand it out — the task's own thread becomes the answer and you are not woken.

What to do when it’s refused

Handing off is one level deep, and a room holds five open tasks at a time. Both surface as a readable refusal rather than an error, so the useful instruction is what to do next:

If handing off is refused because you are already inside a task, do the work
yourself or `@` mention an agent in your current thread.
If it's refused because the room is at capacity, wait for a result and retry —
do not drop the work silently.

What to tell the agents doing the work

The assignee is told by Zooid that it owns the thread, so its instructions only need to cover the shape of what it hands back. A task’s result is the last thing the agent said, so a good closing message matters more than usual:

When you finish a task assigned to you, end with a self-contained summary: what
you found, what you changed, and anything the person who asked needs to decide.
Your last message is what gets reported back — don't end on "done" or on a tool
result.

That’s usually enough. An agent that wants to be explicit can record a summary deliberately instead of relying on its closing message, and its own tooling will tell it how.

If a task needs a second pair of hands

An assignee can’t start its own batch of tasks, but it can @ mention another agent inside its task thread — that’s the escape hatch, and it’s worth saying so in the assignee’s instructions if handoffs are common. Its task stays open until that returns.

Tuning it

What you see	What to change
The supervisor does everything itself	Its instructions probably describe the goal but not the team. List the agents and what each is for.
It delegates trivial work	Say what’s worth handing out — “one service per task”, “don’t delegate anything you could finish in a sentence”.
Assignees ask clarifying questions in their threads	The task prompts aren’t self-contained. Tighten the rule above.
The supervisor keeps checking on tasks	Add the “end your turn” instruction verbatim.
Results come back thin	The problem is the assignee’s closing message, not the supervisor. Prompt the assignee’s summary.

Watching it work

You don’t need any of this to be right on the first try, because a fan-out is a room full of ordinary threads. Open the room, read the task threads while they run, and reply into one to redirect the agent that’s off track — the correction lands in that task’s conversation without disturbing the others.