@sjawhar/pi-envoy 13.9.1 → 13.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/envoy.js CHANGED
@@ -37251,7 +37251,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
37251
37251
 
37252
37252
  // package.json
37253
37253
  var name = "@sjawhar/pi-envoy";
37254
- var version2 = "13.9.1";
37254
+ var version2 = "13.10.0";
37255
37255
  var package_default = {
37256
37256
  name,
37257
37257
  version: version2,
@@ -10,7 +10,6 @@ Dispatch is a record for the people who decide, never a log of your work.
10
10
  - Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
11
11
  - Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`). Give object and list fields as JSON.
12
12
  - Exit 1 is a refusal, 2 a usage error. A refusal lists each problem: fix them all, then call once.
13
- - `DOC_SERVICE_UNAVAILABLE`: the document is reloading, nothing was written; retry shortly.
14
13
 
15
14
  ## Asks and ask blocks
16
15
 
@@ -45,7 +44,7 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
45
44
 
46
45
  Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, `done` with `--reason` once driven in production. An issue with the `legion` label, or under one: never write its status or route it, and claim it only as a Legion role of its tree, even when its claim reads `· not running`, as a suspended architect's does: taking it removes the tree from the workflow.
47
46
 
48
- A claim, or `dispatch issue-update --route session:<your id>` (`--route ''` on release), brings a person's answers, comments and messages; for agents' activity, `envoy_subscribe notifications.dispatch.issue.<KEY>.>`, which shows no event Dispatch marks quiet, like an unnamed autosave.
47
+ A claim, or `dispatch issue-update --route session:<your id>` (`--route ''` on release), brings a person's answers, comments and messages; for agents' activity, `envoy_subscribe notifications.dispatch.issue.<KEY>.>`, which shows no event Dispatch marks quiet.
49
48
 
50
49
  ## Close what you opened
51
50
 
@@ -54,7 +53,7 @@ A claim, or `dispatch issue-update --route session:<your id>` (`--route ''` on r
54
53
 
55
54
  ## Structure over stream
56
55
 
57
- - One issue per deliverable, its content the issue's document. Decisions are asks.
56
+ - One issue per deliverable, its content the issue's document.
58
57
  - A message replies to a person or tells them what they must know now.
59
58
  - Text a person must read to decide belongs in the spec. An artifact is a real file.
60
59
 
@@ -80,7 +79,7 @@ dispatch://PROJECT/artifact/<slug>/ask/<id>
80
79
  dispatch://PROJECT/artifact/<slug>/comment/<id>#b-<block>[@vN]
81
80
  ```
82
81
 
83
- A bare id or filename is not a reference. An ask or comment id can be an 8-hex prefix.
82
+ A bare id or filename is not a reference. Write each id whole, from `dispatch read`'s `Ask id:` or the page URL: the command takes a prefix, a person's link does not.
84
83
 
85
84
  ## Setup and the HTTP API
86
85
 
@@ -31,7 +31,7 @@ For each spec, ask, comment and message:
31
31
 
32
32
  - Write in `skill://asd-ste100`'s strict mode.
33
33
  - Write about the current design, never the person or how people reached it. Never quote people or upload their words.
34
- - Link each source where the person wrote it. With no link, state the design.
34
+ - Link each source where the person wrote it, each id whole. With no link, state the design.
35
35
  - In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
36
36
  - A sentence that cites a gate passing (a test, review, check or proof) also says what the pass does not show: "The tests pass; they catch a wrong verdict, not a proof of a contradiction."
37
37
  - Name your session only if a reader must reach it.
@@ -0,0 +1,111 @@
1
+ ---
2
+ name: outside-message
3
+ description: "Use before any text reaches a person outside the company: a comment on an issue or pull request of a repository the company does not own, an email, a chat message to another company, a release note, an enrollment reply, a bug report, a disclosure. Use it also before you open an ask that asks the operator to approve such text. Not for a message to the operator, to another agent, or inside the company's own organization."
4
+ ---
5
+
6
+ # A message to someone outside the company
7
+
8
+ The operator approves every message that leaves the company, and four steps come before you ask.
9
+ The rules below are the operator's own, from the answers that set them; this skill is where they
10
+ are written down.
11
+
12
+ ## The exclusions
13
+
14
+ An exclusion exists only where the operator has stated it. Never infer one from the shape of a
15
+ message.
16
+
17
+ **A project the operator has excluded by name** goes out without approval. Only the operator's own
18
+ answer names such a project, and your stream's brief is where that answer reaches you. With no such
19
+ answer for the project in front of you, there is no exclusion.
20
+
21
+ **A pull request to a project that has already enrolled**, with its description and its comments to
22
+ that project's maintainers. The operator does not want to be asked for approval every time for an
23
+ enrolled project, and ceremony around a pull request must not stop the work. The four steps still
24
+ apply. The approval ask does not. The work does not wait for the pull request either: prepare and
25
+ sign the changes locally, and send them when the work they belong to ends.
26
+
27
+ What counts as enrolled is the enrolling project's own record, and its stream's brief says where
28
+ that record is. Do not decide enrollment from a message's tone, or from a maintainer having replied
29
+ to the company before.
30
+
31
+ Everything else waits for the operator: a first contact with a project that has not enrolled, a bug
32
+ report, a disclosure, and a reply to a maintainer who wrote first.
33
+
34
+ ## The four steps
35
+
36
+ 1. **Research the audience.** Read the repository's contributing guide, its issue and pull-request
37
+ templates, its code of conduct, and its last ten issues or pull requests. Read how the
38
+ maintainers write to each other. Search for what has already been discussed about your subject; a
39
+ question they answered last month, asked again, costs you the reader.
40
+ 2. **Write for that audience, in their conventions.** Use their template where they have one, their
41
+ terms, their level of detail. Run `skill://asd-ste100` and `skill://plain-words` over the text.
42
+ Neither removes AI writing tells; where your session has a pass for those, run it as well.
43
+ 3. **Follow their conventions in form as well as words.** A pull request on their repository uses
44
+ their pull-request template. An issue uses their issue template. A thread reply matches the
45
+ thread.
46
+ 4. **A fresh reviewer reads it and cuts.** Dispatch a subagent that has not seen the drafting, give
47
+ it the message and the research, and tell it to remove everything that is not needed to
48
+ understand the core message. A reviewer that only approves has not done step 4. A subagent with
49
+ no model of its own runs on yours. Where your session can give the reviewer a different model,
50
+ do: a reader of the same model as the writer is the weaker check, though no measurement here
51
+ separates the two.
52
+
53
+ **Step 4 ends with a list of what it removed, and that list goes in the ask.** Measured on
54
+ 2026-10-30 over 18 drafts of three real messages: drafts written with this skill met the bar 9
55
+ times in 9, drafts with no guidance 8 times in 9, so the first three steps changed almost nothing
56
+ — the research teaches them. The step that changed the message was the cut, and it is the step
57
+ agents skip: 2 of 9 with the skill and 3 of 9 without had no cut at all. Only the cut drafts lost
58
+ a promise about a future release, and they lost half their length. An instruction alone did not
59
+ make the cut happen, so the list is what proves it did: three lines naming what came out, or the
60
+ sentence "the reviewer removed nothing", which is itself an answer.
61
+
62
+ The form of the text is not in this skill. Where the stream that owns the relationship keeps its own
63
+ rules for writing to maintainers — in its project's `AGENTS.md`, in its skills, or in its brief —
64
+ those rules decide how the message reads, and some of them are owned by people through that
65
+ repository's code owners. Read them before you draft, and send a change to the form there rather
66
+ than into this file.
67
+
68
+ This skill covers when approval is needed and what comes before the ask. The project's own rules
69
+ cover how the text reads.
70
+
71
+ ## Then the ask
72
+
73
+ **Put the full message text in the ask itself.** Not a link to a document holding it, not a summary
74
+ of it, not "the draft is at …". The operator has to open another document to read the message in
75
+ almost every one of these asks, and cannot judge the message from the ask.
76
+
77
+ An ask for an outside message has, in this order:
78
+
79
+ - who the reader is, and one line on what they already know about this;
80
+ - **the message, in full, as it would be sent**;
81
+ - **what the reviewer removed in step 4**, in three lines or fewer, or "the reviewer removed
82
+ nothing";
83
+ - what changes if the answer is no.
84
+
85
+ Link the research, not the message. An ask with no removal line has not had step 4, whatever it
86
+ says.
87
+
88
+ ## Never write these
89
+
90
+ Delete the empty verb phrases and say the literal thing instead. These shapes:
91
+
92
+ | Never | Write instead |
93
+ |---|---|
94
+ | "to name the problem" | say the problem |
95
+ | "land the change" | merge it, release it, deploy it — whichever it is |
96
+ | "carry the finding to X" | tell X, send X, put it on the issue |
97
+ | "this shows the gap" | the gap is … |
98
+ | "that pays for itself" | it costs $X and returns $Y |
99
+
100
+ The test: delete the verb phrase and ask what literally happens. If you cannot say what happens, you
101
+ did not know, and the phrase hid that from both of you. Write what happens.
102
+
103
+ The same rule runs over asks, specs, messages, commit bodies and pull-request descriptions, not only
104
+ outside messages. `skill://plain-words` has the full list and the rewrites.
105
+
106
+ ## What this skill does not cover
107
+
108
+ - Text written in a person's own name, which that person signs off.
109
+ - A message to another agent or to the operator: write it plainly and send it; no approval step.
110
+ - Posting a release the pipeline publishes from approved template text: the template was approved
111
+ once; the release needs no new ask unless its text changes.
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: plain-words
3
+ description: "Use before you send or publish any text a person reads: an ask, a spec, a Dispatch comment, a message to a colleague, a pull-request body, a commit message, a report, a status update. It removes empty verb phrases and replaces each with the literal thing. Use it after you write and before you send."
4
+ ---
5
+
6
+ # Say the literal thing
7
+
8
+ The operator made this a rule: delete the empty verb phrases agents keep using, and say the literal
9
+ thing instead.
10
+
11
+ Run this over your text before you send it. It takes a minute and it is not optional.
12
+
13
+ ## The test
14
+
15
+ Take the verb phrase out and ask: **what literally happens?** Write that. If you cannot say what
16
+ happens, you did not know, and the phrase hid it from you as well as from the reader.
17
+
18
+ ## The phrases, in the order agents actually use them
19
+
20
+ Counted on 2026-10-30, in one day's 198,898 assistant messages across one fleet of agents:
21
+
22
+ | Never | Used that day | What to write |
23
+ |---|---:|---|
24
+ | land the change, land the PR | **1,053** | merge it, release it, deploy it, apply it — whichever one it is |
25
+ | unblock the work | 151 | X can start once Y merges |
26
+ | name the problem, name the owner, name a date | 23 | say the problem; who owns it is X; it is due on 11-02 |
27
+ | it pays for itself, that pays | 13 | it costs $16,306 and returns $60,379 a month |
28
+ | carry it to X, carry the finding | 11 | tell X; send it to X; put it on the issue |
29
+ | this shows the gap, the number shows | 5 | the gap is 12 of 30; the number is 1.17 |
30
+
31
+ **The trigger for the commonest one:** you reach for "land" when you cannot say whether it merged,
32
+ released or deployed. If you can say which, say it. If you cannot, that is the sentence — "it is
33
+ approved and not merged" — and it is more useful than any verb.
34
+
35
+ **"name the X" is the one an instruction does not fix.** It survived at the same rate with this
36
+ skill and without it (11 drafts against 10, over 72). Use the test rather than the row: if deleting
37
+ "name" leaves a sentence that says what happens, delete it; if it does not, you were about to write
38
+ a verb for an action you had not decided on.
39
+
40
+ Three phrases were cut from this table because the same count found zero uses of them in a day:
41
+ "move the needle", "drive it to zero", "surface the issue". A rule against a phrase nobody writes
42
+ costs a reader attention and buys nothing.
43
+
44
+ ## Untested, and here because the fault is the same
45
+
46
+ These were measured at 0 of 72 drafts in both arms, so this skill has no evidence that naming them
47
+ changes anything. They stay as examples, not as rules:
48
+
49
+ - **A verb with no actor.** "The fix is being prioritised." Who is doing it, and when?
50
+ - **A noun that should be a number.** "Significant improvement." From what to what?
51
+ - **A promise with no object.** "We will follow up." On what, with whom, by when?
52
+ - **A hedge that costs the reader a second read.** "It may be worth considering whether we should."
53
+ Either recommend it or do not raise it.
54
+
55
+ **Where this skill helps, measured:** over 72 drafts of six real status messages, when the writer
56
+ works from notes it went from 16 of 18 clean to 18 of 18. When the task was already prose, both arms
57
+ were 18 of 18. So it earns its place where an agent writes up its own work, which is where these
58
+ phrases live.
59
+
60
+ ## Do not shout
61
+
62
+ The operator, on an ask written in capitalised headers: why do you keep writing your asks in this
63
+ obnoxious format with all caps headers and stuff?
64
+
65
+ No capitalised headers. No capitalised phrases for emphasis. Bold only where a number, a name or a
66
+ choice needs to be found again.
67
+
68
+ The reason it appears: an agent writes a long passage, cannot find its point, and puts a handle on
69
+ it so a reader can. **The handle is a symptom. Cut the passage instead.** A paragraph that needs a
70
+ shouted header to be skimmable is a paragraph nobody should have to skim.
71
+
72
+ The same goes for a message to another agent. A capitalised line in a brief reads as an instruction
73
+ shouted twice, and a reader who sees three of them stops seeing any.
74
+
75
+ ## What stays
76
+
77
+ Plain verbs that describe a real action stay: merge, delete, send, read, measure, kill a process by
78
+ pid, repoint a link. The rule is against phrases that sound like an action and name none.
79
+
80
+ A term of art stays when it is the literal name of the thing: a merge queue merges, a garbage
81
+ collector collects, a sweep sweeps.
82
+
83
+ ## Where this fits
84
+
85
+ `skill://asd-ste100` constrains grammar and vocabulary for a reader whose first language may not be
86
+ English. This skill removes verb phrases that carry no fact. Neither removes AI writing tells, so
87
+ where your session has a pass for those it is a third one. Run them all on an outside message
88
+ (`skill://outside-message`); run this one on everything.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "13.9.1",
3
+ "version": "13.10.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {