legate

name	legate
description	Use this skill when you need to reach another agent session — send a message to a named peer or "the pane on the right", check your inbox, wait for a reply, spawn or close a peer session, or dispatch work to fulfill a role and get a verdict back.

legate

The Legate — gateway skill for the Legion, the front door to agent session spawning, messaging, and dispatch. It classifies the request and either runs the matching cyberlegion CLI call directly or hands routing judgment to dispatch-governance. It is a thin classifier: it holds no production logic, loads no other governance, and writes no state of its own.

Version pin. Every invocation below reads npx cyberlegion@0.3.1 ... — a placeholder. The package is not yet published to npm (legion-publish is a later CR in the extraction); until then, resolve the CLI from a workspace checkout (packages/cyberlegion/bin/cyberlegion.mjs) or whatever pinned version the project has declared. Never invent a version number.

Doorbell vs mailbox

Two different primitives, never confused: a nudge (unit nudge <ref>) is a dumb doorbell — it rings a peer's pane and carries no content. The payload always lives in the mailbox (mail send, or the brief file unit spawn drops for a new unit) — a peer that receives a nudge reads its mail to learn why it was rung. Never encode meaning in a nudge itself; never skip the mailbox because a nudge already fired.

Classification map

User intent	Handling
Send a message to a named peer, "the pane on the right", a claude/cursor peer	npx cyberlegion@0.3.1 mail send --to <handle> (or unit nudge <ref> first if the peer needs waking, then mail send)
Check inbox / read unread mail	npx cyberlegion@0.3.1 mail inbox — mail read <msg-id> to peek, mail ack <msg-id> once handled
Spawn a new peer session	npx cyberlegion@0.3.1 unit spawn --agent <name> ... — cyberlegion owns worktree creation; pass --cwd <dir> only when the caller already has a directory to spawn into (e.g. reusing an existing worktree)
Close / tear down a peer session	npx cyberlegion@0.3.1 unit close <id>
Wait for a threaded reply	npx cyberlegion@0.3.1 mail await --thread <id>
Watch mail as it streams in (observer, never acks)	npx cyberlegion@0.3.1 mail watch
List addressable peers	npx cyberlegion@0.3.1 unit who
Sweep dead peers	npx cyberlegion@0.3.1 unit prune
Onboard / set up cyberlegion (register the surfacing hook, bind the main owner pane, first-run setup)	invoke the init-cyberlegion skill — the interactive onboarding front door over cyberlegion init / unit register --standing / attach
Diagnose the environment (harness, multiplexer, pane, hub root)	npx cyberlegion@0.3.1 mux doctor
Register the surfacing hook by hand (low-level, explicit harness)	npx cyberlegion@0.3.1 init --agent <harness> — the init-cyberlegion skill wraps this; use directly only when scripting a known harness
Dispatch work to fulfill a role with a brief and expect a verdict back (routing judgment needed — which strategy, which agent def, warm vs cold)	hand off to dispatch-governance — do not compose unit spawn/mail await/the Task tool yourself
No user channel at all (unattended trigger, multi-unit fan-out)	spawn the headless-legate agent by name — it realizes this same gateway + dispatch-governance flow headless

Load the handling skill in-session

For an attended session (a user or peer session holds this gateway), classify and act directly — spawn nothing. The one exception is a dispatch intent: routing which strategy to use (warm channel, cold subagent, or run-inline) is judgment this gateway does not carry — load dispatch-governance in-session and let it decide.

Headless (no user channel): spawn headless-legate. When this gateway is reached with no live user or peer channel to relay through — an unattended scheduler, a multi-unit fan-out — spawn the headless-legate agent by name. It is not a separate role: it is this same classify-then-route flow, realized headless, batching needs-input instead of asking live.

Boundaries

This skill never talks to the filesystem or another session directly — every mechanic is a cyberlegion CLI call. It never chooses a dispatch strategy itself (that is dispatch-governance's one job) and never invokes a harness's Task/subagent tool (that is the caller's own tool, used only inside dispatch-governance's subagent path via subagent-backend-governance).