@sjawhar/opencode-legion-envoy 0.31.0 → 0.33.0

package/README.md

@@ -32,8 +32,8 @@ the session working directory, stamps it with the OpenCode session id and title,
 `details.topic` as tool metadata so a successful mutation subscribes to that exact Dispatch topic.
 
 `dispatch_artifact` accepts exactly one upload source: a local `path`, or inline `content`.
-An architect can post a primary specification directly with
-`{ issue, name: "spec.md", content: "# Design", primary: true }`.
+An architect can post a specification directly with
+`{ issue, name: "spec.md", content: "# Design" }`.
 
 It also maintains the live session registry metadata needed for Envoy to discover OpenCode sessions and their API ports.
 

package/dist/src/server.js

@@ -13603,6 +13603,16 @@ function dispatchToolSchema(spec, z, opts) {
   return spec.validation === undefined ? z.object(shape, opts) : z.refineObject(shape, spec.validation.check, spec.validation.message, opts);
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue in the repository's dashboard-configured project or, failing that, the default project (DISPATCH_DEFAULT_PROJECT).";
+var SPEC_SECTIONS = [
+  "Decisions needed",
+  "Acceptance",
+  "Requirements",
+  "Design",
+  "Errors",
+  "Testing",
+  "Rejected"
+];
+var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Every line is a fact, decision, or risk; use tables over prose; see skills/dispatch Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
 var DOC_EDIT_OPS = ["replace", "delete", "insert"];
 var dispatchToolSpecs = [
@@ -13614,7 +13624,7 @@ var dispatchToolSpecs = [
       title: z.string().describe("Concise issue title."),
       parent: z.string().describe("Optional parent issue.").optional(),
       external: z.string().describe("Optional external issue reference.").optional(),
-      spec: z.string().describe("Optional initial primary-document markdown.").optional()
+      spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional()
     })
   },
   {
@@ -13680,7 +13690,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic text edits to a document. Do not use it for review feedback or for reading; use " + `dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. ${ISSUE_REFERENCE}`,
+    description: "Apply deterministic text edits to a document. Do not use it for review feedback or for reading; use " + `dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. ${ISSUE_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       artifact: z.string().describe("Artifact slug or id for the document."),
@@ -13714,7 +13724,6 @@ var dispatchToolSpecs = [
       name: z.string().describe("Artifact filename shown in Dispatch."),
       path: z.string().describe("Local path to the file to upload.").optional(),
       content: z.string().describe("Inline text to store as a Markdown document.").optional(),
-      primary: z.boolean().describe("Make this document the issue primary artifact.").optional(),
       summary: z.string().describe("Optional version summary.").optional()
     }),
     validation: {
@@ -14359,8 +14368,6 @@ class DispatchClient {
       return this.#json("POST", artifactPath, input);
     const form = new FormData;
     form.set("name", input.name);
-    if (input.primary !== undefined)
-      form.set("primary", String(input.primary));
     if (input.summary !== undefined)
       form.set("summary", input.summary);
     if (input.actor !== undefined)
@@ -14879,20 +14886,17 @@ Open anchored asks/comments: ${marks.join(", ")}`,
       };
     }
     case "dispatch_artifact": {
-      const primary = optionalBoolean(args, "primary");
       const summary = optionalString(args, "summary");
       const name = stringArg(args, "name");
       const content = optionalString(args, "content");
       const result = await client.artifact(issue(), content === undefined ? {
         name,
         file: Bun.file(resolvePath(input.cwd, stringArg(args, "path"))),
-        ...primary === undefined ? {} : { primary },
         ...summary === undefined ? {} : { summary },
         actor
       } : {
         name,
         content,
-        ...primary === undefined ? {} : { primary },
         ...summary === undefined ? {} : { summary },
         actor
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -12,6 +12,38 @@ The server enforces high signal: an ask question is at most 800 characters with
 options; comment and message bodies are at most 2,000 characters; an artifact is at most 25 MiB.
 It refuses over-limit input; it never truncates it. GitHub threads and markers no longer exist.
 
+## Writing a spec
+
+A spec is a decision record for the human who decides and the implementer who builds, not a
+transcript of your thinking. Use exactly these document headings in this order.
+
+| Section | Required content | Form |
+| --- | --- | --- |
+| **Decisions needed** | Only decisions requiring human authority, taste, or risk appetite. Each states one question, two or three options with tradeoffs, and a recommendation. Every item is an anchored `dispatch_ask`. Answered items move into Requirements with provenance, then leave this section. No other section asks the reader anything. Empty means `None.` | One decision per line; anchor each ask to that line. |
+| **Acceptance** | Every outcome names its check and user-facing surface. An outcome without a verification method is not acceptance criteria. | Numbered lines; browser scenario, API call, or CLI command. |
+| **Requirements** | Provenance is a verbatim human quote or `inferred: <reasoning>`; readers treat inferred requirements as hypotheses. Do not restate the prompt in prose. | `requirement \| provenance` table. |
+| **Design** | State the files, components, routes, and data flow that change. | Facts, not narrative; diagrams only for genuine structure. |
+| **Errors** | Name the behaviour for every error condition; never specify a silent fallback. | `condition \| behaviour` table. |
+| **Testing** | Map every acceptance line to the proof that exercises it. | Suite or scenario. |
+| **Rejected** | Record each considered alternative and why it was rejected so it is not proposed again. | One alternative per line. |
+
+### Rules
+
+- Every sentence is a fact, decision, or risk; delete the rest.
+- Use tables over prose and keep one idea per line.
+- Do not use Overview, Background, Introduction, Summary, or Conclusion sections.
+- Do not hedge with “might” or “could consider.”
+- Do not use TBD, TODO, or placeholders; an open item is a Decision needed.
+- Keep each section to one screen; work that exceeds one screen per section is two specs.
+- Update the spec in place as decisions land. The spec is the record; comments are the discussion.
+
+### Self-review
+
+- [ ] No placeholders remain.
+- [ ] No sections conflict.
+- [ ] The spec covers one implementation plan's worth of work.
+- [ ] Every requirement has exactly one reading.
+
 ## Your issue
 
 Every session works on an issue. Legion pre-fills `issue` from `LEGION_ISSUE`: use a native issue key
@@ -26,6 +58,7 @@ dispatch_issue({ project, title, parent?, external?, spec? })
 ```
 It returns `details` `{ issue, topic }`. Use `dispatch_issue` only to create an issue; never use
 it to park a question.
+When `spec` is supplied, follow [Writing a spec](#writing-a-spec).
 
 ## Asking
 
@@ -43,8 +76,10 @@ dispatch_ask({
 It returns `details` `{ issue, topic, ask }`. Options are buttons: never enumerate choices in
 prose. Put the recommendation in `question`, and put each selectable choice in `options`.
 Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence` is
-zero-based and selects a repeated quote. An anchor whose quote disappears becomes orphaned but
-remains readable against its original document version.
+zero-based and selects a repeated quote. The server writes the resulting mark. The HTTP API also
+accepts `{ artifact, mark_id }` from a browser that has already written its mark; Dispatch tools
+use the quote form. An anchor whose quote disappears becomes orphaned but remains readable against
+its original document version.
 
 An ask stays open until a human answers, unless its question no longer needs that answer. Retract a
 moot or superseded question, or self-resolve one after finding the answer:
@@ -65,6 +100,7 @@ answer. Use `reply_to_ask` on `dispatch_comment` to reply under your own ask; it
 exclusive with `reply_to`.
 
 ## The spec is where narrative goes
+Write and update the issue specification according to [Writing a spec](#writing-a-spec).
 
 Read the current document before changing it:
 
@@ -72,7 +108,7 @@ Read the current document before changing it:
 dispatch_doc_read({ issue?, artifact?, version?, ref? })
 ```
 It returns live or versioned markdown with open marks and `details` `{ issue }`; omit `artifact`
-with `issue` to read the primary document. Then write narrative with:
+with `issue` to read the issue specification. Then write narrative with:
 
 ```ts
 dispatch_doc_edit({ issue, artifact, ops, summary? })
@@ -107,7 +143,8 @@ dispatch_comment({ issue, artifact?, quote?, occurrence?, body, reply_to?, reply
 ```
 
 It returns `details` `{ issue, topic, comment }`. `quote` requires `artifact`; omit both for a
-floating issue comment. Use `reply_to` to continue a comment thread; use `reply_to_ask` to reply
+floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no `quote`; it belongs to its
+parent's anchor. Use `reply_to` to continue a comment thread; use `reply_to_ask` to reply
 directly under a question asked with `dispatch_ask`. The two are mutually exclusive.
 
 Propose an exact replacement instead of describing it:
@@ -118,28 +155,31 @@ dispatch_suggest({ issue, artifact, quote, replace_with, body?, occurrence? })
 
 It returns `details` `{ issue, topic, comment }`. A human accepts or rejects a suggestion. On
 `TARGET_AMBIGUOUS`, add zero-based `occurrence`. On `TARGET_NOT_FOUND`, re-read the document
-before retrying. `INVALID_OP` names a malformed edit; `CAP_EXCEEDED` never truncates;
-`ISSUE_CLOSED` rejects a write. `ACTOR_KIND`, `ROUTE_INVALID`, and `PRIMARY_NOT_DOC` reject an
-invalid actor, route, or primary artifact.
+before retrying. `INVALID_ANCHOR` requires exactly one nonempty anchor `quote` or `mark_id`;
+`ANCHOR_MISSING` means a browser mark was not observed in the live tree, and
+`ANCHOR_ORPHANED` means its marked text no longer exists. `INVALID_MARKDOWN` and `DOC_SCHEMA`
+reject Markdown or a live tree outside the Proof schema. `INVALID_OP` names a malformed edit;
+`CAP_EXCEEDED` never truncates; `ISSUE_CLOSED` rejects a write. `ACTOR_KIND` and `ROUTE_INVALID`
+reject an invalid actor or route.
 
 ## Artifacts
 
 Attach an image, diagram, or local file with:
 
 ```ts
-dispatch_artifact({ issue, name, path, primary?, summary? })
+dispatch_artifact({ issue, name, path, summary? })
 ```
 
 Or, when the text is already in the call, post a Markdown document directly:
 
 ```ts
-dispatch_artifact({ issue, name: "spec.md", content: "# Design\n...", primary: true })
+dispatch_artifact({ issue, name: "spec.md", content: "# Design\n..." })
 ```
 
 Exactly one of `path` and `content` is required. The inline form sends JSON with
 `Content-Type: application/json`. It returns `details` `{ issue, topic, artifact, version }`.
-Uploading the same `name` creates its next version. Use `content` for an architect's primary spec;
-set `primary: true` only for Markdown documents.
+Uploading the same `name` creates its next version. Use `content` when the text is already in
+the call.
 
 ## Messages
 

package/skills/legion-architect/SKILL.md

@@ -70,13 +70,15 @@ exercise a criterion end to end, building that path is a child issue of this tre
   relationship from `parent`. Keep the returned issue keys in ordered waves; a child is
   inert until released.
 
+Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
+
 Write one root specification containing the accepted scope, adoption/decomposition,
 waves, acceptance criteria, and integration test. When the config-armed root design gate
 applies, run this exact sequence **before any Legion-role spawn**, including a
 sub-architect:
 
 ```text
-dispatch_artifact({ issue: "<root issue>", name: "spec.md", content: "<root specification>", primary: true, summary: "<one-line summary>" })
+dispatch_artifact({ issue: "<root issue>", name: "spec.md", content: "<root specification>", summary: "<one-line summary>" })
 askId = dispatch_ask({
   issue: "<root issue>",
   question: "<specification summary and the decision requested>",

package/skills/legion-worker/SKILL.md

@@ -118,6 +118,8 @@ path-scoped workflow.
 
 ## Phase work
 
+Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
+
 Follow the repository's normal engineering workflow and the assigned issue's acceptance
 criteria. Your phase's own charter and the predecessor handoffs you read define the phase
 artifact and its completion evidence. Do not replace architect-owned decomposition, gate