@sjawhar/pi-envoy 16.4.0 → 16.6.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/THIRD_PARTY_NOTICES +90 -0
- package/dist/dispatch.js +2753 -252
- package/dist/envoy.js +2591 -79
- package/dist/skills/dispatch/SKILL.md +0 -1
- package/dist/skills/dispatch-first/SKILL.md +0 -1
- package/dist/skills/dispatch-writing-specs/SKILL.md +18 -14
- package/package.json +1 -1
|
@@ -24,7 +24,6 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
|
|
|
24
24
|
:::
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
- 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`).
|
|
28
27
|
- An open ask is the request; never repeat it per message.
|
|
29
28
|
- Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
|
|
30
29
|
- 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.
|
|
@@ -27,7 +27,6 @@ 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
|
-
- In Legion, file no finding outside your issue (`skill://legion-worker/references/findings.md`).
|
|
31
30
|
|
|
32
31
|
## Reach a person only through Dispatch
|
|
33
32
|
|
|
@@ -5,17 +5,22 @@ description: "Use in a session with Dispatch before you write or change a spec,
|
|
|
5
5
|
|
|
6
6
|
# Writing specs
|
|
7
7
|
|
|
8
|
-
## The
|
|
8
|
+
## The conversation
|
|
9
9
|
|
|
10
|
-
Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes none (`skill://legion-worker`).
|
|
10
|
+
Reach shared understanding with the person at the least cost of their time. A spec is a conversation, not a document you write and then ask about. A Legion phase worker writes none (`skill://legion-worker`). In order:
|
|
11
|
+
|
|
12
|
+
1. Read the issue, the code and what the person wrote.
|
|
13
|
+
2. Send what you found and the questions it leaves open, a few at a time, before the spec states a design.
|
|
14
|
+
3. Write each part only after the answers it rests on.
|
|
15
|
+
4. A wrong premise or a changed request changes the request first.
|
|
11
16
|
|
|
12
17
|
## The outline
|
|
13
18
|
|
|
14
|
-
Find the issue's project with `dispatch projects` or `
|
|
19
|
+
Find the issue's project with `dispatch projects` or `search`, never the environment. The spec's `##` parts, in order:
|
|
15
20
|
|
|
16
21
|
Part | Content
|
|
17
22
|
--- | ---
|
|
18
|
-
`Summary` | The change in the reader's
|
|
23
|
+
`Summary` | The change in the reader's terms, at most 100 words
|
|
19
24
|
`Problem` | What goes wrong, for whom, with counts
|
|
20
25
|
`Goals and non-goals` | What is in and out of scope
|
|
21
26
|
`Requirements` | a `:::requirement` block each, `**R1.**` on, its source (`From:`)
|
|
@@ -30,26 +35,25 @@ Part | Content
|
|
|
30
35
|
For each spec, ask, comment and message:
|
|
31
36
|
|
|
32
37
|
- Write in `skill://asd-ste100`'s strict mode.
|
|
33
|
-
- Write about the current design, never the person or how people reached it, and never quote
|
|
38
|
+
- Write about the current design, never the person or how people reached it, and never quote or upload their words.
|
|
34
39
|
- Link each source where the person wrote it, each id whole. With no link, state the design.
|
|
35
40
|
- In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
|
|
36
41
|
- A sentence that cites a gate passing (test, review, check) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
|
|
37
|
-
- Name your session only if a reader must reach it.
|
|
38
42
|
- Keep only text that helps a reader understand, decide, build, check.
|
|
39
|
-
- Explain each name
|
|
43
|
+
- Explain each name a new reader may not know, and what each issue you name does for them.
|
|
40
44
|
- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
|
|
41
45
|
|
|
42
46
|
## Questions
|
|
43
47
|
|
|
44
|
-
- Name the concrete case
|
|
45
|
-
- A choice inside what the person asked for, or one their messages favour, is yours
|
|
48
|
+
- Name the concrete case and its numbers, then the choice in those terms, never "Which option?".
|
|
49
|
+
- A choice inside what the person asked for, or one their messages favour, is yours.
|
|
46
50
|
- Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
|
|
47
|
-
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options
|
|
51
|
+
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone.
|
|
48
52
|
|
|
49
53
|
## Each version
|
|
50
54
|
|
|
51
|
-
1. After a person's answer, comment or edit, rewrite what
|
|
52
|
-
2. Before each spec write, paste the whole spec, never a path, into a fresh subagent: it lists gaps, conflicts, uncheckable requirements, unclear text and
|
|
55
|
+
1. After a person's answer, comment or edit, reread the problem and rewrite what the answer touches, deleting what it contradicts: an answer is integrated, never appended. Answer each comment in its thread. Never narrate an edit: versions and comments hold the history.
|
|
56
|
+
2. Before each spec write, paste the whole spec, never a path, into a fresh subagent: it lists gaps, conflicts, uncheckable requirements, unclear text and needless questions. Fix or record each.
|
|
53
57
|
3. Before each approval request, `wait` for a read-only fact check: `task(agent="scout")`.
|
|
54
58
|
4. Name each version with `dispatch doc-edit --summary`.
|
|
55
59
|
|
|
@@ -58,13 +62,13 @@ For each spec, ask, comment and message:
|
|
|
58
62
|
Choices—answered asks included—earn `decisions.md` `##` sections only if a disagreeing reader would act differently; keep others to one spec line each.
|
|
59
63
|
|
|
60
64
|
- The heading names the choice; the text gives the reason and the options weighed.
|
|
61
|
-
- Link each spec block it shaped, `dispatch://KEY/spec#b-<id
|
|
65
|
+
- Link each spec block it shaped, `dispatch://KEY/spec#b-<id>`, and a person's decision its ask, `dispatch://KEY/ask/<id>`.
|
|
62
66
|
- An unsure section adds a paragraph that starts `Unsure:`: what would change your mind.
|
|
63
67
|
- A replaced section moves under a final `## Replaced` as a `###`.
|
|
64
68
|
|
|
65
69
|
## Old specs
|
|
66
70
|
|
|
67
|
-
|
|
71
|
+
Rewrite a spec outside the outline whole in one version, its ask blocks moved with `doc-edit`'s `move`; restate each retelling, quotation or unlinked attribution as design, or cut it.
|
|
68
72
|
|
|
69
73
|
## Approval
|
|
70
74
|
|