@sjawhar/opencode-legion-envoy 9.3.0 → 9.5.0

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -18,15 +18,15 @@ Dispatch is a record for the people who decide, never a log of your work.
 
 ```md
 :::ask{urgency="med"}
-The problem and why it matters. Recommendation: the option and its reason.
+Which machines, files or people, the numbers, then "A happens to X, or B to Y?" Recommendation: the option and its reason.
 
 - Option one: what it costs.
 - Option two: what it costs.
 :::
 ```
 
-- A to-do or permission only a person can give, or a decision with no document, is a `dispatch ask`. A Legion phase worker sends its decision to its architect.
-- In Legion, file no issue for an outside finding. Fix a clear defect in code your tree uses. Hand others to the controller. Ask about decisions (`skill://legion-worker/references/findings.md`).
+- A to-do or permission only a person can give, or a decision with no document, is a `dispatch ask`.
+- In Legion, fix a clear defect in code your tree uses, hand others to the controller, and ask about decisions (`skill://legion-worker/references/findings.md`).
 - An open ask is the request. Do not raise it again in each message.
 - Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
 - Answer a person's reply to an open ask with `dispatch comment --reply-to-ask`; `--turn agent` for a note that needs nothing from them.
@@ -54,7 +54,7 @@ A claim delivers no comments: that turn, `dispatch issue-update --route session:
 
 ## Structure over stream
 
-- One issue per deliverable, its content the issue's document. Decisions are asks. A message only announces.
+- One issue per deliverable, its content the issue's document. Decisions are asks.
 - A message replies to a person or tells them what they must know now.
 - Text a person must read to decide belongs in the spec. An artifact is a real file.
 

package/skills/dispatch-first/SKILL.md

@@ -27,7 +27,7 @@ dispatch search --query 'reviewer threads OR review comments'
 - **Work already tracked:** put the finding on that issue. File a new issue only when no hit covers the work, and cite the nearest one you ruled out (`dispatch://KEY`).
 - **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`). Do not ask again.
 - **Duplicate found:** keep the issue with the spec, copy to it what only the duplicate has, and close the duplicate (`--status done --reason 'Duplicate of dispatch://KEY.'`). When it has the `legion` label or another holder's claim, comment the kept issue's name on it instead.
-- **Each ask and message stands alone:** the reader sees only that text. Put the facts, options and your recommendation in it.
+- **Each ask and message stands alone:** the reader sees only that text. Name the concrete case (which machines, files, people, numbers), ask the choice in its terms, and recommend.
 - In Legion, file no finding outside your issue (`skill://legion-worker/references/findings.md`).
 
 ## Reach a person only through Dispatch
@@ -42,6 +42,6 @@ A person does not watch your chat. Reach them through an ask, an ask block or an
 | Before you | Read |
 | --- | --- |
 | run your first `dispatch` command in this session | `skill://dispatch` |
-| write or change a spec, or write an ask, comment or message a person reads | `skill://dispatch-writing-specs` (in a session with Dispatch it replaces superpowers' `brainstorming`) |
+| write or change a spec, or write an ask, comment or message a person reads | `skill://dispatch-writing-specs` |
 | plan work whose spec a person approved | superpowers' `writing-plans`, stored as the issue's `plan.md` (`skill://dispatch-writing-specs`, "The plan") |
 | write a Legion architect's own spec | `skill://legion-architect` too |

package/skills/dispatch-writing-specs/SKILL.md

@@ -7,7 +7,7 @@ description: "Use in a session with Dispatch before you write or change a spec,
 
 ## The aim
 
-Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes no spec: it sends decisions to its architect (`skill://legion-worker`).
+Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes no spec (`skill://legion-worker`).
 
 ## The outline
 
@@ -32,19 +32,19 @@ For each spec, ask, comment and message:
 - Write in `skill://asd-ste100`'s strict mode.
 - State the current design, never how people reached it.
 - Link each source where the person wrote it: `dispatch://KEY/comment/<id>`, `/ask/<id>`, `/message/<id>`, or a Slack URL. With no link, state the design.
-- Write about the design, never the person. Never quote people, repeat an answered ask, or upload their words.
+- Write about the design, never the person. Never quote people or upload their words.
 - Name your session only if a reader must reach it.
 - Keep only text that helps a reader understand, decide, build, check.
-- Explain each name or term a new reader may not know. Name an issue by its `dispatch://` link, and say in a clause what it does for this reader. Never write a bare key.
+- Explain each name or term a new reader may not know. Name an issue by its `dispatch://` link, and say in a clause what it does for this reader.
 - In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
 
 ## Questions
 
+- Name the concrete case first: which machines, files, sessions or people, and the numbers. Then ask the choice in those terms, never "Which option?": a reader cannot work back from a general question to the case.
 - Propose an answer to each point, numbers included, with a reason.
 - A choice inside what the person asked for, or one their messages favour, is settled: decide it.
 - Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
-- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks) at the end of its section: 2 to 4 options with costs, your recommendation, answerable on a phone.
-- Chat reaches nobody: use an ask or approval request.
+- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options with costs, your recommendation, answerable on a phone.
 
 ## Each version
 

package/skills/legion-architect/references/decomposition.md

@@ -27,10 +27,18 @@ child waits in your tree until Legion starts it.
 
 ```bash
 dispatch issue --project <project> --parent <root issue> --title '<child outcome>' --spec-file - <<'EOF'
-<acceptance criteria, scope, and context>
+<the child's spec, written as skill://dispatch-writing-specs says, scaled to the child>
 EOF
 ```
 
+- Write each child's spec as `skill://dispatch-writing-specs` says, scaled to the child: its
+  outline (`Summary` through `Acceptance`, a few sentences a part for a small child), a proposed
+  answer to each point, each term a new reader may not know explained, no item number from another
+  document (name a requirement of the root by what it says), and no text copied from the root that
+  does not apply to this child. The child's workers read only this spec.
+- Before `dispatch issue` creates each child, paste its whole spec into a fresh
+  `task(agent="plan-gap-analyst")` to check it against `skill://dispatch-writing-specs`, and fix
+  what it flags: your own reread misses the terms and item numbers you already know.
 - `--project` is the issue key's prefix before `-<n>` (`LEGSMOKE-3` → `LEGSMOKE`).
 - In a root session `$LEGION_ISSUE` is the root (it equals `$LEGION_TREE`): pass it as `--parent`.
   The daemon makes the sub-issue link from `--parent`.

package/skills/legion-retro/SKILL.md

@@ -82,7 +82,7 @@ missing proof goes back as step 1 says. The Dispatch message (step 7) is for a f
    Dispatch's message limit, and ends with your attribution footer:
 
    ```bash
-   dispatch message --issue "$LEGION_ISSUE" --body-file - <<'EOF'
+   dispatch message --issue '<KEY>' --body-file - <<'EOF'
    ## Retro Complete
 
    **Learnings documented in:** docs/solutions/<path>.md, or none: <why no point qualified>.

package/skills/legion-worker/references/findings.md

@@ -57,7 +57,8 @@ says which), its first line exactly `Clear defect from <your role token>`. It pr
 `expects_reply: none`. It holds:
 
 - your role token, from your `Legion addressing` line
-- the defect, as its reader recognises it, and the issue it came from (`dispatch://<KEY>`)
+- the defect: what went wrong, where and to whom, with the numbers, and the issue it came from
+  (`dispatch://<KEY>`)
 - where the fix belongs: the repository and the component
 - the fix
 - the evidence comment, `dispatch://<REPORT KEY>/comment/<id>`
@@ -132,39 +133,42 @@ check's `Production:` line then names the finding as sent to the controller, or
 
 ## What the ask says
 
-The question stands alone, since the ask view shows no comment. It holds at most 800 characters,
+The question stands alone, since the ask view shows no comment. It holds at most 2,000 characters,
 the `Ref: <reference>` line `--ref` appends included (about 75 characters for a comment's
 reference). Its first line names who asks: `Clear defect from <your role token>` for a clear
 defect no controller took, else `Finding from <your role token>`. The architect's acceptance and the
-controller's catch-up find a finding ask by that line. Then it carries:
+controller's catch-up find a finding ask by that line. Then it names the concrete case before any
+general statement of it:
 
-- the problem, as its reader recognises it, and the issue it came from (`dispatch://<KEY>`);
-- where the fix would belong: the repository or layer, and a plain statement that it is not
+- what went wrong, where and to whom: the issue it came from (`dispatch://<KEY>`), the machine,
+  file, command or session, and the numbers;
+- where the fix would belong: the repository and component, and a plain statement that it is not
   Legion's when it is not. A problem is not Legion's because you work in Legion: name the
   component that misbehaved;
-- the decision a person must make, and your recommendation and its reason. A clear defect no
-  controller took carries the fix instead, and its options ask where the work goes, with
-  `Hand it to the owning tree` first and recommended.
-
-The evidence (the commands, their output and its time, the file and line, the pull request) does
-not fit. Post it first as a `dispatch comment` on the issue the ask goes on, which prints `Posted
-comment <id>`, and cite that comment with `--ref`, the one reference an ask takes. That issue,
+- the decision a person must make, what happens to whom under each option, and your
+  recommendation and its reason. A clear defect no controller took carries the fix instead, and its
+  options ask where the work goes, with `Hand it to the owning tree` first and recommended.
+
+Evidence the decision does not need (full command output, logs, every file and line, the pull
+request) goes in a comment. Post it first as a `dispatch comment` on the issue the ask goes on,
+which prints `Posted comment <id>`, and cite that comment with `--ref`, the one reference an ask
+takes. That issue,
 `<ASK KEY>` below, is the report issue, except as [When no controller takes
 it](#when-no-controller-takes-it) says:
 
 ```bash
-dispatch comment --issue <ASK KEY> --body-file - <<'EOF'
+dispatch comment --issue '<ASK KEY>' --body-file - <<'EOF'
 <the evidence: commands, output with its time, file:line, links>
 EOF
 # Keep `File it for Legion` only when your Legion addressing line lists the repository where the
 # fix belongs. For a clear defect no controller took, replace the `File an issue` option below with
 # 'Hand it to the owning tree: <the tree, when you know it>', the first option and recommended.
-dispatch ask --issue <ASK KEY> --ref 'dispatch://<ASK KEY>/comment/<id>' --question-file - \
+dispatch ask --issue '<ASK KEY>' --ref 'dispatch://<ASK KEY>/comment/<id>' --question-file - \
   --option 'File an issue: <what it would track, and who would own it>' \
   --option 'File it for Legion: Legion works it once it is filed' \
   --option 'Do not file: <what stays as it is>' <<'EOF'
 Finding from <your role token>
-<the problem and dispatch://<KEY> it came from; where the fix belongs, and that it is not Legion's when it is not; your recommendation and why>
+<what went wrong, where and to whom, with dispatch://<KEY> and the numbers; where the fix belongs, and that it is not Legion's when it is not; what each option does to whom; your recommendation and why>
 EOF
 ```