@sjawhar/pi-envoy 11.1.0 → 11.3.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 +211 -35
- package/dist/envoy.js +2064 -504
- package/dist/skills/dispatch/SKILL.md +12 -12
- package/dist/skills/envoy/SKILL.md +1 -1
- package/dist/skills/envoy/references/deliveries.md +1 -1
- package/package.json +1 -1
|
@@ -7,14 +7,14 @@ description: "Use before your first dispatch command in a session: a message, co
|
|
|
7
7
|
|
|
8
8
|
Dispatch is a record for the people who decide, never a log of your work.
|
|
9
9
|
|
|
10
|
-
- Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives
|
|
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
|
|
13
|
+
- `DOC_SERVICE_UNAVAILABLE`: the document is reloading, nothing was written; retry in a few seconds.
|
|
14
14
|
|
|
15
15
|
## Asks and ask blocks
|
|
16
16
|
|
|
17
|
-
- A question
|
|
17
|
+
- A design question a document records is an ask block (a decision block) at the end of its section, at each phase:
|
|
18
18
|
|
|
19
19
|
```md
|
|
20
20
|
:::ask{urgency="med"}
|
|
@@ -30,37 +30,37 @@ The problem and why it matters. Recommendation: the option and its reason.
|
|
|
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.
|
|
33
|
-
- When an answer's option and text disagree, the text
|
|
33
|
+
- When an answer's option and text disagree, the text wins.
|
|
34
34
|
- An ask block has a block id, for `doc-edit`, and an ask id, for the ask commands. `dispatch read --ref dispatch://KEY/ask/<id>` takes either.
|
|
35
35
|
- An ask reaches the issue's assignee. On an unassigned issue, name who must answer.
|
|
36
36
|
|
|
37
37
|
## Choosing what to work on
|
|
38
38
|
|
|
39
|
-
- When you finish an issue, take the top ready
|
|
40
|
-
- `todo` means specced and waiting on nothing
|
|
39
|
+
- When you finish an issue, take the top ready one: `todo`, by priority then board rank, per project.
|
|
40
|
+
- `todo` means specced and waiting on nothing; one that waits goes in `backlog`, saying on what.
|
|
41
41
|
- Hold at most three issues in flight; move the rest to `backlog`, saying where each is.
|
|
42
42
|
- Never reorder the board: one agent keeps each project's order (`issue-update --before`/`--after`). If the top looks wrong, tell `notifications.role.legion-<project>-controller`.
|
|
43
43
|
|
|
44
44
|
## Issue status is yours to move
|
|
45
45
|
|
|
46
|
-
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,
|
|
46
|
+
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, 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 takes the tree out of the workflow.
|
|
47
47
|
|
|
48
|
-
A claim delivers no comments:
|
|
48
|
+
A claim delivers no comments: that turn, `dispatch issue-update --route session:<your id>` (`--route ''` on release) or `envoy_subscribe notifications.dispatch.issue.<KEY>.>`. Never route such an issue.
|
|
49
49
|
|
|
50
50
|
## Close what you opened
|
|
51
51
|
|
|
52
|
-
- An ask you opened is yours until
|
|
52
|
+
- An ask you opened is yours until answered or resolved. If it is answered another way or made moot, `dispatch resolve-ask` it that turn.
|
|
53
53
|
- Resolve each open ask a later write names that is no longer needed; retract one a new ask replaces.
|
|
54
54
|
|
|
55
55
|
## Structure over stream
|
|
56
56
|
|
|
57
57
|
- One issue per deliverable, its content the issue's document. Decisions are asks. A message only announces.
|
|
58
|
-
- A message replies to a person
|
|
59
|
-
- Text a person must read to decide
|
|
58
|
+
- A message replies to a person or tells them what they must know now.
|
|
59
|
+
- Text a person must read to decide belongs in the spec. An artifact is a real file.
|
|
60
60
|
|
|
61
61
|
## Architecture components
|
|
62
62
|
|
|
63
|
-
Attach each architectural issue to its components (`--components-json`), the root before
|
|
63
|
+
Attach each architectural issue to its components (`--components-json`), the root before decomposing it. Change code and `.dispatch/architecture/<id>.md` in the same review.
|
|
64
64
|
|
|
65
65
|
## References
|
|
66
66
|
|
|
@@ -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
|
|