@sjawhar/opencode-legion-envoy 9.0.0 → 9.2.0

package/skills/dispatch/SKILL.md

@@ -1,200 +1,85 @@
 ---
 name: dispatch
-description: "Use when posting to Dispatch: a message, status update, comment, artifact, spec or document edit, claim or status change. Use when asking a human a question, also one that cites another message, artifact or eval. Use when brainstorming or asking about a design change, or when running any dispatch command."
+description: "Use before your first dispatch command in a session: a message, comment, ask, artifact, document edit, claim or status change."
 ---
 
 # Dispatch
 
-Dispatch holds an issue's or project document's spec, asks, comments and artifacts. It is a high-signal record for the humans who decide, never a log of your work. Narrate progress in your transcript, not here.
+Dispatch is a record for the people who decide, never a log of your work.
 
-- Write to Dispatch only with the `dispatch` command in your shell. `dispatch --help` lists the commands. `dispatch <command> --help` gives the flags, the limits and an example.
-- Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'` … `EOF`). Give object and list fields as JSON (`--ops-json`).
-- Exit code 0 means it wrote or read, 1 means Dispatch refused, 2 means a usage error.
-- Dispatch refuses over-limit input with the number to trim. It never truncates. It lists every problem of a call in one refusal, so fix them all and call once again.
+- Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
+- Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`). Give object and list fields as JSON.
+- Exit 1 is a refusal, 2 a usage error. A refusal lists each problem: fix them all, then call once.
+- `DOC_SERVICE_UNAVAILABLE`: the document is reloading, nothing was written; retry in a few seconds.
 
-## Where the detail lives
+## Asks and ask blocks
 
-Open a reference when you reach its step, not before. On a host with no `skill://` scheme (Claude Code, OpenCode), the path after `skill://dispatch/` is relative to this skill's directory.
+- A design question a document records is an ask block (a decision block) at the end of its section, at each phase:
 
-| Before you | Read |
-| --- | --- |
-| run `dispatch doc-edit` | [Editing a document](skill://dispatch/references/document-edits.md) |
-| write a typed block, comment, suggest, upload an artifact, request approval, or retry `DOC_SERVICE_UNAVAILABLE` | [Documents](skill://dispatch/references/documents.md) |
-| choose, claim or move an issue, set priority, reorder a board, or audit a backlog | [Working an issue](skill://dispatch/references/issues.md) |
-| route, edit, retract, resolve or reply to an open ask, or follow its thread | [Asks after they open](skill://dispatch/references/asks.md) |
-| catch up after a restart, trace what cites a node, or write a `dispatch://` reference | [Reading back](skill://dispatch/references/reading.md) |
-| answer a BTW, Aside or Steer frame, or an Agents-page message | [Targeted and direct messages](skill://dispatch/references/messages.md) |
-| want a worked example | [Before and after](skill://dispatch/references/examples.md) |
-| set up a token, or call a route no command covers | [Authentication and the HTTP API](skill://dispatch/references/api.md) |
+```md
+:::ask{urgency="med"}
+The problem and why it matters. Recommendation: the option and its reason.
 
-## Design changes are brainstormed here
-
-A design change that needs the human's choices is brainstormed in its issue's spec, not in chat or a repository design document. Its plan is the issue's `plan.md` document. Read `skill://dispatch-brainstorming` before a spec's first version, before each next turn, and before you write a plan.
-
-## Writing for the human
-
-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.
-
-- 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.
-- 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)).
-- 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.
-- 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.
-- 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.
-- 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.
-- 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.
-
-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.
-
-## Writing a spec
-
-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.
-
-- **Each open question is a decision block** ([Decision blocks](#decision-blocks)).
-- **An answered decision block is the record.** It shows the chosen option, the person's words, who and when. Never restate it.
-- **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.
-- **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.
-- **Sections follow the topic.** No heading is required or fixed.
-- **Rewrite a changed point. Do not append.** The decision block stays as the record. Versions keep the history.
-- **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.
-- **No progress**: no status, timestamps, "Update HH:MMZ" sections, PR lists or handoff notes.
-- **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.
-- **No commentary**: never call it a draft, version or turn, preview a later version, describe a correction, or narrate the exchange.
-
-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.
-
-## Decision blocks
-
-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.
-
-- 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.
-- Prose questions reach nobody. Only the block reaches the Inbox. A spec with no blocks is right only when no human decision is needed.
-- 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)).
-- Syntax and checks: [Typed blocks](skill://dispatch/references/documents.md#typed-blocks). Whether to ask at all: [Before you ask](#before-you-ask).
-
-## Your owner
-
-- 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`.
-- 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>'`.
-- 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.
-- 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.
-
-## Search first
+- Option one: what it costs.
+- Option two: what it costs.
+:::
+```
 
-- Search as `skill://dispatch-first` says before you plan, file, ask, post, start a design document or start work. `dispatch search --help` has the syntax and paging. A paraphrase can match by meaning. Without an embedder, search says so and ranks by keyword. Never paste a passage: a query over 1,000 characters is refused. Cite the hit (`dispatch://KEY`) or say "no prior issue".
-- `POSSIBLE_DUPLICATE` compares title words only. Read the candidates. Reference the existing issue, or use `--force` for new work. Then give the new title the difference, and open its spec with the distinction, citing the named issue.
-- **Symptom versus cause.** Work goes on the issue whose title names the fix. The symptom's issue gets a pointer. Before you post a finding, search for the failing component's name. A symptom issue that gathers messages with no human reply is the sign.
+- 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.
+- 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`).
+- An open ask is the request. Do not raise it again in each message.
+- Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
+- 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.
+- When an answer's option and text disagree, the text wins.
+- 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.
+- An ask reaches the issue's assignee. On an unassigned issue, name who must answer.
 
-## Claim the issue before you work it
+## Choosing what to work on
 
-- Before you implement, `dispatch claim --issue <KEY>` and `dispatch issue-update --issue <KEY> --status in_progress`. Release with `--release` when you finish, hand over or switch. Closing releases it.
-- Claiming does not deliver the issue's comments to you. In the same turn, route the issue to your session, `dispatch issue-update --issue <KEY> --route session:<your session id>`, or subscribe to it with `envoy_subscribe notifications.dispatch.issue.<KEY>.>`. When you release, clear the route with `--route ''`. Never route an issue with the `legion` label, or under one: Legion's roles work it, not your session.
-- Reading, commenting, asking or gating a PR claims nothing.
-- `409 ISSUE_CLAIMED`: someone else holds it. Never work it in parallel. Refusals and takeovers: [issues.md](skill://dispatch/references/issues.md).
+- When you finish an issue, take the top ready one: `todo`, by priority then board rank, per project.
+- `todo` means specced and waiting on nothing; one that waits goes in `backlog`, saying on what.
+- Hold at most three issues in flight; move the rest to `backlog`, saying where each is.
+- 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`.
 
 ## Issue status is yours to move
 
-Outside Legion, the session doing the work moves its issue and the children it owns. Use `in_progress` at implementation and `testing` while proven on a production-like surface. Use `needs_review` while its PR waits on the merge queue, and `done` with `--reason` once driven in production. Never write the status of an issue with the `legion` label or under one. The daemon writes those.
-
-## Asking
-
-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.
-
-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.
-
-### Before you ask
-
-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.
-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.
-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.
-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.
-
-Nobody else audits or retracts your asks. Passing the gates is your own check.
+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. An issue with the `legion` label, or under one: never write its status, and claim it only as a Legion role of its tree, even when its claim reads `· not running`, as a suspended architect's does: taking it takes the tree out of the workflow.
 
-```bash
-dispatch ask --issue <KEY> --question-file - --option 'Label: what it costs' --option 'Other: what it costs' <<'EOF'
-<the problem, what constrains the answer (each answer of theirs you rely on, linked), your recommendation and why>
-EOF
-```
-
-- You follow the ask you open. `--ref` appends a `dispatch://` link to the question.
-- 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`).
-- 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.
-- 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.
-- 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)).
-
-### When you need a human
-
-- Before you say you wait on a human, run `dispatch open-asks`. Add `--project <KEY>` to see every open ask in a project.
-- **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.
-- **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.
-- First try to make the step unnecessary: a value on the machine, a permission you hold, an API that replaces the click.
-- One ask per item, `--urgency high` when work halts on it. Keep working on everything else.
-- **Ask once.** Do not raise an open ask again in each message. The open ask is the request.
-- After it opens: [Asks after they open](skill://dispatch/references/asks.md).
-
-## Architecture components
-
-- Attach every architectural issue to the components it changes. Attach the root before you decompose it: children inherit.
-- `--components-json '{"mode":"explicit","ids":["web"]}'`, `'{"mode":"none","reason":"hiring, not code"}'` (only for non-architectural work, with a concrete reason), or `'{"mode":"inherit"}'`.
-- 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.
-- 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)).
+A claim delivers no comments: that turn, `dispatch issue-update --route session:<your id>` (`--route ''` on release) or `envoy_subscribe notifications.dispatch.issue.<KEY>.>`. Never route such an issue.
 
 ## Close what you opened
 
-- An ask you opened is yours until answered or resolved. When the answer arrives another way, or the design made it moot, `dispatch resolve-ask` in the same turn. Never leave it for the human.
-- Each later write names your open asks (`You still have an open ask on …`). Keep the ones still needed. Resolve the rest with the resolving fact as the reason.
-- Before a new ask, check your open ones. Retract one it supersedes with `--kind retracted` in the same turn.
-
-## Approval of a spec
-
-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.
-
-- 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`).
-- 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.
-- 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.
-- 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.
-- `--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.
-- Only humans approve. Never put "Approve" options in a `dispatch ask`. Details: [Approval requests](skill://dispatch/references/documents.md#approval-requests).
-
-## The Spec
-
-- Name each version that records a decision with `dispatch doc-edit --summary`.
-- 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.
-- Edit in place as [Editing a document](skill://dispatch/references/document-edits.md) says.
-
-## Typed blocks
-
-Write an `:::ask` or a callout only as [Documents](skill://dispatch/references/documents.md#typed-blocks) says.
-
-## Artifacts
-
-- 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.
-- 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).
+- An ask you opened is yours until answered or resolved. If it is answered another way or made moot, `dispatch resolve-ask` it that turn.
+- Resolve each open ask a later write names that is no longer needed; retract one a new ask replaces.
 
 ## Structure over stream
 
-- One issue per deliverable (an email to send, a document to review, a decision with its own life), with the content as its document. A message that carries a draft, a spec or more than a couple of paragraphs is an issue or an artifact instead.
-- Content lives in documents, decisions in asks. Messages only announce. Never split one deliverable into a message and an ask that points at it: put the reference in the question.
-- `You've sent N messages …` means three messages in a row with no human reply. Then wait, or ask once.
-
-## Messages
+- One issue per deliverable, its content the issue's document. Decisions are asks. A message only announces.
+- A message replies to a person or tells them what they must know now.
+- Text a person must read to decide belongs in the spec. An artifact is a real file.
 
-A message is a reply to a human's message, or a change a human must know now, such as a deliverable that landed. Never progress, "starting X", "still working", spec restatements or timed status. The PR summarises the work.
+## Architecture components
 
-```bash
-dispatch message --issue <KEY> --body-file - <<'EOF'
-<what landed, with its link>
-EOF
-```
+Attach each architectural issue to its components (`--components-json`), the root before decomposing it. Change code and `.dispatch/architecture/<id>.md` in the same review.
 
-- A message is not a decision or document feedback (`dispatch comment`). It wakes nobody unless the issue is routed.
-- Show a screenshot inline with `--image` on `message`, `comment` or `ask` ([Documents](skill://dispatch/references/documents.md#artifacts)).
-- Answer BTW, Aside, Steer and Agents-page messages as [messages.md](skill://dispatch/references/messages.md) says.
+## References
 
-## Following
+Link each item you name:
+
+```text
+dispatch://KEY
+dispatch://KEY/spec
+dispatch://KEY/artifact/<slug>[@vN]
+dispatch://KEY/ask/<id>
+dispatch://KEY/comment/<id>
+dispatch://KEY/message/<id>
+dispatch://PROJECT/artifact/<slug>[@vN]
+dispatch://PROJECT/artifact/<slug>/ask/<id>
+```
 
-You follow each ask you open or reply to. Replies to your comments and new comments on documents you wrote also reach you. Nothing else on an issue reaches you unless you subscribe ([asks.md](skill://dispatch/references/asks.md#following)).
+A bare id or filename is not a reference. An ask or comment id can be an 8-hex prefix.
 
-## References
+## Setup and the HTTP API
 
-Link every reference: an issue, ask, comment, spec or message ([reference forms](skill://dispatch/references/reading.md#reference-forms)), or an artifact. Link an eval by its viewer URL, a Slack message by its permalink, a Drive file by its share link. Never write "see this eval", "the comment above" or "per the spec" without a link. If a thing has no address, say so.
+- Use a personal token from Dispatch **Settings → Agent tokens**, as `DISPATCH_TOKEN` or `dispatch.token` in the session's `envoy.json`.
+- `GET /api/v1` lists every route; never guess one. Branch on an error's `code`, not its text.

package/skills/dispatch-first/SKILL.md

@@ -5,37 +5,43 @@ description: "Use when a session has the dispatch command, before you plan, file
 
 # Dispatch first
 
-Dispatch holds the open issues, their specs and the answers humans gave. A duplicate issue or a repeated question costs a human time and splits the history.
+Dispatch holds the open issues, their specs and people's answers. A duplicate issue or repeated question costs a person time.
 
 ## Search before you act
 
-- Before you plan, file an issue, ask, post a finding or start work, run `dispatch search` (`dispatch --help` lists every command).
-- Every query word must match, so each added word can only lose hits. Use two or three words: the thing and what is wrong with it, as a user names them. Never paste a draft.
+- Before you plan, file an issue, ask, post a finding or start work, run `dispatch search`.
+- Each query word must match. Use two or three words: the thing and what is wrong with it. Never paste a draft.
 
 ```bash
 dispatch search --query 'broadcast send order'
 dispatch search --query 'reviewer threads OR review comments'
 ```
 
-- No hits: drop a word before you add one. Try two or three wordings (the component's name, the symptom, the fix) before you conclude that nothing exists.
-- Open each hit that could be yours with `dispatch read`, then its parent (the `child_of` row under `Links:`; a document hit names its issue on `Issue:`). The parent's children and the `Components:` line show where the rest of the work is.
+- No hits: remove a word before you add one. Try two or three wordings before you decide nothing exists.
+- Open each hit that can be yours with `dispatch read --issue KEY`, then its parent (`child_of` under `Links:`, or a document's `Issue:`).
 
 ## What to do with what you find
 
-`dispatch issue` and `dispatch ask` also search: treat a hit in the result's `advice.suggestions` as one you found.
+`dispatch issue` and `dispatch ask` also search. Treat a hit in `advice.suggestions` as yours to read.
 
-- **Work already tracked:** put the finding on that issue (a comment, a message, or a spec edit). File a new issue only when no hit covers the work, and cite the nearest one you ruled out (`dispatch://KEY`).
-- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`) where you rely on it. Do not ask again.
-- **Duplicate found:** keep the issue with the spec and the discussion, and copy over what only the duplicate has. Then close it: `dispatch issue-update --issue <KEY> --status done --reason 'Duplicate of dispatch://KEY.'`. If it has the `legion` label, or another session or a human holds its claim, comment on it with the survivor's name. Do not close it.
-- **Every ask and message stands alone:** the reader sees only that text. Put the facts, the options and your recommendation in it. Link what you cite (`dispatch://…`). Never write "see above" or "my earlier message".
-- **In a Legion session, a finding outside your own issue is never an issue you file.** A Legion role, and each of its subagents, opens a `dispatch ask` as `skill://legion-worker/references/findings.md` says, in place of filing above.
+- **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`).
+- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`). Do not ask again.
+- **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.
+- **Each ask and message stands alone:** the reader sees only that text. Put the facts, options and your recommendation in it.
+- In Legion, file no finding outside your issue (`skill://legion-worker/references/findings.md`).
 
-## Design in the spec
+## Reach a person only through Dispatch
 
-- A design conversation with a person, or the plan that follows it, uses `skill://dispatch-brainstorming`. Read it before your first design question, the spec, or the plan. It replaces superpowers' `brainstorming` and `writing-plans` here, also when the user names one of them.
-- 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.
-- 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.
+A person does not watch your chat. Reach them through an ask, an ask block or an approval request.
 
-## Load the full skill before you write
+- 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`.
+- 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.
 
-Before any write to Dispatch, load `skill://dispatch`: an ask, a message, a comment, a document edit, a status change, a claim. Skip this if you loaded it in this session.
+## Which skill to read
+
+| Before you | Read |
+| --- | --- |
+| run your first `dispatch` command in this session | `skill://dispatch` |
+| 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`) |
+| plan work whose spec a person approved | superpowers' `writing-plans`, stored as the issue's `plan.md` (`skill://dispatch-writing-specs`, "The plan") |
+| write a Legion architect's own spec | `skill://legion-architect` too |

package/skills/dispatch-writing-specs/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: dispatch-writing-specs
+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."
+---
+
+# Writing specs
+
+## The aim
+
+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`).
+
+## The outline
+
+The spec is the issue's primary document. Find its project with `dispatch projects` or `dispatch search`, never the environment. Its `##` parts, in order:
+
+Part | Content
+--- | ---
+`Summary` | The change in the reader's own terms, at most 100 words
+`Problem` | What goes wrong, for whom, with counts
+`Goals and non-goals` | What is in and out of scope
+`Requirements` | `**R1.**` on, each naming its source (`From:`)
+`Design` | How it meets them; a value for each limit, size and time
+`Decisions` | Your own choices
+`Acceptance` | `**A1.**` on, each naming the requirements it tests
+
+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.
+
+## Rules for the text
+
+For each spec, ask, comment and message:
+
+- Write in `skill://asd-ste100`'s strict mode.
+- State the current design, never how people reached it.
+- 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.
+- Write about the design, never the person. Never quote people, repeat an answered ask, or upload their words.
+- Name your session only if a reader must reach it.
+- Keep only text that helps a reader understand, decide, build, check.
+- 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.
+- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
+
+## Questions
+
+- Propose an answer to each point, numbers included, with a reason.
+- A choice inside what the person asked for, or one their messages favour, is settled: decide it.
+- Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
+- 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.
+- Chat reaches nobody: use an ask or approval request.
+
+## Each version
+
+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.
+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.
+3. Before each approval request, a read-only agent checks its facts: `task(agent="scout")`, or `plan-gap-analyst` and `plan-reviewer` in Legion.
+4. Name each version with `dispatch doc-edit --summary`.
+
+## Decisions
+
+- Each design choice no source states is a `###` entry: choice, reason, options weighed, parts shaped.
+- An unsure entry adds an `Unsure:` paragraph: what would change your mind.
+- A replaced entry moves under a final `### Replaced`.
+- A person's decision is their answered ask block. Each part it shapes links it.
+
+## Old specs
+
+At your next edit, rewrite a spec outside the outline whole, in one version. Move its ask blocks with `doc-edit`'s `move`.
+
+## Approval
+
+- 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.
+- When their answer is the whole change since approval, Dispatch carries it.
+- 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.
+- A Legion root spec's design gate follows `skill://legion-architect`.
+
+## The plan
+
+Write the approved spec's plan with `writing-plans` as the issue's `plan.md`, not a repository file.

package/skills/leading-a-work-stream/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: leading-a-work-stream
+description: Use when you lead a work stream or team of agents, when an agent asks you to approve, confirm or review its step or pull request, when you want to know the state of the stream, when an agent starts a long project, or when you consider building tooling or a restriction for agents.
+---
+
+# Leading a work stream
+
+If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
+
+A lead raises the stream's numbers by making its agents faster, and is not a gate: agents waiting on your reply are a queue, and a queue is the stream's largest hidden cost. Keep it empty — answer at once, or reply "your call" — and when one kind of question keeps arriving, write the answer into the stream's plan or skill, or build the tool that makes the question unnecessary. The stream's own facts (its numbers, scoreboard format, plan, dashboard) are in its issue spec or the organization's stream document; read them there.
+
+In a Legion tree, the daemon's workflow and your role prompt decide who starts a worker, who accepts the work and how it merges. This skill does not change that sequence. There, a tool the stream needs is a child of your tree or a finding (`skill://legion-worker/references/findings.md`), not an agent you start on your own. Why each rule below works: [sources.md](skill://leading-a-work-stream/references/sources.md).
+
+## What a lead does
+
+1. **Sets direction**: the numbers and targets, the bottleneck, and which experiments run in what order, written where every agent can read it, so each agent constrains its own choices by it. How to open the stream's issue and get its three lines from the user: [direction-and-coaching.md](skill://leading-a-work-stream/references/direction-and-coaching.md).
+2. **Removes obstacles** its agents cannot: access, a decision above their authority, a conflict with another stream.
+3. **Checks results against the numbers**, not against its own reading of the work.
+4. **Coaches each agent's loop**: does it measure its number, write a prediction before each change, and compare more than one design? Give procedure, not solutions, because the agent has the facts of its own work. Which workflow a change or an experiment runs through, and what it predicts before it starts: [direction-and-coaching.md](skill://leading-a-work-stream/references/direction-and-coaching.md).
+5. **Makes the stream faster**: finds where agents lose time and changes the skill, tool or step that causes it.
+6. **Proves its facts with a command.** A claim about what exists or what a thing can do rests on a command and its output, not on a reading. A claim that nothing exists rests on a command whose search could have found it: state the search and why it could match. A lead's facts about its own stream are the ones nobody else checks.
+7. **Keeps the stream's record of what each agent accepted.** At each check-in, read it against the agents' issues and open asks. An item that is neither done, in progress, nor an open ask is dropped work. The lead finds its owner and has it recorded at once.
+
+## The speed loop
+
+Arm a reminder that wakes you every 3 hours and run the six-step loop it names: [speed-tick.md](skill://leading-a-work-stream/references/speed-tick.md). A reminder inside the session dies with the session, and a stream nobody measures for speed slows to the pace of its slowest wait.
+
+## Dates
+
+A date is the time the work takes at agent speed, plus only the waits nobody can shorten. Agents run in parallel and around the clock, so a day of agent work is due tomorrow, and ten minutes of work is due within the hour.
+
+- Each date carries its basis in one line ("about 3 h of work, 2 h of benchmark runs"), so padding is visible.
+- A key performance indicator (KPI) is one of the stream's numbers in its issue spec. A KPI target's date is the earliest date the fastest plan you can write down reaches it. Then shorten the plan: more agents in parallel, the slow step removed, a first slice that lands today.
+- When a date will slip, say so the moment you know, with the new date and why. A date beaten by days was padded: set the next date for that kind of work earlier by the margin you beat this one by.
+
+## What a lead does not do
+
+- Gate a decision an agent can make. A concern about a reversible step goes to the agent as a constraint, and the agent decides.
+- Review every pull request. Peer review and tests are the approval.
+- Require a plan, spec or confirmation to be sent to it before an agent acts.
+- Ask agents for a report of each decision or step. Read results in GitHub, Dispatch and the numbers, and measure a number with a command you run.
+- Ration a shared resource (disk, VMs, compute) by approving each use. Set the limit, and the agents apply it themselves or through a tool.
+- Relay messages between agents who can talk directly.
+- Give an agent orders specific to its own work (which task to launch, at what size, what to regrade): the agent has the facts of its own work and the lead does not. Give the rule and the goal (the target, the budget, the bottleneck) and let each agent choose its steps. Before you pass on a precondition from another agent, check it against the code or have its owner send it directly.
+
+## Decision rights
+
+A step that is easy to undo is the agent's: it acts and reports to nobody, and you read the result in GitHub, Dispatch and the numbers. A step that is hard to undo goes from the agent to its owner directly — a person through that agent's own Dispatch ask, the other stream's lead, the owner of the shared infrastructure — never through you, because a relay adds a wait and loses the agent's own facts. Which steps fall where: [decision-rights.md](skill://leading-a-work-stream/references/decision-rights.md).
+
+When an agent asks permission for an easy-to-undo step, reply "your call" and state any constraint it must keep; add no check of your own before it may act. Do not send a "yes" to an agent that said it would not wait, because the reply arrives as an interruption with nothing in it.
+
+## Rules reach agents through what they read
+
+A rule sent only by message reaches the agents online that day, in the lead's paraphrase, and is gone for the next session. Put each rule where agents read it before they act — the skill that covers the step, the stream's brief, the repository's own instructions — written as an instruction at the step it governs.
+
+Keep one record of the words of the person the stream works for, each quoted with its date and source, and link that quote wherever a text says the person wants something ([user-quotes.md](skill://leading-a-work-stream/references/user-quotes.md)). Never shorten a quote into a stronger rule ("don't regrade his finished versions without asking him" is not "never regrade"), and never turn a direction into a number the person did not give.
+
+## Keep every request and wait in Dispatch
+
+You answer for every request the user gives any of your agents, and for every wait any of them has.
+
+- **A request from the user goes on a claimed Dispatch issue before work on it starts**: a line in that issue's `open-items.md` artifact, never its spec, since each spec edit after approval is a new version that closes the design gate. Add it within the hour — what, who asked, a link to the source, what done means (deployed, merged, measured) and a date. A line leaves only with a link to the evidence that it is done, or to the user's agreement that it is dropped.
+- **Done is delivered and checked: you saw the result yourself** (deployed, merged, measured). Written into a spec, an approval requested, a todo closed or a message sent to an agent is not done.
+- **A wait on a person is an open Dispatch ask the moment you know it** — never only a chat question, a note, a peer message, a comment on an answered ask, or a review request, because nobody tracks those. A wait on anything else is an `open-items.md` line naming the blocker, its owner and its link. Keep working on everything else.
+- **Every hour, run the stream's Dispatch check,** the command its brief names. **Once a day, run the repository's dropped-work audit over each agent's transcript and your own;** it also lists long idle spans with work open and long projects that do not use their workflow skill. Each agent gets its own findings directly, and you write in the stream's issue how many items each audit found.
+- Three more rules of this upkeep — checking a delegated result, a step held back from a hand-over, and what to re-read after a restart — are in [dispatch-upkeep.md](skill://leading-a-work-stream/references/dispatch-upkeep.md).
+
+## Plan the day with the team
+
+Every morning by 09:00 Pacific, you and your agents agree on Envoy what the stream will merge today, and you write that list into the stream's record, checking that each item has an agent that committed to land it; without it each agent optimises its own day and the stream's numbers move by accident. How the planning runs, what an item must say, and the end-of-day comparison: [daily-plan.md](skill://leading-a-work-stream/references/daily-plan.md).
+
+## Knowing the state of the stream
+
+From records you read yourself (GitHub, Dispatch, the numbers), answer: what is the target; what is the actual value now; what is the obstacle, and which one is being worked on; what is the next step and what should it do to the number; when will we know? Message an agent to plan the day with it, to remove an obstacle or to change its direction, not to collect status.
+
+## Before you say something is blocked
+
+**Read the thing itself, not the thing next to it.** Before you write that X is blocked by Y, read X's own state: `gh pr checks` at the head, not the queue's length; the process (`ps -eo pid,etimes,args | grep <session-id>`) and the session's last tool call, not a registry's session list; the job's own start time, not the pool's history. In one day on one box this error was made four times and two of those reached every stream; each was cheap to check and expensive to act on, because a stopped resource and a contended one look identical from a queued job, and a session waiting for its workers looks identical to a dead one.
+
+**A blocker you relay to other streams carries the command that shows it.** Without it, each stream spends a check to disprove it after acting on it.
+
+**Ask a fresh reviewer, for each claimed cause, to name the command or record that would show it FALSE, and to run it.** A reviewer that reads only the prose confirms a confident wrong cause. The causes that cost most are the ones nobody could falsify, because nobody looked for what would disprove them.
+
+**Run a watch that names quiet sessions, and let it restart nothing.** A session that dies mid-task stays dead until a person notices: measured at about 7 hours on a day when one credential failure stopped a box, and at 5 minutes or less once a watch existed. A watch reads the session's transcript modification time, its process and, if it can, its pane; it reports, and the owner decides. Two traps: a systemd user service on a dev box may not reach the tmux server at all (it answers `server exited unexpectedly` while the same command works from a pane), and a watch built on an agent-messaging registry reports live sessions as dead under load. Test it by making it report something you know is true.
+
+## Delegation and tooling
+
+- Use subagents and peer agents for review, research and skill improvement. Delegation keeps the responsibility with you: when a delegated result lands, read the number it was meant to move yourself.
+- When an agent starts a long project, check that it uses the workflow skill for that kind of work and name the skill: the `/sdd` workflow for an engineering project, `building-and-delivering-tasks` for RL task work. That skill's own review steps replace review by the lead.
+- When agents keep losing time to the same chore, start an agent to build the tool that removes it. Do not wait to be asked.
+- Do not build, file or ask for a restriction, guard or gate against a failure nobody has seen. Fix a real failure at its cause, after it happens.
+- When the user asks the stream for an explainer video, you own it: have a subagent make it with the `making-explainer-videos` skill.
+
+## Improving this skill
+
+When a rule here failed or was missing, edit this file directly, and put the evidence in the commit message, so the next lead gets the fix instead of the same failure.

package/skills/leading-a-work-stream/references/daily-plan.md

@@ -0,0 +1,8 @@
+# Planning the day with the team
+
+Every morning, by 09:00 Pacific, the lead and its agents agree on Envoy what the stream will merge today, as a working team does at its daily planning: each agent says what it can land and what stands in the way, the team settles the list, and the lead writes it into the stream's record. The lead owns the list and that it is real.
+
+- Each item starts with the key performance indicator (KPI, one of the stream's numbers) it moves and the change expected, for example "Grade wall time 7,104 s -> 5,700 s: ...", so the day can be checked against the numbers.
+- Work that moves no KPI goes on the list only when it unblocks an item that does, and names that item.
+- During the day, an agent that will miss an item says so as soon as it knows, so the team can move work.
+- At the end of the day, post each item's actual KPI reading next to its prediction in the stream's record, and ask the owner of each missed item on Envoy what blocked it.

package/skills/leading-a-work-stream/references/decision-rights.md

@@ -0,0 +1,6 @@
+# Decision rights
+
+| The step | Who decides |
+| --- | --- |
+| Easy to undo: a code change, a flag, a branch, opening or merging a pull request that passed peer review and tests, a planned experiment, and any spending the workflow itself calls for (a paid-API review, compute, a VM, a model run the task needs) | The agent. It acts and reports to nobody: the lead reads the result in GitHub, Dispatch and the numbers. |
+| Hard to undo: deleting data someone else created, a new financial commitment (a contract, a subscription), a message outside the organization, security, another stream's work or shared state | The agent takes it to its owner directly: a person through the agent's own Dispatch ask, the other stream's agent or lead, the owner of the shared infrastructure. It does not pass through the lead. |

package/skills/leading-a-work-stream/references/direction-and-coaching.md

@@ -0,0 +1,13 @@
+# Setting direction and coaching the loop
+
+## The stream's three lines
+
+Open the stream's issue with three lines above its targets: the problem the stream exists to solve, the one approach it commits to, and what it will not do. Agents use the third line as a constraint on their own choices, so without it they take work the stream decided against.
+
+Ask the user those three questions once, in one message, each with a draft answer taken from the user's own words. If an answer rules no work in and none out, ask once more with two concrete options.
+
+## Coaching an agent's loop
+
+- An experiment on a number, with a benchmark that runs in minutes, goes through `/autoresearch`: the expected gain is in its notes before each run, and the change is run again before it is kept, so a result that came from noise does not survive.
+- Use the `ce-optimize` skill instead when the result is noisy or has several objectives.
+- A one-off change still gets its prediction written in the scoreboard before it starts, so a wrong prediction is visible instead of explained away afterwards.

package/skills/leading-a-work-stream/references/dispatch-upkeep.md

@@ -0,0 +1,7 @@
+# Dispatch upkeep: the rest of the lead's rules
+
+These go with the "Keep every request and wait in Dispatch" section of the skill.
+
+- **Check a delegated or relayed result against its done before you report it**, because an agent's "done" is often a message sent, not a thing delivered. Each follow-up the result names becomes a claimed issue, an ask, or an `open-items.md` line, the same hour.
+- **A step you keep back from a hand-over becomes its own claimed issue,** blocked by the handed-over one, or it is lost when the hand-over closes.
+- **After a restart or a compaction, first re-read your claimed issues and your open asks** (`dispatch open-asks`), then the transcript since your last audit, because what you were waiting for is not in the new context.

package/skills/leading-a-work-stream/references/sources.md

@@ -0,0 +1,9 @@
+# Why these rules
+
+- Bezos, [2015 shareholder letter](https://www.sec.gov/Archives/edgar/data/1018724/000119312516530910/d168744dex991.htm): reversible decisions go to individuals, fast; a heavy process on them causes "slowness, unthoughtful risk aversion".
+- DORA, [Streamlining change approval](https://dora.dev/capabilities/streamlining-change-approval/): external approval slows delivery and does not cut failed changes; peer review plus automation works; more process after problems makes things worse.
+- US Army, [ADP 6-0 Mission Command](https://armypubs.army.mil/epubs/DR_pubs/DR_a/ARN47032-ADP_6-0-000-WEB-1.pdf), 1-37 to 1-44: act within intent; delegation cuts response time; responsibility stays with the commander.
+- Google re:Work, [research behind great managers](https://rework.withgoogle.com/intl/en/guides/following-the-data-the-research-behind-great-managers): good managers coach and "empower the team without micromanaging".
+- Rother & Liker, [A Kata for PDCA](https://cdn.prod.website-files.com/68b9f0686639ca6b3c064d61/68dd8a5720bf6d3042bafc50_a_kata_for_pdca_-_target_summer_2014.pdf), and [LEI, Kata](https://www.lean.org/lexicon-terms/kata/): the five questions; the coach gives procedure, not solutions.
+- Reinertsen, [Product Development Flow, ch. 1](http://lpd2.com/wp-content/uploads/2013/06/ReinertsenFLOWChap1.pdf): queues are the largest hidden cost.
+- [Summary of Grove's High Output Management](https://www.becausetech.rocks/blog/high-output-management/): meddling makes people refer problems up; follow delegated work through.