hera

name

hera

description

Inside an argus sandbox (cwd under ~/.argus/worktrees/ or ARGUS_TASK_ID set), coordinate multi-agent work via hera's mcp__argus__hera_* tools — bootstrap an orchestrator, claim or attach a worker/freelance role, spawn workers, and message roles over the idle-gated bus. Load this skill when you are (or are becoming) a coordinator, when you're spawned as a hera worker, or before delegating work that must run as its OWN argus session (separate worktree / long-running agent / own PR / own sandbox) — as opposed to in-process Claude sub-agents, which stay the right tool for ephemeral in-session fan-out. For staged or dependency-ordered multi-worker plans, this skill routes you to the companion `hera-plan` skill. NOT for non-argus sessions, where these MCP tools are not registered.

Hera — native multi-agent coordination inside argus

Hera is argus's native, in-tree layer for running a team of agents. It is not a separate daemon or plugin — coordination runs in-process in the argus daemon, the rail/tree render directly in the TUI's second tab, and agents drive it entirely through the mcp__argus__hera_* MCP tools. State lives in the same ~/.argus/data.sql (the hera_* tables). You never touch the plumbing; you call the tools.

1. When this applies (and when it does NOT)

This skill applies only inside an argus task sandbox. You are in one if either holds:

• ARGUS_TASK_ID is set, or
• the current working directory is under ~/.argus/worktrees/.

If neither holds, stop. The mcp__argus__hera_* tools are not registered in this session — there is no CLI fallback and nothing below applies.

Every hera tool takes cwd — always pass cwd=$PWD. That is how hera resolves which argus task (and therefore which role) this session is. There is no separate "auth" or session handle.

2. The role model

• Orchestrator — a named coordination graph (one per project / feature / wave). Roles live under it. Created by hera_new_orchestrator (idempotent by name).
• Coordinator role — the orchestrator's driver. Created by hera_new_orchestrator. Talks to the human in its own agent pane; talks to other roles via hera_send. Folded into the rail's orchestrator header (it is not a separate row).
• Worker role — does the actual work. Normally born-bound: spawned by a coordinator with hera_spawn_worker, which creates the argus task (worktree + session) AND the role + binding in one transaction. A born-bound worker does not need to hera_join — its session opens already bound.
• Freelance role — a helper that attaches itself to an existing orchestrator on its own initiative (no coordinator spawned it). Created via hera_join attach mode with kind=freelance.
• Binding — the live link between this argus task and one role. Invariants:
  • One live binding per (task, orchestrator) — enforced by a partial unique index.
  • A task MAY hold several live bindings at once — one per orchestrator (e.g. a worker in A that promotes itself to coordinator of nested orchestrator B). When a task holds 2+ live bindings, you must pass orchestrator=<name> to every tool so hera knows which role you are acting as; omitting it returns an ambiguity error listing your options.

3. The coordination tools

All take cwd. orchestrator is optional with exactly one live binding and required with 2+. Arg names below are exact — do not invent others. These nine cover bootstrap, messaging, and status; the plan-DAG authoring/mutation tools live in the companion hera-plan skill (pointer at the end of this section).

Bootstrap / join

• hera_new_orchestrator(cwd, name, coordinator_role_name, [prompt]) — "I am the coordinator." Creates (or fetches, idempotent-by-name) the orchestrator, creates the named coordinator role, and binds this task to it. Returns the orchestrator name, role name, binding_id, and argus task id. Rejects if this task already holds a live binding under that orchestrator (use hera_join to retrieve it). The canonical "become an orchestrator" entry point — don't hera_join first; there is nothing to join yet.

• hera_join(cwd, [orchestrator], [role_name], [kind], [prompt], [status]) — two modes:

  • Claim mode (role_name omitted) — retrieves this task's existing live binding + role and its unread message count. Use right after a born-bound worker terminal opens to read your assigned role/mission. Pass orchestrator= if the task has 2+ bindings. Claim mode does not consume the inbox.
  • Attach mode (role_name + kind supplied) — creates a new role under an existing orchestrator (orchestrator required) and binds this task to it. kind must be worker or freelance (coordinator is rejected — use hera_new_orchestrator). Optional prompt (stored on the role) and status (idle/working/blocked/done). Use to join a team nobody spawned you into.

• hera_spawn_worker(cwd, prompt, [orchestrator], [role_name], [project], [branch], [backend], [model]) — spawn a new born-bound worker task + session under the caller's orchestrator. Caller must hold a live coordinator binding. Creates an argus task (worktree + session) and, transactionally, a worker role + binding pre-bound to it; an orientation prefix naming the coordinator + orchestrator is prepended to the prompt automatically. Args:

  • prompt (required) — the worker's MISSION/task only. The verbatim prompt is also stored on the role row and shown as the node's description in the plan-DAG view. Do NOT prepend the org/security policy — see the mission-only gotcha in §6.
  • project — defaults to the coordinator's own task project (authoritative, not role.ArgusProject).
  • branch — base branch passed to argus task creation. Defaults to the project default — see the base-branch gotcha in §6.
  • backend — defaults to project default.
  • model — per-worker model override, scoped to the worker's resolved backend (claude: opus/sonnet/ haiku; codex: e.g. gpt-5; pi: its ids). Empty = backend default. Match it to task complexity.
  • role_name — derived from a prompt slug if omitted; uniquified within the orchestrator.
  • orchestrator — disambiguates when the calling task holds multiple live coordinator bindings.

  Returns the orchestrator, worker role name, binding_id, argus task id, and project.

Messaging (idle-gated bus)

• hera_send(cwd, body, tldr, status, [to], [in_reply_to], [orchestrator]) — message another role in the same orchestrator. body and tldr are required; tldr is a one-line summary ≤120 chars, written from the recipient's perspective (see §5). status is REQUIRED for worker/freelance senders (one of idle/working/blocked/done/failed) and is applied to the sender's role synchronously before the message is sent — it is never delivered async. Omitting status as a worker/freelance sender is an error; coordinator senders may omit it. Worker/freelance senders may omit to — it default-routes to the orchestrator's coordinator. Coordinators must supply an explicit to. in_reply_to threads a reply to a prior message id. Returns the message_id, recipient, and delivery mode. Caps: 64 KiB body, 500 unread per recipient, 50 sends/min/sender. Cross-orchestrator messaging is not possible — to always resolves within your own orchestrator.

• hera_inbox(cwd, [orchestrator]) — fetch all unread messages addressed to your role, oldest first. Reading IS acknowledgment: this both cancels pending pane deliveries AND marks the messages read — no separate hera_mark_read needed for normal consumption. Call it whenever you get a doorbell.

• hera_mark_read(cwd, message_ids, [orchestrator]) — explicitly mark specific message ids read and cancel their pending deliveries. Use when you read via hera_get_messages instead of hera_inbox.

Status / tree

• hera_status(cwd, status, [orchestrator]) — set your role status: idle | working | blocked | done | failed. Mirrored (best-effort) to argus task_meta so the coordinator sees it without asking. A worker-kind role reporting status=done also rolls its bound argus task to in_review and stamps ready_to_close (visible in the rail) — see §4. A worker reporting status=failed rolls its task to in_review WITHOUT ready_to_close (needs-attention, not ready to check off). The gater treats a failed blocker as explicitly failed (no need to wait for session death). Coordinators/freelancers just update status.

• hera_tree_updates(cwd, [orchestrator], [since]) — scan the caller's orchestrator subtree (nested sub-orchestrators included) for messages since a cursor. Returns TLDR-only subject lines — no bodies (capped at 200), plus a next_cursor. The cursor is stored per-role and auto-advances when you omit since; passing an explicit since is a one-off scan that does NOT clobber the stored cursor. The token-efficient way to see whole-team activity without flooding context with bodies.

• hera_get_messages(cwd, ids, [orchestrator]) — fetch full message bodies by id list, after scanning hera_tree_updates. Access is scoped to the caller's orchestrator subtree (sender OR recipient must live in it); inaccessible / missing ids get a per-id error field rather than a top-level error.

Plan-DAG authoring (staged, dependency-ordered work) → the hera-plan skill

With a live coordinator binding, do NOT use the harness TaskCreate system-reminder for coordinated work — coordinate via the hera tools (hera_spawn_worker, or the plan-DAG), never bare task creation.

For work that decomposes into multiple hera worker units with dependencies among them (one stage needs another's output, or a required ordering), hera offers a plan-DAG: planned nodes wired by blocking edges that the daemon gater materializes into born-bound workers in dependency order, auto-stacking each stage's branch on the prior. It renders in the TUI's second tab and is a living graph (edit / re-point / cancel as work evolves).

Load the companion hera-plan skill before authoring or driving a plan-DAG. It carries the six plan tools (hera_plan, hera_plan_node, hera_block, hera_plan_node_update, hera_unblock, hera_plan_node_cancel), the gating contract (a node materializes ONLY when every blocker reaches role-status done), automatic branch-stacking and its fan-in footgun, short-id node naming, sub-coordinator nodes, and the self-guard prompt patterns — none of which the tool schemas convey. The decision triad in §4 tells you when the plan-DAG is the right tool versus spawning workers directly or using in-session sub-agents.

4. Decision rules

• Starting a coordination effort? hera_new_orchestrator. Don't hera_join first.
• A coordinator spawned you (fresh born-bound worker terminal)? hera_join(cwd) to read your role
  • mission, then hera_status(working). You are already bound — no attach needed.
• Joining a team that didn't spawn you? hera_join attach mode with explicit role_name + kind.
• new_orchestrator vs join: new_orchestrator makes you a coordinator of a new orchestrator; join claims/attaches a role under an existing one. A worker can do BOTH — stay a worker in the parent and hera_new_orchestrator to become a coordinator of a nested team (multi-binding).
• spawn_worker vs adopt: native hera has no adopt step — workers are born bound at spawn time. (The old depends_on-driven auto-adopt watcher was retired with the DAG.) To delegate, just hera_spawn_worker.
• The coordination decision — in-session sub-agents vs hera workers vs the plan-DAG (settle this BEFORE delegating):
  1. Ephemeral, in-session work — research, review, fan-out reads, anything that returns results to you and needs no worktree/PR of its own? → use Claude's native sub-agents (Agent/Task tool). NOT hera. Hera is overkill and slower for in-session parallelism.
  2. Work whose unit must be its OWN argus session — separate worktree / its own PR / long-running / its own sandbox? → hera. Then split by dependency:
     • Units have dependencies among them (one needs another's output, or a required ordering)? → plan-DAG: load the hera-plan skill, author planned nodes + blocking edges, let the gater run them in dependency order. Decide this yourself when the dependency is obvious — don't ask the human. Internal dependencies are the clean signal to plan a DAG rather than spawn ad hoc.
     • Units are independent (no ordering)? → just hera_spawn_worker them in parallel; no DAG.
  3. Ask the human only when it's genuinely ambiguous whether the work warrants multi-session orchestration at all — never for the routine dependency call above.
• This task holds 2+ bindings? Pass orchestrator= on EVERY tool call.
• Got a doorbell? Call hera_inbox(cwd=$PWD) immediately — the content is in the inbox, not the doorbell line.
• Want whole-team state? hera_tree_updates(cwd=$PWD), then hera_get_messages(ids=[…]) for the ones worth reading.
• How completion flows back: a worker finishing sends a closing hera_send(status="done", …) — the synchronous status apply rolls its task to in_review + ready_to_close, visible in the rail. A worker that cannot complete sends hera_send(status="failed", …) — rolls to in_review WITHOUT ready_to_close (needs attention, not ready to check off); the gater holds any dependent planned nodes and pings you. Both rolls are idempotent and only fire when the task is still in_progress. The live session is left running.
• Don't use hera_send to talk to the human — the human reads the coordinator's own agent pane; the bus is role-to-role only.

5. TLDR discipline

Every hera_send requires a tldr ≤120 chars, written from the recipient's perspective. It is shown in the doorbell, returned by hera_tree_updates, and stored permanently.

• Good: "PR #47 open, tests green, needs review" / "Blocked on missing API key — need rotation"
• Bad: "update" (says nothing) / "Done with the work" (no specifics) / multi-line.

6. Gotchas worth calling out

• hera_send requires status for worker/freelance senders — omitting it is an error. The status is applied synchronously before the send completes; it never rides the async delivery bus. This means every hera_send call doubles as a role-status heartbeat. There is no default; the error message on omission names the valid values (idle/working/blocked/done/failed).
• Spawned workers default to the project's stale default branch, NOT the coordinator's branch. hera_spawn_worker's branch defaults to the project default (e.g. an old master/main), not the coordinator's current worktree branch. If the worker must build on the coordinator's (or a sibling's) work, pass branch= explicitly and verify ancestry — otherwise the worker starts from stale code.
• Pass the MISSION only in hera_spawn_worker / hera_plan_node prompts — never prepend the org/security policy. A hera worker is a full argus session that receives its org instructions independently, via its OWN session's harness injection (an <organizationInstructions> block, verified present in every spawned session regardless of the parent). So a manually prepended copy is a redundant duplicate — and argus stores the prompt verbatim on the role and renders its opening lines as the node's description in the plan-DAG, so a prepended policy pollutes the DAG (every node reads the boilerplate instead of its mission). Write the prompt as exactly the message you want the worker to act on.
• Bake all requirements into the initial hera_spawn_worker prompt. Mid-flight hera_send to a worker is often missed: delivery is idle-gated and best-effort, so a busy worker never receives it and an idle/finished worker may not act on it. Put the full spec in the spawn prompt; verify via the branch diff and re-dispatch a fresh worker if one idled out without the requirement.
• The message bus is idle-gated and best-effort for delivery, durable for storage. Storage always succeeds (the row is committed); live pane delivery soft-fails (logged, never rolled back) when the recipient has no live binding or never becomes idle. hera_inbox always returns the durable rows, so the recipient can always catch up by reading — don't assume a sent message was seen just because it sent.
• worker done must keep the role messageable. Native deliberately does NOT auto-archive a role on hera_status(done) (the external plugin did). An archived role drops out of name-keyed recipient resolution, so auto-archiving a still-live worker would make the coordinator's hera_send to it bounce. Done flips the task to in_review; it does not archive the role.
• Coordinators must name a recipient. hera_send from a coordinator with to omitted errors — only worker/freelance senders get the default-to-coordinator routing.

7. Worked workflows

(a) Bootstrap an orchestrator, spawn two workers, collect results

You are a coordinator-to-be in your argus sandbox:

1. hera_new_orchestrator(cwd=$PWD, name="checkout-revamp", coordinator_role_name="coord", prompt="Coordinate the checkout revamp").
2. Spawn workers, each with the FULL spec baked in and an explicit base branch:
   • hera_spawn_worker(cwd=$PWD, role_name="cart-api", branch="argus/<base>", prompt="<complete cart-API spec…>")
   • hera_spawn_worker(cwd=$PWD, role_name="checkout-ui", branch="argus/<base>", prompt="<complete checkout-UI spec…>")
3. Poll progress without flooding context: hera_tree_updates(cwd=$PWD) → scan TLDRs → hera_get_messages(cwd=$PWD, ids=[…]) for the interesting ones.
4. When a worker reports done (its task rolls to in_review + ready_to_close in the rail), review its branch/PR, then reply or spawn the next stage. To stack work, branch the next worker off the prior worker's branch via branch=.

(b) A spawned worker reports completion

You opened in a born-bound worker terminal:

1. hera_join(cwd=$PWD) → read your role name, mission (role prompt), and unread count.
2. hera_status(cwd=$PWD, status="working").
3. Do the work in your worktree. If you hit a fork that needs the coordinator's call: hera_send(cwd=$PWD, status="working", body="<question + context>", tldr="Need decision: X vs Y for the cart schema") (no to needed — default-routes to the coordinator), then check hera_inbox(cwd=$PWD) on the doorbell for the answer. Always supply status on every hera_send — it is required for worker/freelance senders.
4. Land your work (open a PR via iris, or leave commits for the coordinator to pull).
5. hera_send(cwd=$PWD, status="done", body="<summary + PR link>", tldr="cart-api done, PR #47, tests green") — the synchronous status apply rolls your task to in_review + ready_to_close so the coordinator sees you finished. If you cannot complete: hera_send(cwd=$PWD, status="failed", body="<reason>", …).

(c) Author a staged plan-DAG

When the work decomposes into multiple multi-session units with dependencies among them, load the hera-plan skill and author a plan-DAG — it carries the tools, gating, branch-stacking, naming, and a full worked seed→fan-out→fan-in example. The §4 decision triad tells you when that's the right tool.

Worker promotion: becoming a sub-coordinator

If you already know up front (at plan-authoring time) that a stage is a sub-team, prefer the declarative form: a kind=subcoord plan node (see the hera-plan skill). The gater then materializes the sub-coordinator for you when its blockers finish. The runtime promotion below is for when a worker discovers the need mid-task.

If a worker realizes mid-task it needs its own team (cross-repo work, real parallelism, a long sub-task):

1. hera_new_orchestrator(cwd=$PWD, name="<sub-team>", coordinator_role_name="coord", prompt="…") — now this session is a coordinator of a nested orchestrator AND still a worker in the parent (multi-binding; pass orchestrator= on subsequent calls).
2. hera_spawn_worker(...) to dispatch into the right project.
3. Report the sub-orchestrator name back to the parent coordinator via hera_send. Prefer using Claude's native sub-agents for in-session parallelism; reserve hera_spawn_worker for work where the session itself (separate worktree / repo / sandbox) is the unit.

8. Composition with sibling argus tools

Hera owns identity, messaging, and coordination — nothing else. Reach the rest through their own MCP tools:

• iris (mcp__argus__iris_*) — host-side git/gh. A worker codes + commits locally in its worktree, then uses iris to push / open a PR / merge back. Use iris_gh_pr_create rather than gh pr create so the PR is stamped onto the task's pr meta namespace — that is what the Hera rail's PR indicator reads (best-effort, never fetched by the view).
• plannotator-argus (mcp__argus__plannotator_*) — review UI. A coordinator routes a worker's output to review there; hera carries the decision and the handoff message, plannotator carries the review surface.

These are orthogonal — hera does not wrap them and they do not wrap hera. Pick per op: iris when an action touches the host, plannotator when it's a review surface, hera when it's about roles or messaging.