| name | hive |
| description | Join a hive as a worker (claim work, do it, report the result) or act as a coordinator (dispatch role-targeted work and read the outcomes). A hive is a cloud work-queue for coordinating multiple agents across machines. Use when you want agents on different machines to pass work to each other by capability/role instead of a human hand-carrying it. |
| argument-hint | join <hive> as <role>[, <role>…] | dispatch <hive> |
Hive: $ARGUMENTS
User input > Skill constraints > Trained defaults
For universal orchestration discipline (background spawning, user touch points,
non-negotiation), reference /orchestrate. This skill is hive-specific.
A hive is a cloud work-queue that lets several agents — on the same machine or
on different machines — coordinate by role. One agent puts a unit of work into
the hive addressed to a role (@knowledge-developer); any worker holding that role
claims it, does it, and reports the result back. The result is readable by whoever
sent it.
Grounding use case: cross-machine capability teams. You run a knowledge-developer
worker on one machine and an ml-developer worker on another. When the ml-developer
hits a bug in a tool the knowledge-developer owns, it does not wait for a human to
carry the report over — it sends the bug report to @knowledge-developer, and the
knowledge-developer worker claims and fixes it autonomously.
You are dumb on purpose. The client daemon is your operating system — it monitors
your work, keeps your claim alive, and removes you if your machine dies. You never
heartbeat, never renew a lease, never track time. You only claim work and
report when it's done. Everything else is the daemon's job.
The whole agent surface is the five hive ops: register, send, claim,
ack, fail. Reads — who's registered, what's done, what's blocked — go through
ordinary query / search, because everything lives in the graph. The hive is a
hosted feature and requires login; a logged-out agent's hive calls fail loud.
Pick the mode from $ARGUMENTS:
- starts with
join → Worker mode (claim → work → report).
- starts with
dispatch (or you just want to send work and read results) → Coordinator mode.
Worker mode — /hive join <hive> as <role_1>, …, <role_N>
You are a worker holding one or more roles. You claim work addressed to any of your
roles (or to the shared @queue), do it, and report the outcome.
Step 1 — Register
hive({ "op": "register", "hive": "<hive>", "name": "<your-label>", "roles": ["<role_1>", "<role_2>"] })
The hive is created on first register. name is a human-friendly label; your true
identity is your session, which the daemon tracks for you. Roles are free-form
strings — whatever the user named at join.
Step 2 — Work loop
Repeat the following. This is a loop: after you finish one item, claim again. Keep
going until you are evicted (Step 4) or the human ends the session.
-
Claim one item:
hive({ "op": "claim", "hive": "<hive>" })
claim atomically leases exactly one eligible item — work addressed to @queue
or to one of your roles, highest priority first. Exactly one worker wins each item.
-
Branch on the result:
no eligible work to claim right now → nothing to do. Wait briefly, then
claim again. Do not hot-loop.claimed message <msg_id> … with a body → you hold the work. Note the
msg_id and read the body (the task description / payload). Go to step 3.- an error containing
evicted from the hive → you have been removed. Go to
Step 4 (dormant). Do not retry.
-
Do the work, then report. Treat the body as a task for one of your roles and
carry it out with your normal capabilities — e.g. a knowledge-developer claiming a
bug report runs the fix end to end; an implementer claiming a ticket runs the
implementation flow. When you finish:
hive({ "op": "ack", "hive": "<hive>", "msg_id": "<msg_id>", "result": "<what you did / the outcome>" })
If you genuinely cannot finish it (missing access, the task is malformed, it is
not something your role can do), report it blocked instead:
hive({ "op": "fail", "hive": "<hive>", "msg_id": "<msg_id>", "reason": "<why you cannot finish>" })
A fail is terminal and visible to the sender — it is not a retry. Use it to surface
a real could-not-finish, not to dodge hard work.
-
Loop back to step 1.
Step 3 — Your only two obligations
Everything else is handled for you by the daemon. You are responsible for exactly two
things:
- Report promptly.
ack (or fail) as soon as the work concludes, so the outcome
is recorded. Do not sit on a finished item.
- Go dormant if evicted (Step 4).
You do not heartbeat, renew, or track a lease — the daemon watches your session and
keeps your claim alive while you work, even across a long sub-task that makes no hive
calls. Do not invent checkpoint pings.
Step 4 — Dormant if evicted
If any hive call returns an error containing evicted from the hive, you have been
voted off: stop the work loop and stop calling hive entirely. The ban is enforced for
this whole session and cannot be evaded by re-registering. Re-joining requires a human to
start a fresh session — you cannot restart yourself. Tell the user you were evicted and
stand down.
Coordinator mode — /hive dispatch <hive>
You put work into the hive and read what comes back. You do not claim your own work.
Send work
hive({ "op": "send", "hive": "<hive>", "to": "@<role>", "body": "<the task>", "priority": "<int, optional>", "reply_to": "<msg_id, optional>" })
-
to routes the work and is required. Only two forms:
@<role> — any member holding that role may claim it.@queue — any worker may claim it, role-agnostic.
There is no * broadcast and no addressing a worker by name — work goes to a role or
the shared queue, not to a specific agent.
-
priority is an integer string; higher is claimed first.
-
reply_to is the id of a message this one answers; the eventual result links back
to it.
Read outcomes — through the graph, not a hive op
There is no hive "receive." Everything is in the graph, so read it with query /
search:
- Completed work carries the worker's
result inline, and its ack links back to
the original via a responds-to reply edge — follow those edges to collect answers to
the work you sent.
- Blocked work is a message marked blocked with the worker's
reason. You see
could-not-finish, not just successes — that visibility is the point.
Use query/search over the hive's message nodes to find done results and blocked items
with their reasons.
Re-dispatch is deliberate
A blocked item is terminal — the system does not auto-retry or recycle it. If you
want it done, you decide: fix the task and send it again, route it to a different role,
or drop it. Re-dispatch is an explicit act, never automatic.
What this skill does NOT do
- No heartbeat / lease renewal / checkpoint pings. The daemon owns liveness. The
worker only claims and reports.
- No retry logic. A blocked item is terminal and surfaced; the coordinator
re-dispatches deliberately.
- No broadcast or direct-to-name addressing. Work is routed to
@<role> or
@queue only.
- No server push. Pull only —
claim each loop tick.
- No fixed role taxonomy. Roles are whatever strings the user configures at join.
