autonomous-hive-agent-coordinator

name	autonomous-hive-agent-coordinator
description	Coordinate complex asynchronous multi-agent work with Honeybee `hive` and Pollinate. Use when Codex must plan, launch, ramp, monitor, message, collect, merge, stop, or recover many hive agents, from a few Claude/Codex/Grok bees to tens, hundreds, or thousands of sharded asynchronous agents, including Pollinate-triggered schedules/webhooks/polls and Hive flows/loops.

Autonomous Hive Agent Coordinator

Use this skill to act as the orchestration layer above Honeybee and Pollinate. Honeybee executes and observes agents; Pollinate fires triggers; the coordinator owns decomposition, routing, policy, quality gates, and merge judgment.

Coordination Model

1. Define the mission in external artifacts: task list, shard map, output schema, stop conditions, owner, and cleanup policy.
2. Prove the path with one bee. Then run a tiny swarm. Only then scale.
3. Use Hive for execution: sessions, swarms, frames, flows, loops, buz, seals, search.
4. Use Pollinate for activation: schedules, polls, webhooks, router bindings, batching/debouncing.
5. Treat seals and ledgers as the contract. Do not coordinate from screenshots or vague pane reads when structured output is possible.
6. Use dynamic workflow structure to prevent partial completion, self-review bias, and goal drift: isolate worker contexts, add verifier agents, and keep the control loop outside worker prompts.
7. Use native harness features through Hive when they fit. A Hive bee is still a Claude/Codex/OpenCode/Grok/Pi/Droid session, so prompts may invoke supported native features such as /goal, /loop, model modes, or built-in review/research tools. Verify per harness before relying on them.
8. Hold no fleet state in your head. Reconcile from ground truth every cycle, never from memory — context compaction silently drops the in-context bee list, so a coordinator that tracks bees mentally will lose them (spawn orphans, re-dispatch done shards, forget blocked bees). Spawning a child through hive from inside a bee now records the parent edge automatically, so hive fleet --json reconstructs your whole live tree straight from disk — every descendant with state (running/blocked/sealed/dead), idle time, and last seal. Read it at the top of every cycle, backstopped by your own assignments file for shard→bee intent, and act from that reconciled view.
9. Stay lean and route by cost. A coordinator that carries every worker's history re-reads a huge context each turn — cache-read tokens dominate the bill and it compacts sooner (which triggers rule 8's failure). Keep detail in worker seals and the assignments file, not your own transcript. Reserve the most capable (most expensive) model for cross-cutting judgment — decomposition, hazard detection, merge; run mechanical coordination (status sweeps, dispatch, kills) at lower effort or on a cheaper model. Verify with hive spend (see below), not by guessing.

Read references/orchestration-playbook.md for launch/ramp/monitor/stop patterns and references/scale-patterns.md for high-scale sharding and backpressure.

Launch Checklist

• Scope: write the work queue and shard boundaries.
• Output contract: define required seal fields, artifact paths, and status values.
• Harness mix: choose bee kinds and auth homes; reserve scarce profiles.
• CWD and permissions: set --cwd, node, yolo/approval policy, and tool limits.
• Backpressure: set max concurrent bees/jobs per harness/node.
• Stop: define success, timeout, max iterations, and kill/cleanup commands.
• Observability: record swarm ids, flow run ids, loop ids, Pollinate trigger/job ids.
• Budget: set max live bees, max token/tool budget when known, max retries, and any commands workers must avoid.

Primitive Selection

• Small one-off: hive run or hive x.
• One cohort, one assignment: hive spawn --count and hive send @swarm.
• Role split: hive frame define, hive spawn --frame --briefed.
• Programmatic fan-out/collect: TS hive flow.
• Repetitive queue work: hive loop start.
• External events/time: Pollinate trigger action to honeybee-flow, honeybee-loop, honeybee-spawn, or honeybee-send.
• Per-subject long-lived external thread: Pollinate router.
• Adversarial or taste work: generate/filter or tournament flow.
• Unknown amount of work: loop-until-done with mechanical stop conditions.

Ramp Pattern

# 1. State
hive ps --wide
pol status

# 2. Proof
hive run codex -p "Do shard 0 only. Seal JSON." --cwd "$PWD" --wait --last

# 3. Tiny swarm
hive spawn codex --count 3 --cwd "$PWD" --colony mission-x --swarm-id mission-x-proof
hive send @mission-x-proof "Take shard IDs 1-3 from shard-map.json. Seal one result each."

# 4. Scale via flow or repeated bounded batches
hive flow run mission-x-fanout --arg shardStart=4 --arg shardCount=50 --background

Only increase concurrency after outputs are valid and the monitor loop is working.

Coordination Contracts

• Every bee gets a unique shard and a clear finish condition.
• Every bee reports status through a seal or explicit queue message.
• Every shard has exactly one owner at a time.
• Merge agents do not modify worker artifacts in place; they produce a merge artifact.
• Review agents challenge merged output against raw seals.
• Coordinators pause or stop swarms when duplicate work, blocked state, or runaway retries appear.

Cost And Efficiency Observability

Honeybee prices every bee's token usage at API-equivalent list rates. Use the ledger to catch an inefficient coordinator before it burns a day of budget, and to justify the model mix:

hive spend usage --granularity day            # today's spend by model, all seats
hive spend usage --granularity month          # month-to-date, with a daily sparkline
hive spend session <coordinator-bee>          # one session: cost, model mix, caching
                                              # health, and a context-per-turn sparkline

Read the session drill-down as a diagnosis:

• cache-write/read high (>~10%) → prompt-prefix thrashing (tools/system/early context changing mid-run). Stabilize the prefix; this is the expensive failure mode.
• context/turn climbing toward the model's cap before it drops → the coordinator is hoarding context; cache-read cost scales with how high it climbs × turns spent there. Compact/checkpoint sooner or externalize state (rule 8).
• one costly model dominating on routine turns → route status sweeps, dispatch, and cleanup to a cheaper model/lower effort; keep the premium model for reasoning (rule 9).

A healthy long coordinator shows low cache-write/read (stable prefix) and a context trajectory that stays flat or saw-tooths (regular compaction), not one that ramps to the cap.

Pollinate Integration

Use Pollinate when work should start from time or events:

pol create nightly-research --source schedule --cron '0 2 * * *' --timezone Europe/Oslo \
  --cwd "$PWD" --delivery immediate --max-concurrent 1 \
  --action honeybee-flow --flow research-fanout --arg date='{{fired_at}}'

pol create event-swarm --source webhook --path mission/event --delivery debounced --quiet-period 2m \
  --cwd "$PWD" --action honeybee-flow --flow event-triage --arg event='{{batch}}'

Safety Rules

• Never jump directly to huge concurrency. Ramp from 1 to 3-10 to larger batches.
• Do not spawn thousands of live interactive tmux agents unless nodes, auth homes, API quotas, and cleanup are explicitly planned. Prefer Pollinate batches, Hive flows, loops, and queued shards.
• Cap per-node and per-harness concurrency; leave headroom for coordinator/reviewer agents.
• Use --background flows for durable work and save run ids.
• Use hive flow cancel, hive loop stop --now, and hive retire (archive — the everyday stop; keeps records revivable) as first-class rollback steps. Reserve hive kill --yes for a deliberate purge (it permanently deletes the record, seals, and run dir). After a substrate crash (tmux server died), recover the fleet with hive revive --crashed.
• Prefer queue/passive buz for async coordination; reserve interrupt for urgent control.
• Treat provider auth homes as capacity-limited resources.
• Use mechanical stop conditions before LLM judge conditions.
• Quarantine untrusted external content. Reader bees may process public input; action bees perform privileged operations only from sanitized summaries.

Output Contract

When using this skill, produce a concrete orchestration packet: shard plan, commands or flow/trigger definitions, ramp schedule, monitor commands, collection/merge contract, stop criteria, and cleanup/recovery commands.