@sjawhar/opencode-legion-envoy 5.3.1 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/AGENTS.md

@@ -8,6 +8,7 @@ event intake, process lifecycle, credentials, and role delivery.
 | --- | --- | --- |
 | `ce-simplify-code/` | the implementer, once per pull request | the behaviour-preserving simplify pass before the reviewer's final pass (Legion's copy of the MIT-licensed Compound Engineering skill; `LICENSE` beside it) |
 | `dispatch/` | every role, and any session writing to Dispatch | specs, asks, comments, artifacts, and messages on native Dispatch |
+| `dispatch-brainstorming/` | any session with Dispatch that starts a design conversation or writes a plan, as `dispatch-first` directs | the design conversation in the issue's spec, turn by turn to one approval, and the plan as the issue's `plan.md`; in a session with Dispatch it replaces superpowers' `brainstorming` and `writing-plans` |
 | `dispatch-first/` | every session with Dispatch configured, injected by each host plugin on every request (Oh My Pi), on every `SessionStart` (startup, resume, clear, compact, fork) and `SubagentStart` (Claude Code), or as an instruction file (OpenCode) | searching Dispatch before acting, extending the existing issue, citing decisions, closing duplicates; kept under 60 lines and 6,000 characters |
 | `envoy/` | every role | subscriptions, agent-to-agent messages, and topic formats |
 | `legion-architect/` | root and sub-architects | tree ownership, decomposition, waves, gates, integration, sign-off |

package/skills/dispatch/SKILL.md

@@ -26,7 +26,6 @@ after `skill://dispatch/` is relative to this skill's base directory.
 | call `dispatch_doc_edit`: rewrite a paragraph, insert or move a block, change a table's cells, rows or columns | [Editing a document](skill://dispatch/references/document-edits.md) |
 | write a typed block (an `:::ask`, a callout), comment on or suggest a change to a document, upload an artifact, or retry after `DOC_SERVICE_UNAVAILABLE` | [Documents](skill://dispatch/references/documents.md) |
 | choose your next issue, claim one, move its status or priority, reorder a board, or audit a project's backlog | [Working an issue](skill://dispatch/references/issues.md) |
-| start or answer a design conversation in a spec: each turn, a comment that settles a question, coming to terms, a worked example | [Brainstorming in the spec](skill://dispatch/references/brainstorming.md) |
 | find who answers an ask, edit, retract or resolve one, reply with the turn, or follow a thread | [Asks after they open](skill://dispatch/references/asks.md) |
 | catch up after a restart, trace what cites a node, or write a `dispatch://` reference | [Reading back](skill://dispatch/references/reading.md) |
 | answer a BTW, Aside or Steer frame, or a message from the Agents page | [Targeted and direct messages](skill://dispatch/references/messages.md) |
@@ -36,17 +35,9 @@ after `skill://dispatch/` is relative to this skill's base directory.
 ## Design changes are brainstormed here
 
 When a session has Dispatch, a design change needing the human's choices is brainstormed in its
-issue's spec, not chat or a repository design document. The first version holds only established
-facts and every ready question, each 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. Each next version replies in each
-human comment's thread (`dispatch_comment` with `reply_to`; under an open ask whose next move is
-yours, such as an approval request you must revise or hand back, `reply_to_ask` with
-`turn: "agent"`, since a default-turn reply hands it back to the human), folds the answers into the
-surrounding text while their decision blocks stay, in the human's words (or the option they chose)
-with the date, and adds the questions they open. Approval is requested at the end, not after each
-section, when nothing in the spec is new to the human. Before you write a spec's first version, and
-again before each next turn, read [Brainstorming in the spec](skill://dispatch/references/brainstorming.md):
-each step, and a worked example.
+issue's spec, not chat or a repository design document, and its plan is the issue's `plan.md`
+document. `skill://dispatch-brainstorming` holds the process: read it before a spec's first
+version, before each next turn, and before you write a plan.
 
 ## Writing for the human
 
@@ -89,11 +80,14 @@ a new version that keeps the human's own text, never a second "spec" artifact be
 
 - **Each open question is a decision block**, shaped and placed as [Decision blocks](#decision-blocks)
   says. Because it is an ask, it reaches the human's Inbox, and the answer lands next to its context.
-- **A settled point records the human's own words and the date**, quoted, so no reader mistakes
+- **A settled point records the person's own words and the date**, quoted, so no reader mistakes
   it for your inference; an answer that is only a chosen option is recorded in the form
-  `Sami chose "Commit author" on the question below (2026-10-02)`. A point you inferred says so,
-  with the reasoning. One carried in from another document keeps its provenance: an agent's
-  inference there is marked one here, or stays out until the human raises it.
+  `<name> chose "Commit author" on the question below (<date>)`, naming them from `dispatch_whoami`
+  or the conversation, or "the person" when the token names no owner — never a name you were not
+  given. A point you inferred says so, with the reasoning; during a live brainstorming
+  conversation, `skill://dispatch-brainstorming` is stricter and keeps an inference out of the spec
+  until the human has agreed to it. One carried in from another document keeps its provenance: an
+  agent's inference there is marked one here, or stays out until the human raises it.
 - **Sections follow the topic.** No heading is required and none has a fixed place; name each
   section for what it discusses.
 - **A changed point is rewritten, not appended to.** When an answer or a new fact changes the

package/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.

package/skills/dispatch-first/SKILL.md

@@ -41,10 +41,14 @@ parent's children and the issue's `Components:` line show where the rest of that
   facts, the options and your recommendation in it, and link what you cite (`dispatch://…`)
   instead of writing "see above" or "my earlier message".
 
+## Design in the spec
+
+A design conversation with a person, or the implementation plan that follows one, uses
+`skill://dispatch-brainstorming`: read it before your first design question on a change, the spec,
+or that plan. It replaces superpowers' `brainstorming` and `writing-plans` here, even when the user
+invokes one by name. A Legion architect's own issue spec follows `skill://legion-architect`.
+
 ## Load the full skill before you write
 
-- **Before your first design question on a change, and before you write or change a spec, read
-  `skill://dispatch`,** including its "Writing a spec" section: a design change is brainstormed in
-  its issue's spec, not in chat, even when the brainstorming skill says otherwise.
-- 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.
+Before any 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-worker/references/merge-gate.md

@@ -46,12 +46,16 @@ takes this order: write, commit and push the handoff; submit the review of the h
 made, by its SHA; then complete. An approval waits for the CI verdict to settle green at that head
 before you submit it, since an approval stands only on green checks and GitHub can dismiss one
 once the head moves, and a verdict that settles red there makes the round's decision a request for
-changes naming the failing checks; a request for changes does not wait, since it stands whatever CI says and the
-issue leaves reviewing with it. A review of a head the handoff push then replaces names a head
-the pull request no longer has. A round that writes none (the final approval of the `.legion/`
-deletion head) reviews the head as it is. The daemon moves the issue once both are in —
-the decision GitHub reports and your completion, in either order — so a review posted without a
-completion leaves the issue in reviewing until you finish.
+changes naming the failing checks; a request for changes does not wait, since it stands whatever
+CI says and the issue leaves reviewing with it. The verdict is of the checks the base branch
+requires, the set READY checks: red when one of them failed, and never red for a check the base
+branch does not require. A required check that was cancelled, or that the head's checks settled
+without, leaves no verdict until a later settlement decides it, since a run can be cancelled or
+not yet queued when the head settles. A review of a head the handoff push
+then replaces names a head the pull request no longer has. A round that writes none (the final
+approval of the `.legion/` deletion head) reviews the head as it is. The daemon moves the issue
+once both are in — the decision GitHub reports and your completion, in either order — so a
+review posted without a completion leaves the issue in reviewing until you finish.
 
 ## Retro
 

package/skills/dispatch/references/brainstorming.md

@@ -1,53 +0,0 @@
-# Brainstorming in the spec: each turn, from the first version to approval
-
-This overrides the brainstorming skill's pace: no design question goes to chat, there is no limit
-of one question per message, and there is no approval after each section, only the one at the end.
-Its stages still shape what you ask (clarifying questions, then two or three approaches with a
-recommendation, then the design section by section), but a question that depends on no open answer
-goes out at once, whatever its stage.
-
-## 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, shaped as "Decision blocks" in `skill://dispatch` says. Write
-   nothing past those questions.
-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 (an answer that is only a chosen option as
-   `Sami chose "Commit author" on the question below (2026-10-02)`), 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, when nothing in the spec is new to the
-   human:** every block settled, every comment answered, and every point they have not agreed to,
-   however small, either put to them first as its own decision block or, when it is yours to
-   decide, taken out of the spec and made where the work happens. An inference you cannot defend in
-   a decision block comes out of the spec. The request carries nothing new ("Approval of a spec" in
-   `skill://dispatch`).
-
-## 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.
-
-## A worked example
-
-Take the spec for the secrets broker's identity model. Its first version
-held the problem, the human's words, what exists today, and the one question that was ready then;
-it also called itself "a conversation", which the human struck as commentary. Each later version
-folds the answers in with the human's words and date and adds the questions they open. Its first
-approval request, on the spec's version 35, named four inferences the human
-had never discussed; the human rejected it, and each of the four was then either put to the human
-as its own decision block or taken out of the spec.