@sjawhar/pi-envoy 10.26.0 → 11.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/README.md +1 -1
- package/dist/dispatch.js +49 -30
- package/dist/envoy.js +27 -22
- package/dist/skills/dispatch/SKILL.md +54 -169
- package/dist/skills/dispatch-first/SKILL.md +23 -17
- package/dist/skills/dispatch-writing-specs/SKILL.md +76 -0
- package/package.json +1 -1
- package/dist/skills/dispatch/references/api.md +0 -21
- package/dist/skills/dispatch/references/asks.md +0 -43
- package/dist/skills/dispatch/references/document-edits.md +0 -59
- package/dist/skills/dispatch/references/documents.md +0 -79
- package/dist/skills/dispatch/references/examples.md +0 -85
- package/dist/skills/dispatch/references/issues.md +0 -66
- package/dist/skills/dispatch/references/messages.md +0 -31
- package/dist/skills/dispatch/references/reading.md +0 -32
- package/dist/skills/dispatch-brainstorming/SKILL.md +0 -56
|
@@ -1,200 +1,85 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dispatch
|
|
3
|
-
description: "Use
|
|
3
|
+
description: "Use before your first dispatch command in a session: a message, comment, ask, artifact, document edit, claim or status change."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Dispatch
|
|
7
7
|
|
|
8
|
-
Dispatch
|
|
8
|
+
Dispatch is a record for the people who decide, never a log of your work.
|
|
9
9
|
|
|
10
|
-
-
|
|
11
|
-
- Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`
|
|
12
|
-
- Exit
|
|
13
|
-
-
|
|
10
|
+
- Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives each command's rules and an example.
|
|
11
|
+
- Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`). Give object and list fields as JSON.
|
|
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` means the document is reloading and nothing was written. Wait a few seconds and repeat the call.
|
|
14
14
|
|
|
15
|
-
##
|
|
15
|
+
## Asks and ask blocks
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
- A question about a design a document records is an ask block (a decision block) at the end of its section, at each phase:
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
| write a typed block, comment, suggest, upload an artifact, request approval, or retry `DOC_SERVICE_UNAVAILABLE` | [Documents](skill://dispatch/references/documents.md) |
|
|
23
|
-
| choose, claim or move an issue, set priority, reorder a board, or audit a backlog | [Working an issue](skill://dispatch/references/issues.md) |
|
|
24
|
-
| route, edit, retract, resolve or reply to an open ask, or follow its thread | [Asks after they open](skill://dispatch/references/asks.md) |
|
|
25
|
-
| catch up after a restart, trace what cites a node, or write a `dispatch://` reference | [Reading back](skill://dispatch/references/reading.md) |
|
|
26
|
-
| answer a BTW, Aside or Steer frame, or an Agents-page message | [Targeted and direct messages](skill://dispatch/references/messages.md) |
|
|
27
|
-
| want a worked example | [Before and after](skill://dispatch/references/examples.md) |
|
|
28
|
-
| set up a token, or call a route no command covers | [Authentication and the HTTP API](skill://dispatch/references/api.md) |
|
|
19
|
+
```md
|
|
20
|
+
:::ask{urgency="med"}
|
|
21
|
+
The problem and why it matters. Recommendation: the option and its reason.
|
|
29
22
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
## Writing for the human
|
|
35
|
-
|
|
36
|
-
Every spec, ask, comment, message and PR body goes to a person who has not read the code. They do not share your vocabulary, and often read on a phone.
|
|
37
|
-
|
|
38
|
-
- Write plain English in full sentences, one idea each. Never use repo shorthand or nouns you coined ("fix 8c", "PR B", "spec@v3", "the pair"). Say what the thing is.
|
|
39
|
-
- Name a real product, tool operation (`dispatch request-approval`), event (`artifact.approved`), route, setting or status exactly. Say in a clause how it works. Never use a vague verb such as "notice", "accept", "tell" or "pick up" ([example](skill://dispatch/references/examples.md#naming-the-mechanism)).
|
|
40
|
-
- Expand each identifier on first use. Give an issue key or PR number its title, a file its purpose, a session id who it is. Link a URL, not a bare id.
|
|
41
|
-
- Describe a change first by what its reader stands to lose. Say who can do what today, what they cannot do after it, what still works, and what you cannot tell. Then name each mechanism. Write that first sentence with a human subject. A shorter engineering sentence is not a reader's sentence.
|
|
42
|
-
- When the text carries a judgment, lead with it in one sentence and put the mechanism under it. Then the judgment comes first, and the rule above shapes the sentence under it. This never pre-decides an open question or drops its real options.
|
|
43
|
-
- When you state a root cause or a blocker, include the command, error output or record that shows it, with its time. Without it, call the diagnosis a hypothesis. A diagnosis in progress can say so.
|
|
44
|
-
- Phone test before you post: can the human, reading only this text on a phone, know what they are told or asked? If not, rewrite. Density is the problem, not length.
|
|
45
|
-
|
|
46
|
-
A question lives in the spec or discussion it came from, as [Decision blocks](#decision-blocks) says, never as a compressed standalone ask. It carries the problem the reader recognises, why it matters now, what constrains the answer, and your recommendation with its reason. It asks how to solve the problem or which outcome is wanted. It never lists the choices: the options carry the different approaches, each a label and a description of what it costs.
|
|
47
|
-
|
|
48
|
-
## Writing a spec
|
|
49
|
-
|
|
50
|
-
A spec is the design conversation with the human, written down. It starts as the problem and its evidence: what goes wrong, for whom, and the counts or cases that show it. It grows in place. It is the issue's one primary document: extend it with a new version that keeps the human's text, never a second "spec" artifact.
|
|
51
|
-
|
|
52
|
-
- **Each open question is a decision block** ([Decision blocks](#decision-blocks)).
|
|
53
|
-
- **An answered decision block is the record.** It shows the chosen option, the person's words, who and when. Never restate it.
|
|
54
|
-
- **Mark an inference as one**, with its reasoning. A security concern, a restriction or a cost nobody measured is an inference, not a settled constraint. A point carried from another document keeps its provenance. `skill://dispatch-brainstorming` keeps an inference out of a live brainstorm's spec until the human agrees to it.
|
|
55
|
-
- **A decision from a comment, conversation or waiver has no rendered record.** Write it into the text in the person's words, quoted and dated. Name them from `dispatch whoami` or the conversation. If neither names them, write "the person". Never use a name you were not given.
|
|
56
|
-
- **Sections follow the topic.** No heading is required or fixed.
|
|
57
|
-
- **Rewrite a changed point. Do not append.** The decision block stays as the record. Versions keep the history.
|
|
58
|
-
- **No placeholders**: no TBD, TODO or hedging. An open item is a decision block or a two-lane contract you settle over Envoy. Or it is a technical decision your lane makes where the work happens, outside the spec.
|
|
59
|
-
- **No progress**: no status, timestamps, "Update HH:MMZ" sections, PR lists or handoff notes.
|
|
60
|
-
- **Repeated measurements** (hourly counts, a fleet table) go in one artifact that you edit in place, linked once from the spec. Never post them as ask replies or as new spec rows.
|
|
61
|
-
- **No commentary**: never call it a draft, version or turn, preview a later version, describe a correction, or narrate the exchange.
|
|
62
|
-
|
|
63
|
-
Before a version goes out, read it as the human will. No two passages conflict, each point has one reading, and each decision block passes the phone test.
|
|
64
|
-
|
|
65
|
-
## Decision blocks
|
|
66
|
-
|
|
67
|
-
A decision a human must make is an `:::ask{#slug}` block at the end of the section that discusses it. Shape it as [Writing for the human](#writing-for-the-human) says. Split what constrains it into measured, known and unknown. Give 2–4 options and a recommendation, with the trade-off in the prose around it. It asks how to solve the problem, never whether to apply a change already chosen.
|
|
68
|
-
|
|
69
|
-
- Never gather decisions in a list, at the top, at the bottom, or in an "open questions" section. Never ask one as a standalone `dispatch ask` that points at the spec.
|
|
70
|
-
- Prose questions reach nobody. Only the block reaches the Inbox. A spec with no blocks is right only when no human decision is needed.
|
|
71
|
-
- Fix a pile with `move`, not a rewrite. `dispatch doc-edit --ops-json '[{"op":"move","block":"<block-uuid>","after":"<last sentence of its section>"}]'` keeps the ask, its answer and its followers. Move the lifted context the same way and delete the empty section. An ask block has two different ids ([Editing a document](skill://dispatch/references/document-edits.md)).
|
|
72
|
-
- Syntax and checks: [Typed blocks](skill://dispatch/references/documents.md#typed-blocks). Whether to ask at all: [Before you ask](#before-you-ask).
|
|
73
|
-
|
|
74
|
-
## Your owner
|
|
75
|
-
|
|
76
|
-
- Every owner-scoped command takes exactly one owner. That is `--issue` (a key such as `LEGION-3`, `owner/repo#n`, or a bare number for the cwd repository), or `--project` with `--artifact`. Legion pre-fills `--issue` from `LEGION_ISSUE`.
|
|
77
|
-
- An external reference addresses the Dispatch issue linked to it. If none is linked, create one: `dispatch issue --external owner/repo#n --project <project> --title '<title>'`.
|
|
78
|
-
- Create an issue for new work with `dispatch issue --project <KEY> --title '<title>'`. Set `--priority` ([issues.md](skill://dispatch/references/issues.md#priority-is-yours-to-set)). Set `--assignee` only when the human said who owns it. Set `--repo` only when it differs from what the issue inherits. Creating an issue does not subscribe you. Never create an issue to park a question.
|
|
79
|
-
- File work in a project that exists (`dispatch projects`). Work across projects goes in the one that owns most of it. Create a project only when the human asks. You cannot rename or delete a project.
|
|
80
|
-
|
|
81
|
-
## Search first
|
|
23
|
+
- Option one: what it costs.
|
|
24
|
+
- Option two: what it costs.
|
|
25
|
+
:::
|
|
26
|
+
```
|
|
82
27
|
|
|
83
|
-
-
|
|
84
|
-
-
|
|
85
|
-
-
|
|
28
|
+
- A to-do or permission only a person can give, or a decision with no document, is a `dispatch ask`. A Legion phase worker sends its decision to its architect.
|
|
29
|
+
- In Legion, file no issue for an outside finding. Fix a clear defect in code your tree uses. Hand others to the controller. Ask about decisions (`skill://legion-worker/references/findings.md`).
|
|
30
|
+
- An open ask is the request. Do not raise it again in each message.
|
|
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
|
+
- 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 is the answer.
|
|
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
|
+
- An ask reaches the issue's assignee. On an unassigned issue, name who must answer.
|
|
86
36
|
|
|
87
|
-
##
|
|
37
|
+
## Choosing what to work on
|
|
88
38
|
|
|
89
|
-
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
-
|
|
39
|
+
- When you finish an issue, take the top ready issue: status `todo`, by priority and then board rank, in each project.
|
|
40
|
+
- `todo` means specced and waiting on nothing. An issue that waits goes in `backlog`, saying on what.
|
|
41
|
+
- Hold at most three issues in flight; move the rest to `backlog`, saying where each is.
|
|
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`.
|
|
93
43
|
|
|
94
44
|
## Issue status is yours to move
|
|
95
45
|
|
|
96
|
-
Outside Legion,
|
|
97
|
-
|
|
98
|
-
## Asking
|
|
99
|
-
|
|
100
|
-
A design decision a document records is a decision block in it, at every phase, approved or not. A block in an approved document makes the approval stale until its answer. A Legion phase worker sends the decision to its architect (`skill://legion-worker`). A to-do or permission only a human can give, or a decision with no document, is a `dispatch ask`. The gates apply to both.
|
|
101
|
-
|
|
102
|
-
In a Legion session, a role or any of its subagents that finds a problem outside its own issue never files an issue for it (the issue creation in [Your owner](#your-owner) included). It opens a `dispatch ask` as `skill://legion-worker/references/findings.md` says, on the issue that reference names. That overrides "Ask on your own issue" in gate 1, and gate 4's rule to ask nothing beside what the human asked for.
|
|
103
|
-
|
|
104
|
-
### Before you ask
|
|
105
|
-
|
|
106
|
-
1. **Does it need the human's authority, taste or risk appetite?** Your lane decides schema shapes, field names and migration internals. Decide them in the plan or code, not in the spec. Settle a two-lane contract over Envoy, with no ask. A halt condition passes the gate. That is an IAM change, deleting or exposing production data, or anything that reaches a customer. Ask on your own issue.
|
|
107
|
-
2. **Is there real uncertainty, and did you measure what you can?** With none, execute. The one ask without uncertainty is permission only a human can give: a production write, an external send, a console action. Start it with the problem and why, then what it changes and risks. Options name outcomes. Measure first: how many are affected, what reaches the path, the current state. Put the measurement and the population size in the ask. One fix cannot fix most of that population and another can? Drop the first. Never offer it cut down. An option not to act (Hold) stays. Report what the measurement could not establish, with its own control. "I found no evidence" and "there is none to find" differ. A control with the query's blind spot proves neither. The test for a new ask is not whether you asked on this issue before. It is whether it makes the human report again an answer they already gave.
|
|
108
|
-
3. **Can someone who has not read the code answer it on a phone?** Say who can do what today and what changes. Give two options with costs, and your recommendation. No slice or decision numbers, no coined nouns. If you cannot write it so, you do not understand it yet.
|
|
109
|
-
4. **Is it outside what the human already said they want?** If not, it is settled, with every choice inside it their words leave open. Build it and ask nothing about it or beside it until delivered, whatever the ask says about the build. After that, ask only about a choice their message raised and left open, quoting it and naming what you delivered. A cause you diagnosed or a neighbouring behaviour is not in their message: do not ask about it or build it. Fixing the cause of the thing they named is delivery. Do not turn a complaint about one control into a choice about another. Still ask at once about any blocker in [When you need a human](#when-you-need-a-human), including a conflict between their request and another of their rules.
|
|
110
|
-
|
|
111
|
-
Nobody else audits or retracts your asks. Passing the gates is your own check.
|
|
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, and `done` with `--reason` once you drove it in production. Never write the status of an issue with the `legion` label, or under one.
|
|
112
47
|
|
|
113
|
-
|
|
114
|
-
dispatch ask --issue <KEY> --question-file - --option 'Label: what it costs' --option 'Other: what it costs' <<'EOF'
|
|
115
|
-
<the problem, what constrains the answer (each answer of theirs you rely on, linked), your recommendation and why>
|
|
116
|
-
EOF
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
- You follow the ask you open. `--ref` appends a `dispatch://` link to the question.
|
|
120
|
-
- Never lead with a file path, line number, sequence number, version or role token. Evidence under it can cite one. Anchor it to a passage with `--anchor-json '{"artifact":"spec","quote":"…"}'` (optional zero-based `occurrence`).
|
|
121
|
-
- The ask must be answerable from its own text and anchor. The ask view does not show the issue's comments. Never write "see above", "my comment above" or "as attached". Put the content in the ask. If it does not fit in 800 characters, split the step. A `dispatch://` reference or an anchor may cite, with one line on what it holds.
|
|
122
|
-
- A runbook for the human is one self-contained ask per step: what, where, what result proves it, and outcome options. Open each step after the previous is answered, with its verified result in one line.
|
|
123
|
-
- If the human must read an artifact to decide, link `dispatch://KEY/artifact/<slug>`, never a filename. Text needed to decide belongs in the spec ([Artifacts](#artifacts)).
|
|
124
|
-
|
|
125
|
-
### When you need a human
|
|
126
|
-
|
|
127
|
-
- Before you say you wait on a human, run `dispatch open-asks`. Add `--project <KEY>` to see every open ask in a project.
|
|
128
|
-
- **Unsettled product shape needs a decision before implementation.** Product shape can come from a page, navigation entry, table key, customer-scoping rule or persisted sidecar. If the human has not settled it, write a decision block in the work's document before the first implementation commit. In a Legion tree the architect writes it. A lane's schema choice or a two-lane contract does not settle product shape. A behaviour the human asked for in words is settled, with each choice inside it. Routine work needs no approval.
|
|
129
|
-
- **Anything you are blocked on a human for is visible in Dispatch.** An agent waits on a human only through an open ask. Make each blocker a `dispatch ask` the moment you know. Blockers are a to-do, a permission, a credential or grant renewal, a human-only setting, a review click, or a conflict between two of their rules. Start with the problem and why, then constraints, options with costs, and your recommendation. For a human-only action, state what it changes and risks. Never make the action the question. A to-do only in a spec, comment, message or PR body reaches no Inbox.
|
|
130
|
-
- First try to make the step unnecessary: a value on the machine, a permission you hold, an API that replaces the click.
|
|
131
|
-
- One ask per item, `--urgency high` when work halts on it. Keep working on everything else.
|
|
132
|
-
- **Ask once.** Do not raise an open ask again in each message. The open ask is the request.
|
|
133
|
-
- After it opens: [Asks after they open](skill://dispatch/references/asks.md).
|
|
134
|
-
|
|
135
|
-
## Architecture components
|
|
136
|
-
|
|
137
|
-
- Attach every architectural issue to the components it changes. Attach the root before you decompose it: children inherit.
|
|
138
|
-
- `--components-json '{"mode":"explicit","ids":["web"]}'`, `'{"mode":"none","reason":"hiring, not code"}'` (only for non-architectural work, with a concrete reason), or `'{"mode":"inherit"}'`.
|
|
139
|
-
- Component ids: each non-external `components[].id` from `GET /api/v1/projects/{key}/architecture`, or the file names under `.dispatch/architecture/` in any of the project's source repositories. A project may import from several; ids are project-wide, so one issue can name components of different sources. Others are refused `COMPONENTS_INPUT`. A closed issue can be classified without reopening.
|
|
140
|
-
- Change code and `.dispatch/architecture/<id>.md` in the same review. A stale model: `dispatch architecture-sync` ([issues.md](skill://dispatch/references/issues.md#syncing-a-projects-architecture-model)).
|
|
48
|
+
A claim delivers no comments: in the same turn, `dispatch issue-update --route session:<your id>` (clear with `--route ''` on release) or `envoy_subscribe notifications.dispatch.issue.<KEY>.>`. Never route such an issue.
|
|
141
49
|
|
|
142
50
|
## Close what you opened
|
|
143
51
|
|
|
144
|
-
- An ask you opened is yours until answered or resolved. When the answer
|
|
145
|
-
-
|
|
146
|
-
- Before a new ask, check your open ones. Retract one it supersedes with `--kind retracted` in the same turn.
|
|
147
|
-
|
|
148
|
-
## Approval of a spec
|
|
149
|
-
|
|
150
|
-
A human approves one version. A later version makes the approval stale, unless the human's own answer to a decision block is the whole change. Then Dispatch records the approval and emits `artifact.approved`: request nothing. If the answer changes text outside its block, rewrite that text, run the fresh reader, and request again. A new version also moves an open request, which then waits on you.
|
|
151
|
-
|
|
152
|
-
- Request only when all three hold: every block is answered or waived, the human agreed to every point, and this version is not approved. A Legion root spec under an armed design gate always goes to approval then (`skill://legion-architect`).
|
|
153
|
-
- First have a fresh read-only reader check the spec against the code and the human's words, and resolve every finding. A Legion architect uses `plan-gap-analyst`. Then request in the same pass: a finished design with nothing in the Inbox waits on nobody.
|
|
154
|
-
- If the human asks for approval while a block is open, name each open block and ask them to answer or waive it. For a waiver, `dispatch resolve-ask --kind resolved` with their words as `--reason`, write the decision into the text, then request.
|
|
155
|
-
- A request carries nothing new. An unagreed point first gets a decision block with your recommendation. A choice that is yours (gate 1), where the human will not want a say, leaves the spec. An inference you cannot defend in a block leaves the spec.
|
|
156
|
-
- `--summary` is one to three sentences on what they approve, with no commentary and no question. After an earlier approval, one sentence on what changed.
|
|
157
|
-
- Only humans approve. Never put "Approve" options in a `dispatch ask`. Details: [Approval requests](skill://dispatch/references/documents.md#approval-requests).
|
|
158
|
-
|
|
159
|
-
## The Spec
|
|
160
|
-
|
|
161
|
-
- Name each version that records a decision with `dispatch doc-edit --summary`.
|
|
162
|
-
- Read the current document with `dispatch doc-read` before you change it. `--blocks` lists block ids and tokens for edits. It also shows pictures: open a written picture file with your file-read tool.
|
|
163
|
-
- Edit in place as [Editing a document](skill://dispatch/references/document-edits.md) says.
|
|
164
|
-
|
|
165
|
-
## Typed blocks
|
|
166
|
-
|
|
167
|
-
Write an `:::ask` or a callout only as [Documents](skill://dispatch/references/documents.md#typed-blocks) says.
|
|
168
|
-
|
|
169
|
-
## Artifacts
|
|
170
|
-
|
|
171
|
-
- Text the human must read to decide (a draft, a proposal, a summary) is a section of the spec. An artifact is for a real file: sent as-is, a long report, a binary, a screenshot.
|
|
172
|
-
- Link an uploaded artifact as `dispatch://KEY/artifact/<slug>` where the reader needs it, and in the ask that needs it. A filename is not a reference. Uploading: [Documents](skill://dispatch/references/documents.md#artifacts).
|
|
52
|
+
- An ask you opened is yours until it is answered or resolved. When the answer comes another way, or the design makes it moot, `dispatch resolve-ask` it in the same turn.
|
|
53
|
+
- Resolve each open ask a later write names that is no longer needed; retract one a new ask replaces.
|
|
173
54
|
|
|
174
55
|
## Structure over stream
|
|
175
56
|
|
|
176
|
-
- One issue per deliverable
|
|
177
|
-
-
|
|
178
|
-
-
|
|
179
|
-
|
|
180
|
-
## Messages
|
|
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, or tells them a change they must know now.
|
|
59
|
+
- Text a person must read to decide is a section of the spec. An artifact is a real file.
|
|
181
60
|
|
|
182
|
-
|
|
61
|
+
## Architecture components
|
|
183
62
|
|
|
184
|
-
|
|
185
|
-
dispatch message --issue <KEY> --body-file - <<'EOF'
|
|
186
|
-
<what landed, with its link>
|
|
187
|
-
EOF
|
|
188
|
-
```
|
|
63
|
+
Attach each architectural issue to its components (`--components-json`), the root before you decompose it. Change code and `.dispatch/architecture/<id>.md` in the same review.
|
|
189
64
|
|
|
190
|
-
|
|
191
|
-
- Show a screenshot inline with `--image` on `message`, `comment` or `ask` ([Documents](skill://dispatch/references/documents.md#artifacts)).
|
|
192
|
-
- Answer BTW, Aside, Steer and Agents-page messages as [messages.md](skill://dispatch/references/messages.md) says.
|
|
65
|
+
## References
|
|
193
66
|
|
|
194
|
-
|
|
67
|
+
Link each item you name:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
dispatch://KEY
|
|
71
|
+
dispatch://KEY/spec
|
|
72
|
+
dispatch://KEY/artifact/<slug>[@vN]
|
|
73
|
+
dispatch://KEY/ask/<id>
|
|
74
|
+
dispatch://KEY/comment/<id>
|
|
75
|
+
dispatch://KEY/message/<id>
|
|
76
|
+
dispatch://PROJECT/artifact/<slug>[@vN]
|
|
77
|
+
dispatch://PROJECT/artifact/<slug>/ask/<id>
|
|
78
|
+
```
|
|
195
79
|
|
|
196
|
-
|
|
80
|
+
A bare id or filename is not a reference. An ask or comment id can be an 8-hex prefix.
|
|
197
81
|
|
|
198
|
-
##
|
|
82
|
+
## Setup and the HTTP API
|
|
199
83
|
|
|
200
|
-
|
|
84
|
+
- Use a personal token from Dispatch **Settings → Agent tokens**, as `DISPATCH_TOKEN` or `dispatch.token` in the session's `envoy.json`.
|
|
85
|
+
- `GET /api/v1` lists every route; never guess one. Branch on an error's `code`, not its text.
|
|
@@ -5,37 +5,43 @@ description: "Use when a session has the dispatch command, before you plan, file
|
|
|
5
5
|
|
|
6
6
|
# Dispatch first
|
|
7
7
|
|
|
8
|
-
Dispatch holds the open issues, their specs and
|
|
8
|
+
Dispatch holds the open issues, their specs and people's answers. A duplicate issue or repeated question costs a person time.
|
|
9
9
|
|
|
10
10
|
## Search before you act
|
|
11
11
|
|
|
12
|
-
- Before you plan, file an issue, ask, post a finding or start work, run `dispatch search
|
|
13
|
-
-
|
|
12
|
+
- Before you plan, file an issue, ask, post a finding or start work, run `dispatch search`.
|
|
13
|
+
- Each query word must match. Use two or three words: the thing and what is wrong with it. Never paste a draft.
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
dispatch search --query 'broadcast send order'
|
|
17
17
|
dispatch search --query 'reviewer threads OR review comments'
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
- No hits:
|
|
21
|
-
- Open each hit that
|
|
20
|
+
- No hits: remove a word before you add one. Try two or three wordings before you decide nothing exists.
|
|
21
|
+
- Open each hit that can be yours with `dispatch read --issue KEY`, then its parent (`child_of` under `Links:`, or a document's `Issue:`).
|
|
22
22
|
|
|
23
23
|
## What to do with what you find
|
|
24
24
|
|
|
25
|
-
`dispatch issue` and `dispatch ask` also search
|
|
25
|
+
`dispatch issue` and `dispatch ask` also search. Treat a hit in `advice.suggestions` as yours to read.
|
|
26
26
|
|
|
27
|
-
- **Work already tracked:** put the finding on that issue
|
|
28
|
-
- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`)
|
|
29
|
-
- **Duplicate found:** keep the issue with the spec
|
|
30
|
-
- **
|
|
31
|
-
-
|
|
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
|
+
- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`). Do not ask again.
|
|
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
|
+
- **Each ask and message stands alone:** the reader sees only that text. Put the facts, options and your recommendation in it.
|
|
31
|
+
- In Legion, file no finding outside your issue (`skill://legion-worker/references/findings.md`).
|
|
32
32
|
|
|
33
|
-
##
|
|
33
|
+
## Reach a person only through Dispatch
|
|
34
34
|
|
|
35
|
-
|
|
36
|
-
- Before a spec's first version and each approval request, get a fresh read-only subagent to check it. On Oh My Pi, use `task(agent="scout")`. Elsewhere, use the host's read-only agent. It checks the spec against the code, the human's words and the command output that its claims rest on. Scout has no shell: save that Dispatch, gh and git output to files first and give it their paths. Resolve what it flags.
|
|
37
|
-
- A Legion architect's own issue spec follows `skill://legion-architect`. Its fresh reader in that Legion session is the Legion plugin's `plan-gap-analyst` agent.
|
|
35
|
+
A person does not watch your chat. Reach them through an ask, an ask block or an approval request.
|
|
38
36
|
|
|
39
|
-
|
|
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
|
+
- 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
39
|
|
|
41
|
-
|
|
40
|
+
## Which skill to read
|
|
41
|
+
|
|
42
|
+
| Before you | Read |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| run your first `dispatch` command in this session | `skill://dispatch` |
|
|
45
|
+
| write or change a spec, or write an ask, comment or message a person reads | `skill://dispatch-writing-specs` (in a session with Dispatch it replaces superpowers' `brainstorming`) |
|
|
46
|
+
| plan work whose spec a person approved | superpowers' `writing-plans`, stored as the issue's `plan.md` (`skill://dispatch-writing-specs`, "The plan") |
|
|
47
|
+
| write a Legion architect's own spec | `skill://legion-architect` too |
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dispatch-writing-specs
|
|
3
|
+
description: "Use in a session with Dispatch before you write or change a spec, and before an ask, comment or message a person reads. It replaces superpowers' brainstorming there. A Legion architect also follows skill://legion-architect."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Writing specs
|
|
7
|
+
|
|
8
|
+
## The aim
|
|
9
|
+
|
|
10
|
+
Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes no spec: it sends decisions to its architect (`skill://legion-worker`).
|
|
11
|
+
|
|
12
|
+
## The outline
|
|
13
|
+
|
|
14
|
+
The spec is the issue's primary document. Find its project with `dispatch projects` or `dispatch search`, never the environment. Its `##` parts, in order:
|
|
15
|
+
|
|
16
|
+
Part | Content
|
|
17
|
+
--- | ---
|
|
18
|
+
`Summary` | The change in the reader's own terms, at most 100 words
|
|
19
|
+
`Problem` | What goes wrong, for whom, with counts
|
|
20
|
+
`Goals and non-goals` | What is in and out of scope
|
|
21
|
+
`Requirements` | `**R1.**` on, each naming its source (`From:`)
|
|
22
|
+
`Design` | How it meets them; a value for each limit, size and time
|
|
23
|
+
`Decisions` | Your own choices
|
|
24
|
+
`Acceptance` | `**A1.**` on, each naming the requirements it tests
|
|
25
|
+
|
|
26
|
+
Another agent can build and check the work from the spec alone. Length scales with the change: a small change gets a few sentences per part, no matrix. Split a large design into child issues.
|
|
27
|
+
|
|
28
|
+
## Rules for the text
|
|
29
|
+
|
|
30
|
+
For each spec, ask, comment and message:
|
|
31
|
+
|
|
32
|
+
- Write in `skill://asd-ste100`'s strict mode.
|
|
33
|
+
- State the current design, never how people reached it.
|
|
34
|
+
- Link each source where the person wrote it: `dispatch://KEY/comment/<id>`, `/ask/<id>`, `/message/<id>`, or a Slack URL. With no link, state the design.
|
|
35
|
+
- Write about the design, never the person. Never quote people, repeat an answered ask, or upload their words.
|
|
36
|
+
- Name your session only if a reader must reach it.
|
|
37
|
+
- Keep only text that helps a reader understand, decide, build, check.
|
|
38
|
+
- Explain each name or term a new reader may not know. Name an issue by its `dispatch://` link, and say in a clause what it does for this reader. Never write a bare key.
|
|
39
|
+
- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
|
|
40
|
+
|
|
41
|
+
## Questions
|
|
42
|
+
|
|
43
|
+
- Propose an answer to each point, numbers included, with a reason.
|
|
44
|
+
- A choice inside what the person asked for, or one their messages favour, is settled: decide it.
|
|
45
|
+
- Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
|
|
46
|
+
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks) at the end of its section: 2 to 4 options with costs, your recommendation, answerable on a phone.
|
|
47
|
+
- Chat reaches nobody: use an ask or approval request.
|
|
48
|
+
|
|
49
|
+
## Each version
|
|
50
|
+
|
|
51
|
+
1. After a person's answer, comment or edit, rewrite what it touches; delete what it contradicts. Write what is true now. Never narrate an edit or what used to be here; versions and comments hold the history. Reply in a comment's thread; resolve the ask it answers.
|
|
52
|
+
2. Before each spec write, paste the whole spec, never a path, into a fresh subagent's assignment. It lists gaps, conflicts, uncheckable requirements, unclear text, and missing or needless questions. Fix or record each.
|
|
53
|
+
3. Before each approval request, a read-only agent checks its facts: `task(agent="scout")`, or `plan-gap-analyst` and `plan-reviewer` in Legion.
|
|
54
|
+
4. Name each version with `dispatch doc-edit --summary`.
|
|
55
|
+
|
|
56
|
+
## Decisions
|
|
57
|
+
|
|
58
|
+
- Each design choice no source states is a `###` entry: choice, reason, options weighed, parts shaped.
|
|
59
|
+
- An unsure entry adds an `Unsure:` paragraph: what would change your mind.
|
|
60
|
+
- A replaced entry moves under a final `### Replaced`.
|
|
61
|
+
- A person's decision is their answered ask block. Each part it shapes links it.
|
|
62
|
+
|
|
63
|
+
## Old specs
|
|
64
|
+
|
|
65
|
+
At your next edit, rewrite a spec outside the outline whole, in one version. Move its ask blocks with `doc-edit`'s `move`.
|
|
66
|
+
|
|
67
|
+
## Approval
|
|
68
|
+
|
|
69
|
+
- Request approval once, when each ask block is answered or waived, each claim is checked, and this version is unapproved. Unbuilt acceptance checks never delay it.
|
|
70
|
+
- When their answer is the whole change since approval, Dispatch carries it.
|
|
71
|
+
- After approval, version only a change to scope, acceptance, cost, risk or a person's decision, all at once. Put other fixes in the plan or a comment.
|
|
72
|
+
- A Legion root spec's design gate follows `skill://legion-architect`.
|
|
73
|
+
|
|
74
|
+
## The plan
|
|
75
|
+
|
|
76
|
+
Write the approved spec's plan with `writing-plans` as the issue's `plan.md`, not a repository file.
|
package/package.json
CHANGED
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
# Authentication and the HTTP API
|
|
2
|
-
|
|
3
|
-
Read this to set up a Dispatch token, or to call a route no `dispatch` command covers.
|
|
4
|
-
|
|
5
|
-
## Agent authentication
|
|
6
|
-
|
|
7
|
-
- Use a personal token. A human mints it in Dispatch **Settings → Agent tokens**. Supply it as `DISPATCH_TOKEN` or as `dispatch.token` in the session's `envoy.json`. The server records that human as the owner of your writes.
|
|
8
|
-
- Which `envoy.json`: the session's own directory under an Oh My Pi profile other than `default`, a Claude Code `CLAUDE_CONFIG_DIR` or an OpenCode `OPENCODE_CONFIG_DIR`. Otherwise the file `ENVOY_CONFIG_FILE` names, else `~/.config/legion/envoy.json` (under `$XDG_CONFIG_HOME` when set).
|
|
9
|
-
- The plugin passes its choice in `ENVOY_CONFIG_FILE` with `DISPATCH_HOST`. In a Claude Code Bash that lacks both, `CLAUDE_CODE_CHILD_SESSION=1` makes the command read `CLAUDE_CONFIG_DIR`'s file. A Legion pane reads the `DISPATCH_TOKEN_FILE` path the daemon sets.
|
|
10
|
-
- A `dispatch.token` written `!<command>` is a command that prints the token.
|
|
11
|
-
- A checkout's `.envoy/envoy.json` sets `dispatch.serverUrl` and `dispatch.token` only together. Its `envoy` section is not read. A file's token goes only to its own server: a `DISPATCH_URL` for another server needs `DISPATCH_TOKEN` or `DISPATCH_TOKEN_FILE`.
|
|
12
|
-
- Never configure `DISPATCH_AGENT_TOKEN` (the shared devbox fallback) for one agent.
|
|
13
|
-
- Never set the sign-in callback origin in an agent's `envoy.json`. It is `DISPATCH_SERVER_URL` in the deployment `compose/.env`: the exact URL humans type. `<DISPATCH_SERVER_URL>/auth/callback` is registered on the sign-in client (`DISPATCH_SIGNIN_CLIENT_ID`).
|
|
14
|
-
|
|
15
|
-
## Finding a route
|
|
16
|
-
|
|
17
|
-
- `GET /api/v1` (no credential) lists every route as `{method, path, auth, description}`. `auth` is `public`, `any`, `human` (a bearer gets `403 HUMAN_ONLY`) or `bearer`.
|
|
18
|
-
- `404 NOT_FOUND` with "GET /api/v1 lists every route" means a wrong path. Read the index, do not guess.
|
|
19
|
-
- Branch on an error's `code`, never its text.
|
|
20
|
-
- `GET /api/v1/issues` returns every match unpaged, or one page with `limit` (1–250) or `offset`: `{issues, total, limit, offset}`. Only the unpaged array is exact: a page walk can repeat or skip an issue that changes. `cursor` is `400 INVALID_QUERY`. `dispatch issues` pages for you.
|
|
21
|
-
- Event logs page with `after` or `before` and `limit`. `GET /api/v1/search` takes `limit` up to 50 with no next page. Other routes do not page.
|
|
@@ -1,43 +0,0 @@
|
|
|
1
|
-
# Asks after they open: who answers, editing, resolving, replying, and following
|
|
2
|
-
|
|
3
|
-
Read this once an ask is open. Whether to ask, and how to write it, is "Before you ask" in `skill://dispatch`.
|
|
4
|
-
|
|
5
|
-
## Who answers an ask
|
|
6
|
-
|
|
7
|
-
- An ask goes to the issue's assignee's Inbox: the `Assignee:` that `dispatch read` prints decides whose, not the project's default. On an unassigned issue it is in nobody's default Inbox or `Needs you` count. A project's default assignee fills in only when an issue is created with nobody named and nothing earlier in the chain below names someone; an issue created with an explicit nobody, set to nobody later, or created before the default was set stays unassigned.
|
|
8
|
-
- `dispatch whoami` prints whom you act for: your token owner's email, or no owner (a service token shows as `<namespace>/<name>`, as your writes do). An issue you create goes to your owner, else inherits its parent's assignee, else goes to the project's default assignee when a person set one on the Settings page, else stays unassigned.
|
|
9
|
-
- On an unassigned issue where the answer matters, assign it to your owner, or name in the question who should answer. Assign with `PATCH /api/v1/issues/{key}` and `{"assignee": "<email>"}`. An email nobody signed in with gets `ASSIGNEE_NOT_ALLOWED`.
|
|
10
|
-
- Never reassign an issue a human holds to get a faster answer. That is the human's call.
|
|
11
|
-
|
|
12
|
-
## Handing a human a to-do, editing, resolving, and replying
|
|
13
|
-
|
|
14
|
-
- A to-do follows the question-and-options contract of "Writing for the human". For a human-only action, what it changes and risks constrains the answer. No label is special. If an outcome needs a reason, say so in its description.
|
|
15
|
-
|
|
16
|
-
```bash
|
|
17
|
-
dispatch ask --issue DSP-42 \
|
|
18
|
-
--question 'The fix is merged but cannot run in production: the signing certificate it needs expired, and only its owner can renew it in the registrar console. Renewing replaces the certificate every client checks. How should we proceed? Recommendation: renew it now because the fix cannot run without it.' \
|
|
19
|
-
--option 'Renew the certificate: Lets the fix run but replaces the certificate every client checks.' \
|
|
20
|
-
--option 'Leave it expired: Changes nothing now but leaves the fix unable to run.'
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
- Correct an open ask in place with `dispatch edit-ask`, not a second ask, while the same decision stays open. The human then reconfirms. You cannot edit an answered or resolved ask. If the decision of an open ask changed, retract it and open a new one. If the decision of an answered ask changed, open a new one.
|
|
24
|
-
- `edit-ask` on a block ask writes the block too, so it mints a version and closes a spec's design gate until approved. Change anything else about the block with `dispatch doc-edit`. A retry with unchanged fields is safe.
|
|
25
|
-
- A human can change an answer. A new `ask.answered` carries `previous_answer`. Act on the newest.
|
|
26
|
-
- When the selected option and the typed text disagree, the text is the answer. Act on it. To clarify, open a new ask.
|
|
27
|
-
- Retract a moot or superseded ask, or resolve one whose answer you found:
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
dispatch resolve-ask --ask <id> --kind retracted --reason 'A newer ask supersedes this question.'
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
- Use `retracted` for obsolete, `resolved` for found. Always give a reason: the question stays in its card. Resolution never records a human decision. An answered ask cannot be resolved.
|
|
34
|
-
- `doc-edit` refuses to delete an open ask's block. A block deleted another way (an upload, the browser) closes its ask. Restoring it reopens the ask.
|
|
35
|
-
- Reply under an ask with `dispatch comment --reply-to-ask <id>`. Close your review comment with `dispatch resolve-comment` ([Documents](skill://dispatch/references/documents.md#comments-and-suggestions)).
|
|
36
|
-
- A human reply while the ask is open (`ask_state: open`) is a request for clarification, not an answer. Answer in the thread with `--reply-to-ask`, or reword with `edit-ask`. Do not open a second ask.
|
|
37
|
-
- Each reply sets whose turn it is. Your default reply (`--turn human`) puts the ask in the human's `Waiting on you`. For any progress or working-on-it note, use `--turn agent`. A human reply hands the turn to you. Reads show it as `waiting_on`.
|
|
38
|
-
|
|
39
|
-
## Following
|
|
40
|
-
|
|
41
|
-
- You follow an ask you opened or replied to, or one a human added you to. Its answer, edits, resolution and replies reach your agent topic directly.
|
|
42
|
-
- Leave or rejoin: `dispatch follow --ask <id> --action unfollow` (or `follow`). `--ask` takes a full id, a `dispatch://KEY/ask/<id>`, or an 8+ hex prefix unique among your open asks. Removal arrives as `ask.follower_removed`, an add as `ask.follower_added`.
|
|
43
|
-
- No write subscribes you to an owner. Replies to your comments and new comments on your documents also reach you. For everything else, subscribe: `envoy_subscribe notifications.dispatch.issue.<KEY>.>` or `envoy_subscribe notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The topic carries every event. `notify` controls only wake and routed delivery. A human can unsubscribe you (`subscription.removed`).
|
|
@@ -1,59 +0,0 @@
|
|
|
1
|
-
# Editing a document
|
|
2
|
-
|
|
3
|
-
Edit every Dispatch document (an issue's spec, a project document) in place with `dispatch doc-edit`. Never upload it again. `dispatch doc-edit --help` has the full rules for each operation: markers, task boxes, hard breaks, anchors and preconditions.
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
dispatch doc-edit --issue <KEY> --artifact spec --summary '<names the version>' --ops-json-file - <<'EOF'
|
|
7
|
-
[{"op": "replace", "find": "old sentence", "with": "new sentence"}]
|
|
8
|
-
EOF
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
- Ops: `replace`, `delete`, `insert`, `retype`, `move`, `delete_row`, `delete_column`. Keys: `op`, `find`, `with`, `occurrence`, `markdown`, `after`, `before`, `block`, `index`, `type`, `attributes`. An unknown key is refused before sending. A misspelled `with` would turn the `replace` into a delete.
|
|
12
|
-
- The output names the version, `unchanged_ops`, `lost_ops`, and a `Document token:`.
|
|
13
|
-
- Use `--summary` to name a version that records a decision.
|
|
14
|
-
|
|
15
|
-
## Targeting text
|
|
16
|
-
|
|
17
|
-
- Quote text as rendered: inline code without backticks, bold without asterisks, link text without syntax, a cell by its text, code without fences. One quote stays in one textblock. Split changes that span blocks.
|
|
18
|
-
- A miss names the three nearest blocks. A `heading:` anchor must match the whole heading. Use zero-based `occurrence` for a repeat. Re-read before you retry a missing or ambiguous target.
|
|
19
|
-
- `dispatch doc-read --blocks` lists each live block's id, type, token, anchor count and opening words, and each table row and cell index. Only live ids address an edit.
|
|
20
|
-
|
|
21
|
-
## Rewriting paragraphs
|
|
22
|
-
|
|
23
|
-
- **One `replace` per paragraph, then a read-back.** A `with` of two paragraphs is refused. Each `replace` keeps the block id and the anchors outside the text you change. An anchor on changed text loses its quote but keeps its pin.
|
|
24
|
-
- More new paragraphs than old: add the rest as **one** `insert` holding them all, `after` the last rewritten paragraph as it now reads. Two inserts at one anchor come out reversed. An insert lands after the top-level block that holds the quote.
|
|
25
|
-
- Fewer: `delete` each leftover paragraph by its whole text or `block` id.
|
|
26
|
-
- `replace` keeps a block's kind. When the new text adds a non-paragraph block (heading, list, table, quote, rule, fence or typed block) beside paragraphs, `insert` it beside the paragraph you replaced. Only when no paragraph of the new text stays, `delete` the old block, then `insert` the new one, anchored on the block before or after it.
|
|
27
|
-
- An empty `with` deletes the matched text on purpose and leaves an empty block. Read the passage and its neighbours back with `dispatch doc-read`. A grep for your new words is not a check.
|
|
28
|
-
- Dispatch refuses block HTML (`<div>`, `<!-- -->`, a lone `<br>` paragraph) in `with`. Inline HTML stays.
|
|
29
|
-
- To add a rule, `insert` `***`. A `---` in `with` is stored as `\---`.
|
|
30
|
-
|
|
31
|
-
## Blocks and ids
|
|
32
|
-
|
|
33
|
-
- A block loses its id only when deleted: by `delete`, by `delete_row` / `delete_column` (its cells), or by a `move` that empties its container. Its anchors go with it. `replace`, `insert`, `move` and `retype` keep ids.
|
|
34
|
-
- `delete` of a block's whole text deletes the block. A partial match keeps it. A bullet with a nested list hoists the list. A bullet with other content needs `delete {block:"<item id>"}`.
|
|
35
|
-
- Dispatch refuses a `delete` or `retype` that takes out an open ask's block, delete-then-insert included. Reword with `replace`, relocate with `move`, or use `dispatch edit-ask`. Moving an open block out of a container and deleting the container takes two calls.
|
|
36
|
-
- `retype` turns a paragraph or typed block into a typed block in place, keeping its id. Use it when a paragraph is the question that should become a decision.
|
|
37
|
-
- An ask block has two ids. The block id (`:::ask{#<id> …}`) goes bare in `block` for `move` / `delete` (`block:<id>` only in `before` / `after`). `dispatch read --ref dispatch://KEY/ask/<id>` takes either id, whole or as a unique prefix of 8 or more hex characters, and prints the ask id as `Ask id:`. `dispatch open-asks` lists ask ids. `edit-ask`, `resolve-ask`, `follow` and `--reply-to-ask` take only the ask id.
|
|
38
|
-
|
|
39
|
-
## Tables
|
|
40
|
-
|
|
41
|
-
- `delete_row` / `delete_column` take the table `block` and a zero-based `index`. Row 0 is the header. The last body row and a row's last column cannot go. Open asks or unresolved comments on the cells block it.
|
|
42
|
-
- Inserting bare body rows (no header or delimiter) at a cell quote extends that table. A wider row is `TABLE_WIDTH`. A full table with a header pasted there becomes a second table.
|
|
43
|
-
|
|
44
|
-
## Stale and concurrent edits
|
|
45
|
-
|
|
46
|
-
- Guard with `--precondition-json`: `{"document": "<token>"}` or `{"blocks": [{"id": "<id>", "token": "<token>"}]}`. Use a document token for `insert` and `move`. A block guard must cover every block the batch changes.
|
|
47
|
-
- Chain guarded edits by passing each output's token to the next. Read once, not once per edit.
|
|
48
|
-
- `409 PRECONDITION_FAILED` or `409 EDIT_LOST_TO_CONCURRENT_CHANGE`: nothing written. Re-read and decide again. Non-empty `lost_ops` on success: a browser deleted that text after the write. Re-read before you build on it. A result that could not check survival: re-read.
|
|
49
|
-
- A batch that changes nothing mints no version, even with `--summary`. `POST /api/v1/artifacts/<id>/versions` names the current state as a version on purpose.
|
|
50
|
-
|
|
51
|
-
## Edge cases
|
|
52
|
-
|
|
53
|
-
- Inside a code block, `with` is the code's literal text. Trailing line breaks, and whitespace-only lines in a list item's code, do not survive a read.
|
|
54
|
-
- A CR LF or lone CR in any text you write is stored as a line feed.
|
|
55
|
-
- Replacing a non-paragraph block writes its marker as text. A backtick fence becomes an inline code span. A tilde fence stays literal.
|
|
56
|
-
- An anchor that straddles the rewritten text keeps its mark on the words you left, with a shorter quote.
|
|
57
|
-
- Emptying a task item's first paragraph while another block follows it is `INVALID_OP`.
|
|
58
|
-
- A later op in one batch that names a block an earlier `delete {block}` took out fails as `INVALID_OP`. So does a move anchored inside the moved block, or a delete that leaves a typed block without its required body.
|
|
59
|
-
- An op that only takes text out is never reported lost.
|