@sjawhar/pi-envoy 11.2.0 → 11.4.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/README.md +18 -1
- package/dist/dispatch.js +3830 -3758
- package/dist/envoy.js +6457 -4938
- package/dist/skills/dispatch/SKILL.md +4 -4
- package/dist/skills/dispatch-first/SKILL.md +2 -2
- package/dist/skills/dispatch-writing-specs/SKILL.md +5 -5
- package/dist/skills/envoy/SKILL.md +1 -1
- package/dist/skills/envoy/references/deliveries.md +1 -1
- package/package.json +1 -1
|
@@ -18,15 +18,15 @@ Dispatch is a record for the people who decide, never a log of your work.
|
|
|
18
18
|
|
|
19
19
|
```md
|
|
20
20
|
:::ask{urgency="med"}
|
|
21
|
-
|
|
21
|
+
Which machines, files or people, the numbers, then "A happens to X, or B to Y?" Recommendation: the option and its reason.
|
|
22
22
|
|
|
23
23
|
- Option one: what it costs.
|
|
24
24
|
- Option two: what it costs.
|
|
25
25
|
:::
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
- A to-do or permission only a person can give, or a decision with no document, is a `dispatch ask`.
|
|
29
|
-
- In Legion,
|
|
28
|
+
- A to-do or permission only a person can give, or a decision with no document, is a `dispatch ask`.
|
|
29
|
+
- 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`).
|
|
30
30
|
- An open ask is the request. Do not raise it again in each message.
|
|
31
31
|
- Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
|
|
32
32
|
- 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:
|
|
|
54
54
|
|
|
55
55
|
## Structure over stream
|
|
56
56
|
|
|
57
|
-
- One issue per deliverable, its content the issue's document. Decisions are asks.
|
|
57
|
+
- One issue per deliverable, its content the issue's document. Decisions are asks.
|
|
58
58
|
- A message replies to a person or tells them what they must know now.
|
|
59
59
|
- Text a person must read to decide belongs in the spec. An artifact is a real file.
|
|
60
60
|
|
|
@@ -27,7 +27,7 @@ dispatch search --query 'reviewer threads OR review comments'
|
|
|
27
27
|
- **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`).
|
|
28
28
|
- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`). Do not ask again.
|
|
29
29
|
- **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.
|
|
30
|
-
- **Each ask and message stands alone:** the reader sees only that text.
|
|
30
|
+
- **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.
|
|
31
31
|
- In Legion, file no finding outside your issue (`skill://legion-worker/references/findings.md`).
|
|
32
32
|
|
|
33
33
|
## 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
|
|
|
42
42
|
| Before you | Read |
|
|
43
43
|
| --- | --- |
|
|
44
44
|
| run your first `dispatch` command in this session | `skill://dispatch` |
|
|
45
|
-
| write or change a spec, or write an ask, comment or message a person reads | `skill://dispatch-writing-specs`
|
|
45
|
+
| write or change a spec, or write an ask, comment or message a person reads | `skill://dispatch-writing-specs` |
|
|
46
46
|
| plan work whose spec a person approved | superpowers' `writing-plans`, stored as the issue's `plan.md` (`skill://dispatch-writing-specs`, "The plan") |
|
|
47
47
|
| write a Legion architect's own spec | `skill://legion-architect` too |
|
|
@@ -7,7 +7,7 @@ description: "Use in a session with Dispatch before you write or change a spec,
|
|
|
7
7
|
|
|
8
8
|
## The aim
|
|
9
9
|
|
|
10
|
-
Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes no spec
|
|
10
|
+
Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes no spec (`skill://legion-worker`).
|
|
11
11
|
|
|
12
12
|
## The outline
|
|
13
13
|
|
|
@@ -32,19 +32,19 @@ For each spec, ask, comment and message:
|
|
|
32
32
|
- Write in `skill://asd-ste100`'s strict mode.
|
|
33
33
|
- State the current design, never how people reached it.
|
|
34
34
|
- 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.
|
|
35
|
-
- Write about the design, never the person. Never quote people
|
|
35
|
+
- Write about the design, never the person. Never quote people or upload their words.
|
|
36
36
|
- Name your session only if a reader must reach it.
|
|
37
37
|
- Keep only text that helps a reader understand, decide, build, check.
|
|
38
|
-
- 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.
|
|
38
|
+
- 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.
|
|
39
39
|
- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
|
|
40
40
|
|
|
41
41
|
## Questions
|
|
42
42
|
|
|
43
|
+
- 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.
|
|
43
44
|
- Propose an answer to each point, numbers included, with a reason.
|
|
44
45
|
- A choice inside what the person asked for, or one their messages favour, is settled: decide it.
|
|
45
46
|
- Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
|
|
46
|
-
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks)
|
|
47
|
-
- Chat reaches nobody: use an ask or approval request.
|
|
47
|
+
- 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.
|
|
48
48
|
|
|
49
49
|
## Each version
|
|
50
50
|
|
|
@@ -66,6 +66,6 @@ Every topic starts with `notifications.`.
|
|
|
66
66
|
|
|
67
67
|
- Send to one session with `envoy_send`, to the one session that holds a named duty with a role, and to a group with a team topic.
|
|
68
68
|
- Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`; never subscribe to a role topic, because the listener forwards a role message to its holder only. A publish returns the live `holder`; an unheld role returns an error. `envoy_role_get(role=...)` finds the holder first.
|
|
69
|
-
- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches only the sessions subscribed when it is published (yours too, when you subscribe, unless you are a serve-port session, which receives it only through a listener run with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` and never its own publish), and is not kept for a session that subscribes later. A topic outside `notifications.` is refused.
|
|
69
|
+
- For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches only the sessions subscribed and connected when it is published (yours too, when you subscribe, unless you are a serve-port session, which receives it only through a listener run with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` and never its own publish), and is not kept for a session that subscribes later or whose connection was down. A topic outside `notifications.` is refused.
|
|
70
70
|
- How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
|
|
71
71
|
- In a Legion pane, the plugin claims your role at session start; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
|
|
@@ -53,7 +53,7 @@ envoy:
|
|
|
53
53
|
|
|
54
54
|
It depends on where a session takes its deliveries, not on whether the topic is built in or your own.
|
|
55
55
|
|
|
56
|
-
- A session that holds its own NATS connection (every Oh My Pi session, and a Claude Code one) receives every message published on a subject it subscribes to, whoever sent it: its own publish included, and a subagent's publish to a topic the parent subscribes to. This holds for a topic the stream keeps and for a live team topic alike.
|
|
56
|
+
- A session that holds its own NATS connection (every Oh My Pi session, and a Claude Code one) receives every message published on a subject it subscribes to, whoever sent it: its own publish included, and a subagent's publish to a topic the parent subscribes to. This holds for a topic the stream keeps and for a live team topic alike while it is connected. After an outage they differ: once its connection or subscription is back, the session recovers from the stream what was published meanwhile on its own inbox and on each kept topic it follows, up to 72 hours back, and is shown each message once, marked as published while its connection was down; what a team topic carried meanwhile is gone.
|
|
57
57
|
- A session the listener delivers to by push, over a serve port (such as the OpenCode plugin), does not receive its own publish, and receives a team topic only through the listener that owns it when that listener runs with `ENVOY_SUBSCRIBE_ALL_TOPICS=1` (the shared hub's listener does not).
|
|
58
58
|
- A role is not a subject its holder subscribes to: the listener finds the live holder and forwards the message to it, and drops the message when that holder is the message's source session.
|
|
59
59
|
|