@sjawhar/codex-envoy 0.0.0-stage → 5.1.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/.codex-plugin/plugin.json +90 -0
- package/README.md +23 -2
- package/dist/THIRD_PARTY_NOTICES +816 -0
- package/dist/codex-hook.js +32304 -0
- package/dist/codex-tool-hook.js +135 -0
- package/dist/dispatch.js +34103 -0
- package/dist/envoy-channel.js +68935 -0
- package/dist/session-hook.js +32557 -0
- package/dist/session-title-hook.js +373 -0
- package/hooks/hooks.json +48 -0
- package/package.json +16 -4
- package/skills/agent-secrets/SKILL.md +106 -0
- package/skills/agent-secrets/references/store-a-secret.md +9 -0
- package/skills/approval-review/SKILL.md +35 -0
- package/skills/approval-review/references/never-decide.md +154 -0
- package/skills/asd-ste100/LICENSE +21 -0
- package/skills/asd-ste100/SKILL.md +81 -0
- package/skills/asd-ste100/examples/before-after.md +57 -0
- package/skills/dispatch/SKILL.md +92 -0
- package/skills/dispatch-first/SKILL.md +48 -0
- package/skills/dispatch-writing-specs/SKILL.md +77 -0
- package/skills/envoy/SKILL.md +93 -0
- package/skills/envoy/references/check-settlement.md +45 -0
- package/skills/envoy/references/deliveries.md +28 -0
- package/skills/envoy/references/legion.md +17 -0
- package/skills/envoy/references/roles.md +14 -0
- package/skills/envoy/references/sources.md +33 -0
- package/skills/outside-message/SKILL.md +45 -0
- package/skills/plain-words/SKILL.md +54 -0
- package/skills/thermonuclear-code-quality/LICENSE +21 -0
- package/skills/thermonuclear-code-quality/SKILL.md +59 -0
- package/skills/thermonuclear-code-quality/agents/openai.yaml +5 -0
- package/skills/thermonuclear-deep-review/LICENSE +21 -0
- package/skills/thermonuclear-deep-review/SKILL.md +76 -0
- package/skills/thermonuclear-deep-review/agents/openai.yaml +5 -0
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# What the agent never decides
|
|
2
|
+
|
|
3
|
+
Some requests are not yours to answer, whatever your confidence and however clear the answer
|
|
4
|
+
looks. This file names them. It is the whole rule: there is no list of words or phrases behind
|
|
5
|
+
it, and nothing else states it.
|
|
6
|
+
|
|
7
|
+
When a document falls under one of these kinds, you decide nothing. You say which kind it falls
|
|
8
|
+
under and you hand it back to the person.
|
|
9
|
+
|
|
10
|
+
## The one question
|
|
11
|
+
|
|
12
|
+
**Does the document ask for the act, or does it only mention it?**
|
|
13
|
+
|
|
14
|
+
A request is often a technical document, and a technical document is full of deletions,
|
|
15
|
+
credentials, vendors and organization settings that it only describes. Describing is not asking.
|
|
16
|
+
Ask yourself what follows from a person writing "approved" under this document as it stands:
|
|
17
|
+
|
|
18
|
+
- if one of the acts below is then **authorised** — somebody may now do it, or is being asked to
|
|
19
|
+
do it, or the approval itself is the permission — the document asks for it, and it is held;
|
|
20
|
+
- if the act is **reported** (it already happened), **described** (this is how the system works,
|
|
21
|
+
how it worked last month, what a job already does), **proposed as somebody else's separate
|
|
22
|
+
request**, or **turned down** ("we will not drop it"), the document does not ask for it, and
|
|
23
|
+
you decide it as you would any other.
|
|
24
|
+
|
|
25
|
+
Both failures cost something. Deciding a request you were never given costs a person something
|
|
26
|
+
they never agreed to. Holding an ordinary change costs them an answer they were waiting for, and
|
|
27
|
+
a rule that holds everything is no rule at all. Judge what the document asks for, not which
|
|
28
|
+
words appear in it.
|
|
29
|
+
|
|
30
|
+
The act does not need a person's name beside it. "Drop the legacy table on the primary", "The
|
|
31
|
+
operator drops it", "You drop it" and a change list that reads "- Drop the legacy table" all ask
|
|
32
|
+
for the same act; a change list is written in the imperative, and that is still the request.
|
|
33
|
+
|
|
34
|
+
## The seven kinds
|
|
35
|
+
|
|
36
|
+
### `destructive-act`
|
|
37
|
+
|
|
38
|
+
The document asks for data or infrastructure to be destroyed, overwritten or made unrecoverable:
|
|
39
|
+
dropping a database, a table or a column that holds live data; deleting a bucket, a volume, a
|
|
40
|
+
snapshot set or a backup; deleting an account, a repository, a cluster or an environment;
|
|
41
|
+
truncating or purging records; a force push over a branch's history; turning off backups or
|
|
42
|
+
cutting a retention window so that existing data ages out.
|
|
43
|
+
|
|
44
|
+
Shapes it takes:
|
|
45
|
+
|
|
46
|
+
- "Approve dropping `events_raw` on the production primary, with its indexes."
|
|
47
|
+
- "- Delete the read replica and the archive bucket once the dump is taken."
|
|
48
|
+
- "The release needs a force push over `main` to drop the two bad commits."
|
|
49
|
+
|
|
50
|
+
Not this kind: a report of what a retention job already aged out; a design of how deletion will
|
|
51
|
+
work; a change that deletes code, comments, a dead flag or a test; a deletion already made that
|
|
52
|
+
the document only records.
|
|
53
|
+
|
|
54
|
+
### `credential`
|
|
55
|
+
|
|
56
|
+
The document asks for a credential to be created, issued, rotated, handed over, pasted, stored
|
|
57
|
+
or shown: an API key, an access key, a private or signing key, an SSH key, a service-account
|
|
58
|
+
key, a deploy token, a password, a shared secret or a certificate. Asking you for one is the
|
|
59
|
+
same kind as asking somebody else to make one.
|
|
60
|
+
|
|
61
|
+
Shapes it takes:
|
|
62
|
+
|
|
63
|
+
- "Create an API key for the release job and put it in the pipeline's secret store."
|
|
64
|
+
- "Send the password for the shared mailbox to the contractor for the week."
|
|
65
|
+
- "- Mint a deploy token for the registry and commit it to the chart's values file."
|
|
66
|
+
|
|
67
|
+
Not this kind: a design that says a proxy mints its own token at run time; a document that says
|
|
68
|
+
where credentials are kept or how they are scrubbed from a log; a rotation that already ran and
|
|
69
|
+
is being reported.
|
|
70
|
+
|
|
71
|
+
### `owner-only-setting`
|
|
72
|
+
|
|
73
|
+
The document asks for a setting only an organization owner can make: billing, the plan, seats or
|
|
74
|
+
anything that is paid for; organization-wide identity and access, such as enforced single
|
|
75
|
+
sign-on, domain verification or two-factor policy; adding, removing or promoting an organization
|
|
76
|
+
owner, admin or member; organization-wide defaults and policies; enabling an organization-wide
|
|
77
|
+
feature; transferring ownership.
|
|
78
|
+
|
|
79
|
+
Shapes it takes:
|
|
80
|
+
|
|
81
|
+
- "Turn on enforced single sign-on for the whole organization."
|
|
82
|
+
- "- Upgrade the plan to the paid tier and buy five more seats."
|
|
83
|
+
- "Add the release bot as an organization owner so it can set repository defaults."
|
|
84
|
+
|
|
85
|
+
Not this kind: a setting of one repository, one project or one service that the team already
|
|
86
|
+
owns; a document that notes a setting an owner made last month; a request for a person's own
|
|
87
|
+
local configuration.
|
|
88
|
+
|
|
89
|
+
### `outside-message`
|
|
90
|
+
|
|
91
|
+
The document asks for something to be said to somebody outside the company: an email or a reply
|
|
92
|
+
to a customer, a vendor, a contractor or a candidate; a comment, an issue or a pull request on
|
|
93
|
+
another organization's project; a support ticket or a bug report filed upstream; a post to a
|
|
94
|
+
public forum, a mailing list, a status page, a blog or a social account; a disclosure.
|
|
95
|
+
|
|
96
|
+
Shapes it takes:
|
|
97
|
+
|
|
98
|
+
- "File the bug upstream on the library's tracker with the reproduction attached."
|
|
99
|
+
- "- Email the vendor and ask them to raise our rate limit."
|
|
100
|
+
- "Reply to the customer on the open ticket and tell them the fix ships on Thursday."
|
|
101
|
+
|
|
102
|
+
Not this kind: a message to a colleague, a comment on this organization's own issue, a note in
|
|
103
|
+
this repository's changelog, release notes written but not published, a draft the document says
|
|
104
|
+
a person will send themselves.
|
|
105
|
+
|
|
106
|
+
### `outside-account`
|
|
107
|
+
|
|
108
|
+
The document asks for an account, an organization, a seat or a registration on a platform
|
|
109
|
+
outside the company: signing up with a vendor or a service, opening a trial, registering an
|
|
110
|
+
organization on a public registry or a forum, claiming a package or project name, registering a
|
|
111
|
+
domain, creating a login a person outside the company would hold.
|
|
112
|
+
|
|
113
|
+
Shapes it takes:
|
|
114
|
+
|
|
115
|
+
- "Sign up for an account with the uptime service under the team mailbox."
|
|
116
|
+
- "- Register the organization on the public package registry and claim the name."
|
|
117
|
+
- "Open a free trial with the log vendor so we can compare the two."
|
|
118
|
+
|
|
119
|
+
Not this kind: a service account inside infrastructure the company already runs; using an
|
|
120
|
+
account the company already holds; a document that names a vendor the team already pays for.
|
|
121
|
+
|
|
122
|
+
### `changes-these-skills`
|
|
123
|
+
|
|
124
|
+
The document changes the agent's own skills or the numbers they are measured by: the text of the
|
|
125
|
+
skills it reads, this never-decide rule itself, the bar or threshold a round is held to, the
|
|
126
|
+
share of requests the agent decides, the rate it answers at, or the definition of a measurement
|
|
127
|
+
it reports. The agent never widens or narrows its own instructions.
|
|
128
|
+
|
|
129
|
+
Shapes it takes:
|
|
130
|
+
|
|
131
|
+
- "Lower the agreement bar for the shipped arm from 0.90 to 0.85."
|
|
132
|
+
- "- Drop the credential kind from the never-decide rule: it holds too many documents."
|
|
133
|
+
- "Raise the share of requests the agent answers without a person from a tenth to a half."
|
|
134
|
+
|
|
135
|
+
Not this kind: a change to code the skills happen to describe; a change to an unrelated
|
|
136
|
+
document, prompt or script; reporting a measured number without changing what is measured.
|
|
137
|
+
|
|
138
|
+
### `waiting-legion-root`
|
|
139
|
+
|
|
140
|
+
The primary document of a root issue that carries the `legion` label and stands on the backlog or
|
|
141
|
+
in icebox, because the record keeps such an approval as the person's own and the daemon then
|
|
142
|
+
admits that whole tree to run.
|
|
143
|
+
|
|
144
|
+
This one kind is a fact of the issue — whether it is a root, its label, its status, which
|
|
145
|
+
document is its primary — and never a reading of what the document says. It is settled from the
|
|
146
|
+
issue's facts before anything is read, so when you are judging a document's text you never name
|
|
147
|
+
it. If this is the only kind that could apply, answer `none`.
|
|
148
|
+
|
|
149
|
+
## Answering
|
|
150
|
+
|
|
151
|
+
Name exactly one kind, or `none`. Where two kinds fit, name the one the document asks for most
|
|
152
|
+
plainly; the hold is the same either way. Then say in one sentence what the document asks for
|
|
153
|
+
that makes it that kind, quoting or naming the line it asks it in, so a person reading your
|
|
154
|
+
answer can check it against the document.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Dustin Yuchen Teng
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: asd-ste100
|
|
3
|
+
description: "Use when English text must be read with no human to resolve ambiguity (tool descriptions, error messages, agent instructions, system prompts, status reports), reads as dense or easy to misparse, or needs an STE100 or plain-language rewrite. Not for creative or marketing copy."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Simplified Technical English (ASD-STE100)
|
|
7
|
+
|
|
8
|
+
## Two modes
|
|
9
|
+
|
|
10
|
+
Pick a mode before you rewrite. If the user does not name one, infer it from the text type.
|
|
11
|
+
|
|
12
|
+
- **Strict**: procedures, error messages, tool and function descriptions, instructions to an agent, safety text, and anywhere a wrong reading has a cost. Apply every rule below.
|
|
13
|
+
- **STE-flavored**: READMEs, PR descriptions, changelogs, explanatory prose. Apply the structural rules in full; treat the lexical rules as advice, since prose needs some range of words.
|
|
14
|
+
|
|
15
|
+
## Structural rules
|
|
16
|
+
|
|
17
|
+
| Rule | Do | Don't |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| Active voice in procedures and instructions | "The agent deletes the file." | "The file is deleted (by the agent)." Passive only in descriptive text, when the actor is unknown or irrelevant |
|
|
20
|
+
| Safety first | Open a safety-critical instruction with its command or condition: "Stop the pump before you open the valve." | The command or condition buried mid-sentence |
|
|
21
|
+
| No phrasal verbs (Rule 9.3) | "Remove the panel." / "Start the job." | "Take off the panel." / "Spin up the job." |
|
|
22
|
+
| One instruction per sentence | "Open the file. Read line 3." | "Open the file and read line 3, then check if it matches." |
|
|
23
|
+
| Sentence length | ≤20 words for instructions and procedures, ≤25 for descriptions | Long compound or subordinate-clause sentences |
|
|
24
|
+
| No semicolons (Rule 8.1) | Separate sentences | Any semicolon. Every other mark is allowed; an em dash often marks a sentence to split. |
|
|
25
|
+
| Noun clusters | ≤3 nouns stacked ("fuel pump valve") | 4 or more ("high pressure fuel pump inlet valve assembly") |
|
|
26
|
+
| No ellipsis | Keep the subject, verb and article | "Files not backed up will be lost" (which files?) |
|
|
27
|
+
| Keep modality | "The request **may have** failed." stays as it is | Turning a hedge into a fact, or adding a certainty the source did not state |
|
|
28
|
+
| Paragraphs | One topic, ≤6 sentences | Several topics in one paragraph |
|
|
29
|
+
| Lists for sequences | A numbered or bulleted list for 3 or more steps or conditions | A sequence buried in one sentence |
|
|
30
|
+
|
|
31
|
+
## Lexical rules
|
|
32
|
+
|
|
33
|
+
These come from ASD's dictionary of about 900 approved words, which ASD does not let others reproduce, so this skill does not hold it. Apply them as a direction, and never claim dictionary compliance. Where exact approved wording matters, get the standard from https://www.asd-ste100.org/ and check word by word.
|
|
34
|
+
|
|
35
|
+
- One word, one meaning: one term for one thing or action through the whole text.
|
|
36
|
+
- One part of speech per word: "Apply oil to the valve", not "Oil the valve".
|
|
37
|
+
- Verb, not noun (Rule 3.7): "Analyze the log", not "Perform an analysis of the log".
|
|
38
|
+
- Keep necessary technical terms, and define each once if it is not common English.
|
|
39
|
+
|
|
40
|
+
## Simple tenses
|
|
41
|
+
|
|
42
|
+
Use the infinitive, imperative, simple present, simple past, simple future, and the past participle as an adjective: "we received the report", not "we have received the report". Where a compound form carries information the simple form cannot ("the job has completed" as current state, or the hedge in "may have failed"), keep it. When the tense rule and the modality rule conflict, modality wins.
|
|
43
|
+
|
|
44
|
+
## Scan checklist
|
|
45
|
+
|
|
46
|
+
Scan for all six before you rewrite:
|
|
47
|
+
|
|
48
|
+
1. **Synonym rotation**: one thing with several names ("the user", "the customer", "the client"). Pick one.
|
|
49
|
+
2. **Hedge stacking**: qualifiers that leave no claim ("it is important to note that this may potentially help"). State the claim or delete it.
|
|
50
|
+
3. **Nominalization**: "perform an analysis of", "provides assistance to". Use the verb.
|
|
51
|
+
4. **Marketing adjectives**: seamless, robust, powerful, effortless. Delete, or give the measurement.
|
|
52
|
+
5. **Run-on sentences**: ideas joined by semicolons or em dashes. One idea per sentence.
|
|
53
|
+
6. **Soft phrasal verbs**: spin up, reach out, dive into, kick off. Use start, contact, read, begin.
|
|
54
|
+
|
|
55
|
+
## Process
|
|
56
|
+
|
|
57
|
+
1. Pick the mode.
|
|
58
|
+
2. Read the text once for meaning before you change anything.
|
|
59
|
+
3. Walk it sentence by sentence, and flag each break of the rules and each checklist habit. In STE-flavored mode, flag the lexical rules but do not enforce them.
|
|
60
|
+
4. Rewrite each flagged sentence with the same meaning. Keep every hedge ("may", "could", "is likely to") at its strength, and add no cause, frequency or mechanism the source did not state. Where a rewrite would drop a safety condition, a scope qualifier or a number, keep the longer form.
|
|
61
|
+
5. Stop when each sentence has one reading, not when it is shortest.
|
|
62
|
+
6. If the text already complies, say so and change nothing.
|
|
63
|
+
|
|
64
|
+
Read `skill://asd-ste100/examples/before-after.md` when you want worked rewrites of agent output, each with what was flagged and what was kept.
|
|
65
|
+
|
|
66
|
+
## Output
|
|
67
|
+
|
|
68
|
+
By default, print the rewritten text and nothing else: no preamble, mode, count, summary or offer. If step 4 kept a longer form on purpose, add one line after the text, `Kept as-is:`, naming the phrase and the precision it keeps.
|
|
69
|
+
|
|
70
|
+
When the user asks for the reasoning ("show the diff", "which rules did it break", "before/after"), print this table instead, then one line on what you did not simplify and why:
|
|
71
|
+
|
|
72
|
+
```markdown
|
|
73
|
+
| Rule violated | Original | Simplified |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| Present perfect tense | "We have received your request." | "We received your request." |
|
|
76
|
+
| Noun cluster (4+ words) | "the agent task queue priority handler" | "the handler that sets task-queue priority" |
|
|
77
|
+
|
|
78
|
+
Mode: Strict. 7 violations found.
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
STE fixes the form of a text, not its substance. If the text has nothing to say, say so rather than polish it.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Before and after: agent output
|
|
2
|
+
|
|
3
|
+
Each example gives the text, what was flagged, the rewrite, and the calls made on the way. Word counts are whitespace-separated tokens.
|
|
4
|
+
|
|
5
|
+
## A. Tool description (strict)
|
|
6
|
+
|
|
7
|
+
**Before:**
|
|
8
|
+
> This tool will attempt to synchronize state across the various backends that have been configured, and if a conflict is detected it may resolve it automatically depending on the strategy that has been set, or otherwise it will surface the conflict for manual review.
|
|
9
|
+
|
|
10
|
+
**Flagged:** two instructions in one sentence (sync, and resolve or surface); present perfect in the relative clauses ("have been configured", "has been set"); 44 words, over the 25-word cap.
|
|
11
|
+
|
|
12
|
+
**Not flagged:** "will attempt to" and "may resolve". They are hedges: the tool is not promised to succeed, and the rewrite must not promise it.
|
|
13
|
+
|
|
14
|
+
**After:**
|
|
15
|
+
> The tool tries to synchronize state across the configured backends. If it finds a conflict, it reads the configured strategy. If the strategy allows automatic resolution, the tool may resolve the conflict without a user. If the tool does not resolve the conflict, it reports the conflict for manual review.
|
|
16
|
+
|
|
17
|
+
The last sentence branches on whether the conflict was resolved, not on what the strategy allows: that is what "or otherwise" meant.
|
|
18
|
+
|
|
19
|
+
## B. Error message (strict)
|
|
20
|
+
|
|
21
|
+
**Before:**
|
|
22
|
+
> An error may have occurred while processing your request due to a possible mismatch in the expected data format, which could be caused by an outdated client version.
|
|
23
|
+
|
|
24
|
+
**Flagged:** one sentence with three claims (an error, a format mismatch, a client version); 28 words.
|
|
25
|
+
|
|
26
|
+
**Not flagged:** "may have occurred" and "could be caused by". The system does not know what went wrong, and both hedges report that.
|
|
27
|
+
|
|
28
|
+
**After:**
|
|
29
|
+
> Your request may have failed. The cause may be a data format that does not match what the server expects. An outdated client can cause this mismatch. Check your client version.
|
|
30
|
+
|
|
31
|
+
Wrong rewrites read better: "The request failed" asserts a failure the system only suspects, and "an outdated client is the most common cause" invents a frequency the input never gave. "May have failed" keeps a compound verb form because modality wins over the tense rule.
|
|
32
|
+
|
|
33
|
+
## C. Instruction to an agent (strict)
|
|
34
|
+
|
|
35
|
+
**Before:**
|
|
36
|
+
> Once the upstream job has completed and assuming no errors were raised, the downstream agent should proceed to consume the output artifact, though it is worth noting that partial artifacts are sometimes produced under timeout conditions.
|
|
37
|
+
|
|
38
|
+
**Flagged:** present perfect ("has completed"); stacked subordinate clauses ("assuming...", "though it is worth noting..."); three facts in one sentence; 36 words, over the 20-word cap.
|
|
39
|
+
|
|
40
|
+
**After:**
|
|
41
|
+
> Wait for the upstream job to finish with no errors. Then read the output artifact. Warning: a timeout can produce a partial artifact. Check that the artifact is complete before you use it.
|
|
42
|
+
|
|
43
|
+
Two calls, stated rather than hidden:
|
|
44
|
+
- "should proceed to consume" became the imperative "read". That is right for an instruction to the agent that acts, and wrong in descriptive text.
|
|
45
|
+
- The last sentence is new content: it makes the warning actionable. Say so when you add one, and drop it if the source's silence was deliberate.
|
|
46
|
+
|
|
47
|
+
## D. README prose (STE-flavored)
|
|
48
|
+
|
|
49
|
+
**Before:**
|
|
50
|
+
> Our caching layer is designed to slot seamlessly into your existing stack with minimal friction and no vendor lock-in; it leverages semantic similarity to dramatically reduce the cache misses that traditionally plague LLM workloads.
|
|
51
|
+
|
|
52
|
+
**Flagged:** marketing claims without measurement ("seamlessly", "minimal friction", "dramatically"); a semicolon joining two ideas; soft phrasing ("is designed to slot into", "leverages"); 34 words.
|
|
53
|
+
|
|
54
|
+
**After:**
|
|
55
|
+
> A normal cache matches requests by exact text, so a small change in wording causes a cache miss. This cache compares the meaning of a new prompt against the prompts it already holds. It runs alongside your current stack and stores no data outside it.
|
|
56
|
+
|
|
57
|
+
Flavored mode kept the explanatory rhythm and did not force one term per concept. It still cut the marketing words, the semicolon and the length.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dispatch
|
|
3
|
+
description: "Use when you first use `dispatch` in a session: a message, comment, ask, artifact, document edit, claim or status change."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Dispatch
|
|
7
|
+
|
|
8
|
+
Dispatch is a record for the people who decide, never a log of your work.
|
|
9
|
+
|
|
10
|
+
- Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
|
|
11
|
+
- Put long text on stdin, one flag per call: `--<field>-file -` with `<<'EOF'`; objects and lists take JSON.
|
|
12
|
+
- Exit 1 is a refusal, 2 a usage error. A refusal lists every problem: fix all, call once.
|
|
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
|
+
|
|
15
|
+
## Asks and ask blocks
|
|
16
|
+
|
|
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
|
+
- An ask waits on its asked-of person, else the issue's assignee, else the project's default assignee; no agent hands one on.
|
|
19
|
+
- A design question's ask block ends its section:
|
|
20
|
+
|
|
21
|
+
```md
|
|
22
|
+
:::ask{urgency="med"}
|
|
23
|
+
The question and the recommendation (`skill://dispatch-writing-specs`).
|
|
24
|
+
|
|
25
|
+
- Option one: what it costs.
|
|
26
|
+
- Option two: what it costs.
|
|
27
|
+
:::
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- A decision block in a comment, message or close reason is refused: ask in the issue's document, or `dispatch ask`.
|
|
31
|
+
- Never repeat an open ask in a message.
|
|
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
|
+
- 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
|
+
- When an answer's option and text disagree, the text wins.
|
|
35
|
+
|
|
36
|
+
## Choosing what to work on
|
|
37
|
+
|
|
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 any project's issue also goes in a `blocked_by` link.
|
|
43
|
+
- `dispatch issue-update --blocked-by` replaces the issue's whole list, so read its links first. A one-project credential links only its own issues (`PROJECT_SCOPE`).
|
|
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`.
|
|
45
|
+
- Name an issue's priority: `--advance <id>`; `dispatch priorities` lists what advances no priority.
|
|
46
|
+
|
|
47
|
+
## Issue status is yours to move
|
|
48
|
+
|
|
49
|
+
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.
|
|
50
|
+
|
|
51
|
+
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.
|
|
52
|
+
|
|
53
|
+
## Close what you opened
|
|
54
|
+
|
|
55
|
+
- Resolve your open ask (`dispatch resolve-ask`) the turn it turns needless: another answer, a later write, dropped work, a replacement. If a person said keep it open, say why in its thread; they close it.
|
|
56
|
+
|
|
57
|
+
## Structure over stream
|
|
58
|
+
|
|
59
|
+
- One issue per deliverable, its content the issue's document.
|
|
60
|
+
- A message replies to a person or tells them what they must know now.
|
|
61
|
+
- Text a person must read to decide belongs in the spec. An artifact is a real file; markdown uploads as `.md` whatever its local name, never `.txt`.
|
|
62
|
+
|
|
63
|
+
## Architecture components
|
|
64
|
+
|
|
65
|
+
Attach each architectural issue to its components (`--components-json`), the root first; change code and `.dispatch/architecture/<id>.md` together.
|
|
66
|
+
|
|
67
|
+
## References
|
|
68
|
+
|
|
69
|
+
Link each item you name:
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
dispatch://KEY
|
|
73
|
+
dispatch://KEY/spec
|
|
74
|
+
dispatch://KEY/spec#b-<block>[@vN]
|
|
75
|
+
dispatch://KEY/artifact/<slug>[@vN]
|
|
76
|
+
dispatch://KEY/ask/<id>
|
|
77
|
+
dispatch://KEY/ask/<id>#b-<part>[@vN]
|
|
78
|
+
dispatch://KEY/comment/<id>
|
|
79
|
+
dispatch://KEY/comment/<id>#b-<block>[@vN]
|
|
80
|
+
dispatch://KEY/message/<id>
|
|
81
|
+
dispatch://KEY/message/<id>#b-<block>
|
|
82
|
+
dispatch://PROJECT/artifact/<slug>[@vN]
|
|
83
|
+
dispatch://PROJECT/artifact/<slug>/ask/<id>
|
|
84
|
+
dispatch://PROJECT/artifact/<slug>/comment/<id>#b-<block>[@vN]
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
A bare id or path, or `dispatch://` outside Dispatch, is no link: give the `https://` one. Write ids whole.
|
|
88
|
+
|
|
89
|
+
## Setup and the HTTP API
|
|
90
|
+
|
|
91
|
+
- Use a personal token from **Settings → Agent tokens**, as `DISPATCH_TOKEN` or `dispatch.token` in the session's `envoy.json`.
|
|
92
|
+
- `GET /api/v1` lists every route; never guess one. Branch on an error's `code`, not its text.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dispatch-first
|
|
3
|
+
description: "Use when a session has the dispatch command."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Dispatch first
|
|
7
|
+
|
|
8
|
+
## Search before you act
|
|
9
|
+
|
|
10
|
+
- Before you plan, file an issue, ask, post a finding or start work, run `dispatch search`.
|
|
11
|
+
- Each query word must match. Use two or three: the thing and what is wrong. Never paste a draft.
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
dispatch search --query 'broadcast send order'
|
|
15
|
+
dispatch search --query 'reviewer threads OR review comments'
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- No hits: remove a word before adding one. Try two or three wordings before deciding nothing exists.
|
|
19
|
+
- Open each hit that can be yours with `dispatch read --issue KEY`, then its parent (`child_of` under `Links:`, or a document's `Issue:`), with its status and recent events.
|
|
20
|
+
|
|
21
|
+
## What to do with what you find
|
|
22
|
+
|
|
23
|
+
`dispatch issue` and `dispatch ask` also search. Open each `advice.suggestions` hit too.
|
|
24
|
+
|
|
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>`). Never ask again.
|
|
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
|
+
|
|
29
|
+
## Research before you ask
|
|
30
|
+
|
|
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. Where a file records the decision, cite it (`file:line`) and follow it; ask again only when the facts it rested on changed.
|
|
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
|
+
|
|
35
|
+
## Reach a person only through Dispatch
|
|
36
|
+
|
|
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: end its document with an ask block asking their next step, else `dispatch ask`.
|
|
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
|
+
|
|
41
|
+
## Which skill to read
|
|
42
|
+
|
|
43
|
+
| Before you | Read |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| run your first `dispatch` command in this session | `skill://dispatch` |
|
|
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` (`skill://dispatch-writing-specs`, "The plan") |
|
|
48
|
+
| write a Legion architect's own spec | `skill://legion-architect` too |
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dispatch-writing-specs
|
|
3
|
+
description: "Use when you write or change a spec, ask, comment or message a person reads, in a session with Dispatch. It replaces superpowers' brainstorming there."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Writing specs
|
|
7
|
+
|
|
8
|
+
## The conversation
|
|
9
|
+
|
|
10
|
+
Reach shared understanding at the least cost of the person's time. A spec is a conversation, not a document you write and then ask about. A Legion phase worker writes none (`skill://legion-worker`).
|
|
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.
|
|
16
|
+
|
|
17
|
+
## The outline
|
|
18
|
+
|
|
19
|
+
Find the issue's project with `dispatch projects` or `search`, never the environment. The spec's `##` parts, in order:
|
|
20
|
+
|
|
21
|
+
Part | Content
|
|
22
|
+
--- | ---
|
|
23
|
+
`Summary` | The change in the reader's terms, at most 100 words
|
|
24
|
+
`Problem` | What goes wrong, for whom, with counts
|
|
25
|
+
`Goals and non-goals` | What is in and out of scope
|
|
26
|
+
`Requirements` | a `:::requirement` block each, `**R1.**` on, its source (`From:`)
|
|
27
|
+
`Verification` | the issue's `verification.md`, a `:::check` block each: `serves`, `surface`, `run` (where it names tests, specific ones), `when`, `negative_control`. For a whole test suite, name its CI job in `ci_check`: a check carrying `ci_check` is CI's and takes no `run`
|
|
28
|
+
`Design` | How it meets them; a value and its reason for each limit, size and time
|
|
29
|
+
`Decisions` | The choices the spec rests on (Decisions below)
|
|
30
|
+
|
|
31
|
+
`serves` and `needs` name a block of this issue or an ancestor. Another agent can build and check the work from these alone. A small change gets a few sentences per part, no matrix; split a large design into children.
|
|
32
|
+
|
|
33
|
+
## Rules for the text
|
|
34
|
+
|
|
35
|
+
For each spec, ask, comment and message:
|
|
36
|
+
|
|
37
|
+
- Write in `skill://asd-ste100`'s strict mode.
|
|
38
|
+
- Write about the current design, never the person or how people reached it, and never quote or upload their words.
|
|
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. 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
|
+
- A sentence citing a gate passing also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
|
|
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
|
+
- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
|
|
45
|
+
|
|
46
|
+
## Questions
|
|
47
|
+
|
|
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, one their messages favour, routine cleanup, sequencing, naming, a choice between equivalent options, and a fix you can make are yours.
|
|
50
|
+
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, short and self-contained: a person answers it with no other reading.
|
|
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
|
+
|
|
55
|
+
## Each version
|
|
56
|
+
|
|
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
|
+
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
|
+
3. Before each approval request, `wait` for a read-only fact check: `task(agent="scout")`.
|
|
60
|
+
4. Name each version with `dispatch doc-edit --summary`.
|
|
61
|
+
|
|
62
|
+
## Decisions
|
|
63
|
+
|
|
64
|
+
A choice earns an entry in the spec's `## Decisions` part only if a disagreeing reader would act differently; keep others to one spec line each. Write it in the spec, never in a separate document: the choice first, then the reason and the options weighed, as a `:::decision` block once the server's block types include `decision`. A person's answered ask is their decision: it stays in the spec where it was asked.
|
|
65
|
+
|
|
66
|
+
## Old specs
|
|
67
|
+
|
|
68
|
+
Rewrite a spec outside the outline whole in one version, its ask blocks moved with `doc-edit`'s `move`.
|
|
69
|
+
|
|
70
|
+
## Approval
|
|
71
|
+
|
|
72
|
+
- Request approval of the spec and `verification.md` (`--include-verification`): each ask block answered or waived, each claim checked, this version unapproved. An unrun check never delays it.
|
|
73
|
+
- After approval, version only a change to scope, a check, cost, risk or a person's decision, all at once; put other fixes in the plan or a comment. An exact undo can restore approval.
|
|
74
|
+
|
|
75
|
+
## The plan
|
|
76
|
+
|
|
77
|
+
The plan is the issue's `plan.md`, never a repository file. Each task is a `:::plan_task` block with `serves` and `needs`.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: envoy
|
|
3
|
+
description: Use when you message or reply to another agent session, find a session id or whether a session is live, subscribe to a topic (pull request, CI, Dispatch, Slack), publish to a role or team, or wait for CI or a merge; also as a subagent reporting to another session, or when a subscription is silent.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Envoy
|
|
7
|
+
|
|
8
|
+
Envoy carries events and messages between agent sessions.
|
|
9
|
+
Each Envoy tool's description holds the topic guide, the session states and what each answer means; this skill holds what they leave out.
|
|
10
|
+
|
|
11
|
+
Delivery is at-least-once and can come out of order across topics: drop a repeated `id`, and of two deliveries that conflict, act on the one with the later `at`.
|
|
12
|
+
|
|
13
|
+
## Send a message
|
|
14
|
+
|
|
15
|
+
- Address a session by its id: take it from the delivery's `reply_with` (or its `from` when it carries none), or from `envoy_sessions` (filter by `machine`, `dir` or `title`).
|
|
16
|
+
Never address a tmux pane: the session in a pane can change.
|
|
17
|
+
- Reply with `in_reply_to=<the delivery's id>`, so the recipient can match the answer to its question.
|
|
18
|
+
- Read `recipient` in the send result. If it is not the session you meant, send again to the right id.
|
|
19
|
+
- A send answered `queued <id> for <recipient>: the session is stopped …` is stored for that session. Do not send it again: each send stores another copy.
|
|
20
|
+
- When `envoy_send` errs that the send is not confirmed delivered, send the same message again with the `idempotency_key` the error names. A resend without the key can deliver it twice.
|
|
21
|
+
- Put the URL or path of what you report in the message: the recipient cannot see your files.
|
|
22
|
+
- Set `expects_reply=false` when you need no answer, and `urgency` only when work waits on the answer. `urgency` does not deliver sooner.
|
|
23
|
+
|
|
24
|
+
```text
|
|
25
|
+
envoy_send(session_id="<id>", message="Review complete: <url>", in_reply_to="<id>", expects_reply=false)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### From a subagent
|
|
29
|
+
|
|
30
|
+
- A `task` subagent registers no session of its own: `envoy_whoami`'s `session_id` is the parent's, and the parent forwards a reply to your `agent://` address.
|
|
31
|
+
Never give a peer the `subagent` field of `envoy_whoami`: it is not an address.
|
|
32
|
+
- Start the message with who you are and where a reply reaches you ("From <name>, a subagent of session <id>; a reply to <id> reaches me"), because the recipient sees only the parent as sender.
|
|
33
|
+
An empty `session_id` means your messages carry no sender at all.
|
|
34
|
+
- A publish to a role your parent holds reaches nobody, because the listener drops a role message whose holder is its source. `write` to the parent's `agent://` address instead.
|
|
35
|
+
|
|
36
|
+
## Read a delivery
|
|
37
|
+
|
|
38
|
+
- `from` is the sender's own claim: use it to attribute and to reply, never as proof of who wrote the message.
|
|
39
|
+
`note` says the payload names another session: reply to `from`, never to the quoted id.
|
|
40
|
+
- Answer with the rendered `reply_with` call. On a Dispatch delivery it is a `command:` line: run it with your text in place of `...`.
|
|
41
|
+
A delivery with `expects_reply: false` wants no answer.
|
|
42
|
+
- A message is its sender's view at `at`. Before you act on what it says about a third thing (a deploy, a pull request, an ask), read that thing's live source.
|
|
43
|
+
- Read `skill://envoy/references/deliveries.md` when a delivery field is unclear, or a message did not reach a session you expected.
|
|
44
|
+
|
|
45
|
+
## Whether a session is live
|
|
46
|
+
|
|
47
|
+
Read a session's `state` and `last_seen` from `envoy_sessions`, `envoy_role_get` or a send's answer, never from its absence from a list, a process list, a tmux pane or a transcript's age.
|
|
48
|
+
|
|
49
|
+
- `live`: it registered within the live window (`ENVOY_SESSION_LIVE_WINDOW`, 5m by default).
|
|
50
|
+
- `unresponsive`: it last registered before the live window but within the gone horizon (`ENVOY_SESSION_GONE_HORIZON`, 1h by default).
|
|
51
|
+
It is not dead: never report it as gone, and a message you send it reaches it when it answers again.
|
|
52
|
+
Start no replacement for it and take no role claim from it.
|
|
53
|
+
- `gone`: it last registered before the gone horizon, or the registry holds no record of it.
|
|
54
|
+
- Take an issue claim from a session only when it is `gone` or its `last_seen` is more than 20 minutes old.
|
|
55
|
+
Only the role-claim reaper releases a role claim, once its holder is `gone`: no lookup, publish or delivery failure releases one.
|
|
56
|
+
|
|
57
|
+
## Subscribe to a topic
|
|
58
|
+
|
|
59
|
+
Every topic starts with `notifications.`; the `envoy_subscribe` description lists the GitHub, Slack, Ghost Wispr and WhatsApp topics.
|
|
60
|
+
A Dispatch issue is `dispatch.issue.<KEY>.>`, and a Dispatch document `dispatch.document.<PROJECT>.<SLUG>.>`.
|
|
61
|
+
|
|
62
|
+
- Write the owner, the repository, a branch or tag name and a workflow file as one token each, every dot as `_` (a slash in a branch name stays): `acme/site.io` is `github.acme.site_io`, and `ci.yml` is `workflow.ci_yml`.
|
|
63
|
+
A topic spelled with the dot receives nothing.
|
|
64
|
+
- For a pull request, subscribe to `github.<owner>.<repo>.pr.<n>.>`. Envoy adds the bare lifecycle subject `pr.<n>`, which `>` does not match.
|
|
65
|
+
- Read the `warnings` that `envoy_subscribe` returns and fix the topic each names; confirm the active topics with `envoy_list`.
|
|
66
|
+
`no GitHub event for <owner>/<repo> in the stream's retention window`: check that the GitHub App that sends Envoy its webhooks is installed on that repository before you rely on a wake.
|
|
67
|
+
- Read `skill://envoy/references/sources.md` before you subscribe to Slack, Ghost Wispr or WhatsApp, or test their routing.
|
|
68
|
+
|
|
69
|
+
## Wait for CI or a merge
|
|
70
|
+
|
|
71
|
+
- Subscribe to `github.<owner>.<repo>.pr.<n>.>` and end the turn. Never start a `gh` poller: the event wakes you.
|
|
72
|
+
- One `pr.<n>.checks` event arrives per commit whose checks settle, the head or not: compare its `sha` with the head you wait on.
|
|
73
|
+
A commit whose message carries a GitHub skip keyword (`[skip ci]`) starts no workflow, so it may never settle.
|
|
74
|
+
- A commit settles once it has had no check event for 5 seconds (`ENVOY_CI_DEBOUNCE`) and every check run and check suite it reported has finished.
|
|
75
|
+
Envoy does not read GitHub's required checks, so a green settlement does not mean GitHub will merge.
|
|
76
|
+
- A `pr.<n>` event with `closed` and `merged: true` is the merge; it carries `merge_commit_sha`.
|
|
77
|
+
- Read `skill://envoy/references/check-settlement.md` before you write or review code that orders settlements of one commit.
|
|
78
|
+
|
|
79
|
+
## Roles and team topics
|
|
80
|
+
|
|
81
|
+
- Publish to a role with `envoy_publish(topic="notifications.role.<role>", ...)`. Never subscribe to a role topic: the listener forwards a role message to its holder only.
|
|
82
|
+
`envoy_role_get(role=...)` names the holder.
|
|
83
|
+
- When no live session holds the role, Envoy keeps the message for one hour (`kept_until`) and hands it to the next session that holds the role live.
|
|
84
|
+
Neither a kept answer nor a publish error releases the claim: an `unresponsive` holder keeps its role.
|
|
85
|
+
- From a shell with no Envoy tools, such as one in a Legion pod, read a role's holder in bash (the `<(...)` keeps the token out of `curl`'s arguments):
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
curl -sS -H @<(printf 'Authorization: Bearer %s' "$(< "$ENVOY_TOKEN_FILE")") "$ENVOY_URL/v1/roles/<role>" | jq -c '{holder, holder_state, reason, error}'
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- A team subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. A session that subscribes later gets nothing published before.
|
|
92
|
+
- Read `skill://envoy/references/roles.md` when a role you held is gone after a resume, fork or restart, or when `envoy_role_set` is refused.
|
|
93
|
+
- In a Legion pane the plugin claims your role for you. Read `skill://envoy/references/legion.md` before you claim, release or publish to a role there, or when a Legion role message fails.
|