@sjawhar/pi-envoy 0.0.0 → 8.1.0

package/dist/skills/dispatch/references/examples.md

@@ -0,0 +1,132 @@
+# Before and after: a decision block, a reply, a message, and a draft
+
+`skill://dispatch` sends you here for worked examples: a design decision in its document, a reply
+that names its mechanism, a message that should not be sent, and a draft placed where the human
+reads it.
+
+## Before / after
+
+Before — a wall of text hides the decision and the human never receives it:
+
+```text
+The deploy branch has the migration and dashboard changes. Staging is fine, but release notes are
+not reviewed before tomorrow's customer demo. Review the notes, ship without them, or cut the
+dashboard from the release. Waiting is safest, but the list above may be stale.
+```
+
+After — write the decision into the document section it concerns: state the problem, and make each
+genuinely different option a button, so the answer stays with the release design:
+
+```ts
+dispatch_doc_edit({
+  issue: "LEGION-815",
+  artifact: "spec",
+  ops: [{
+    op: "insert",
+    after: "Release requires reviewed operator instructions before deployment.",
+    markdown: `:::ask{#release-gate urgency="high"}
+Release notes are unreviewed, and tomorrow's customer demo means the release cannot wait for a later review. How should we proceed? Recommendation: review the notes, then ship, to keep the release complete and reviewed.
+
+- Review notes, then ship: Delays release for review but keeps the release complete and reviewed.
+- Ship now: Meets the demo deadline but leaves the release notes unreviewed.
+:::`,
+  }],
+})
+```
+
+Before — a progress note that nobody needs, posted where humans look for decisions:
+
+```ts
+dispatch_message({ issue: "LEGION-815", body: "Merged the release PR, moving to docs next." })
+```
+
+After — nothing. The merge is visible on the pull request; the docs work shows up as its own deliverable. Post a message only when
+a human must act or a deliverable is theirs to use:
+
+```ts
+dispatch_message({
+  issue: "LEGION-815",
+  body: "Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.",
+})
+```
+
+Before — a draft the human must read is uploaded as a separate file, the spec only names it, and
+the ask does not point at it, so the reader has to go looking:
+
+```ts
+dispatch_artifact({ issue: "OPS-52", name: "cu-update-2026-09-15.md", content: "Hi team, ..." })
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft (artifact cu-update-2026-09-15.md)" },
+]})
+dispatch_ask({
+  issue: "OPS-52",
+  question:
+    "Customers need an update today, but the draft is only in a separate file, so the reader cannot review it in context. How should we proceed? Recommendation: put the draft in the spec before sending it.",
+  options: [
+    { label: "Put the draft in the spec", description: "Adds a spec edit before sending but lets the reader review it in context." },
+    { label: "Keep the separate file", description: "Saves the spec edit but leaves the reader to find the draft." },
+  ],
+})
+```
+
+After — the draft is a section of the spec, and the ask anchors there. Sending it is a to-do only a
+human can complete, so it stays a standalone ask. If it really must be a file, the spec and the ask
+both link the slug from the upload result:
+
+```ts
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft\n\nHi team, ..." },
+]})
+dispatch_ask({
+  issue: "OPS-52",
+  question:
+    "Customers need an update today, and the reviewed text is ready in the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.",
+  options: [
+    { label: "Send the reviewed update", description: "Delivers the update today but makes its text external." },
+    { label: "Hold the update", description: "Avoids sending now but leaves customers without the update." },
+  ],
+  anchor: { artifact: "spec", quote: "Hi team," },
+})
+// or, for a real file — the spec links it where the reader needs it, and so does the ask:
+dispatch_doc_edit({ issue: "OPS-52", artifact: "spec", ops: [
+  { op: "insert", after: "## Context", markdown: "## Draft\n\nThe update to send: dispatch://OPS-52/artifact/cu-update-2026-09-15-md" },
+]})
+dispatch_ask({
+  issue: "OPS-52",
+  question:
+    "Customers need an update today, and its reviewed text is linked from the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.",
+  options: [
+    { label: "Send the reviewed update", description: "Delivers the linked update today but makes its text external." },
+    { label: "Hold the update", description: "Avoids sending now but leaves customers without the update." },
+  ],
+  ref: "dispatch://OPS-52/artifact/cu-update-2026-09-15-md",
+})
+```
+
+## Naming the mechanism
+
+Before — a reply explaining a design paraphrases its tool, its route and its event away, so the
+reader has to ask which tool, and how Legion "notices" anything:
+
+```text
+Today, when a spec is ready, the architect tells Legion so with a dedicated call on its Legion
+tool, and Legion then waits for your approval. This change removes that call, because Legion will
+notice your approval of the spec by itself.
+```
+
+After — the reader's sentence first, then each mechanism by its real name, with how it works in a
+clause:
+
+```text
+For you nothing changes: you still click Approve on the spec. What goes is a step the architect
+takes today: it calls `register_gate` on its `legion` tool, which posts to the daemon's
+`POST /legion/v1/gates/register` route and names the spec document and the version that gate the
+tree. The daemon opens the gate when Dispatch emits `artifact.approved` for that document at that
+version, which Dispatch does when you click Approve on the request the architect opened with
+`dispatch_request_approval`. Without `register_gate`, the daemon reads the issue's primary
+document from Dispatch itself and waits for the same event.
+```
+
+"A dedicated call", "tells" and "notice" each stood for something the reader can search for, find
+in a log, or set. None is a noun anyone coined, so each is named; the clause after each name is
+what keeps the reply readable on a phone.

package/dist/skills/dispatch/references/issues.md

@@ -0,0 +1,213 @@
+# Working an issue: choosing, claiming, status, priority, and the backlog
+
+`skill://dispatch` sends you here when you pick your next issue, claim or release one, get
+`409 ISSUE_CLAIMED`, move an issue's status or priority, reorder a board, reassign an issue, sync a
+project's architecture model, or list or audit a project's backlog.
+
+## Choosing what to work on
+
+When you finish an issue, or are told to work on the next thing, take the top ready issue of the
+whole backlog, across every project: status `todo`, highest priority first, then board rank. There
+are no areas: a standing role, a product owner and a lane each take the top issue like everyone
+else. `todo` means ready: specced, unblocked, and waiting on neither a deploy nor a
+decision. An issue that waits on one belongs in `backlog`, with what it waits on said on the issue.
+
+Hold at most three issues in flight (`in_progress`, `testing`, `needs_review` or `retro`), of any
+kind. The limit is per agent and has nothing to do with the week's priorities: the priorities
+decide only what you pull next. Past three:
+push any unfinished work, say where in one comment on the issue, move it to `backlog` and clear
+its route. Each issue counts on its own; a child does not ride under its parent's slot.
+In-flight issues with no owner at all go
+back to `backlog` as well: no claim or route held by a live session, no Dispatch activity in the
+last day, and no pull request moving on GitHub (an owner working there leaves no Dispatch trace).
+The order keeper sweeps those. Never write the status of an issue that carries the `legion`
+label, or of any issue under one: the Legion daemon writes those statuses. A status your session
+writes on the root of a tree Legion is running is set back and the tree's architect told who wrote
+it; only a person in the dashboard, or `legion status`, stops that tree. On an issue under one, a
+status that takes it out of the flow parks that issue and stops its workers.
+
+One agent keeps the backlog's order against those priorities. Setting an
+issue's priority stays yours ([Priority is yours to set](#priority-is-yours-to-set)); reordering
+the board does not.
+When the top of the backlog looks wrong, or a priority's next step is not yet a ready issue,
+publish it to `notifications.role.backlog-order`, which the order keeper holds, instead of
+reordering the board yourself.
+
+## Claim the issue before you work it
+
+Before you start implementing an issue, claim it:
+
+```ts
+dispatch_claim({ issue: "LEGION-234" })                  // I am implementing this
+dispatch_claim({ issue: "LEGION-234", release: true })   // I have stopped; it is free
+```
+
+A claim records **your** session — the one making the call, never another — and shows on every
+read of the issue: the dashboard header, the issue list and board, `dispatch_read` (a
+`Claimed by:` line) and `dispatch_issues` (a claim on the row). A session's claim there ends
+`· not running` when the live agent registry does not list that session, as the dashboard's chip
+does — that claim is free to take — and `· liveness unknown` when the registry could not be read,
+which says nothing either way. `dispatch_issues` plus the dashboard's **Unclaimed** filter is how
+you find work nobody is on.
+
+- **`409 ISSUE_CLAIMED` means someone else holds this issue.** When it is another session, the
+  refusal names it and says it is still running: do not work the issue in parallel — message
+  that session (its id is in the message; `envoy_send` reaches it) or pick up something else,
+  and tell the human if you believe the work should be yours. When a **human** holds it, the
+  refusal names the person and says nothing about a session running, because there is none to
+  message: ask them with `dispatch_ask` instead, so the open ask appears in their Inbox, and
+  never assume their claim has lapsed — only a human releases or forces a human's claim.
+- **`409 CLAIM_CONTENDED` means the issue changed hands twice while your call ran**, so nothing
+  was applied and nobody's liveness was checked. Read the issue and decide again; it is not a
+  refusal by a live holder.
+- **A claim whose session has ended is yours to take.** If the Envoy listener no longer lists
+  the holder, your claim simply succeeds; the takeover is recorded on the issue and the session
+  that lost it is told.
+- **Release it when you stop** — finished, handing over, or moving to something else. A claim is
+  released by its holder or any human — and by any agent once the holder's session is no longer
+  running, the same rule that lets you take it. Closing the issue releases it for you.
+- A claim is intent to implement, not contact: reading the issue, commenting, asking, or gating
+  its pull request claims nothing, so a coordinator never collides with an implementer.
+
+**Claiming and moving the status are two separate actions, and you do both.** A claim says which
+session is on the work; the status says where the work has got to, and humans use it to track
+that too. So when you start: `dispatch_claim({ issue })` **and**
+`dispatch_issue_update({ issue, status: "in_progress" })`.
+
+## Issue status is yours to move
+
+The issue's status is how a human sees delivery without asking a session. Outside Legion (where
+the daemon writes it), the session doing the work moves it, the way a person moves a card:
+`in_progress` when implementation starts, `testing` when the change is being proven on a
+production-like surface, `needs_review` when its pull request is open and waiting on the merge
+queue, `done` when the change has been driven in production (a merge is not `done`). Move child
+issues you own as well as the root. An issue left at `triage` while work is underway is a defect.
+Waiting for the deploy lane is not a status and is never announced.
+
+```ts
+// PATCH /api/v1/issues/{key} — status, title, labels, priority, external_links (merged by URL), route, parent
+dispatch_issue_update({ issue: "PROJ-175", status: "testing" })
+dispatch_issue_update({ issue: "PROJ-175", status: "done", reason: "Shipped in owner/repo#7; verified on the production dashboard." })
+dispatch_issue_update({ issue: "PROJ-175", priority: 1 }) // 0–3; see Priority is yours to set
+dispatch_issue_update({ issue: "PROJ-175", external_links: ["https://github.com/owner/repo/pull/7"] })
+dispatch_issue_update({ issue: "PROJ-175", parent: "PROJ-170" }) // same-project key; "" clears the parent
+```
+
+Closing takes a `reason`, and the tool refuses `status: "done"` without one: it posts the reason on
+the issue as a message, then closes it, because a closed issue refuses messages, comments, and
+artifacts, so a reason left for later has nowhere to go. When the close fails after the post, the
+error names the posted message; after a timeout or a server error it also says the close may have
+landed, so read the issue's status first. A retry points its reason at the posted message rather
+than repeating it.
+
+The two clears differ: `priority` clears with `null`, while `parent` and `route` clear with `""`.
+Guessing the other one is a refusal either way.
+
+Link the pull request that delivers the issue in `external_links` when you open it; the issue page
+renders its state and checks from that link, and `dispatch_read` lists it under `External links:`.
+The call is authenticated with the same bearer as every
+other `dispatch_*` tool: a Legion pane reads it from the `DISPATCH_TOKEN_FILE` path the daemon sets on
+the pane; an OMP session outside Legion reads `dispatch.token` from `~/.config/opencode/envoy.json`.
+
+A write to an issue still in `triage` answers once with `… is still in triage …`; move the status
+when work has started.
+
+## Priority is yours to set
+
+Priority is the coarse bucket a backlog is read by: `0` is P0, the highest, through `3`, P3, the
+lowest, and `null` clears it. Agents set it (`dispatch://LEGION/artifact/issue-status-conventions-md`)
+— on creation, and on a grooming pass over issues that have none — and say what you set and why;
+the human overrides anything they disagree with from the dashboard. A closed
+issue takes only `rank`, `components`, and a reopening `status` (any status but `done`);
+everything else, `priority` included, waits for the reopen (`409 ISSUE_CLOSED`). So reopen it
+first, then set the priority — the two cannot go in one call. `rank` itself is not a tool field:
+reorder it the way [Issue reads](#board-rank-priority-and-assignee-on-a-read) describes, through `PATCH /api/v1/issues/{key}`.
+
+## Board rank, priority, and assignee on a read
+
+Issue reads include `rank`, the server-owned ordering key used by project boards; reorder through `PATCH /api/v1/issues/{key}` with `{"rank": {"before": "<key>", "after": "<key>"}}`, either neighbor optional and both in the issue's project. A bearer caller also names its own session in that body, `"actor": {"kind": "session", "id": "<your session id>"}`, or the server refuses with `ACTOR_KIND`. They also include nullable coarse priority (`P0` highest through `P3` lowest) and `assignee`: the lowercase email of the person who answers the issue's asks, or `null` when nobody holds it. `dispatch_read` of an issue prints it as `Assignee: <email>` or `Assignee: unassigned`.
+
+## Reading a project's backlog
+
+To see the shape of a project rather than find a phrase, list its issues:
+```ts
+dispatch_issues({ project, status?, parent?, label?, priority?, route_status?, updated_since?, limit?, offset? })
+```
+Each row carries the issue key, title, status, priority, parent, labels, its open-ask count, and
+when it last changed — a roadmap or backlog pass without opening every issue. Filter with `status`
+(a lifecycle status), `parent` (one issue's children), `label`, `priority` (a list of `0`–`3`, with
+`null` for an issue with no priority: `[0, 1]` is every P0 and P1), `route_status` (below), or
+`updated_since` (an RFC3339 timestamp, for "what moved this week"). `limit` is the page size, 50 by
+default and 250 at most, and `offset` is where the page starts; the answer says how many issues
+match. Repeating with the next offset walks every matching issue only while the list does not
+change: an issue that enters or leaves what your filters match, or whose status or rank changes,
+between two pages shifts rows across a page boundary, and the walk then shows one issue twice and
+misses another.
+
+This is not search: it matches no text. Use `dispatch_search` for a keyword or phrase, and
+`dispatch_issues` when you want every issue in a project and its current state.
+
+### The owner audit
+
+As the owner of a surface, list the project's P0 and P1 issues and staff or close each one nobody
+has started:
+```ts
+dispatch_issues({ project, priority: [0, 1], limit: 250 })
+```
+Every unclaimed row in `triage`, `icebox`, `backlog` or `todo` is a decision: someone takes it and
+builds it, or it closes. A row in `in_progress`, `testing`, `needs_review` or `retro`, or one that
+carries a claim, is work under way ([Issue status is yours to move](#issue-status-is-yours-to-move))
+and is not re-staffed. A todo with a finished spec reads as queued work that nobody is doing.
+
+A close that says the defect cannot happen cites the code that makes it impossible. An issue
+closed because a rewrite forecloses it names the file and line in the rewrite that does so; a
+close that cannot name one is not foreclosed, it is unread. The cheapest way for a rewrite to reach
+parity is to port the code, defect included.
+
+The audit finds four shapes:
+
+- **Unstaffed work.** A plan or measurement exists, and no one is building it.
+- **Unrecorded delivery.** An issue not yet in `testing` or `done`, claimed or not, has a merged PR
+  naming it. Check the change live, then move the issue.
+- **Unrecorded practice.** Someone does the issue's work by hand, more than once, while the issue
+  sits in backlog. It leaves no plan and no PR to find; the tell is your own messages. Doing
+  something by hand more than once means an issue is wearing the wrong status.
+- **Unreachable route.** An open issue whose route names a role nobody holds, or a session that is
+  not running, reaches nobody, whatever its priority, and the priority filter above never finds
+  it. List it on its own:
+  ```ts
+  dispatch_issues({ project, route_status: "no_holder", limit: 250 })
+  ```
+  Each row reads `route role:sre (nobody holds it right now)` or `route session:<id> (that session
+  is not running right now)`. That is one read of the listener, and one read cannot tell a
+  restart gap from a vacancy: an agent box that restarts or resumes keeps the session id, but the
+  session is absent from the listener for minutes, and its role with it.
+  So a route is unowned only when it is `no_holder` on two reads at least ten minutes apart: list
+  again after ten minutes and act on the issues both lists name. Confirm with the second
+  `dispatch_issues` read, not `envoy_role_get`: a role lookup releases the claim of a holder whose
+  session is absent from the registry as it answers. Then staff the role, re-route the
+  issue to a live holder, or clear the route and assign it. `route_status: "unknown"` means the
+  listener did not answer, so a route could not be judged; a `no_holder` filter refuses rather
+  than answer an empty list then.
+
+Run the audit as a step of a coordinator's loop, at each checkpoint, not as a habit: these shapes
+are found by running the check, not by noticing them.
+
+## Search paging
+
+`skill://dispatch` sends you here when a `dispatch_search` page is not enough: more hits remain,
+or a kind runs out before the page does.
+
+A page holds `limit` hits (20 by default, 50 at most); the first line names how many match
+(`showing 1-20 of 312`), and, while more can be reached, the last line names the next `offset`.
+Each kind lists at most its best 100, so when the result says the rest cannot be paged to, narrow
+the query or name a `project`.
+
+## Syncing a project's architecture model
+
+Import a project's architecture model from its configured source repository now (a human configures the source in Settings):
+```ts
+dispatch_architecture_sync({ project: "CORE" })
+```
+It returns the imported commit, or the recorded error when the model was rejected — the previous model stays up. Without a configured source it answers 404 `SOURCE_NOT_FOUND`.
+

package/dist/skills/dispatch/references/messages.md

@@ -0,0 +1,74 @@
+# 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 dashboard calls a steer
+**Send**). 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 Oh My Pi's `agent://` messages. 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. On Oh My
+Pi, a person's **Send** or **Aside** arrives as their own user message, exactly as if they had
+typed it at your terminal: your Envoy plugin takes it only once Dispatch accepts it as a person's
+own fresh message to you, and injects the text Dispatch stored. Answer it in the conversation as
+you would anything typed, with no `dispatch_message`; the Agents page shows your conversation
+live, so they read your answer there.
+
+Everything else still arrives as a Dispatch frame: a **BTW**, a broadcast, a direct message on a
+host that takes no user turn from its plugin (Claude Code), and one Dispatch did not accept.
+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/dist/skills/dispatch/references/reading.md

@@ -0,0 +1,64 @@
+# 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.
+
+An anchored comment or ask also prints `Position:`, where its quote's block stands — `table[3] › row 5 (Red-teamer loop), column Due`
+is the fourth top-level block, a table, its row 5 (row 0 is the header; the index `delete_row` takes), labelled by the row's cells
+before the anchored one, in the column headed Due; outside a table it is the path of types and child indexes down to the block. The
+same facts are `anchor_block` on `GET /api/v1/comments/{id}` and `GET /api/v1/asks/{id}`, and
+`GET /api/v1/artifacts/{id}/blocks/{block_id}` answers them for any block id a document holds. When Dispatch could not read the
+document, the read still answers and prints `Position: unavailable (DOC_SERVICE_UNAVAILABLE)` (try again shortly),
+`Position: unavailable (DOC_SCHEMA)` (the document needs repair) or `Position: unavailable (INTERNAL)`; the API carries that
+code as `anchor_block_error`.
+
+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/dist/skills/dispatch-brainstorming/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: dispatch-brainstorming
+description: "Use in a session with Dispatch tools whenever a design conversation with a person starts: brainstorming or /brainstorming, \"let's design\", writing or changing a spec, writing an implementation plan, or a feature request or change that needs a person's choices. In a session with Dispatch it replaces superpowers' brainstorming and writing-plans; a Legion architect's own spec follows skill://legion-architect instead."
+---
+
+# Brainstorming in Dispatch
+
+This skill governs a design conversation with a person, never a Legion architect's own issue
+spec: an architect follows `skill://legion-architect` for that, even for a child issue.
+
+In a session with Dispatch, such a conversation happens in its issue's spec, and the plan that
+follows is a document on the same issue. This skill replaces superpowers' `brainstorming` and
+`writing-plans` there, even when the user invokes one of them by name:
+
+- No design question goes to chat. Every question is a decision block in the spec, and your reply
+  in chat links the issue and asks nothing.
+- There is no limit of one question per message. Every question that is ready goes out at once.
+- There is no approval after each section, only the one at the end.
+- A small change gets a short spec, never a design in chat: its size shortens the spec and changes
+  nothing about where the conversation happens.
+- No spec or plan file goes in the repository (`docs/superpowers/specs/`,
+  `docs/superpowers/plans/`, `docs/plans/`): the spec is the issue's primary document and the plan
+  is its `plan.md` document.
+
+The brainstorming stages still shape what you ask: clarifying questions, then two or three
+approaches with a recommendation, then the design section by section. A question that depends on
+no open answer goes out at once, whatever its stage.
+
+Read `skill://dispatch` before the first version: its "Writing a spec", "Decision blocks",
+"Writing for the human" and "Approval of a spec" sections define the spec's shape, each block's
+shape, and when approval is requested. A Legion phase worker never writes the spec; it sends a
+decision to its architect (`skill://legion-worker`).
+
+## Where the spec lives
+
+Search Dispatch first, as `skill://dispatch-first` says. When an issue already tracks the work, its
+primary document is the spec: extend it in place with `dispatch_doc_edit`, keeping the human's own
+text. Otherwise create the issue with its first version as `spec`, in the project a search hit
+already named or, when none does, the project the human names:
+
+```ts
+dispatch_issue({ project, title, spec })
+```
+
+No tool lists every project, so when nothing you found names one, ask the human in chat which
+project the issue belongs in before you create it — a filing question with nowhere else to land
+yet, not a design question, so it does not change "your reply in chat links the issue and asks
+nothing" for the design itself. Never read the project from the environment, a configuration file,
+or the Dispatch HTTP API: every read and write goes through a `dispatch_*` tool.
+
+Before the first version, read the code and documents the design touches, so the facts you write
+are ones you checked.
+
+## Each turn
+
+1. **Start with what is established.** The first version holds only what the conversation has
+   established: the problem and its evidence, what the human has said in their own words, the
+   facts the next questions need, and each question that is ready, as a decision block at the end
+   of the section that sets it up. Write nothing past those questions: no design, no defaults you
+   chose, no "what we will build", and no recommendation outside a decision block's own text. A
+   point the human has not stated, however obvious it seems (what a word in the request means, how
+   an edge case behaves, what a change does to an existing command), goes inside a decision block
+   or stays out. This is stricter than `skill://dispatch`'s general rule for an inferred point
+   elsewhere in a spec ("a point you inferred says so, with the reasoning"): in a live conversation
+   nothing is settled until the human has seen it, so even a flagged inference waits for its own
+   decision block.
+2. **The human answers or comments.** Reply to each human comment in its thread
+   (`dispatch_comment` with `reply_to`), then rewrite the passage the answer or the comment changes.
+   Under an open ask whose next move is yours, such as the approval request you must revise or
+   hand back, reply with `reply_to_ask` and `turn: "agent"` instead: a `reply_to` reply takes the
+   default turn, which hands the request back to the human unchanged, and a call with a corrected
+   `summary` is refused while it waits on them.
+3. **Each next version folds the answers in and adds what they open.** Keep each answered
+   decision block where it is, fold its answer into the surrounding text in the human's words with
+   the date, recording the person as `skill://dispatch`'s "Writing a spec" says for a settled
+   point. Then add the next sections, each with its question. Every question that is ready goes out
+   at once, each as a decision block at the end of the section that sets it up; a question waits
+   only when it depends on an answer still open.
+4. **A comment that answers a question settles it** as surely as the block does. Fold it into the
+   text at once, and close the block with `dispatch_resolve_ask` if the human has not.
+5. **Request approval at the end, not after each section.** Once nothing in the spec is new to the
+   human, request it exactly when "Approval of a spec" in `skill://dispatch` says: every decision
+   block settled and folded in, the human has agreed to every point in the spec, and the current
+   version is not yet approved (or waived, as that section's next paragraph covers). The request
+   carries nothing new, as that section also says.
+
+## Coming to terms
+
+The conversation comes to terms in both directions. Explain what the code does today, plainly
+enough for the human to react to and with each tool, event and route it uses named exactly (as
+"Writing for the human" in `skill://dispatch` says), and ask; the human's model comes out of those
+reactions, and so do corrections to it. Neither your model nor theirs is the starting truth.
+
+## The plan
+
+Once the spec is approved — or, when the issue needed no spec at all (a bug fix with no design
+decision), once you have enough to plan from — the implementation plan is the issue's `plan.md`
+document, never its spec and never a repository file:
+
+```ts
+dispatch_artifact({ issue, name: "plan.md", content })
+```
+
+Uploading `plan.md` again writes its next version. `writing-plans`'s content rules still apply in
+full — file structure, task right-sizing, bite-sized steps, no placeholders, the header, and its
+self-review — only where the plan lives changes: the issue's `plan.md`, never a repository file.
+Technical choices inside the approved design are made in the plan and need no question. A plan
+never changes a decision the human made in the spec: a change to one goes back to the spec as a
+decision block, with the evidence for it.
+
+Execution reads the plan the same way: `dispatch_doc_read({ issue, artifact: "plan.md" })` in place
+of opening a plan file, then follows `executing-plans` or `subagent-driven-development` as it would
+for a file on disk.