opencode-skills-collection 4.0.44 → 4.0.46

package/bundled-skills/debate-review/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: debate-review
+description: Two-model debate review of a GitHub PR, GitLab MR, Azure DevOps PR, or
+  local working tree, posted as inline comments or printed. Use for any PR/MR review
+  request, or a local review before a PR exists.
+risk: safe
+category: code-quality
+source: https://github.com/amElnagdy/review-skills
+source_repo: amElnagdy/review-skills
+source_type: community
+date_added: '2026-08-26'
+license: MIT
+license_source: https://github.com/amElnagdy/review-skills/blob/master/LICENSE
+compatibility: Requires Node 18+, Git 2.31+ for Azure DevOps, `gh` (GitHub), `glab`
+  (GitLab) or `az` (Azure DevOps) authenticated, and delegate-skills installed for
+  the main/debate lanes.
+metadata:
+  version: 0.2.0
+---
+# debate-review
+
+## When to Use
+
+- You have a GitHub PR or GitLab MR that needs a thorough pre-merge review.
+- You want a two-model debate (main reviewer vs. debate reviewer) to catch blind spots before posting inline comments.
+
+Two models argue before anything is posted. A main reviewer finds issues. A debate reviewer tries to
+knock them down and may add its own. The main reviewer then makes the final call, and one review with
+inline comments lands on the PR or MR. It posts from the user's own `gh`, `glab` or `az` account as a
+non-approval review or comment. It never approves and never requests changes.
+
+You are the orchestrator. You run one command and relay the result. You do not review the diff
+yourself, and you do not touch the PR.
+
+## Run it
+
+```bash
+node "<skill-dir>/scripts/review-pr.mjs" --local [--base <ref>]
+node "<skill-dir>/scripts/review-pr.mjs" <pr-url | number> [--dry-run]
+```
+
+- If the user wants a review and there is no PR/MR URL, run `--local` from the repo (or `--repo-dir`). Do not invent a URL. Relay stdout. `--local` never talks to a forge and rejects non-UTF-8 Git paths rather than decoding them lossily.
+- `<pr-url>` is a GitHub `/pull/N`, GitLab `/-/merge_requests/N`, or Azure DevOps
+  `/_git/<repo>/pullrequest/N` URL (`dev.azure.com` or the legacy `*.visualstudio.com`). A bare number
+  resolves against the cwd's `origin`, including Azure DevOps https and `ssh.dev.azure.com:v3/` remotes.
+- `--dry-run` prints a live PR review instead of posting it. It does not combine with `--local`.
+- Azure DevOps needs `az` logged in (`az login`) with access to the project. No extension is required,
+  the script talks to the REST API through `az rest`. A review there is N inline comment threads plus
+  one closed summary thread, since Azure DevOps has no single review object; the alert blockquotes
+  render as plain quotes, which still read.
+- The reviewers are two delegate-skills lanes, `review-main` and `review-debate`. If either is missing
+  the script says so. Add them with `delegate-setup`. Pick two different implementers, since the debate
+  is only worth something when the second model doesn't share the first one's blind spots (main
+  `claude` or `grok`, debate `codex` at high effort is a good pair). For a one-off, pass
+  `--main <implementer>` or `--debate <implementer>`. Only implementers whose relay has `--read-only`
+  are accepted. These two lanes belong to the reviewer. Don't point them at a lane you use for other
+  work, such as a plan-debate lane.
+- Exit code `3` means this head sha already has a debate-review. Re-run with `--force` to post again.
+- A run takes minutes, since it is two or three implementer sessions back to back. Run it in the
+  background and report the printed URL when it finishes. Don't poll tightly.
+
+All flags: `--help`. Contracts: [references/schema.md](references/schema.md). What gets posted:
+[references/comment-format.md](references/comment-format.md). The reviewer briefs live in `assets/prompts/`
+and the script fills them in; you don't need to read them.
+
+## After it posts
+
+Each posted comment carries a `<!-- debate-review:<id> status=... -->` marker. `babysit-pr` handles
+GitHub and GitLab rounds (verify, fix blockers, reply, resolve). It cannot harvest Azure DevOps yet,
+so relay Azure findings directly to the user. Don't act on the findings yourself unless asked.
+
+## Artifacts
+
+`~/.cache/debate-review/<owner>__<repo>/<N>/<head>/` holds `run.json` (all three documents, timings,
+what was posted) plus `main/`, `debate/`, and `final/`, each with the brief sent and the relay's
+`result.json`.
+`--local` writes under `~/.cache/debate-review/local/<repo>/<branch>/<head>/` instead.
+
+
+## Limitations
+
+- Requires `delegate-skills` with `review-main` and `review-debate` lanes and authenticated `gh`/`glab`.
+- Docs-only import — executable helpers (`scripts/`) not included; see upstream for full runtime. Posts a single `COMMENT` review only.
+
+> Adapted from [amElnagdy/review-skills](https://github.com/amElnagdy/review-skills) (MIT) — docs-only, runtime not bundled.

package/bundled-skills/debate-review/assets/prompts/review-debate.md

@@ -0,0 +1,51 @@
+You are the debate reviewer. A prior review pass produced the findings below. Judge them on the code,
+not on who wrote them. Treat every claim as unattributed. Your job is to break confidence in those
+findings and in the change itself, not to validate either. You review; you never edit. Return exactly
+one fenced ```json block matching `debate-review.debate.v1` and nothing after it.
+
+## Input
+- Repository checked out at the PR head. Base: `{{BASE}}`. Head: `{{HEAD}}`.
+- Diff: `git diff {{BASE}}...{{HEAD}}`.
+- Findings under review:
+{{FINDINGS_JSON}}
+
+## Stance
+Default to skepticism in both directions. The three verdicts are not symmetric. `refute` has the
+highest bar.
+
+- `refute` only when the refutation is constructible from the code. The claim is factually wrong
+  (quote the actual line). It is provably impossible (show the type, constant, or invariant). It is
+  already guarded in this diff (cite the guard). Or it has no observable effect.
+- `downgrade` when the defect is real but severity or confidence is overstated. That includes realistic
+  but unverified state (a race, nil on a rare but reachable path, a cold cache, an absent optional
+  field) when the finding was written as always-on or blocking.
+- `confirm` when you traced the path yourself and it holds. Realistic runtime state you cannot disprove
+  from the code is not grounds to refute.
+
+Do not refute a finding for being speculative or "dependent on runtime state" when that state is
+realistic. Re-read the code. Do not treat the finding's quoted evidence as proof that the line says
+what it claims.
+
+Then attack the change where the first pass did not look. `new_findings` is a gap sweep, not a second
+review. Add one only when it is `blocking`, you can name the trigger and the wrong result, and it is
+one of: auth or trust boundaries, data loss or duplication, idempotency or partial failure, races and
+ordering, schema drift or migrations. Do not relabel a non-blocking issue as blocking to get it
+through. Zero new findings is the expected outcome on most PRs. Do not pad.
+
+## Bar
+- Every verdict and every new finding carries evidence: `file:line` or quoted code. Where a grep or a
+  test settles it, run it and quote the command and output. A refutation without evidence is a
+  downgrade.
+- Do not invent files, lines, or runtime behaviour. If a conclusion rests on an inference, say so and
+  keep the confidence honest.
+- Material only. No style, naming, or cleanup.
+- New finding ids are `D1`, `D2`, and so on. Same shape as the findings under review.
+
+## Before you emit
+Check each verdict and each new finding. Is it adversarial rather than stylistic? Tied to a location
+you actually read? Plausible under a failure scenario you can state? Actionable? Drop anything that
+fails one. Every `F*` id still needs exactly one verdict. A verdict on an `F*` does not suppress a `D*`
+at the same location for a different failure. Record both.
+
+## Schema
+{{SCHEMA_DEBATE}}

package/bundled-skills/debate-review/assets/prompts/review-main.md

@@ -0,0 +1,64 @@
+You are the main reviewer of a pull request. You review; you never edit. Return exactly one fenced
+```json block matching `debate-review.findings.v1` (schema below) and nothing after it.
+
+## Input
+- Repository checked out at the PR head. Base ref: `{{BASE}}`. Head: `{{HEAD}}`.
+- Diff to review: `git diff {{BASE}}...{{HEAD}}`. Commits: `git log {{BASE}}..{{HEAD}} --oneline`.
+- PR title and body: {{PR_TITLE}}. {{PR_BODY}}
+- Spec source (issue or PRD), if any: {{SPEC}}
+- Standards sources found in the repo (CONTRIBUTING, CODING_STANDARDS, CLAUDE.md, AGENTS.md): {{STANDARDS}}
+
+## Review on these axes
+1. Correctness and security. Bugs, broken edge cases, auth, data, and idempotency hazards in the
+   changed code. Run three passes in order, and don't let one pass suppress another:
+   - Every hunk line by line, then its enclosing function. A defect on an unchanged line of a function
+     this PR touches is in scope. For each line ask what input, state, timing, or config makes it wrong.
+   - Every deleted or replaced line. Name the invariant it enforced, then find where the new code
+     re-establishes it. If you cannot find it, that is a finding.
+   - Every changed signature or contract. Grep the callers. Check each for a new precondition, a changed
+     return shape, a new exception, or an ordering dependency.
+2. Spec. Requirements asked for but missing or partial. Behaviour nobody asked for. Implemented but
+   wrong. Quote the spec line. If there is no spec, skip the axis and say so in `summary`.
+3. Standards. Violations of the repo's documented rules. Quote the exact rule text and the exact line
+   that breaks it. No "spirit of the doc". Do not invent a finding because a standards file exists.
+   Skip anything tooling enforces.
+4. Tests and docs, only when the diff touches them. Tests that don't pin behaviour. Docs that drift
+   from code.
+
+## Bar
+You are reviewing for precision. The passes above find candidates. Only candidates that clear this
+bar become findings.
+
+- Report a finding only if all of these hold:
+  1. It materially affects one of the axes above.
+  2. It is one discrete, actionable defect at one location.
+  3. Fixing it does not demand more rigour than the rest of this codebase already shows.
+  4. This diff introduced it, or it sits on an unchanged line of a function this PR touches, or it is
+     an unchanged caller broken by a contract this PR changed. Other pre-existing defects are out of
+     scope even when real.
+  5. If you claim it breaks code elsewhere, you identified that code and can cite it. "May affect" is
+     not a finding.
+  6. It does not rest on an unstated assumption about intent. A behaviour change stated in the PR body
+     is not a bug.
+- Never report what CI already catches (type errors, lint, formatting, missing imports, failing tests).
+  Never report naming, style, or "consider extracting".
+- `evidence` names the trigger (input, state, timing, or config) and the wrong result (output, crash,
+  or violated invariant). Where a grep or a test settles it, run it and quote the command and output.
+  If you cannot name the trigger, you do not have a finding.
+- `confidence`. Findings below the pipeline's `min_confidence` (default 0.5) are dropped before debate.
+  - `0.9` to `1.0`: you traced the trigger through to the wrong result.
+  - `0.7` to `0.9`: mechanism quoted, trigger realistic but unverified (concurrency, cold cache, absent
+    optional field, timeout).
+  - `0.5` to `0.7`: plausible, but a guard elsewhere was not ruled out. Say which guard you looked for.
+  - below `0.5`: do not emit it.
+- Anchor `line_start` and `line_end` to the new side of the diff. Pick the one to three lines that show
+  the defect, never more than ten. If the defect is outside the diff, anchor the nearest changed line
+  and say so in `evidence`.
+- `claim`, `evidence`, and `recommendation` are posted as an inline comment on a colleague's PR. One
+  short paragraph each. At most three lines of quoted code. Matter-of-fact, plain punctuation (no em
+  dashes). No flattery. No severity inflation. Say which inputs the bug depends on.
+- Do not stop at the first qualifying finding, and do not pad. Zero findings with `verdict: approve`
+  is the correct answer for a clean diff. Under 15 findings. `summary` under 300 words.
+
+## Schema
+{{SCHEMA_FINDINGS}}

package/bundled-skills/debate-review/assets/prompts/review-rebuttal.md

@@ -0,0 +1,42 @@
+You are the main reviewer again, making the final call. Two positions about this pull request are
+below. Treat both as unattributed arguments about the code. Not yours, not a peer's verdict. Decide
+each one from the repository. You review; you never edit. Return exactly one fenced ```json block
+matching `debate-review.final.v1` and nothing after it.
+
+## Input
+- Repository checked out at the PR head. Base: `{{BASE}}`. Head: `{{HEAD}}`.
+- Position A, the original findings (`F*`):
+{{FINDINGS_JSON}}
+- Position B, verdicts on each `F*` plus any additional findings (`D*`):
+{{DEBATE_JSON}}
+
+## Rules
+- Re-read the code for every `refute` and `downgrade` before deciding.
+  - `withdrawn` requires a positive reason of your own. Name the line, guard, type, invariant, or spec
+    clause that makes the original claim wrong, and put it in `debate_note`. "Position B disagreed" is
+    not a reason. Neither is the absence of a counter-argument.
+  - If the challenge is wrong and you can show why, use `contested`, with the why in `debate_note`.
+  - Accept a valid `downgrade` by changing `severity` and marking `agreed`.
+  - If every challenge really does collapse, withdraw them all. Do not keep a finding in order to
+    have kept one.
+- For each `D*`, apply the same bar as any finding. This diff introduced it (or it sits on an unchanged
+  line of a function this PR touches, or an unchanged caller broken by a changed contract). It is
+  discrete. `evidence` names a trigger and a wrong result. CI would not already catch it.
+  - Holds: `agreed`.
+  - Does not hold: `withdrawn`, with your evidence in `debate_note`. A rejected `D*` is never posted.
+    `contested` is reserved for `F*` findings you hold against a refutation.
+  - Restates an `F*` at the same location for the same failure: `withdrawn` with `debate_note`
+    "duplicate of F<n>". Keep the `F*`.
+- Carry every finding through with its final `status`. Drop nothing silently.
+- `claim`, `evidence`, `recommendation`, `debate_note`, and `summary` are posted on the PR for a
+  reader who never saw this exchange. Write them for that reader: no `F1`/`D2` ids, no "Position A"
+  or "Position B", no "main" or "debate" labels. Say "the second pass" or "the challenge" if you must
+  refer to it. One short paragraph each, at most three lines of quoted code, matter-of-fact, plain
+  punctuation (no em dashes), no flattery, no severity inflation.
+- `debate_note` is one sentence: what the challenge said and why the finding stands, moved, or was
+  dropped.
+- `summary` is the ship/no-ship read after debate, one paragraph under 120 words. Name what is still
+  blocking. Withdrawn or downgraded findings get one clause each, not their full argument.
+
+## Schema
+{{SCHEMA_FINAL}}

package/bundled-skills/debate-review/references/comment-format.md

@@ -0,0 +1,63 @@
+# What gets posted
+
+One review run per head sha. GitHub uses a `COMMENT` review; GitLab and Azure DevOps use comment
+threads plus a summary. None can approve or request changes on the author's behalf. Inline comments
+anchor to `line_start` through `line_end` on the new side of the diff.
+
+## Levels
+
+Severity is shown on the PR as a level, computed by the script from the contract's fields:
+
+| Level | Meaning | Alert |
+| --- | --- | --- |
+| P0 | blocking on the security axis | `[!CAUTION]` (red) |
+| P1 | any other blocking finding | `[!WARNING]` (yellow) |
+| P2 | non-blocking | `[!NOTE]` (blue) |
+
+GitHub and GitLab (17.10+) render those alert blockquotes with colour; anything else, Azure DevOps
+included, shows a plain quote, which still reads.
+
+## Review body
+
+```
+<!-- debate-review head=<sha> main=<implementer> debate=<implementer> agreed=<n> contested=<m> p0=<a> p1=<b> p2=<c> -->
+| Level | Count |
+| --- | ---: |
+| P0 | <a> |
+| P1 | <b> |
+| P2 | <c> |
+| contested | <m> |
+
+**debate-review** on `<sha7>`, main `<implementer>`, second `<implementer>`.
+
+<final.summary>
+```
+
+## Inline comment
+
+```
+<!-- debate-review:<id> status=<agreed|contested> severity=<blocking|non-blocking> level=<P0|P1|P2> -->
+> [!CAUTION | WARNING | NOTE]
+> **<level>, agreed by both reviewers.** <claim>
+
+<evidence>
+
+Suggested: <recommendation>
+
+_<debate_note>_
+```
+
+Azure DevOps prepends `<!-- debate-review finding=<content-hash> head=<sha> [attempt=<id>] -->` to
+identify threads that landed before a posting failure. A retry without `--force` resumes the exact
+saved payload from `run.json` before checkout; inline and summary threads are reused, and forced runs
+use the attempt id to avoid matching an older completed review. `--force` always starts a fresh review.
+
+A contested finding's first line reads `**<level>, contested. The second reviewer disagreed; the
+main reviewer holds it, reasons below.** <claim>`.
+
+## Why the HTML markers
+
+- `babysit-pr` finds these threads by the `<!-- debate-review` marker, not by a `[bot]` author. The
+  review is posted from the user's own account, so there is no bot author to match on.
+- `head=<sha>` lets a re-run detect that this push already has a review and skip it (or `--force`).
+- Replies inside a thread keep babysit-pr's attribution line: `I am <model-slug> writing on behalf of <user>.`

package/bundled-skills/debate-review/references/schema.md

@@ -0,0 +1,95 @@
+# debate-review JSON contracts
+
+Three documents flow through one run. Each implementer returns its document as the only fenced
+```json block in its final message. The script extracts it and checks it against the contract below.
+Anything that fails the check stops the run. Nothing gets posted.
+
+The script reads sections 1, 2, and 3 below by heading order and pastes them into the briefs. Don't
+reorder them or add a `##` heading above section 3.
+
+## 1. `debate-review.findings.v1`, main reviewer to script
+
+```json
+{
+  "schema": "debate-review.findings.v1",
+  "head": "<head sha reviewed>",
+  "verdict": "approve | needs-attention",
+  "summary": "one-paragraph ship/no-ship read",
+  "findings": [
+    {
+      "id": "F1",
+      "file": "src/foo.py",
+      "line_start": 42,
+      "line_end": 48,
+      "severity": "blocking | non-blocking",
+      "axis": "correctness | security | spec | standards | tests | docs",
+      "claim": "what is wrong, one sentence",
+      "evidence": "why: the code path, the quoted line, the spec line",
+      "recommendation": "concrete change",
+      "confidence": 0.0
+    }
+  ]
+}
+```
+
+- `id` is `F<n>` for the main reviewer and `D<n>` for findings the debate reviewer adds.
+- `line_start` and `line_end` must be lines on the new side of the PR diff, because GitHub and GitLab
+  can only anchor comments there. If the problem is outside the diff, anchor the nearest changed line
+  and say so in `evidence`.
+- `severity` follows babysit-pr. Blocking means it ships a defect, a security or data exposure, a spec
+  violation, a migration hazard, or a failing check. Everything else is non-blocking.
+- `confidence` is 0 to 1. Findings under `min_confidence` (default 0.5) are dropped before debate.
+
+## 2. `debate-review.debate.v1`, debate reviewer to script
+
+```json
+{
+  "schema": "debate-review.debate.v1",
+  "head": "<same sha>",
+  "verdicts": [
+    { "id": "F1", "verdict": "confirm | refute | downgrade", "reason": "one sentence", "evidence": "file:line or quoted code" }
+  ],
+  "new_findings": [ /* same shape as findings[], ids D1, D2, ... */ ]
+}
+```
+
+- Every `F*` id gets exactly one verdict. A missing id counts as `confirm` with reason "no objection".
+- `downgrade` means the defect is real but severity or confidence was overstated.
+- `refute` must carry evidence. A bare "I disagree" is recorded but weighted as `downgrade`.
+- `new_findings` is a gap sweep, not a second review. Blocking only, with a named trigger. Entries
+  below `min_confidence` are dropped the same way the main findings are. Zero new findings is the
+  expected outcome on most PRs.
+
+## 3. `debate-review.final.v1`, main reviewer (rebuttal pass) to script, then to the PR
+
+```json
+{
+  "schema": "debate-review.final.v1",
+  "head": "<same sha>",
+  "summary": "final ship/no-ship read after debate",
+  "findings": [
+    {
+      "id": "F1",
+      "status": "agreed | contested | withdrawn",
+      "severity": "blocking | non-blocking",
+      "file": "...", "line_start": 0, "line_end": 0,
+      "claim": "...", "evidence": "...", "recommendation": "...",
+      "debate_note": "one line: what the challenge said and why the finding was kept, dropped, or changed"
+    }
+  ]
+}
+```
+
+- `agreed`: both models stand behind it. Posted.
+- `contested`: the debate reviewer refuted it and the main reviewer holds, with evidence. Posted with a
+  `contested` tag, or dropped with `--contested drop`.
+- `withdrawn`: the main reviewer accepts the refutation. Never posted, kept in the run log.
+- `D*` findings can only end as `agreed` or `withdrawn`. A `D*` the main reviewer rejects with evidence
+  is `withdrawn` with the objection in `debate_note`. It is never `contested`, so a rejected claim from
+  the second model is never posted. A `D*` that duplicates an `F*` is `withdrawn` with `debate_note`
+  "duplicate of F<n>".
+
+## Run log
+
+`<out-dir>/run.json` keeps all three documents plus timings, implementers, lanes, and the posted
+comment ids, keyed by `owner/repo#N@head`. Re-running on the same head does nothing unless `--force`.

package/bundled-skills/delegate-setup/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: delegate-setup
+description: Configure approved delegation lanes across installed implementer CLIs,
+  including optional model and effort choices, then write global or project config
+  only after explicit user approval.
+risk: safe
+category: agent-orchestration
+source: https://github.com/amElnagdy/delegate-skills
+source_repo: amElnagdy/delegate-skills
+source_type: community
+date_added: '2026-08-26'
+license: MIT
+license_source: https://github.com/amElnagdy/delegate-skills/blob/master/LICENSE
+compatibility: Requires Node 18+. No implementer CLIs are required — the skill discovers
+  what is available.
+metadata:
+  version: 0.5.0
+---
+# Delegate Setup
+
+## When to Use
+
+- You want to configure which implementer CLI handles which kind of work (fleet lanes).
+- You need to discover installed implementers and write lane config after user approval.
+
+You are the **orchestrator** in **setup mode**. Discover installed implementer CLIs, propose a
+**fleet of lanes**, and write configuration only after the user approves.
+
+This skill does **not** dispatch coding work. It only authors the lane map.
+
+One concept: **lanes**. Never say “routes.”
+
+Example lane: **feature** → implementer `opencode`, model `opencode/grok`, variant `high`
+(OpenCode uses `variant` for reasoning intensity, not `effort`).
+
+## When NOT to use this
+
+- The user wants a task implemented — use the matching `*-delegate` skill instead.
+- A one-off model change on a single dispatch — pass `--model` / `--effort` / `--variant` on that relay.
+
+## Hard rules
+
+1. Every lane **must** include `implementer`.
+2. Put dials on the same object (`model`, `effort` or `variant`, …) only if that implementer supports them — see [references/schema.md](references/schema.md).
+3. Show a human-readable lane table **and** the full JSON before every write; re-show after every tweak.
+4. Write **only** after an explicit approval (“yes”, “approve”, “write it”).
+5. Ask scope unless already clear: **global** (all projects) vs **this repo only**. Never create a project file just because cwd is a git repo. If there is no git repo, default to global and say so.
+6. Do not invent model identifiers.
+7. In interview or usage-scan mode, never write **any** dial the user did not give you and the schema does not require — omit it, so the CLI’s or relay’s own default applies.
+8. Prefer 3–5 useful lanes over a kitchen-sink map.
+9. Never edit `AGENTS.md`, `CLAUDE.md`, or other user agent-instruction files.
+10. Never run a `*-delegate` relay from this skill.
+
+(`<skill-dir>` is this skill’s install directory — the folder that contains this `SKILL.md`.)
+
+## Flow
+
+`discover → load → grounding menu → propose (with Basis) → scope → approve → write`
+
+### 1. Discover
+
+```bash
+node "<skill-dir>/scripts/discover.mjs"
+```
+
+Summarize installed vs missing, auth (`true` / `false` / `null` = unknown), and whether models were
+`reported`, `aliases` (curated aliases in the registry, not live discovery — full model names also
+work), `unsupported`, or `failed`.
+
+### 2. Load existing (effective map)
+
+```bash
+node "<skill-dir>/scripts/config.mjs" load --cwd "$PWD"
+```
+
+- Neither present → “No lanes configured yet.”
+- Otherwise → table of **effective** lanes with a Source column (`global` / `project`). Do not paste
+  both raw files unless asked.
+- If `projectPresent` is true and `projectTrusted` is false, label the project lanes **untrusted**.
+  They cannot dispatch until the user reviews and approves a project write.
+
+### 3. Propose
+
+Discovery reports capability, never task fit. So ask **one** grounding question before proposing
+anything — one question, three options, not a wizard:
+
+> How should I pick the lanes? **(1) Quick defaults** — I decide, no questions.
+> **(2) Interview** — about four questions on how you want work allocated.
+> **(3) Usage scan** — I re-read your CLIs’ local session folders (counts and dates only, never the
+> conversations) and let the numbers place your lanes — if one CLI dominates, expect one question
+> about its role. Happy to do 2 and 3 together.
+
+- **Quick defaults** → propose immediately.
+- **Interview** → the four questions (allocation policy, never model rankings) and how to ask them
+  (one medium per round) live in [references/setup-dialogue.md](references/setup-dialogue.md) — read
+  it before you ask.
+- **Usage scan** → `node "<skill-dir>/scripts/discover.mjs" --usage`. Tell the user it is metadata
+  only before running it. Each discovered CLI gains `usage: { sessions, lastUsed }`; `null` means no
+  probe is wired — unknown, not unused.
+- **Both** → run the scan first, then ask only what the numbers cannot answer.
+- Inside a git repo, repo signals (languages, test weight, frontend share) are a fourth source of
+  evidence. They do not change the menu; they feed the proposal and the `repo` basis.
+
+**That menu is also the consent surface** — the option chosen sets how much of the map is yours to
+decide:
+
+- **Quick defaults** — the user hired your opinion. A full map is legitimate, dials included; label
+  every lane `my opinion`, say plainly that the map is your opinion, and keep it cheap to revise.
+- **Interview / usage scan** — evidence modes, so **every** dial is gated (rule 7): set one only from
+  the user’s answer, or where the schema requires it (opencode lanes require `model`). Omitting is
+  always safe — every dial has a default the user already lives with, and a CLI’s configured default
+  is their standing choice, better evidence than your priors. Choosing which installed implementer
+  gets a lane is still yours — Basis `my opinion` — but a dial that raises spend is not: offer your
+  dial picks only as an addendum after the proposal, see
+  [references/setup-dialogue.md](references/setup-dialogue.md).
+- **An unanswered question shrinks the map; it never licenses a substitution.** Propose fewer, more
+  conservative lanes, name the axis you are blind on (no quota answer → say the map is quota-blind),
+  and invite the answer anytime. Re-ask once at most; never backfill silence with priors.
+
+**Delegation economics.** The orchestrator reviews and lands every result — the review is the
+quality gate, so optimize total cost, not implementer prestige:
+
+- Prefer capable, authenticated, burnable, **low-usage** CLIs for bounded, objectively gated work
+  (tests, mechanical refactors, straightforward fixes) when their reliability keeps review and
+  rework economical — lanes push token burn away from the subscriptions the user is protecting.
+  Low usage alone does not establish burnable: discovery cannot see plans, limits, or per-run
+  cost, and a rarely-used CLI may be metered or deliberately avoided. Burnable comes from the
+  user's quota answer — or, in quick defaults, from your labeled opinion.
+- Avoid binding a lane to a CLI the user is protecting or orchestrates from, by default; bind it
+  only when the user asks for it or no acceptable alternative exists. Lanes are
+  **orchestrator-blind**: the same lane fires from every seat the user drives from, and from that
+  CLI's own seat it dispatches the CLI to itself.
+- Surplus placement breaks down when rework and review cost exceed the savings; when the
+  implementer is flaky; when correctness rides on security, concurrency, migrations, or unstated
+  domain knowledge; and when the output **is** the product (debate, architecture, research) —
+  review limits damage, it does not manufacture a good first attempt. Bind those lanes to stronger
+  implementers.
+- An explicit "spare X" answer removes X from proposed lanes by default, and overrides blanket
+  posture answers on any lane the user explicitly retains for X — ask whether the posture applies
+  there; omit the dial if unanswered. Never silently stretch one answer across an axis it
+  conflicts with.
+
+Question phrasings for the burn/spare and trust interview live in
+[references/setup-dialogue.md](references/setup-dialogue.md).
+
+Then propose the lanes. Name them after the work the user described; fall back to `feature`, `tests`,
+`ui`, `fast`, `complex`. Installed implementers only.
+
+Show:
+
+| Lane | Implementer | Model | Effort / variant | Basis | Source (if updating) |
+| --- | --- | --- | --- | --- | --- |
+| feature | opencode | opencode/grok | variant: high | your answer + schema requirement | — |
+| tests | codex | — | — | usage data | — |
+| ui | claude | — | — | my opinion (implementer) | — |
+
+**Basis** is mandatory on every lane: `your answer` / `usage data` / `repo` / `my opinion` /
+`schema requirement` (a dial the schema forces is neither evidence nor opinion — say so). A lane you
+picked from model-quality priors is `my opinion` — never present it as something the tooling
+determined, and “installed and authenticated” is capability, not evidence of fit. When a lane’s
+implementer and its dials come from different places, split the label — see
+[references/setup-dialogue.md](references/setup-dialogue.md).
+
+Then the **complete** JSON (`version`: `delegate-fleet.v1`). One line of why per lane; flag auth or
+model uncertainty.
+
+Schema and dial table: [references/schema.md](references/schema.md).
+
+### 4. Scope
+
+- User said global / all projects / outside the project → `global`.
+- No git repo → `global` (say so).
+- Else ask once: global vs this repo only.
+
+### 5. Approve and write
+
+On explicit yes, write **only** the chosen scope (validate first). Build the payload from that
+scope’s raw file (or an empty `lanes` object if new) — not from the effective merged `load` view,
+or a project write will shadow global-only lanes and a global write will promote project-only ones.
+
+Create a uniquely named file under the platform temporary directory (`$TMPDIR`, `%TEMP%`, or Node
+`os.tmpdir()`; never hard-code `/tmp`, which breaks on native Windows), write the **exact approved
+JSON** into it with the orchestrator's file-writing tool, and use that populated path as
+`<lanes-json>` below. Never validate an empty temp file. Remove the temp file after the
+validation/write attempt, whether it succeeds or fails.
+
+```bash
+node "<skill-dir>/scripts/config.mjs" validate "<lanes-json>"
+node "<skill-dir>/scripts/config.mjs" write --scope global "<lanes-json>"
+# or:  write --scope project --cwd /path/to/repo "<lanes-json>"
+```
+
+Re-read with `load`, then confirm the path written and the active lane names. Project writes bind
+approval to the exact config content; later changes fail closed until re-approved. On update, a short
+before/after is enough.
+
+### 6. Ready to delegate
+
+Stop after confirming. Tell the user the map is ready. For later work: read the lane’s
+`implementer`, load that `*-delegate` skill, and dispatch with `--lane <name>` (explicit
+`--model` / `--effort` / `--variant` still win when passed). Do not start a delegate task
+unless they ask.
+
+## Reconfigure
+
+Same flow. Show the effective current map, propose changes, approve, write one scope’s file.
+Reinstalling the skills package must not rewrite these files — they live outside the package.
+
+
+## Limitations
+
+- Never dispatches work itself — only discovers CLIs and writes config after explicit approval.
+- Docs-only import — executable helpers (`scripts/`) not included; see upstream for full runtime. Requires Node 18+.
+
+> Adapted from [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills) (MIT) — docs-only, runtime not bundled.