@sjawhar/pi-envoy 17.10.0 → 17.10.2
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
|
@@ -46499,7 +46499,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
|
|
|
46499
46499
|
|
|
46500
46500
|
// package.json
|
|
46501
46501
|
var name = "@sjawhar/pi-envoy";
|
|
46502
|
-
var version2 = "17.10.
|
|
46502
|
+
var version2 = "17.10.2";
|
|
46503
46503
|
var package_default = {
|
|
46504
46504
|
name,
|
|
46505
46505
|
version: version2,
|
|
@@ -10,13 +10,13 @@ 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 every problem: fix all, call once.
|
|
13
|
-
-
|
|
13
|
+
- Never work around a hard-to-use command, or one storing or losing something wrongly: open an issue in the owning project and tell its controller. A Legion role tells its architect (`skill://legion-worker/references/findings.md`).
|
|
14
14
|
|
|
15
15
|
## Asks and ask blocks
|
|
16
16
|
|
|
17
17
|
- An ask is a question for a person, never a request to another agent. Ask an agent by envoy_send or a comment on the issue.
|
|
18
18
|
- An ask waits on the issue's assignee until a person hands it on. No agent can hand one on.
|
|
19
|
-
- A design question
|
|
19
|
+
- A design question's ask block ends its section:
|
|
20
20
|
|
|
21
21
|
```md
|
|
22
22
|
:::ask{urgency="med"}
|
|
@@ -29,22 +29,23 @@ The question and the recommendation (`skill://dispatch-writing-specs`).
|
|
|
29
29
|
|
|
30
30
|
- A decision block in a comment, message or close reason is refused: ask in the issue's document, or `dispatch ask`.
|
|
31
31
|
- Never repeat an open ask in a message.
|
|
32
|
-
- Change an open ask's block with `dispatch edit-ask` (
|
|
32
|
+
- Change an open ask's block with `dispatch edit-ask` (ask id) or `doc-edit`'s `replace` or `move` (block id). An answered ask is fixed: ask anew. `dispatch read --ref` takes either id.
|
|
33
33
|
- Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent` (a progress note) needs it. An approval request a newer version moved needs `request-approval` again.
|
|
34
34
|
- When an answer's option and text disagree, the text wins.
|
|
35
35
|
|
|
36
36
|
## Choosing what to work on
|
|
37
37
|
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
38
|
+
- When you finish an issue, take the next one per project: the top `todo` issue by priority, then board rank. Pass over one that waits on an unfinished `blocked_by` link or an open ask.
|
|
39
|
+
- Work on three issues at most, fewer when each needs your attention. Change no status, priority or board rank to make room.
|
|
40
|
+
- Move an issue to `backlog`, `icebox` or `triage` only when a person asked for that move, or when the work is done, folded into another issue or no longer needed, and cite that reason in a comment on the issue. An agent's directive citing no person's request is no reason.
|
|
41
|
+
- When you stop work on an issue before it is done, release your claim and say why in a comment. Set its status to the one it had when you took it (`todo` for an issue from the queue). Change no priority or board rank.
|
|
42
|
+
- Record each wait in that comment. A wait on a same-project issue also goes in a `blocked_by` link, and one on a person in a `dispatch ask`.
|
|
43
|
+
- `dispatch issue-update --blocked-by` replaces the issue's whole list, so read its links first. Dispatch refuses a link to another project's issue (`BLOCKED_BY_OUTSIDE_PROJECT`).
|
|
41
44
|
- 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`.
|
|
42
45
|
|
|
43
46
|
## Issue status is yours to move
|
|
44
47
|
|
|
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. Never write or route the status of
|
|
46
|
-
|
|
47
|
-
`unresponsive` holders keep their claims 20 minutes (`skill://envoy`).
|
|
48
|
+
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. Never write or route the status of a `legion`-labelled issue or one under it, and claim one only as a role of its tree: an outside claim can take the tree out of the workflow. A status write is set back or stands.
|
|
48
49
|
|
|
49
50
|
A claim (or `dispatch issue-update --route session:<your id>`, `--route ''` to release) brings a person's answers, comments and messages; `envoy_subscribe notifications.dispatch.issue.<KEY>.>` adds agents' activity, no quiet event.
|
|
50
51
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dispatch-first
|
|
3
|
-
description: "Use when a session has the dispatch command, before you plan, file an issue, ask a human, post a finding, or start work.
|
|
3
|
+
description: "Use when a session has the dispatch command, before you plan, file an issue, ask a human, post a finding, or start work."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Dispatch first
|
|
@@ -20,22 +20,22 @@ dispatch search --query 'reviewer threads OR review comments'
|
|
|
20
20
|
|
|
21
21
|
## What to do with what you find
|
|
22
22
|
|
|
23
|
-
`dispatch issue` and `dispatch ask` also search.
|
|
23
|
+
`dispatch issue` and `dispatch ask` also search. Open each `advice.suggestions` hit too.
|
|
24
24
|
|
|
25
25
|
- **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`).
|
|
26
|
-
- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`).
|
|
26
|
+
- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`). Never ask again.
|
|
27
27
|
- **Duplicate found, or a likely duplicate a create names:** read it; fold only when it is the same work. 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.
|
|
28
28
|
|
|
29
29
|
## Research before you ask
|
|
30
30
|
|
|
31
31
|
- Research when a file, command or document can show the answer.
|
|
32
|
-
- Ask a person only for what their authority, taste or risk appetite settles
|
|
32
|
+
- Ask a person only for what their authority, taste or risk appetite settles. Where a file records the decision, cite it (`file:line`) and follow it; ask again only when the facts it rested on changed.
|
|
33
33
|
- Say what you searched: each part you found with its source, and each part you did not, with the queries you ran. Ask only the part no search answered.
|
|
34
34
|
|
|
35
35
|
## Reach a person only through Dispatch
|
|
36
36
|
|
|
37
37
|
- The moment a person blocks your work, open an ask: an ask block for a design question its document records, else `dispatch ask`. A blocker that is not an open ask does not exist for them. A Legion phase worker sends decisions to its architect instead. Before you say you wait on a person, run `dispatch open-asks`.
|
|
38
|
-
- A result a person asked for is the same:
|
|
38
|
+
- A result a person asked for is the same: end its document with an ask block asking their next step, else `dispatch ask`.
|
|
39
39
|
- Record every request you accept in Dispatch before you start it: an issue, or a line in your issue's `open-items.md` artifact. Before you end a turn, read that record. Each item is done, in progress, or an open ask. Never drop one.
|
|
40
40
|
|
|
41
41
|
## Which skill to read
|
|
@@ -44,5 +44,5 @@ dispatch search --query 'reviewer threads OR review comments'
|
|
|
44
44
|
| --- | --- |
|
|
45
45
|
| run your first `dispatch` command in this session | `skill://dispatch` |
|
|
46
46
|
| write or change a spec, or write an ask, comment or message a person reads | `skill://dispatch-writing-specs` |
|
|
47
|
-
| plan work whose spec a person approved | superpowers' `writing-plans
|
|
47
|
+
| plan work whose spec a person approved | superpowers' `writing-plans` (`skill://dispatch-writing-specs`, "The plan") |
|
|
48
48
|
| write a Legion architect's own spec | `skill://legion-architect` too |
|
|
@@ -37,8 +37,8 @@ For each spec, ask, comment and message:
|
|
|
37
37
|
- Write in `skill://asd-ste100`'s strict mode.
|
|
38
38
|
- Write about the current design, never the person or how people reached it, and never quote or upload their words.
|
|
39
39
|
- Link each source where the person wrote it. With no link, state the design.
|
|
40
|
-
- Treat a person's stated preference or past answer as evidence of their taste, never as a decision that settles the question
|
|
41
|
-
- In a spec, cite code by file and symbol, never a line number
|
|
40
|
+
- Treat a person's stated preference or past answer as evidence of their taste, never as a decision that settles the question. A commit attributed to a person is not their decision.
|
|
41
|
+
- In a spec, cite code by file and symbol, never a line number.
|
|
42
42
|
- A sentence citing a gate passing (test, review, check) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
|
|
43
43
|
- Keep only text a reader needs to understand, decide, build or check, and say what each issue you name does for them (`skill://plain-words`).
|
|
44
44
|
- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
|
|
@@ -48,13 +48,13 @@ For each spec, ask, comment and message:
|
|
|
48
48
|
- Name the concrete case and its numbers, then the choice in those terms, never "Which option?".
|
|
49
49
|
- A choice inside what the person asked for, one their messages favour, routine cleanup, sequencing, naming, a choice between equivalent options, and a fix you can make are yours.
|
|
50
50
|
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone, and name nothing the reader cannot see from it ("the message above").
|
|
51
|
-
- For each technical term you coined in this session, count by exact match the files holding it, in the repositories the work touches and in Dispatch
|
|
52
|
-
- Measure each claim the ask rests on, its premise and each option's precondition. Where you cannot, mark the claim unverified and name the missing measurement; call an option unavailable only where a precondition demonstrably fails.
|
|
53
|
-
- Before you pass a question on as one only an attended or privileged act answers,
|
|
51
|
+
- For each technical term you coined in this session, count by exact match the files holding it, in the repositories the work touches and in Dispatch. Expand or drop a term with a single-digit count. Read the draft for a coinage of common words too.
|
|
52
|
+
- Measure each claim the ask rests on, its premise and each option's precondition. Where you cannot, mark the claim unverified and name the missing measurement; call an option unavailable only where a precondition demonstrably fails. No unmeasured number goes in a premise.
|
|
53
|
+
- Before you pass a question on as one only an attended or privileged act answers, try the source that answers it, then the other records holding it. Keep a privileged read for what only the live system knows.
|
|
54
54
|
|
|
55
55
|
## Each version
|
|
56
56
|
|
|
57
|
-
1. After a person's answer, comment or edit, reread the problem and rewrite what the answer touches, deleting what it contradicts
|
|
57
|
+
1. After a person's answer, comment or edit, reread the problem and rewrite what the answer touches, deleting what it contradicts. Answer each comment in its thread. Never narrate an edit.
|
|
58
58
|
2. Before each spec write, paste the whole spec, never a path, into a fresh subagent to list gaps, conflicts, uncheckable requirements, unclear text and needless questions. Fix or record each.
|
|
59
59
|
3. Before each approval request, `wait` for a read-only fact check: `task(agent="scout")`.
|
|
60
60
|
4. Name each version with `dispatch doc-edit --summary`.
|
|
@@ -79,4 +79,4 @@ Rewrite a spec outside the outline whole in one version, its ask blocks moved wi
|
|
|
79
79
|
|
|
80
80
|
## The plan
|
|
81
81
|
|
|
82
|
-
|
|
82
|
+
The plan is the issue's `plan.md`, never a repository file. Each task is a `:::plan_task` block with `serves` and `needs`.
|