opencode-skills-collection 4.0.44 → 4.0.46

package/bundled-skills/zcode-delegate/references/multi-task-queues.md

@@ -0,0 +1,87 @@
+# Multi-task queues
+
+A queue is a sequence of bounded tasks dispatched one at a time, each reviewed and landed before the
+next begins. It is the shape that makes delegation worth the overhead: a migration, a mechanical
+refactor across many files, a removal sweep.
+
+**Run them sequentially.** Parallel dispatches against one working tree produce interleaved edits
+that no reviewer can untangle, and `touchedFiles` stops meaning anything.
+
+## The loop
+
+For each task in the queue:
+
+1. Write the brief for **this task only**.
+2. Dispatch.
+3. Wait for `result.json`.
+4. Review: re-run the gates, read the diff, check scope.
+5. Land it — a commit per task, not one commit at the end.
+6. Note anything learned that the next brief needs.
+
+A commit per task is what makes a queue recoverable. When task 6 of 9 goes wrong, you revert one
+commit instead of unpicking a nine-task blob.
+
+## Carrying constraints forward
+
+Each brief is written cold, so constraints do not survive on their own. Keep a short block and paste
+it into every brief in the queue:
+
+```markdown
+# Standing constraints (apply to every task in this queue)
+- Do not add dependencies.
+- Do not reformat files you are not otherwise changing.
+- Public API in src/api/ is frozen; changing it fails review.
+- Gates: node test/relay-smoke.mjs
+```
+
+Add to this block as you learn. If task 3's review caught a drive-by refactor, task 4's brief should
+forbid it explicitly. The block is how a queue gets *more* reliable as it runs rather than less.
+
+## Fresh session per task, usually
+
+Start each task cold — a new dispatch with no `--session`. Independent tasks should not inherit an
+earlier task's context, which can carry over assumptions you rejected in review.
+
+Use `--session` **within** a task, for rework, not **between** tasks. The exception is a genuinely
+continuous piece of work split across dispatches for length; there, continuing the session preserves
+context that a cold brief would have to restate.
+
+## Tracking progress
+
+Keep a visible checklist — the queue, one line each, marked as landed. Update it after the commit,
+not after the dispatch. A task is done when it is committed and the gates passed, not when ZCode
+said it finished.
+
+Record the `sessionId` of each task next to its line. If a landed task later turns out to be wrong,
+that id is the cheapest way back into its context.
+
+## The end-of-run coherence check
+
+Individually correct changes can be collectively wrong. When the queue is done, review the whole
+range as one diff:
+
+```bash
+git diff <commit-before-the-queue>..HEAD
+```
+
+Look for what per-task review structurally cannot catch:
+
+- **Drift** — the same problem solved three different ways across tasks.
+- **Duplication** — a helper invented in task 2 and reinvented in task 7.
+- **Dead ends** — code added for a task that a later task made unnecessary.
+- **Half-migrations** — the old and new patterns now both present, with no task left to finish it.
+
+Then run the gates once more over the final state. A queue where every task passed its own gates can
+still end with a broken tree, because task N's gates ran before task N+1 existed.
+
+## When to stop the queue
+
+Stop and go back to the human when:
+
+- Two consecutive tasks need rework for the same reason — the standing constraints are wrong, not
+  the implementer.
+- A task reveals the plan was based on a wrong assumption about the codebase.
+- Correct completion needs a scope change. Ask; do not expand the mandate yourself.
+
+Stopping a queue at task 4 with a clear explanation is a better outcome than finishing all nine and
+handing over a diff you cannot defend.

package/bundled-skills/zcode-delegate/references/review-and-land.md

@@ -0,0 +1,81 @@
+# Review and land
+
+ZCode's `result.json` contains its own summary and its own claims about gates. Treat all of it as a
+hypothesis. You are the reviewer; the commit is yours.
+
+## The checklist
+
+1. **Re-run the project's gates yourself.** Every time. "Gates passed" in `finalMessage` is a claim,
+   not evidence. Run the actual commands from the brief and read their output.
+2. **Read the diff against the brief.** Did ZCode do what was asked — nothing more, nothing less?
+   `touchedFiles` tells you where to look; `git diff` tells you what happened.
+3. **Check the "Out of scope" list.** Was anything on it touched?
+4. **Read the DECISIONS section** of the report. Anything ZCode chose that the brief did not specify
+   is something you now own. Surface it; do not absorb it silently.
+5. **On a `--read-only` run**, confirm `touchedFiles` is `[]` and `readOnlyViolation` is `false`.
+   Plan mode refuses edits, but the relay measures rather than assumes — see below.
+6. **Run your guard skills** on the diff if you have them installed. This skill produces the work;
+   those skills judge it.
+7. For schema or migration changes, round-trip them. For removals, grep for dangling references.
+
+## What `readOnlyViolation` means
+
+`plan` mode refused to write in testing, but whether that refusal is enforced by ZCode's tool layer
+or is model compliance is not established. So the relay fingerprints the repository before the run
+and compares afterwards:
+
+- `false` — no Git-visible change was detected. This is the expected result.
+- `true` — something changed during a read-only run. **Stop and inspect the tree.** The relay
+  detects and reports; it does not attribute or revert.
+- `null` — git could not report, so the tripwire has no opinion. Inspect the tree directly.
+
+`readOnlyViolation` is `null` on `yolo` runs, where writes are the point.
+
+## The commit boundary
+
+**The relay never commits.** Not on success, not on a clean gate run, not ever. Committing belongs
+to whoever reviewed the diff, and that is you.
+
+This is not a limitation to work around. If you find yourself wanting the implementer to commit, the
+review step is being skipped.
+
+## Rework: the exact-session cycle
+
+When the diff needs changes, continue the same session rather than starting cold:
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief delta-brief.txt --cd /path/to/repo --session sess_3d8fa06c-…
+```
+
+- Take `sessionId` from the prior `result.json`.
+- **Send only the delta** — what was wrong and what to do instead. ZCode still has the earlier turn;
+  re-sending the original brief wastes context and invites it to redo accepted work.
+- `--resume-last` continues the latest session for `--cd`. It is scoped to that directory rather
+  than being a global "last", which makes it safer than it sounds — but `--session` is still the
+  precise choice when you have the id.
+- Review the result again. A rework cycle gets the same scrutiny as the first pass.
+
+## Authorization model
+
+Delegation is something the human opts into. Once they have — "run this queue", "proceed" —
+committing verified, gate-passing work is the agreed contract. Two limits on that mandate:
+
+**Surface, don't absorb.** Report ZCode's design decisions, its defensible-but-unasked turns, and
+non-blocking nitpicks. Your reviewer's summary should let the human disagree with a choice they
+would not have made. Silently keeping such a change makes it yours.
+
+**Stop for scope changes.** If correct completion requires going beyond the brief — a schema change
+the task implies, a dependency the fix needs, a refactor without which the change is unsafe — ask.
+Do not expand the mandate yourself, and do not let the implementer expand it for you.
+
+## What to tell the human
+
+After landing, say what actually happened:
+
+- what changed, and why
+- which gates you ran, and their real output
+- what ZCode decided that the brief did not specify
+- anything you left undone, and why
+
+If a gate failed, say so with the output. If a step was skipped, say that. A clean report of a messy
+run is more useful than a confident summary that does not survive contact with the diff.

package/bundled-skills/zcode-delegate/references/writing-the-brief.md

@@ -0,0 +1,120 @@
+# Writing the brief
+
+ZCode starts every dispatch cold. It has no orchestrator chat history, no memory of the last task,
+and no idea what you already ruled out. The brief is the entire context, and a vague brief is the
+single most common cause of a diff you have to throw away.
+
+## How the brief reaches ZCode
+
+The relay writes your brief to `brief.md` in its run directory and passes it with ZCode's
+`--attach` flag, alongside a fixed one-line prompt telling ZCode to follow the attached brief.
+
+That matters in two ways:
+
+- **The command line stops bounding the brief.** ZCode has no stdin delivery, so a brief passed as
+  prompt text would be limited by the command line (about 32 767 characters on Windows). Attaching
+  sidesteps that entirely — write the brief the task deserves. The configured model's context window
+  still applies, so this buys room, not an unlimited budget.
+- **The brief is a document, not a chat message.** Structure it with headings. ZCode reads it as a
+  file.
+
+## Structure
+
+```markdown
+# Goal
+One or two sentences. What must be true when this is done.
+
+# Current state
+Where the relevant code lives, what it does today, and anything already tried and rejected.
+Name files with paths. Do not make ZCode hunt.
+
+# Change
+Exactly what to do. Be specific about behaviour, not implementation, unless the implementation
+is the point.
+
+# Out of scope
+What to leave alone. This is the field that prevents scope creep — spend real effort on it.
+
+# Gates
+The project's ACTUAL commands, copied from its CLAUDE.md / AGENTS.md / Makefile / package.json.
+Do not invent these.
+
+    node test/relay-smoke.mjs
+    npx skills add . --list
+
+# Constraints
+Anything non-negotiable: dependency limits, style rules, files that must not be touched,
+platforms that must keep working.
+
+# Report contract
+End your final message with:
+- WHAT CHANGED: one line per file, with the reason
+- GATES: the command you ran and its actual result
+- DECISIONS: anything you chose that the brief did not specify
+- UNFINISHED: anything you could not complete, and why
+
+# You will not commit
+Do not run `git commit`, `git push`, or any command that writes to `.git`.
+The orchestrator reviews the diff and commits.
+```
+
+## The rules that actually matter
+
+**Embed the real gate commands.** The most common failure is a brief that says "run the tests" to an
+implementer with no idea what the test command is. Discover them from the repo first, then paste
+them. If you did not verify the command yourself, do not put it in the brief.
+
+**Spend effort on "Out of scope".** An implementer that is uncertain tends to do more, not less. A
+brief that says only what to change invites reformatting, drive-by refactors, and dependency
+additions. Name the things you do not want touched.
+
+**One task per brief.** If the brief has an "and then also", split it. Queues are for sequences —
+see [multi-task-queues.md](multi-task-queues.md).
+
+**Ask for a report contract.** You are going to re-verify everything anyway, but a structured report
+tells you where to look first, and the DECISIONS section is how you catch defensible-but-unasked
+turns before they reach your commit.
+
+**Say it will not commit.** The relay never commits, and ZCode running under `--mode yolo` has a
+Bash tool. Being explicit costs one line.
+
+## Tool restrictions belong on the command line, not in the brief
+
+If the task genuinely must not touch certain tools, do not ask politely in the brief — pass
+`--disallowed-tools "Write,Edit,Bash"`. That denylist is enforced by ZCode: the named tools are
+absent from the session entirely. Prose in a brief is not.
+
+There is no allowlist counterpart — ZCode has no `--allowed-tools`. You can subtract capability, not
+enumerate it.
+
+## For a read-only run
+
+A `--read-only` dispatch runs in ZCode's `plan` mode, which refuses edits. Briefs for these runs
+should ask for a deliverable **in the final message**, since no files will change:
+
+```markdown
+# Goal
+Give a second opinion on the approach below. Do not change any files.
+
+# Agreed
+...points both sides accept...
+
+# Contested
+1. <point> — Position A: ... Position B: ...
+2. ...
+
+# Report contract
+For each contested point, defend or concede, and say which evidence moved you.
+```
+
+Then verify the result: `touchedFiles` is `[]` and `readOnlyViolation` is `false`. Plan mode's
+refusal is measured by the relay's Git tripwire, not guaranteed by a sandbox, and
+`readOnlyViolation` is tri-state — `true` means Git-visible changes were detected, `false` means
+none were, and `null` means the tripwire could not tell, which calls for inspecting the tree
+yourself rather than assuming either.
+
+## Delta briefs for rework
+
+When you send work back with `--session <sessionId>`, ZCode still has the earlier turn. Send only
+what changed — the correction, not the whole original brief. Repeating the full brief wastes context
+and invites it to redo work you already accepted. See [review-and-land.md](review-and-land.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-collection",
-  "version": "4.0.44",
+  "version": "4.0.46",
   "description": "OpenCode CLI plugin that automatically downloads and keeps skills up to date.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",