@sjawhar/opencode-legion-envoy 6.4.1 → 6.5.0

package/skills/legion-architect/SKILL.md

@@ -23,7 +23,7 @@ separate coordinator to finish necessary work.
   product, scope, design, and cross-phase decisions the same way: `envoy_publish` to your own
   encoded token. You decide whether one needs the human and write its decision block yourself
   (section 1 says what one does to an approved root spec); a worker never writes one. Any role may
-  use `dispatch_ask` directly for a standalone to-do only a human can complete, and replies return
+  use `dispatch ask` directly for a standalone to-do only a human can complete, and replies return
   to the asking session.
 - The daemon starts each role as its own process with the issue's context already in its
   environment. Never hand-format a role token: the daemon encodes one as
@@ -33,7 +33,7 @@ separate coordinator to finish necessary work.
   the `roleToken` helper from `@legion/contracts` exactly the way the daemon does.
 - There is no label vocabulary. Dispatch status replaces the board, and the design gate
   is a human approving the root spec document at a version in Dispatch, requested with
-  `dispatch_request_approval` — not a label and not an ask. Never attempt to apply a label.
+  `dispatch request-approval` — not a label and not an ask. Never attempt to apply a label.
 - Deferring necessary work is failure. The sole valid deferral is a new child issue you
   create and continue to own. Re-file a genuinely independent child through the
   controller rather than treating it as an abandoned dependency.
@@ -59,35 +59,32 @@ exercise a criterion end to end, building that path is a child issue of this tre
 - **No children:** choose a single-issue tree only when its acceptance criteria can be
   completed and integrated as one unit. Otherwise create complete child issues with:
 
-  ```text
-  dispatch_issue({
-    project: "<project>",
-    parent: "<root issue>",
-    title: "<child outcome>",
-    spec: "<acceptance criteria, scope, and context>"
-  })
+  ```bash
+  dispatch issue --project <project> --parent <root issue> --title '<child outcome>' --spec-file - <<'EOF'
+  <acceptance criteria, scope, and context>
+  EOF
   ```
 
-  `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`) — not
+  `--project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`) — not
   the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string. A
   root session has `LEGION_TREE == LEGION_ISSUE`. The daemon establishes the sub-issue
-  relationship from `parent`. Keep the returned issue keys in ordered waves; a child is
-  inert until released. Do not pass `assignee`: the default keeps the tree's questions in one
+  relationship from `--parent`. Keep the returned issue keys in ordered waves; a child is
+  inert until released. Do not pass `--assignee`: the default keeps the tree's questions in one
   Inbox — under the shared token a child inherits its parent's assignee (the human who
   answers the tree's asks); under a personal token it goes to that token's owner, whom
-  `dispatch_whoami` names. Set it only when a human told you a specific person owns that child.
+  `dispatch whoami` names. Set it only when a human told you a specific person owns that child.
 
 Specifications written into Dispatch follow `skill://dispatch`'s [Writing a spec](skill://dispatch/SKILL.md#writing-a-spec).
 Wave releases, child closures, and your own status are visible from the issue tree and the
-handoffs; do not narrate them into the spec or a `dispatch_message`. A to-do only a human can
-clear is a `dispatch_ask`.
+handoffs; do not narrate them into the spec or a `dispatch message`. A to-do only a human can
+clear is a `dispatch ask`.
 
 The issue's primary document **is** the root specification. Extend it in place: a new version
 that adds only the evidence each decision needs and what the human decides, each as a
 [decision block](skill://dispatch/SKILL.md#decision-blocks). The decomposition and its waves, how each
 outcome is proven, and the integration test are your own calls: they go in the child issues and
 the planner's `.legion/<issue>/plan.json`, not the root spec. Never post a second "spec" artifact beside
-it (`dispatch_artifact` with the primary document's name replaces the human's document; do not do
+it (`dispatch artifact` with the primary document's name replaces the human's document; do not do
 that).
 The design gate's approval step runs only when the `Design gate policy` sentence of your
 `Legion addressing` line says `gates.design: root-issues`. When it says `gates.design: off`, write
@@ -97,47 +94,46 @@ sub-architect on a child issue has no policy line and never runs the gate: the r
 covers the tree. When the gate is armed, run this exact sequence **before the tree's work starts**:
 
 ```text
-dispatch_doc_edit({ issue: "<root issue>", ... })   // extend the primary document in place
-// then settle its decision blocks (below)
-result = dispatch_request_approval({
-  issue: "<root issue>",                             // the primary document by default
-  summary: "<what the human is approving>",
-})
+dispatch doc-edit --issue <root issue> --ops-json-file - <<'EOF'   # extend the primary document in place
+...
+EOF
+# then settle its decision blocks (below)
+dispatch request-approval --issue <root issue> --summary '<what the human is approving>'
+    # the primary document by default; prints "Approval requested for spec.md (document id <UUID>) at version <N> …"
 legion({
   op: "register_gate",
   issue: "<root issue>",
-  artifactId: result.details.artifact,   // the document id, a UUID such as 4e0aca36-77b3-43bd-96cf-d58890ae64e4
-  version: result.details.version,       // the version number the human is asked to approve
+  artifactId: "<UUID>",   // the document id from that text, such as 4e0aca36-77b3-43bd-96cf-d58890ae64e4
+  version: <N>,           // the version number the human is asked to approve
 })
 ```
 
 The decision blocks come first: settle every one as
 [Approval of a spec](skill://dispatch/SKILL.md#approval-of-a-spec) says before you request approval;
-`dispatch_request_approval` refuses while one is open. Each answer reaches you, since you follow
+`dispatch request-approval` refuses while one is open. Each answer reaches you, since you follow
 every ask you open. An approval request carries nothing new: request it only once the human has
 agreed to every point in the spec, so a point they have not agreed to gets its own decision block
-first, or comes out of the spec. `summary` says in one to three sentences what the human is
+first, or comes out of the spec. `--summary` says in one to three sentences what the human is
 approving and nothing else: no commentary and no open question.
 
-`dispatch_request_approval` opens a system question on the document with the fixed options
+`dispatch request-approval` opens a system question on the document with the fixed options
 `Approve` and `Request changes`; a human answers it from the Inbox or approves from the
-document's own header. Never open a `dispatch_ask` with an `Approve` option yourself: an
+document's own header. Never open a `dispatch ask` with an `Approve` option yourself: an
 ordinary question is not a gate and the daemon ignores its answer. Copy `artifactId` and
-`version` from the result of `dispatch_request_approval` — its text reads "Approval requested for
-spec.md (document id <UUID>) at version <N> (ask <id>)", followed by the question the human's
-Inbox shows, and its `details.artifact` / `details.version` carry the same two values. The
-document id is never the slug or file name you passed in (`spec`, `spec.md`): the daemon
+`version` from the text `dispatch request-approval` prints: "Approval requested for spec.md
+(document id <UUID>) at version <N> (ask <id>)", followed by the question the human's Inbox shows.
+The document id is never the slug or file name you passed in (`spec`, `spec.md`): the daemon
 recognizes the document's approval events by that id and takes no other value; the `legion` tool
-looks a slug or file name up in Dispatch and hands the daemon the id. Calling `dispatch_request_approval` again while that request
-waits on the human, with the same `summary`, changes nothing and returns it (its text says
-it "already waits on the human"), so it is safe to repeat; a different `summary` is refused then.
+looks a slug or file name up in Dispatch and hands the daemon the id. Calling `dispatch request-approval` again while that request
+waits on the human, with the same `--summary`, changes nothing and returns it (its text says
+it "already waits on the human"), so it is safe to repeat; a different `--summary` is refused then.
 A newer version of the spec moves the open request to that version and leaves it waiting on you,
 with no wake when the edit was yours: once the human has agreed to every point in it, call again
 to hand the same request back at the latest version. If its text instead reads "spec.md (document
 id <UUID>) is already approved at version <N>" — a human approved from the document header before
 you asked — still call `register_gate` with that id and version: the daemon reads the approval
 from Dispatch as it registers, opens the gate, and delivers `design-approved` at once. The same
-read covers a human who answers the question between your `dispatch_request_approval` and
+read covers a human who answers the question between your `dispatch request-approval` and
 `register_gate` calls, so an approval is never lost to timing; you never approve anything
 yourself.
 
@@ -196,7 +192,7 @@ The daemon moves each released child to `todo` and, while the root's design gate
 its phases itself from its fixed workflow table, each phase worker as its own process with the
 child's context already in its environment; it starts no sub-architect, and you start no worker.
 Park while children are in flight. On each child closure, re-scope open work, take obsolete work
-out of the workflow with `park_child` (saying why on the issue with `dispatch_comment`), and
+out of the workflow with `park_child` (saying why on the issue with `dispatch comment`), and
 release the next wave only when it now makes sense. There is no inter-child
 dependency mechanism to encode.
 
@@ -238,12 +234,12 @@ the task.
 Wait for the implementer to report its durable retro result. Retro output is
 `docs/solutions/`, its last commit removing the issue's `.legion/<issue>/` from the head a human
 merges, the PR body content the repository's instructions derive from the pull request's changed
-paths at that head, and one `dispatch_message` on the issue; it must write no handoff or
+paths at that head, and one `dispatch message` on the issue; it must write no handoff or
 rewrite the reviewer-approved head. When the implementer reports that it cannot
 compute that body content or do the work a line of it affirms, that its read of the body failed or
 came back empty, or that GitHub refused the body, it has pushed nothing and is still in its phase.
 Answer it with `envoy_publish` to its role topic, saying how from the deployment instructions;
-when they do not say, open a `dispatch_ask` naming the missing instruction.
+when they do not say, open a `dispatch ask` naming the missing instruction.
 
 ## 6. Architect sign-off and merge
 
@@ -276,7 +272,7 @@ The daemon keeps this order from its fixed table; you start none of its steps:
    It drives the changed path in production through the user's own access path and records
    what it saw on the pull request and on this issue. Sign off only after the implementer's production
    report exists. A defect it finds is a corrective child issue of this tree, not a note on a
-   closed one; if the implementer cannot perform the deploy, it opens a `dispatch_ask` that starts
+   closed one; if the implementer cannot perform the deploy, it opens a `dispatch ask` that starts
    with the production gap and why it matters, then names the required step, its risk, and
    outcome-named options. The issue waits for that answer.
 
@@ -299,12 +295,12 @@ This merge happens only when GitHub reports `CONFLICTING`
 wake — `phase-finished`, `catch-up`, `checks-red`, `review-stuck` — because a `CONFLICTING`
 PR gets no CI and no wake announces it. The moment you see it, tell the worker holding the issue's
 phase (`envoy_publish` to its role topic) to move the issue back to `implementing` with
-`request_backward_move`; in `awaiting_merge`, where no worker holds a phase, open a `dispatch_ask`
+`request_backward_move`; in `awaiting_merge`, where no worker holds a phase, open a `dispatch ask`
 naming the conflict for the human who merges. Do not let the merger send a READY packet for an
 obsolete approval.
 
 If a worker reports that `legion threads resolve` exited 1 naming a review thread GitHub refused
-to resolve, open a `dispatch_ask` that names the thread's URL and GitHub's message for a human to
+to resolve, open a `dispatch ask` that names the thread's URL and GitHub's message for a human to
 resolve it by hand, with options for resolved / could not; the merger does not complete while it
 is open. That is the one review-thread step a human takes: the review App cannot resolve a thread
 on a pull request the implementer opened, and the implementer's and merger's runs of the command
@@ -323,7 +319,9 @@ After the merge result and the implementer's production report are recorded, pos
 close this issue with `sign_off`, which writes `done`:
 
 ```text
-dispatch_comment({ issue: "LEGION-40", body: "<sign-off: scope, integration evidence, review, retro, merge, and the implementer's production report>" })
+dispatch comment --issue LEGION-40 --body-file - <<'EOF'
+<sign-off: scope, integration evidence, review, retro, merge, and the implementer's production report>
+EOF
 legion({ op: "sign_off", issue: "LEGION-40" })
 ```
 
@@ -346,10 +344,10 @@ active phase worker.
 | `design-approved` | Its `version` is the approved one. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
 | `design-changes-requested` | Its `version` and `reason`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec as the reason asks and request approval again as section 1 says; stay parked; the gate is closed. |
 | `phase-finished` | The daemon has already moved the issue to its next phase by its fixed table and started that phase's role; you start nothing. Read the committed handoff for the finishing phase; if it shows unresolved gaps, tell the role now working the issue (`envoy_publish` to its role topic). A `planner` notice that names a departure from the spec's design defers to section 1's full condition: when the approved Summary, Acceptance, scope and settled decisions still hold, the plan is the record; otherwise change the root spec and request approval again as section 1 says. A `reviewer` notice whose GitHub review is `CHANGES_REQUESTED` needs nothing from you: the daemon has returned the issue to `implementing` (Dispatch `in_progress`) and started the **implementer**, whose correction goes through the tester and the reviewer again, never straight to retro. A `reviewer` notice with an `APPROVED` review means the daemon has started retro (step 5). An `implementer` notice for `production_check` is its production report: read the record on the pull request and the issue, then run step 7. A `tester` notice with `verdict: "fail"` — its handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof — has gone back to the **implementer** by the daemon's table; never supply the proof from another role. A worker that reports no surface reaches the changed path sends that report instead of completing its phase, so the daemon starts nothing more on that issue and the worker stays idle in its session, not suspended: file a child issue in this tree to build the surface (infrastructure, tooling, or a skill), and when that child's `child-closed` arrives, tell the waiting worker to continue with `envoy_publish` to its role topic. That report is never a reason to advance the phase. |
-| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached. The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing: the issue stays in its phase, and only the worker holding that phase is running; an earlier phase's worker is suspended. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch_ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. |
+| `pr-blocked` | Its `reason` names the pull request and the `max_fix_attempts` it reached, or reads `Issue reached review_round_cap=<N>.` (the end of this row). The count is of heads pushed onto a red verdict that changed something outside `.legion/` — handoff-only pushes (`.legion/` paths only) never count, a push by the review App (a planner's, tester's, reviewer's or architect's) never counts, and the head after a red the tester's red tests earned (a review-App push that changed a path outside `.legion/`, however many handoff-only pushes follow it) does not count either — so after the tester's handoff-only push onto the implementer's red, the implementer's next push does count; a push the daemon cannot classify (a listener without `changed_paths`, a list the listener stopped at 100 paths or 32,768 runes of text, a push listing no commits) does. Published once per exhausted count, not on every later red verdict for that count. Read the failed CI evidence and recovery attempts. The notice moves nothing: the issue stays in its phase. In `implementing`, give the implementer the failing checks (`envoy_publish` to its role topic). In any later phase a worker holds, tell that worker (`envoy_publish` to its role topic) to move the issue back to `implementing` with `request_backward_move`, naming the failing checks, and the daemon starts the implementer; or file a corrective child. In `awaiting_merge`, where no worker holds a phase and a backward move is refused, open a `dispatch ask` naming the failing checks for the human who merges, as section 6 does for a conflict there. Do not treat the blocked PR as final. A `review_round_cap` reason is the implementer's round count instead: every move back to an earlier phase counts one, and the notice comes again with each round past the cap. It moves nothing either, since the round that reached the cap has already started its worker. Tell the rounds apart by what announced each: a tester's fail by its `phase-finished` with `verdict: "fail"`; a request for changes by the reviewer's `phase-finished` over a `CHANGES_REQUESTED` review; the daemon's own move by a `checks-red` notice, whose reason names either a conflict (`the head conflicts with <base>`) or the required checks that failed (`CI is red at <head>`); a worker's `request_backward_move` by a `phase-finished` from the role that asked, whose reason reaches only the task of the worker the move started, so ask that worker. Judge the cap by the rounds that are not conflicts. Conflict returns need nothing from you beyond the next round. Tester fails, requests for changes and CI-red returns (a `checks-red` notice is raised for CI only when a required check fails on code the branch pushed) are the work going in circles: narrow it, re-plan it with the responsible worker, or ask a human with `dispatch ask`. Judge a worker's backward move by the reason that worker gives. A move you ordered for a conflict found before `awaiting_merge` (section 6) is a conflict return. The merger's move back to `reviewing` because its task names no approved head is not the work going in circles either. A move that sends back code found wrong counts with the tester fails. |
 | `pr-merged` | Its `reason` names the pull request. The PR merged, under the repository's rules, before the issue reached `awaiting_merge`. The workflow runs on and asks no one to merge it: the daemon starts the **implementer** on the production check once the issue gets there, and you start nothing. Its `phase-finished` for `production_check` is what brings you to step 7: verify the record on the pull request and this issue first, then sign off naming it with `sign_off`. A merge is not the close. |
 | `pr-closed-unmerged` | Decide from current scope whether the work is reopened, started over (`park_child` then `rerun_child`, for a child), or ended with a reason. Delegate the repository action to the responsible phase worker and keep ownership. |
-| A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch_comment` with `reply_to`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `reply_to_ask` with `turn: "agent"`, since a default-turn reply hands that request back to the human and a corrected `summary` is then refused), then adjust the plan or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
+| A reply on an ask you follow | Interpret the reply in the issue's design context. Answer in its thread (`dispatch comment --reply-to <comment id>`; under an open ask whose next move is yours, such as the approval request you must revise or hand back, `--reply-to-ask <ask id> --turn agent`, since a default-turn reply hands that request back to the human and a corrected `--summary` is then refused), then adjust the plan or relay it via `envoy_publish` to the responsible worker's role token; scope and product decisions remain with you. |
 | `worker-died` | Its `role` and `phase`. That role's claim failed: its launches or prompts ran out. For a phase worker the daemon holds the issue (phase `held`) and starts nothing more on it. Reassess the work, then decide with `retry_or_escalate`: `retry` when the failure looks agent-specific or transient, `escalate` to hand the held issue to the controller when it looks environmental. |
 | `held` | Its `role` and `phase` (the phase the issue left), or `phase` with `reason: "escalated"`. Without `reason`, that phase's worker ran out of launches or prompts: the issue is held (phase `held`), the `worker-died` that comes with it is yours to answer with `retry_or_escalate` as that row says, and the controller hears of the hold too. With `reason: "escalated"`, it records your own `escalate`: the controller has the issue now, and you start nothing for it. |
 | `ready-refused` | Its `version` and `reason`. The merger's READY was refused, and its packet is kept with the completion so no second READY is ever needed. With `version` greater than 0, `reason` reads `READY refused: approve design version <N> before requesting READY.`: the root's spec is already registered at that version, so get it approved (section 1), and the daemon advances the merge and posts the kept packet the moment it is. With `version` 0, `reason` reads `READY refused: no design version is approved; register and approve the tree's spec before requesting READY.`: the root has no spec registered yet, so register it and get it approved (section 1) exactly as above; the daemon releases the kept packet the same way — at registration itself when that opens the gate (`gates.design: off`, or Dispatch already shows the version approved), otherwise the moment a human approves the version you registered. Either way, nothing else is needed once the gate opens. A `reason` starting `READY_PACKET_MISSING` names a READY refused before the daemon kept packets: that READY is void and the issue stays in merging, so start it over (`park_child` then `rerun_child`, for a child) or end it. |
@@ -361,14 +359,14 @@ cross-tree conflict. Report those to the controller with `envoy_publish` to the
 your `Legion addressing` line names. Handle everything else in the
 tree. A product, scope, or design decision that needs the human, yours or one a worker escalated,
 is a decision block you write (section 1 says what one does to the root spec's gate). A standalone
-human to-do may use `dispatch_ask`; workers may reach the human directly with it the same way. Do not
+human to-do may use `dispatch ask`; workers may reach the human directly with it the same way. Do not
 create a wait loop for any wake source.
 
 Never yield while waiting on a human. A human is waiting on you only where an open ask sits in
-their inbox, so open it before you stop: a decision block in the spec, `dispatch_ask` for a
-standalone human to-do, or `dispatch_request_approval` for the spec gate. Otherwise proceed:
+their inbox, so open it before you stop: a decision block in the spec, `dispatch ask` for a
+standalone human to-do, or `dispatch request-approval` for the spec gate. Otherwise proceed:
 proceeding is the default, and a stop that waits on nobody stalls the tree until someone notices.
 
 ## Architecture components
 
-Bootstrap on a root whose project has an architecture source: in the root's first PR (the implement worker pushes it), write `.dispatch/architecture/<id>.md` files for the planned components — front matter `title`, `parent`, `depends_on`, `external`; no `paths` yet. The importer reads the source branch's head, so the sync and the attach below work only once that PR has merged to the source branch: until then leave the root on `inherit` (the attach would answer `400 COMPONENTS_INPUT`, the component does not exist yet). After the merge, `dispatch_architecture_sync({ project })` and attach the root with `dispatch_issue_update({ issue, components: { mode: "explicit", ids: [...] } })`. Children inherit the root's attachment; give a child its own `components` only when it changes a narrower set, and `{ mode: "none", reason }` when it is not architectural work. Attach before decomposing, and require every implementer to change the component file beside the code it describes in the same review.
+Bootstrap on a root whose project has an architecture source: in the root's first PR (the implement worker pushes it), write `.dispatch/architecture/<id>.md` files for the planned components — front matter `title`, `parent`, `depends_on`, `external`; no `paths` yet. The importer reads the source branch's head, so the sync and the attach below work only once that PR has merged to the source branch: until then leave the root on `inherit` (the attach would answer `400 COMPONENTS_INPUT`, the component does not exist yet). After the merge, run `dispatch architecture-sync --project <KEY>` and attach the root with `dispatch issue-update --issue <root> --components-json '{"mode":"explicit","ids":[…]}'`. Children inherit the root's attachment; give a child its own `--components-json` only when it changes a narrower set, and `{"mode":"none","reason":"…"}` when it is not architectural work. Attach before decomposing, and require every implementer to change the component file beside the code it describes in the same review.

package/skills/legion-controller/SKILL.md

@@ -108,9 +108,9 @@ else:
    as the matching wake below. A parked tree (root phase `done`: it lingers or is closed) needs
    nothing from you: a failed architect ignores the park and reads `failed` until the tree closes.
 2. List the project's triage issues handed to Legion with
-   `dispatch_issues({project, status: "triage", label: "legion", limit: 250, offset: 0})`.
-   When its first line ends `(showing 1-250 of N)`, read the next page with `offset: 250`, and so
-   on until you have all N rows. The rows show no parent, so open each row with `dispatch_read`
+   `dispatch issues --project <PROJECT> --status triage --label legion --limit 250 --offset 0`.
+   When its first line ends `(showing 1-250 of N)`, read the next page with `--offset 250`, and so
+   on until you have all N rows. The rows show no parent, so open each row with `dispatch read`
    and follow `Links:` up through each `child_of` parent (a `child_of` under `Referenced by:` is a
    child of this issue, not its parent). Leave a child that has an ancestor in `admission.active`
    or `admission.waiting`: that tree's architect owns it. Triage every other row as a root,
@@ -137,8 +137,8 @@ only when you take it or file it for Legion, so the label means Legion has the i
 A person's label is their decision: never take it off. A child needs no label: it runs under its
 tree's architect once its root is admitted. `legion status <KEY> todo` admits a root, or a child
 outside a live tree (admitted as a root of its own), only while it carries the label, so an issue
-you hand over or file for Legion to run carries it first (`labels` in `dispatch_issue_update` or
-`dispatch_issue`). Taking the label off a waiting root drops it from the waiting line; taking it
+you hand over or file for Legion to run carries it first (`--label` on `dispatch issue-update` or
+`dispatch issue`). Taking the label off a waiting root drops it from the waiting line; taking it
 off an admitted tree does not stop it.
 
 ## Trees waiting on a root claim (Go daemon)
@@ -147,7 +147,7 @@ A Go root architect whose claim on its root issue was refused starts nothing and
 its slot, until the claim is free; nothing tells it when a session holder lets go without
 replying. So every turn rechecks them ([Turn discipline](#turn-discipline)), the daemon's `tick`
 included, which comes on its interval even with every slot taken: read each root in
-`admission.active` whose `issues.<KEY>.phase` is still `admitted` with `dispatch_read`. When its
+`admission.active` whose `issues.<KEY>.phase` is still `admitted` with `dispatch read`. When its
 `Claimed by:` line is `nobody` or ends `· not running`, tell that tree's architect to claim again
 with `envoy_publish` to `notifications.role.` followed by its claim token,
 `issues.<KEY>.architect.locator.claim` in `legion state --json`. A claim that is its architect's
@@ -199,16 +199,16 @@ only labelled roots, so every root it ran since the daemon required the label ca
 labelled root in `todo` is the daemon's to admit or queue, one in `triage` is yours to triage
 (step 2 above), and one anywhere else was parked by Legion or by a person. A child you take becomes
 a root of its own: the daemon admits a labelled `todo` child whose tree Legion does not run as a
-new tree. The `dispatch_issues` rows show no labels and no children, so the listing below filters
+new tree. The `dispatch issues` rows show no labels and no children, so the listing below filters
 neither: both are checked on each candidate (the table's first rows). List the `todo` issues one
-priority at a time, `priority: [0]` first, then `[1]`, `[2]`, `[3]`, and `[null]` (no priority)
+priority at a time, `--priority 0` first, then `1`, `2`, `3`, and `none` (no priority)
 last, keeping the listing's order within each, which is the board's rank:
 
 ```text
-dispatch_issues({ project: "<PROJECT>", status: "todo", priority: [0], limit: 250, offset: 0 })
+dispatch issues --project <PROJECT> --status todo --priority 0 --limit 250 --offset 0
 ```
 
-When the first line ends `(showing 1-250 of N)`, the next page is `offset: 250`, then `500`. Read
+When the first line ends `(showing 1-250 of N)`, the next page is `--offset 250`, then `500`. Read
 pages only as far as you need: stop listing once the free slots are filled. `<PROJECT>` is the
 Dispatch project key, the prefix of this deployment's issue keys (`PROJ-12` → `PROJ`), which is
 also `daemon.project` in `legion state --json`: the project key exactly as `legion.yaml` writes it.
@@ -217,14 +217,14 @@ the row shows one, comes after the claim) is claimed, as the table below says: s
 reading it.
 
 **Walk.** Take the remaining rows in that order until the free slots are filled. Read each one with
-`dispatch_read({ issue: "<KEY>" })` and skip it when any of these holds. `dispatch_read` shows only
+`dispatch read --issue <KEY>` and skip it when any of these holds. `dispatch read` shows only
 the issue's last 10 events, so the rows that read `Events:` are best-effort: the pull-request row
 leans on `External links:`, and the label row is the one that never depends on history.
 
 | Skip when | How you check it |
 |---|---|
 | It carries the `legion` label | `Labels:` lists `legion`, in any case. Legion has the issue or had it, as **Candidates** above says. |
-| It has any child | `dispatch_read({ ref: "dispatch://<KEY>/children" })` lists any child, open or `done`. It is an umbrella, and a finished umbrella is still no leaf. That also skips an issue whose only child is done, which is accepted. Its open children are candidates themselves, each in its own place in the order. |
+| It has any child | `dispatch read --ref dispatch://<KEY>/children` lists any child, open or `done`. It is an umbrella, and a finished umbrella is still no leaf. That also skips an issue whose only child is done, which is accepted. Its open children are candidates themselves, each in its own place in the order. |
 | An ancestor is Legion's | Follow `Links:` up through each `child_of` parent, reading each one, and skip when any ancestor carries the `legion` label or is recorded under `issues` in `legion state --json`, whatever its status: a Legion tree, running or parked, owns its children. An ancestor's claim or route does not skip the issue: a coordinator holding an umbrella files `todo` leaves for others to pick up, and the claim on the issue itself is what keeps two sessions off the same work. A `child_of` under `Referenced by:` is a child of this issue, not its parent. |
 | Someone is designing it | `Open asks:` lists any ask, a `Spec approval: awaiting …` line shows the spec waits on a human, or `Events:` show an `artifact.version` or an `ask.opened` from the last seven days: a session or a person is shaping it even when nobody claims or routes it. |
 | Legion ran it without the label now on it | `legion state --json` records it under `issues`, whatever its status, or `Events:` show a status write by `session legion-daemon:<PROJECT>`, the daemon's actor on every `legion status` (yours included) and on its own `in_progress` at admission. That covers a root a person took the label off, and one that ran before the daemon required the label and never had it. Name each one you skip for this in your summary. The walk never sends a root Legion already ran back into Legion: a person does that with the label and `todo`, and you do it only when a wake below says to (`worker-died`). |
@@ -232,15 +232,15 @@ leans on `External links:`, and the label row is the one that never depends on h
 | Its route reaches a running session | `Route:` names a route with nothing after it, or with `(held by …)`. `(nobody holds it right now)` and `(that session is not running right now)` reach nobody; `(the Envoy listener did not answer, …)` counts as reaching someone. `Route: none` is free. |
 | A pull request is linked or named | `External links:` lists a pull request (kind `github_pr`, or a URL ending `/pull/<n>`), or a comment or message among `Events:` names one. You cannot read GitHub, so an open, merged, or closed pull request all count. A person who wants Legion on it anyway hands it over themselves: the label, then `todo`. |
 | Its assignee is working it | `Assignee:` names a person who holds the claim (the row above), or whose own comment or message among `Events:` says they are working on it. The assignee alone is who answers the issue's questions, not who works it. |
-| It is outside this deployment's scope | Read the scope the deployment instructions state against the title and, when the title does not settle it, the spec (`dispatch_doc_read({ issue: "<KEY>" })`). When in doubt, skip it. With no scope stated, every issue of the project is in scope. |
+| It is outside this deployment's scope | Read the scope the deployment instructions state against the title and, when the title does not settle it, the spec (`dispatch doc-read --issue <KEY>`). When in doubt, skip it. With no scope stated, every issue of the project is in scope. |
 
 **Take.** For each candidate that passes, in order:
 
-1. Add the label and keep the labels it has, which `Labels:` lists (`none` is no labels). `labels`
-   replaces the whole set, so a label you leave out is removed.
+1. Add the label and keep the labels it has, which `Labels:` lists (`none` is no labels). The
+   `--label` flags replace the whole set, so a label you leave out is removed.
 
    ```text
-   dispatch_issue_update({ issue: "<KEY>", labels: ["<each current label>", "legion"] })
+   dispatch issue-update --issue <KEY> --label <each current label> --label legion
    ```
 
 2. It is already in `todo`, so the label admits it: the daemon records it and gives it the free
@@ -250,7 +250,9 @@ leans on `External links:`, and the label row is the one that never depends on h
    step 4 gives (which follows the design gate policy):
 
    ```text
-   dispatch_comment({ issue: "<KEY>", body: "Legion took this issue: it was the highest-priority open issue nobody else was working on. Assigned to <login>, who will get this tree's questions and its design approval. To stop Legion, move the issue to backlog. To keep Legion off it for good, also take the legion label off; taking the label off alone does not stop a tree that has started." })
+   dispatch comment --issue <KEY> --body-file - <<'EOF'
+   Legion took this issue: it was the highest-priority open issue nobody else was working on. Assigned to <login>, who will get this tree's questions and its design approval. To stop Legion, move the issue to backlog. To keep Legion off it for good, also take the legion label off; taking the label off alone does not stop a tree that has started.
+   EOF
    ```
 
 The daemon admits each root when Dispatch's event reaches it; the next `legion state --json`
@@ -264,28 +266,32 @@ change and why, and what is running.
 
 **Where.** On the issue the deployment instructions name for Legion's reports. With none named,
 on the project's `Legion daily report` issue:
-`dispatch_search({ query: "\"Legion daily report\"", project: "<PROJECT>" })` finds it. When it
+`dispatch search --query '"Legion daily report"' --project <PROJECT>` finds it. When it
 does not exist, create it once and park it in `icebox`, so nobody takes it as work; it never
 carries the `legion` label:
 
 ```text
-dispatch_issue({ project: "<PROJECT>", title: "Legion daily report", spec: "## Summary\n\nLegion's controller posts one message here each day: what Legion finished, what it closed without a change and why, and what is running. This issue is not work, so it carries no `legion` label and stays in icebox." })
+dispatch issue --project <PROJECT> --title 'Legion daily report' --spec-file - <<'EOF'
+## Summary
+
+Legion's controller posts one message here each day: what Legion finished, what it closed without a change and why, and what is running. This issue is not work, so it carries no `legion` label and stays in icebox.
+EOF
 legion status <report KEY> icebox
 ```
 
 **When.** On your first turn of each UTC day, whatever it is: your start, or a wake of any kind.
 While you are registered, the daemon's `tick` gives you a turn at least every
 `controller_wake_interval_seconds`. After the turn's own work, read the report issue with
-`dispatch_read`, and post when its `Events:` show no `message.created` from today.
+`dispatch read`, and post when its `Events:` show no `message.created` from today.
 
-**What.** One `dispatch_message({ issue: "<report KEY>", body })` of at most 2,000 characters,
+**What.** One `dispatch message --issue <report KEY> --body-file -` of at most 2,000 characters,
 written as `skill://dispatch`'s "Writing for the human" says: every issue by its key and title,
 every pull request by its URL.
 
-- **Finished.** `dispatch_issues({ project: "<PROJECT>", status: "done", updated_since: "<the
-  previous report's time, or 24 hours ago>", limit: 250 })`, read every page, and keep the issues
+- **Finished.** `dispatch issues --project <PROJECT> --status done --updated-since <the
+  previous report's time, or 24 hours ago> --limit 250`, read every page, and keep the issues
   `legion state --json` records under `issues` whose `issue.closed` event is after the previous
-  report. For each, `dispatch_read` it: the pull request under `External links:` is the one that
+  report. For each, `dispatch read` it: the pull request under `External links:` is the one that
   merged.
 - **Closed without a change.** Those with no pull request, each with the reason its closing
   message gave (the `message.created` just before `issue.closed` among `Events:`).
@@ -326,7 +332,7 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
   relevant Dispatch issue. A stale or duplicate wake may cost a read, never a wrong action.
 - **Controller state is disposable.** Do not reconstruct or preserve local controller
   bookkeeping between turns.
-- **Write for a human.** Every `dispatch_comment`, `dispatch_message`, and `dispatch_ask` you
+- **Write for a human.** Every `dispatch comment`, `dispatch message`, and `dispatch ask` you
   post follows `skill://dispatch`'s "Writing for the human" rules: plain sentences, every
   identifier expanded on first use, no coined shorthand. A triage note that reads like a log
   line is not a triage note.
@@ -339,7 +345,7 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 | `slot-free on <KEY>` from the Go daemon (payload `{kind: "slot-free"}`) | the root whose slot the daemon released with no waiting root to take it | Verify a free slot in `legion state --json`, then fill it ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `todo on <KEY>` from the Go daemon (payload `{kind: "todo"}`) | an issue not handed to Legion that changed while in `todo` and a slot stood free, sent half a minute later | Verify a free slot, then walk the whole `todo` list ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `tick on <PROJECT>` from the Go daemon (payload `{kind: "tick", openCapabilities?: [<name>, …]}`) | the project key; the daemon's periodic wake, whatever the slots; `openCapabilities` names the deployment capabilities with no decision, each with its detail and `capabilities.decided.<name>` line under `capabilities` in `legion state --json` | Recheck the trees waiting on a claim, then walk if a slot is free — a gap never stops the walk; post the day's report if this is the day's first turn, naming each open capability in it (the operator closes or decides it) |
-| Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; the owning architect writes an issue-design decision as a decision block and opens `dispatch_ask` only for a human to-do |
+| Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; the owning architect writes an issue-design decision as a decision block and opens `dispatch ask` only for a human to-do |
 | Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
 | `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `legion state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `legion status <root> backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
 | `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `legion state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`legion status <root> backlog`, then `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
@@ -347,7 +353,7 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 
 ## New issue triage
 
-1. Read `legion state --json`, then inspect the reported Dispatch issue with `dispatch_read`.
+1. Read `legion state --json`, then inspect the reported Dispatch issue with `dispatch read`.
    Verify the issue is in this project, is eligible for a root process, and whether it
    has pre-existing children. Dispatch and daemon state, not the wake text, decide triage.
    Note the `Assignee:` line: that human answers the tree's asks, and their Inbox opens on
@@ -371,7 +377,7 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
    place. A root never waits for capacity in `backlog`: in `todo` the
    daemon's admission queue holds it (`admission.waiting`), so park only a root that should not
    run now. Do not triage a system-created child as a root issue.
-4. When you post a triage note (a `dispatch_comment` on the issue saying what you decided and
+4. When you post a triage note (a `dispatch comment` on the issue saying what you decided and
    why), name who will be asked with the assignee sentence: `Assigned to <login>, who will get
    this tree's questions and its design approval`, or, when the `Assignee:` line says
    `unassigned`, `Unassigned — nobody's Inbox shows this tree's questions or its design approval
@@ -396,14 +402,14 @@ or when a wake tells you to re-admit it (`worker-died`).
 
 Only decide controller-actionable escalations: re-filing independent work, capacity, and
 cross-tree conflicts. The owning architect writes an issue-design decision as a decision block and
-uses `dispatch_ask` only for a human to-do, not the controller.
+uses `dispatch ask` only for a human to-do, not the controller.
 
 For an independence judgment, verify the child and its parent against current daemon state
 and the Dispatch issue. If the work belongs in an independent root:
 
-1. File a **fresh root issue** with `dispatch_issue({ project, title, spec })` (no `parent`;
-   add `labels: ["legion"]`, without which it is never admitted).
-   `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`): the
+1. File a **fresh root issue** with `dispatch issue --project <KEY> --title '<title>' --spec-file -`
+   (no `--parent`; add `--label legion`, without which it is never admitted).
+   `--project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`): the
    project key exactly as `legion.yaml` writes it, which `legion state --json` shows as
    `daemon.project`. It is not the lowercase project token in role names such as
    `legion-<project>-controller`.

package/skills/legion-retro/SKILL.md

@@ -36,7 +36,7 @@ retrospective's durable output.
    and records it on the PR and the issue: the agent that developed it is responsible for testing
    in production. The architect's sign-off waits for that record.
    The record is the pull request's `Production:` line, one pull-request comment, and a
-   `dispatch_message` on the issue, each naming what was driven, how, what was observed, and the
+   `dispatch message` on the issue, each naming what was driven, how, what was observed, and the
    merge commit. A defect the production check finds becomes a corrective child issue of the same tree,
    owned by the architect and implemented by the same implementer; the parent stays open until it lands.
 
@@ -157,16 +157,15 @@ Then push both commits with one `legion push`, so one CI run covers them. When t
 refused after step 4 wrote the body, write `<dir>/before.md` back the same way before you report
 the refusal to the architect, so the body matches the head GitHub has. After the push, post one
 Dispatch message on
-the issue — `issue` is your `LEGION_ISSUE`; Legion issues live on Dispatch, never on a GitHub
+the issue — `--issue` is your `LEGION_ISSUE`; Legion issues live on Dispatch, never on a GitHub
 issue, and the `gh` shim refuses every GitHub-issue write — naming the documents, the
 one-to-three most useful takeaways, the two proofs you read, and the production check that
 follows the merge. The message must carry this revived implementer's structured
 attribution footer with `phase` set to `retro`; the body is capped at 2,000 characters:
 
-```ts
-dispatch_message({
-  issue: "<KEY>",
-  body: `## Retro Complete
+```bash
+dispatch message --issue <KEY> --body-file - <<'EOF'
+## Retro Complete
 
 **Learnings documented in:**
 - docs/solutions/<path>.md
@@ -178,8 +177,8 @@ dispatch_message({
 
 **Production check:** <what the implementer will drive after the merge, or the deploy/restart step a human will have to perform first>
 
-<!-- legion: {"session":"<session-id>","phase":"retro"} -->`,
-})
+<!-- legion: {"session":"<session-id>","phase":"retro"} -->
+EOF
 ```
 
 The `docs/solutions/` commit, the removal of `.legion/<issue>/`, the PR body lines those commits

package/skills/legion-worker/SKILL.md

@@ -66,7 +66,7 @@ above), carrying the verified facts and the decision needed. A `write` to `agent
 agents inside your own process, not the architect's separate one. Never write a decision block
 into a spec yourself: the architect decides whether the human must answer it and writes the block,
 since a new version of an approved root spec closes the tree's design gate. A standalone to-do
-only a human can do is a `dispatch_ask`, and its replies return to your own session.
+only a human can do is a `dispatch ask`, and its replies return to your own session.
 
 Because the same agent works its role until the issue closes, you may receive more than one
 assignment across your lifetime: your session stays live after your phase ends, and when a later
@@ -228,7 +228,7 @@ subcommand's `comment`, `create`, `edit`, `close`, `reopen`, `delete`, `pin`, `u
 `lock`, `unlock`, and `develop`, and any raw `gh api` call to an `/issues` path whose method is not
 GET (an explicit `-X`, or the POST that `-f`/`-F`/`--input` imply; pull-request conversation
 comments live on that path too, so edit them with `gh pr comment`) — printing
-`Legion issues live on Dispatch; use dispatch_message or dispatch_comment on <your LEGION_ISSUE>`:
+``Legion issues live on Dispatch; use `dispatch message` or `dispatch comment` on <your LEGION_ISSUE>``:
 Legion never reads or writes a GitHub issue. `pr comment`, `pr review`,
 `api …/pulls/…`, `api graphql`, and issue reads are unaffected. The credential reaches `legion`
 through the file `$LEGION_GRANT_FILE` names, written by the extension before each of your bash
@@ -488,6 +488,6 @@ decision required.
 
 Never yield while blocked on a decision someone else owns. Before you stop, make the block visible
 where its owner will see it: a product, scope, design, lifecycle, or cross-phase decision goes to
-the owning architect as above, and a standalone human to-do goes in `dispatch_ask`. Otherwise
+the owning architect as above, and a standalone human to-do goes in `dispatch ask`. Otherwise
 proceed: proceeding is the default, and a phase that stops silently holds its issue until someone
 notices.

package/skills/legion-worker/references/merge-gate.md

@@ -96,7 +96,7 @@ review posted without a completion leaves the issue in reviewing until you finis
   `; ` on the one READY line, or `none` — quoted from the `## For the reviewer` block at that same
   head (or one line saying the body carries no brief — the packet still goes out), then the
   `--summary` output and the PR body's gate facts. The merger sends it as the `summary` of its
-  `handoff_complete` with `ready: true`; the daemon posts it as a `dispatch_message` on the issue,
+  `handoff_complete` with `ready: true`; the daemon posts it as a `dispatch message` on the issue,
   publishes it to the project's merge queue role when one is set, and says on the issue when that
   role has no live holder. The READY packet names both the implementer's and tester's `E2E` lines;
   a missing one is reported to the architect instead of completing. Legion never merges.
@@ -111,10 +111,10 @@ review posted without a completion leaves the issue in reviewing until you finis
   this, since a staging gate does not run every resource production does. If the slot fails on
   the change, the implementer owns the fix and the next slot.
   The record has three places: the PR body's `Production:` line, one pull-request comment
-  carrying the Legion footer, and a `dispatch_message` on the issue — the reviewer and merger
+  carrying the Legion footer, and a `dispatch message` on the issue — the reviewer and merger
   read GitHub, the architect reads the issue. When the deploy that carries the merge has not
   happened (a shared profile still holding the previous plugin release, a daemon still running
-  the previous commit, a slot nobody has run), open a `dispatch_ask` that starts with the
+  the previous commit, a slot nobody has run), open a `dispatch ask` that starts with the
   production gap and why it matters, then names the required install or restart step, its risk,
   and outcome-named options. Keep the `Production:` line at `pending <what is missing>`, and
   complete the check once the human answers. Never record a staging pass as the production check,