@sjawhar/opencode-legion-envoy 9.0.0 → 9.1.0

package/skills/dispatch/references/document-edits.md

@@ -1,59 +0,0 @@
-# Editing a document
-
-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.
-
-```bash
-dispatch doc-edit --issue <KEY> --artifact spec --summary '<names the version>' --ops-json-file - <<'EOF'
-[{"op": "replace", "find": "old sentence", "with": "new sentence"}]
-EOF
-```
-
-- 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.
-- The output names the version, `unchanged_ops`, `lost_ops`, and a `Document token:`.
-- Use `--summary` to name a version that records a decision.
-
-## Targeting text
-
-- 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.
-- 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.
-- `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.
-
-## Rewriting paragraphs
-
-- **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.
-- 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.
-- Fewer: `delete` each leftover paragraph by its whole text or `block` id.
-- `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.
-- 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.
-- Dispatch refuses block HTML (`<div>`, `<!-- -->`, a lone `<br>` paragraph) in `with`. Inline HTML stays.
-- To add a rule, `insert` `***`. A `---` in `with` is stored as `\---`.
-
-## Blocks and ids
-
-- 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.
-- `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>"}`.
-- 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.
-- `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.
-- 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.
-
-## Tables
-
-- `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.
-- 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.
-
-## Stale and concurrent edits
-
-- 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.
-- Chain guarded edits by passing each output's token to the next. Read once, not once per edit.
-- `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.
-- 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.
-
-## Edge cases
-
-- 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.
-- A CR LF or lone CR in any text you write is stored as a line feed.
-- Replacing a non-paragraph block writes its marker as text. A backtick fence becomes an inline code span. A tilde fence stays literal.
-- An anchor that straddles the rewritten text keeps its mark on the words you left, with a shorter quote.
-- Emptying a task item's first paragraph while another block follows it is `INVALID_OP`.
-- 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.
-- An op that only takes text out is never reported lost.

package/skills/dispatch/references/documents.md

@@ -1,79 +0,0 @@
-# Documents: typed blocks, comments, suggestions, and artifacts
-
-Read this to write a typed block, comment, suggest, upload an artifact, request approval, or handle `DOC_SCHEMA`, `INVALID_ASK_BLOCK` or `DOC_SERVICE_UNAVAILABLE`. Text and table edits are [Editing a document](skill://dispatch/references/document-edits.md).
-
-## Typed blocks
-
-- Use only the types, content rules, attributes and enum values from `GET /api/v1/schema/blocks`. Quote values: `:::callout{kind="warning" title="Risk"}`. Never set an attribute marked `server: true`.
-- Write the container form only: `:::name{#block-id key="value"}` on its own line, block children, and a closing line with the same number of colons. A block inside another, or one whose code holds a `:::` line, needs the outer fence one colon longer. Never write Pandoc `::: {.callout}`, leaf `::name` or text `:name`.
-- Dispatch refuses an unclosed block, and an opening indented four or more columns under a paragraph. An opening inside a line is stored as text.
-- For a new block, omit `#block-id`: Dispatch mints it. When you edit one, keep its id and every attribute. Never copy an id into new markdown. To rewrite a block whole, `delete` it, then `insert` it with its id, in one batch. You cannot do this to an open ask's block: use `replace`, `move` or `dispatch edit-ask`.
-- Questions about a document are `ask` blocks, never an "Open questions" section. The body is question paragraphs, then an optional bullet list of `Label: description` options. A code block, heading or quote, a paragraph after the options, or a second list is `INVALID_ASK_BLOCK`.
-
-```md
-:::ask{urgency="high" multiple="false"}
-Today's release is blocked by a database migration. The maintenance window closes in two hours;
-whether production data needs an index rebuild is unknown. How should we complete the migration?
-Recommendation: rehearse on a production snapshot, then apply in the window, because it finds the
-unknown cost before production while keeping today's release possible.
-
-- Apply now: Meets today's release, but recovery may be slower if the index rebuild is needed.
-- Rehearse then apply: Costs rehearsal time, but exposes the rebuild and rollback cost before production.
-- Defer the release: Avoids migration risk today, but leaves the release and its fixes unavailable.
-:::
-```
-
-- A human's answer lives on the ask. Never rewrite the question into its answer or blank its options. Resolve without a human with `dispatch resolve-ask`.
-- An answered or resolved ask's question is fixed. Dispatch writes its block back. To ask something new, write a new block. An open ask's block is its text.
-- `This spec holds no ask blocks …`: either no decision is needed, or you forgot the block. `… typed-block openings in this document are text, not blocks`: fix the markdown and upload again. Put an intended mention in code.
-- Neither check sees a spec wrapped in a code fence, an opening like `::ask{` or `:::ask {`, or any `doc-edit`. After an edit that writes an ask, `dispatch doc-read` the section and check that it renders `:::ask{#<id> …}` on its own line.
-
-## Comments and suggestions
-
-```bash
-dispatch comment --issue <KEY> --artifact spec --quote '<the passage>' --body '<the question or note>'
-dispatch suggest --issue <KEY> --artifact spec --quote '<exact text>' --replace-with '<replacement>'
-```
-
-- An exact replacement is a suggestion, never a comment: a human accepts it with one click. A comment is for a question or note answered in words.
-- Omit `--quote` and `--artifact` for a floating comment. A reply (`--reply-to`, `--reply-to-ask`) takes no quote. Threads are flat. A reply reopens a resolved thread, except a decided suggestion's. `--turn` works only with `--reply-to-ask`.
-- `--ref` names the owner only. Dispatch refuses an ask, comment or message link there.
-- Resolve your own comment once addressed: `dispatch resolve-comment --comment <id>`. It takes no reason, so reply first if needed. Resolve only threads you opened or were asked to close. Reopening a resolved thread from the dashboard is human-only, but your reply to it reopens it, except a decided suggestion's.
-- Suggest only what the quoted block can hold. The accept checks it, and a refused accept stays open.
-- Error codes: `TARGET_AMBIGUOUS` (add `--occurrence`), `TARGET_NOT_FOUND` (re-read), `INVALID_ANCHOR` / `ANCHOR_MISSING` / `ANCHOR_ORPHANED` (bad or stale quote), `INVALID_MARKDOWN` / `DOC_SCHEMA`, `CAP_EXCEEDED`, `ISSUE_CLOSED`.
-
-## Artifacts
-
-```bash
-dispatch artifact --issue <KEY> --name diagram.png --path ./diagram.png
-dispatch artifact --issue <KEY> --name load-test-results.md --content-file - <<'EOF'
-# Load test
-EOF
-```
-
-- Uploading the same `--name` makes its next version. Never upload `spec.md`: it replaces the human's spec. Edit with `dispatch doc-edit`.
-- Address an artifact by the slug the upload printed. A bare `--artifact` that names two documents (a slug and a filename) is refused with both ids. A `dispatch://` reference always uses the slug.
-- A copy of another document's `:::ask` block (same `#id` and text, same owner) opens no ask. It mirrors the original. Answer the original. Change the copy's text and it opens its own ask.
-- A picture from an Agents-page conversation is `dispatch://agent/<session id>/artifact/<slug>@vN`. `dispatch doc-read` reads it by that reference alone.
-- Show a picture inline with `--image` on `message`, `comment` or `ask`, not `dispatch artifact`. Each adds about 60 characters that count toward the cap. A plain `dispatch://KEY/artifact/<slug>` link to an image shows a thumbnail.
-- `dispatch read` and `dispatch doc-read` write pictures to files and print `- picture: <path>`. Open each with your file-read tool. A session sees each picture once. `dispatch doc-read` shows it again, after compaction too.
-- Documents are CommonMark. Put Slack mrkdwn or other non-Markdown in a fenced code block.
-- In a table cell, write every `|` as `\|`, inside code and links too. A row wider than its table is refused.
-
-## Approval requests
-
-```bash
-dispatch request-approval --issue <KEY> --summary '<what the human is approving>'
-```
-
-- It opens an `Approve` / `Request changes` ask on the latest version. It is refused while a decision block is open. A block written in the last few seconds counts as open.
-- An answer or resolve reaches a version about two seconds later. Wait for that version, do not edit to force one. A waiver carries no record: write the decision into the text before you request.
-- A document holds one open request. A new version moves it and leaves it `waiting on agent`. Run the command again when "Approval of a spec" allows, to hand it back. Your own thread reply hands it back too, unless you reply with `--reply-to-ask` and `--turn agent`. A `--reply-to` reply takes no turn flag, so it takes the default, `human`. Exception: a new version moved the request since your last `dispatch request-approval`. Then no reply hands it back: run `dispatch request-approval` again. While it waits on the human, a different `--summary` is refused.
-- The answer arrives as `artifact.approved` or `artifact.changes_requested` with its version. `changes_requested` carries the reason: that is your next work. `stale` means approved, then changed.
-- A human's own answer to a block can carry their approval forward. That needs no change outside the blocks, and their answer on every new or answered block. Then `dispatch doc-read` shows `Approval: approved vN`. Anything else leaves it stale, and the card shows a diff: make the next `--summary` one sentence on what changed.
-
-## A document that is reloading
-
-- `DOC_SERVICE_UNAVAILABLE` (503) means the document's live room is reloading. Your call wrote nothing. Nothing retries for you. Wait a few seconds and repeat the same call.
-- A second refusal in a row: tell the human, with the document's reference.
-- It comes from calls that write a document. Those are `doc-edit`, a quoted `ask` or `comment`, a reply in an anchored thread, and `suggest`. Also `resolve-comment` on an anchored comment, an `artifact` that replaces a document, and `edit-ask` / `resolve-ask` on a block ask. `doc-read` returns it only when the durable copy is unreadable.

package/skills/dispatch/references/examples.md

@@ -1,85 +0,0 @@
-# Before and after: a decision block, a reply, a message, and a draft
-
-## Before / after
-
-Before: a wall of text hides the decision, and the human never gets it.
-
-```text
-The deploy branch has the migration and dashboard changes. Staging is fine, but release notes are
-not reviewed before tomorrow's customer demo. Review the notes, ship without them, or cut the
-dashboard from the release. Waiting is safest, but the list above may be stale.
-```
-
-After: a decision block in the section it concerns, each real option a button.
-
-```bash
-dispatch doc-edit --issue LEGION-815 --artifact spec --ops-json-file - <<'EOF'
-[{
-  "op": "insert",
-  "after": "Release requires reviewed operator instructions before deployment.",
-  "markdown": ":::ask{#release-gate urgency=\"high\"}\nRelease notes are unreviewed, and tomorrow's customer demo means the release cannot wait for a later review. How should we proceed? Recommendation: review the notes, then ship, to keep the release complete and reviewed.\n\n- Review notes, then ship: Delays release for review but keeps the release complete and reviewed.\n- Ship now: Meets the demo deadline but leaves the release notes unreviewed.\n:::"
-}]
-EOF
-```
-
-Before: a progress note nobody needs.
-
-```bash
-dispatch message --issue LEGION-815 --body 'Merged the release PR, moving to docs next.'
-```
-
-After: nothing. The PR shows the merge. Post only when a human must act or can use a deliverable:
-
-```bash
-dispatch message --issue LEGION-815 --body 'Release 1.4 is live on the devbox (dispatch://LEGION-815/artifact/release-notes). Nothing needed from you.'
-```
-
-Before: the draft is a separate file, the spec only names it, and the ask does not link it.
-
-```bash
-dispatch artifact --issue OPS-52 --name cu-update-2026-09-15.md --content 'Hi team, ...'
-dispatch doc-edit --issue OPS-52 --artifact spec \
-  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft (artifact cu-update-2026-09-15.md)"}]'
-```
-
-After: the draft is a spec section, and the ask (a human-only send) anchors there. A real file is linked by its slug from both.
-
-```bash
-dispatch doc-edit --issue OPS-52 --artifact spec \
-  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft\n\nHi team, ..."}]'
-dispatch ask --issue OPS-52 --anchor-json '{"artifact":"spec","quote":"Hi team,"}' \
-  --question 'Customers need an update today, and the reviewed text is ready in the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.' \
-  --option 'Send the reviewed update: Delivers the update today but makes its text external.' \
-  --option 'Hold the update: Avoids sending now but leaves customers without the update.'
-# or, for a real file:
-dispatch doc-edit --issue OPS-52 --artifact spec \
-  --ops-json '[{"op":"insert","after":"## Context","markdown":"## Draft\n\nThe update to send: dispatch://OPS-52/artifact/cu-update-2026-09-15-md"}]'
-dispatch ask --issue OPS-52 --ref dispatch://OPS-52/artifact/cu-update-2026-09-15-md \
-  --question 'Customers need an update today, and its reviewed text is linked from the spec. Sending it cannot be recalled. How should we proceed? Recommendation: send the reviewed update.' \
-  --option 'Send the reviewed update: Delivers the linked update today but makes its text external.' \
-  --option 'Hold the update: Avoids sending now but leaves customers without the update.'
-```
-
-## Naming the mechanism
-
-Before: the reply paraphrases its tool, route and event away.
-
-```text
-Today, when a spec is ready, the architect tells Legion so with a dedicated call on its Legion
-tool, and Legion then waits for your approval. This change removes that call, because Legion will
-notice your approval of the spec by itself.
-```
-
-After: the reader's sentence first, then each mechanism by name, with how it works in a clause.
-
-```text
-For you nothing changes: you still click Approve on the spec. What goes is a step the architect
-takes today: it calls `register_gate` on its `legion` tool, which posts to the daemon's
-`POST /legion/v1/gates/register` route and names the spec document and the version that gate the
-tree. The daemon opens the gate when Dispatch emits `artifact.approved` for that document at that
-version, which Dispatch does when you click Approve on the request the architect opened with
-`dispatch request-approval`. Without `register_gate`, the daemon reads the issue's primary
-document from Dispatch itself and waits for the same event.
-```
-
-"A dedicated call", "tells" and "notice" each stood for something the reader can search, find in a log, or set.

package/skills/dispatch/references/issues.md

@@ -1,66 +0,0 @@
-# Working an issue: choosing, claiming, status, priority, and the backlog
-
-Read this to choose, claim or release an issue, or to handle `409 ISSUE_CLAIMED`. Read it to move status or priority, reorder a board, reassign, sync an architecture model, or audit a backlog.
-
-## Choosing what to work on
-
-- When you finish an issue, or are told to take the next thing, take the top ready issue of the backlog, across every project. Ready means status `todo`, sorted by priority, then board rank. No areas: a standing role, a product owner and a lane take the top issue too.
-- `todo` means ready: specced, unblocked, waiting on no deploy and no decision. An issue that waits on one goes in `backlog`, with what it waits on said on the issue.
-- Hold at most three issues in flight (`in_progress`, `testing`, `needs_review`, `retro`), of any kind, per agent. A child counts on its own. Priorities decide only what you pull next. Past three: push unfinished work, say where in one comment, move it to `backlog` and clear its route.
-- An in-flight issue with no owner goes back to `backlog`. No owner means no claim or route held by a live session, no Dispatch activity in a day, and no PR moving on GitHub. The order keeper sweeps those.
-- Never write the status of an issue with the `legion` label or under one. A status you write on a running Legion root is set back and its architect is told. Only a person in the dashboard, the controller's `set_status`, or the operator stops that tree. On a child, a status out of the flow parks it and stops its workers.
-- Set priority yourself. Never reorder the board: one agent keeps each project's order, and in a Legion deployment that agent is the controller, at `notifications.role.legion-<project>-controller`. When the top looks wrong, or a priority's next step is not a ready issue, publish it there, and say it on the issue where no Legion controller runs.
-- The keeper moves a card with `dispatch issue-update --issue <KEY> --before <OTHER>` or `--after <OTHER>`.
-
-## Claim the issue before you work it
-
-```bash
-dispatch claim --issue LEGION-234             # I am implementing this
-dispatch claim --issue LEGION-234 --release   # I have stopped; it is free
-```
-
-- A claim records your own session. Reads show it (`Claimed by:`). `· not running` means the holder is gone and you can take it. `· liveness unknown` says nothing. Find free work with `dispatch issues` and the dashboard's **Unclaimed** filter.
-- `409 ISSUE_CLAIMED` from a live session: never work it in parallel. Message that session (`envoy_send`) or take other work, and tell the human if you think it should be yours. From a human: ask them with `dispatch ask`. Never assume a human's claim lapsed. Only a human releases or forces it.
-- `409 CLAIM_CONTENDED`: nothing applied. Read the issue and decide again.
-- Release when you stop. The holder, any human, or any agent once the holder's session ended can release it.
-- Claiming moves no status. Do both when you start.
-
-## Issue status is yours to move
-
-- Move it as a person moves a card, root and owned children: `in_progress`, `testing`, `needs_review`, then `done` once driven in production. A merge is not `done`. An issue left in `triage` while work runs is a defect. Waiting for the deploy lane is not a status and is never announced. Never the status of an issue with the `legion` label or under one: the daemon writes those, and a status you write there is undone.
-- `--status done` needs `--reason`. Dispatch posts it as a message, then closes. If the close fails after the post, read the status first. A retry points its reason at the posted message.
-- Clears differ: `--clear-priority`, `--parent ''` / `--route ''` / `--repo ''`, `--clear-external-links` / `--clear-blocked-by`. See `dispatch issue-update --help`.
-- Repository: own `--repo`, else nearest ancestor's, else the project default, else none. Unmapped is `REPO_NOT_MAPPED`. `dispatch read` shows `Repository:`. `Repository: unknown (…)` is an older server: a `--repo` write there fails.
-- Link the delivering PR with `--external-link` when you open it.
-- `… is still in triage …` on a write: move the status once work starts. It never appears on an issue with the `legion` label or under one, since the daemon moves those out of triage itself.
-
-## Priority is yours to set
-
-- `0` (P0, highest) to `3` (P3), `null` clears. Set it on creation and on grooming passes over issues with none. Say what you set and why. The human overrides from the dashboard.
-- A closed issue takes only a board move (`--before` / `--after`), `components`, a reopening status, and an external-links write that adds no link. Reopen first, then set priority, in two commands (`409 ISSUE_CLOSED`).
-- Labels are optional. Dispatch trims them, keeps their case, and drops case-insensitive duplicates.
-
-## Board rank, priority, and assignee
-
-- Reads carry `rank`, nullable priority, and `assignee`: a lowercase email, or `null`. `dispatch read` prints `Assignee: unassigned` for `null`.
-- Move a card with `dispatch issue-update --issue <KEY> --before <OTHER>`, which puts it above that issue, `--after <OTHER>`, which puts it below, or both together, which land it between them. The neighbour is an issue of the same project and never the issue itself, and the server refuses a pair the board does not hold in that order. The move rides along with any other change in the same call, and a closed issue takes it.
-
-## Reading a project's backlog
-
-`dispatch issues --project <KEY>` lists every issue with status, priority, parent, labels, open asks and last change. It is not search. Filters and paging are in `--help`. A page walk is exact only while the list holds still.
-
-### The owner audit
-
-As a surface's owner, run `dispatch issues --project <KEY> --priority 0 --priority 1 --limit 250` at each checkpoint of a coordinator's loop. These shapes show up only when you run the check.
-
-- Each unclaimed row in `triage`, `icebox`, `backlog` or `todo` is a decision: someone builds it, or it closes. Rows in flight or claimed are not re-staffed.
-- A close that says the defect cannot happen cites the code that prevents it. A close by rewrite names the file and line that forecloses it. Without one, the issue is unread, not foreclosed: a rewrite reaches parity most cheaply by porting the defect.
-- Find four shapes:
-  - **Unstaffed work**: a plan or measurement exists, nobody builds it.
-  - **Unrecorded delivery**: a merged PR names an issue not yet in `testing` or `done`. Check it live, then move it.
-  - **Unrecorded practice**: someone does the issue's work by hand more than once. The tell is your own messages. Fix the status.
-  - **Unreachable route**: the priority filter above never finds it, whatever its priority. List it on its own with `dispatch issues --project <KEY> --route-status no_holder --limit 250`. A route is unowned only when two reads ten minutes apart both list it, since a restarting session is absent for minutes. Check with the second `dispatch issues`, not `envoy_role_get`, which releases an absent holder's claim. Then staff the role, re-route to a live holder, or clear the route and assign. `unknown` means the listener did not answer.
-
-## Syncing a project's architecture model
-
-A project imports its model from one or more source repositories, each on its own branch. `dispatch architecture-sync --project CORE` imports every source now and prints a line for each: `Synced CORE architecture from <repo>@<branch>: commit <sha> (<time>).`, or `Sync failed for CORE (<repo>@<branch>): <error>` followed by what of that source still shows: its commit, its component count when the source was re-saved on another branch and has not imported from it yet, or that none ever imported. A failed source keeps its previous components; every other source is untouched. `--repo <owner/name>` imports that one source alone. No source configured, or no source from that repository, answers `SOURCE_NOT_FOUND`. A credential or branch problem is that source's failed line, or with `--repo` an error, `SOURCE_ACCESS`.

package/skills/dispatch/references/messages.md

@@ -1,31 +0,0 @@
-# Answering targeted and direct messages
-
-Read this when a Dispatch frame targets you as BTW, Aside or Steer, or a human messages you from the Agents page.
-
-## Targeted agent messages
-
-- A human (or a bearer over HTTP) can target an issue message at your session or role. The modes are **BTW**, **Aside** or **Steer** (the dashboard says **Send**). The frame names the issue and a `reply_with` hint.
-- Reply on that issue with that command, never a new targeted send:
-
-```bash
-dispatch message --issue CORE-1 --in-reply-to <targeted-message-id> --body 'The requested answer.'
-```
-
-- A BTW can post its answer automatically. Reply yourself when the frame asks the primary agent to.
-- A human's reply to you arrives as a frame with `in_reply_to` and `reply_body`. Answer it the same way, with their reply's id.
-- `dispatch message` never carries `target` or `delivery`. Agent-to-agent traffic goes over Envoy or `agent://`.
-- A bearer that targets over HTTP names its session in `actor` (`{kind: "session", id}`). Target only a session that `GET /api/v1/agents` lists with that mode. Sending to a session with no issue is human-only.
-
-## Answering a direct message
-
-- On Oh My Pi, an Agents-page **Send** or **Aside** arrives as a user message. Answer in the conversation, with no `dispatch message`.
-- A text that starts with `/` runs as that command. Answer what it expands to as typed. A command that never reaches you (`/session`, `/compact`, `/new`) is answered by your plugin: write nothing. For `/force:<tool> <prompt>`, answer only the prompt.
-- Everything else arrives as a Dispatch frame with no issue. That is a BTW, a broadcast, a direct message on Claude Code, or one Dispatch did not accept. Answer with the bare id and no `--issue`:
-
-```bash
-dispatch message --in-reply-to <the direct message's id> --body 'The requested answer.'
-```
-
-- Naming an issue would file your answer on unrelated work. Keep `--issue` whenever the frame gave one. A `dispatch://KEY/message/<id>` names its issue.
-- More to say: run it again with the same `--in-reply-to`. The same text posts nothing, so a retry is safe. Your host may have answered a BTW already: read the output before you write again.
-- Read the whole conversation back with `dispatch read --message <id>`.

package/skills/dispatch/references/reading.md

@@ -1,32 +0,0 @@
-# Reading Dispatch back, and the reference forms
-
-Read this to catch up after a restart, read a node, trace what cites it, or write a `dispatch://` reference.
-
-## What comes back
-
-- After a restart, catch up with `dispatch read --issue <KEY>` (or `--artifact` with `--issue` or `--project`, or `--ref`). It prints the issue's summary, open asks, references and last 10 events, a document's summary (its issue, reference, versions and approval), or an ask's, comment's or message's thread. Reads do not subscribe. Use `dispatch doc-read` for document text.
-- To audit an issue's history (who asked what, which ask was answered), add `--events N` for the last N events or `--all-events` for every one. Both work on `--ref dispatch://KEY/log` too.
-- An anchored comment or ask prints `Position:`, where its quote's block stands. `unavailable (DOC_SERVICE_UNAVAILABLE)` means try again shortly. `unavailable (DOC_SCHEMA)` means the document needs repair.
-- The API gives the same facts as `anchor_block` (or `anchor_block_error`) on `GET /api/v1/comments/{id}` and `GET /api/v1/asks/{id}`. `GET /api/v1/artifacts/{id}/blocks/{block_id}` gives them for any block.
-- Each read ends with `Referenced by:` (what cites the node) and `Links:` (what it cites), across projects. "What led to this decision" is one read on the ask.
-- A whole list is one block, so every issue named in one list previews the list's first item. Give each issue its own paragraph when each backlink should read right.
-- Cite with `dispatch://` whenever you name a node. A bare id or title is invisible to the graph.
-
-## Reference forms
-
-```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/<document-ref>[@vN]
-dispatch://PROJECT/artifact/<document-ref>/ask/<id>
-dispatch://PROJECT/artifact/<document-ref>/comment/<id>
-```
-
-- A reference renders as a link titled by its target. A body that is only a reference gets an unfurl card.
-- A bare UUID or `KEY#seq` is not a reference. `dispatch read` also takes a dashboard URL, also on the public dashboard when `DISPATCH_PUBLIC_URL` names one. An issue read prints its `Link:`: hand that to a person.
-- An ask or comment id can be a unique 8+ hex prefix. A message id is always the full UUID.
-- An ask or comment on an issue's document is `dispatch://KEY/ask/<id>` or `dispatch://KEY/comment/<id>`, never written through its document.

package/skills/dispatch-brainstorming/SKILL.md

@@ -1,56 +0,0 @@
----
-name: dispatch-brainstorming
-description: "Use when a session with Dispatch starts a design conversation with a person: brainstorming, /brainstorming or \"let's design\". Also use it there for a spec, an implementation plan, or a change that needs a person's choices. It replaces superpowers' brainstorming and writing-plans. A Legion architect's own spec follows skill://legion-architect instead."
----
-
-# Brainstorming in Dispatch
-
-A Legion architect's own issue spec, a child's too, follows `skill://legion-architect`. A Legion phase worker never writes the spec: it sends the decision to its architect (`skill://legion-worker`).
-
-This skill replaces superpowers' `brainstorming` and `writing-plans`, even when the user names one:
-
-- The spec is the issue's primary document, the plan its `plan.md`. No `docs/superpowers/` files.
-- Each design question is a decision block in the spec, never a chat question. A small change gets a short spec.
-- Send every ready question at once. Request approval once, at the end.
-- Ask in stages: clarifying questions, two or three approaches with a recommendation, the design by section. A question that depends on no open answer goes out at once.
-- Copy the spec, plan or spec code into the repository only when the person, the issue, its spec or the repository asks.
-
-Before the first version, read the code and documents the design touches. Before the first version, also read the `skill://dispatch` sections "Writing a spec", "Decision blocks", "Writing for the human" and "Approval of a spec".
-
-## Where the spec lives
-
-1. Search first (`skill://dispatch-first`). If an issue tracks the work, extend its primary document with `dispatch doc-edit`, keeping the human's text.
-2. Else run `dispatch issue --project <KEY> --title '<title>' --spec-file -` in the project a search hit names.
-3. If no hit names a project, ask the human in chat which one (`dispatch projects` lists them). This is a filing question, not a design question.
-4. Use only `dispatch` commands. Never get the project from the environment, a configuration file or the Dispatch HTTP API.
-
-## Each turn
-
-1. **First version: only what the human settled.** Write the problem, its evidence, the human's words and the facts the questions need. Add each ready question as a block at the end of its section. Write no design, no default you chose, and no recommendation outside a block. A point the human did not state goes in a block or stays out, however obvious. A flagged inference waits too.
-2. **Reply to each comment in its thread** (`dispatch comment --reply-to <comment id>`), then rewrite what it changes. When the next move on an open ask is yours, such as an approval request to revise, use `--reply-to-ask <ask id> --turn agent`.
-3. **Each next version keeps answered blocks in place** and rewrites every passage a decision changes. The spec records the current design and requirements, never how you got there. Then add the next sections and their ready questions.
-4. **A comment that answers a question settles it.** Write the answer into the text at once, as "Writing a spec" says. Close the block with `dispatch resolve-ask` if it is still open.
-5. **Request approval** when nothing in the spec is new to the human, as "Approval of a spec" says.
-
-## Coming to terms
-
-Explain plainly what the code does now, naming each tool, event and route exactly, and ask. Neither model is true at the start: the human's reactions give their model and its corrections.
-
-## Handing over a spec or plan
-
-1. Start your chat reply with:
-   1. Each decision the human must make: options, trade-offs and your recommendation, clear without the document. The human answers in the block.
-   2. Each point the human has not yet settled, one line each, with a line reference.
-   3. The link.
-2. The reply carries only what is new. The document stays the full current design.
-3. If no decision is open and nothing is new, do not ask for review in the reply. Say the document records what you agreed. Turn step 5 still applies.
-4. When you ask for review, say "ready for review", never "complete". Put the uncertainty first and show your reasoning.
-
-## The plan
-
-- Write it after the spec's approval. With no spec (a bug fix with no design decision), write it when you can plan.
-- Upload it with `dispatch artifact --issue <KEY> --name plan.md --content-file -`. Each upload is a new version.
-- Follow all `writing-plans` content rules: file structure, task size, small steps, no placeholders, the header, its self-review.
-- Make technical choices inside the approved design in the plan, with no question. A change to a human's decision goes back to the spec as a block, with its evidence.
-- If the human says "plan only", stop after the plan.
-- To execute, read it with `dispatch doc-read --issue <KEY> --artifact plan.md`, then follow `executing-plans` or `subagent-driven-development`.