@sjawhar/pi-envoy 16.5.0 → 16.7.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.
@@ -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 aim
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 `dispatch search`, never the environment. The spec's `##` parts, in order:
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 own terms, at most 100 words
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 people or upload their words.
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 or term a new reader may not know, and what each issue you name does for them.
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 first: which machines, files, sessions or people, and the numbers. Then ask the choice in those terms, never "Which option?".
45
- - A choice inside what the person asked for, or one their messages favour, is yours: decide it.
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 with costs, your recommendation and its reason, answerable on a phone.
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 it touches and delete what it contradicts. Never narrate an edit or what used to be here: versions and comments hold the history. Reply in a comment's thread.
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 missing or needless questions. Fix or record each.
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>` (`doc-read --blocks` lists the ids), and a person's decision its ask, `dispatch://KEY/ask/<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
- At your next edit, rewrite a spec outside the outline whole in one version, moving its ask blocks with `doc-edit`'s `move`; restate each retelling, quotation or unlinked attribution as design, or cut it.
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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "16.5.0",
3
+ "version": "16.7.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {