@sjawhar/opencode-legion-envoy 3.13.0 → 3.15.0

package/skills/dispatch/references/messages.md

@@ -0,0 +1,65 @@
+# Answering targeted and direct messages
+
+`skill://dispatch` sends you here when a Dispatch frame targets you as BTW, Aside or Steer, or a
+human messages you directly from the Agents page.
+
+## Targeted agent messages
+
+A human — or any bearer caller over HTTP, such as a test rig — can target the issue message at a
+live Envoy session or role as **BTW**, **Aside**, or **Steer**. The incoming Dispatch frame names
+the issue and includes a `reply_with` hint (`{ tool, args }`, ready to issue on any host); reply on the same open issue with the existing
+tool, never a new targeted send:
+
+```ts
+dispatch_message({
+  issue: "CORE-1",
+  in_reply_to: "<targeted-message-id>",
+  body: "The requested answer.",
+})
+```
+
+`in_reply_to` correlates the answer under the asker's message in its Conversation card. A BTW
+delivery can post its answer automatically; use this call when the frame asks the primary agent to
+reply. A human may reply to your message in turn — the follow-up arrives as a targeted frame whose
+`in_reply_to` names your message and whose `reply_body` quotes it; answer it the same way,
+`dispatch_message({ issue, in_reply_to: "<their reply id>", body })`, so the exchange reads as one
+thread. `dispatch_message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
+through Envoy or the hub. A bearer that targets over HTTP names its own session in `actor`
+(`{kind: "session", id}`), and the card shows that session as the author. `GET /api/v1/agents`
+(any authenticated caller) lists live sessions with their capabilities (`aside`, `btw`, `steer`);
+target only a session that advertises the mode you want. Sending to a session with no issue
+(`POST /api/v1/agents/{session_id}/messages`) stays human-only.
+
+## Answering a direct message
+
+A human can also message you directly from the **Agents** page, with no issue at all. That frame
+names no issue and its `reply_with` hint carries none either; answer it with the message's bare
+id in `in_reply_to`, alone:
+
+```ts
+dispatch_message({
+  in_reply_to: "<the direct message's id>",
+  body: "The requested answer.",
+})
+```
+
+Leave `issue` out — there is no issue to post into, and naming one would file your answer on
+unrelated work. Dispatch threads the reply under their message in the same conversation, and the
+human sees it in your conversation on the Agents page, where it shows as an unread reply until
+they read it. Every other message still names its issue, so keep the `issue`
+the frame gave you whenever it gave you one; a `dispatch://KEY/message/<id>` reference names the
+issue its message lives on, so that form is a reply on that issue, not a direct message.
+
+Have more to say after you answered? Call it again with the same `in_reply_to` and the new text:
+Dispatch threads that follow-up under your first reply, and the tool result names the reply it
+follows. The same text again posts nothing, so a retry is safe. Your host may already have
+answered a **BTW** automatically before you got here; a second call is then your follow-up to
+that answer, so read the result before writing again.
+
+Read the whole conversation back — their message and every reply, yours included — with the
+message id alone; it has no issue:
+
+```ts
+dispatch_read({ message: "<the direct message's id, or any reply's>" })
+```
+

package/skills/dispatch/references/reading.md

@@ -0,0 +1,55 @@
+# Reading Dispatch back, and the reference forms
+
+`skill://dispatch` sends you here when you catch up after a restart, read an issue, ask, comment,
+message or document, trace what cites a node, or need the exact `dispatch://` form for a reference.
+
+## What comes back
+
+After a restart, catch up with:
+
+```ts
+dispatch_read({ issue?, project?, artifact?, ref? })
+```
+
+With an issue ref, it returns the issue summary, open asks, references, and recent events with `details` `{ issue }`. With a project
+document owner or ref, it returns a document summary with `details` `{ project, document }`. With an ask ref, it returns that ask's
+question, options, state, answer, and its reply thread. With a comment ref, it returns that comment and its quoted reply chain. With a
+message ref, it returns that message and its reply chain. Reads do not subscribe; use `dispatch_doc_read` for document contents.
+
+Every read ends with two sections from the reference graph. `Referenced by:` lists what points at the node — every document, ask,
+comment, or message that cites it, plus its structure: child issues, attached documents, anchored and owned asks and comments, replies,
+followers — and `Links:` lists what it cites. Each row is `- <edge kind> <node kind> dispatch://… (<excerpt> · <when>)`; for a
+document source the excerpt is the start of the block holding the mention, and a whole list is one block, so every issue named in
+one list previews the list's first item. When a document references many issues and each backlink should read right, give each
+issue its own paragraph (or block), not an item of one list. Cross-project, always: a message on another project's issue that
+cites an ask shows up under that ask. So "what led to this decision" is one `dispatch_read` on the ask, and "who relies on this
+document" one read on the document. Cite with `dispatch://` references (below) whenever you name a node in a body — a bare id or
+title is invisible to the graph.
+
+## Reference forms
+
+Use these in document, ask, comment, and message bodies. In the dashboard, a reference renders
+as an inline link whose text is the target's title (an issue's title, an ask's question, a
+comment's first line, a document's name) once it resolves; a body that is only a bare reference
+still gets an unfurl card instead. Every `ref` argument below (and `issue`/`project`) accepts
+either form — an issue key or a project key is never ambiguous, since a project key never
+contains a dash:
+
+```text
+dispatch://KEY
+dispatch://KEY/spec
+dispatch://KEY/artifact/<slug>[@vN]
+dispatch://KEY/ask/<id>
+dispatch://KEY/comment/<id>
+dispatch://KEY/message/<id>
+dispatch://PROJECT/artifact/<document-ref>[@vN]
+dispatch://PROJECT/artifact/<document-ref>/ask/<id>
+dispatch://PROJECT/artifact/<document-ref>/comment/<id>
+```
+
+A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records. `dispatch_read` also
+accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server (it maps to the
+`dispatch://` form above), and an ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
+full uuid. A non-uuid id on `GET /asks/{id}`, `/comments/{id}`, or `/issues/{key}/messages/{id}` is a 400 `ASK_ID_INPUT` /
+`COMMENT_ID_INPUT` / `MESSAGE_ID_INPUT`, never a 500.
+

package/skills/dispatch-first/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: dispatch-first
+description: "Use in any session with Dispatch tools, before planning, filing an issue, asking a human, posting a finding, or starting work that someone may already track or have decided."
+---
+
+# Dispatch first
+
+Dispatch already holds most of what you are about to plan, file or ask: the open issues, their
+specs, and the answers humans gave. A second issue for tracked work, or a question a human already
+answered, costs that human the time to notice it and splits the history across two places.
+
+## Search before you act
+
+Before you plan, file an issue, ask, post a finding or start work, search Dispatch. Every word of
+the query must match, so each word you add can only lose hits: search with two or three words, the
+thing and what is wrong with it, as a user would name them. Never paste a draft.
+
+```ts
+dispatch_search({ query: "broadcast send order" })
+dispatch_search({ query: "reviewer threads OR review comments" })
+```
+
+When a query finds nothing, drop a word before you add one. Try two or three wordings (the
+component's name, the symptom, the fix) before you conclude that nothing exists. Open every hit
+that could be yours with `dispatch_read`, then its parent (the `child_of` row under `Links:`); the
+parent's children and the issue's `Components:` line show where the rest of that work lives.
+
+## What to do with what you find
+
+- **The work is already tracked: extend that issue.** Put the finding on it (a comment, a message,
+  or an edit to its spec) instead of filing another. File a new issue only when no hit covers the
+  work, and cite the nearest one you ruled out (`dispatch://KEY`).
+- **The question is already decided: cite the decision.** An answered ask is the record. Point to
+  it where you rely on it (`dispatch://KEY/ask/<id>`) instead of asking again.
+- **You met a duplicate: close it.** Keep the issue that holds the spec and the discussion, carry
+  over anything only the duplicate has, then close the duplicate with a reason that names the
+  survivor: `dispatch_issue_update({ issue, status: "done", reason: "Duplicate of dispatch://KEY." })`.
+  When the duplicate carries the `legion` label, or another session or a human holds its claim,
+  comment on it naming the survivor instead of closing it.
+- **Every ask and message stands on its own.** The person who answers sees only that text: put the
+  facts, the options and your recommendation in it, and link what you cite (`dispatch://…`)
+  instead of writing "see above" or "my earlier message".
+
+## Load the full skill before you write
+
+- **Before you write or change a spec, read `skill://dispatch`,** including its "Writing a spec"
+  section.
+- Before any other write to Dispatch (an ask, a message, a comment, a document edit, a status
+  change, a claim), load `skill://dispatch` unless you already have in this session.

package/skills/legion-architect/SKILL.md

@@ -256,10 +256,10 @@ Preserve this order exactly:
 
 What returns the tree to review: a changed diff — a commit above the approved head that
 touches anything outside `docs/solutions/`, or a conflict-resolution merge whose fingerprint
-(`skill://legion-worker`'s unchanged-diff check) differs from the approved head's. What does not: retro's
+(the unchanged-diff check, `skill://legion-worker/references/conflicts-and-rewrites.md`) differs from the approved head's. What does not: retro's
 `docs/solutions/` commit, and a merge forced by a GitHub-reported conflict whose fingerprint
 is unchanged. For that merge the order is: the implementer merges the bookmark forward with the
-destination (`legion-worker`'s forward-merge procedure — `jj new legion/<KEY> <destination>`,
+destination (the forward-merge procedure in `skill://legion-worker/references/conflicts-and-rewrites.md` — `jj new legion/<KEY> <destination>`,
 never a rebase, since a rebase rewrites every descendant of the chain's fork point, including
 another tree's branch stacked on it), pushes it with the ordinary push procedure (a genuine
 fast-forward), and posts the before/after fingerprints; the tester re-runs the bare gates only;