opencode-skills-collection 4.0.45 → 4.0.46

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

@@ -0,0 +1,126 @@
+# Review and land
+
+Codex did the typing; you own the judgment. This is where delegation earns its keep or quietly ships a
+mistake. The discipline is simple to state and easy to skip under time pressure: **verify against
+reality, never against the self-report — and read the diff as generated code, which fails in ways a
+green gate can't see.**
+
+## Check the tests before trusting the gates
+
+If the diff touches existing tests, review those edits *first* — before the gate re-run means anything.
+A weakened assertion, an added skip, or a deleted test makes the gate measure less than it did before
+the run; green is only meaningful if the yardstick wasn't shortened.
+
+- **Unbriefed edits to existing tests are a contract change, not part of the fix.** The brief asked for
+  an implementation; nothing in it authorized moving the goalposts. Flag them, don't absorb them.
+- **Skipped, disabled, or commented-out tests added in this diff:** treat the underlying test as failing
+  until proven otherwise, whatever the annotation's comment claims.
+- **Loosened assertions** (exact match relaxed to contains/truthy, error-type checks broadened, tolerance
+  widened): same treatment.
+
+## Re-run the gates yourself
+
+`result.json` carries Codex's own claim that the gates passed. Treat that as a claim, not evidence —
+re-run the project's actual test/lint/build commands in the working tree and read the output. And keep
+the result in proportion: **passing is necessary, not sufficient.** An implementer can *game* a gate,
+not just misreport it — that is what the test check above and the sweep below exist to catch.
+
+For changes with their own verification shape, go further:
+
+- **Migrations / schema:** round-trip them (apply, reverse, re-apply on a scratch target) and check for
+  drift, rather than trusting that "the migration is reversible."
+- **Removals / renames:** grep the codebase for dangling references to whatever was removed.
+- **Anything stateful:** exercise the actual behavior, don't just confirm it compiles.
+
+## Read the diff against the brief
+
+Open the diff (`touchedFiles` in the result is your starting list) and hold it against what you asked
+for:
+
+- **Scope creep** — did Codex change things the brief said to leave untouched? Unasked refactors,
+  renames, "while I was here" edits. These are the most common quality problem in delegated work.
+- **Scope shortfall** — did it do the whole task, including the edge cases and cleanup, or stop at the
+  first plausible version?
+- **Quiet judgment calls** — sometimes Codex makes a defensible decision the brief didn't anticipate.
+  Don't just accept it because it looks reasonable; understand it and decide.
+
+## The implementer sweep
+
+Generated code fails in systematic ways that gates are structurally blind to — each of these can sit in
+a diff whose tests are all green. Walk them against every diff before you commit:
+
+- **Hardcoded success or fixture data** on a path the brief says does real work — a canned
+  `{status: "ok"}` or default return passes tests *by design*. If Codex couldn't implement something,
+  the diff should fail loudly, not pretend.
+- **Catch-all error handling that returns a default** instead of propagating — the suppressed failure is
+  exactly what the gate would have caught. A broad catch is only acceptable with a recovery path the
+  contract documents.
+- **Unverified imports and API calls** — confirm every new dependency, method, and signature exists in
+  the *installed* version (read the lockfile or the package, don't trust plausibility).
+- **Dead weight** — unused imports, helpers nothing calls, unreachable branches, "Step 1/Step 2"
+  comment scaffolding, comments that restate the line below them.
+- **A second way to do what the file already does** — a new HTTP client, error idiom, or logging style
+  introduced beside the existing one instead of reusing it.
+- **New tests that assert internals** — asserting that an internal helper was called, or mocking the
+  project's own functions to isolate a "unit." Green, brittle, and worthless as regression cover.
+- **Near-duplicate test bodies** differing by one value — fold into one data-driven test or drop the
+  copies; bloat reads as coverage but isn't.
+- **Speculative surface** — optional parameters, config flags, or abstractions with no caller in this
+  diff or the repo. Delegated work gets the concrete behavior the brief asked for, nothing extra.
+- **Guards for impossible cases** — null/type checks for values the code's own contract already
+  excludes. Noise that buries the validation that matters at real trust boundaries.
+
+Anything the sweep catches goes back to Codex as a delta brief (below) or gets fixed in the tree before
+commit — and either way is reported to the user (see "Surface, don't absorb").
+
+If the `guard-skills` package is installed, run the relevant guard on the diff for the full treatment —
+`clean-code-guard` on production code, `test-guard` on tests, `docs-guard` on documentation. The sweep
+above is the built-in floor; the guards go deeper.
+
+## The commit boundary
+
+When the gates pass and the diff holds, **you commit** — the orchestrator, never Codex. This isn't a
+workaround for a missing feature; it's the deliberate boundary. Codex's sandbox can't reliably write
+`.git`, and more importantly, committing should be the act of the party that verified the work. Write
+a clear message describing what landed. If your project attributes co-authorship, that's the place
+for it.
+
+From dispatch until that commit, the uncommitted working tree is the authoritative copy of the
+implementer's work — the only one you can commit from, and often the only copy at all. Never run `git checkout`, `reset`, `clean`, or a branch switch in the
+workspace between those two points — however messy an interrupted run looks, inspect it first:
+`git status`, `git diff`, `git diff --cached` for anything the implementer staged (plain
+`git diff` is blind to the index), and open any untracked files (`??` in `git status`) directly —
+they are the implementer's new files, and no diff shows their contents. The tree is evidence,
+not clutter. After that inspection the
+verdict can legitimately be to discard — work built on a premise you have since corrected, for
+example — and then `git checkout`/`clean` is the right tool. The ban is on reflexive cleanup
+before anyone has looked.
+
+## Reworking: send the delta, not the whole task
+
+If the review turns up problems, don't restate the entire brief. Continue the same Codex session with
+just the correction:
+
+```bash
+echo "The fix is right, but the test mocks the DB session - use the real migrated fixture instead, and
+drop the now-unused import." | node "<skill-dir>/scripts/relay.mjs" --resume-last --cd /path/to/repo
+```
+
+(`<skill-dir>` is this skill's install directory — see [dispatch-and-poll.md](dispatch-and-poll.md).)
+
+`--session <threadId>` (or `--resume-last`) keeps Codex's context from the first run, so a short delta is enough. Then review
+again — rework gets the same gate-rerun, test check, diff-read, and sweep as the original, no
+shortcuts. Repeat until it's right, then commit.
+
+## Surface, don't absorb
+
+The human opted into delegation, so committing verified, gate-passing work is the agreed contract.
+But keep them in the loop on anything that changes the shape of the work:
+
+- **Report design decisions** Codex made, and any defensible-but-unrequested turns it took.
+- **Note non-blocking nitpicks** you chose not to block on, so the human can overrule you.
+- **Stop and ask** if correct completion requires going beyond the brief — don't expand the mandate on
+  your own. A scope change is the human's call, not yours or Codex's.
+
+For a multi-task run, capture these in the progress file rather than letting them scroll past — see
+[multi-task-queues.md](multi-task-queues.md).

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

@@ -0,0 +1,125 @@
+# Writing the brief
+
+A brief is the entire task as Codex will see it. Codex runs in a fresh process with **no memory of
+your conversation, no access to your prior notes, and no shared context** — only the text you send and
+whatever it can read from the working tree (including the repo's own `AGENTS.md`, which it picks up
+automatically).
+If a constraint isn't in the brief or discoverable in the repo, it doesn't exist for Codex. The single
+most common failure is a brief that assumes context Codex doesn't have.
+
+## The shape that works
+
+Codex responds best to compact, block-structured prompts with XML tags rather
+than long prose. State the task, what "done" looks like, how to behave by default, and the few
+constraints that actually matter. Add a block only when the task needs it — don't ship empty ceremony.
+
+```xml
+<task>
+One or two sentences: the concrete job and where it lives. Then the specifics — current state, what to
+change, and explicitly what to leave untouched. The "leave untouched" list is what keeps Codex from
+wandering into unrelated refactors.
+</task>
+
+<verification_loop>
+Run these before finishing and fix anything they surface, don't just report it:
+  <the project's real test command>
+  <the project's real lint/format command>
+  <the project's real build/typecheck command>
+Confirm the working tree shows only the intended changes afterward.
+</verification_loop>
+
+<action_safety>
+Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
+correctness. Do NOT run git add or git commit — you cannot reliably write .git, and the orchestrator
+commits after reviewing. Leave the work uncommitted in the working tree.
+</action_safety>
+
+<structured_output_contract>
+End with a report in this exact shape:
+  1. What changed and why
+  2. Files touched
+  3. Gate outcomes (paste the test/lint counts)
+  4. Anything you deviated on, left open, or want a decision on
+</structured_output_contract>
+```
+
+That four-block skeleton covers most implementation tasks. Reach for the extra blocks when the task
+profile calls for them:
+
+- **Debugging / open-ended fixes** — add `<completeness_contract>` (resolve fully, don't stop at the
+  first plausible fix) and `<missing_context_gating>` (don't guess missing repo facts; find them or
+  state what's unknown).
+- **Review / diagnosis (read-only)** — add `<grounding_rules>` (ground every claim in evidence; label
+  inferences) and run with `--read-only` so Codex can't edit.
+- **Research / recommendations** — add `<research_mode>` (separate observed facts, inferences, open
+  questions).
+
+## Discover the real gates — don't hardcode
+
+`<verification_loop>` is only useful if it names the project's *actual* commands. Read the repo's
+`CLAUDE.md` / `AGENTS.md` / `Makefile` / `package.json` first and copy the real ones in (`make test`,
+`npm run lint`, `cargo test`, `pytest -q`, whatever it is). A brief that says "run the tests" without
+naming them gets you a Codex that guesses — or skips.
+
+## Honor the repo's conventions
+
+Codex reads the repo's `AGENTS.md` automatically, so house rules there (style, forbidden patterns,
+commit conventions) already apply. If the project forbids certain things in code — say, spec/ticket IDs
+in comments, process language like "MVP"/"for now"/"phase N", or specific test conventions, whatever
+the repo's own conventions ban — restate the load-bearing ones in the brief too, because Codex's
+compliance is only as reliable as what's in front of it.
+
+## One task per brief
+
+Keep each brief to a single, bounded job. "Review this, fix what you find, update the docs, and
+suggest a roadmap" produces a muddled run; split it into separate dispatches. One brief → one Codex
+run → one commit keeps review and rollback clean, and lets a later task assume the earlier one landed.
+
+## Premises freeze at dispatch
+
+The implementer starts from the brief's facts and there is no steering channel mid-run. Audit the
+fact block before sending — ownership, target branch, constraints, anything a judgment call rests
+on. If a premise turns out wrong while the run is live, stop the run and re-dispatch a corrected
+brief rather than discounting the output afterward; for a write-capable run, inspect the working
+tree and reconcile any partial or premise-contaminated edits — keep or revert them — before the
+re-dispatch.
+
+## Expect environment preamble in the reply
+
+Codex's final message may carry environment noise on top of your requested report — a banner injected
+by the repo's `AGENTS.md`, extra text from an MCP tool or extension you've configured, and similar
+local additions. That comes from your own Codex setup, not a relay defect. The
+`<structured_output_contract>` is your defense: ask for a clearly delimited report section so you can
+find the real output regardless of what wraps it.
+
+## A worked example
+
+```xml
+<task>
+In the payments service at services/billing/, the refund path double-charges when a refund is retried
+after a network timeout (the idempotency key isn't checked before re-submitting). Make the refund
+submission idempotent: check for an existing refund by idempotency key before creating a new one.
+Touch only services/billing/refund.py and its tests. Leave the charge path, the API routes, and the
+data models untouched.
+</task>
+
+<verification_loop>
+Run and make green before finishing:
+  pytest tests/billing/ -q
+  ruff check services/billing/
+Confirm git status shows only refund.py and its test file changed.
+</verification_loop>
+
+<action_safety>
+Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave
+changes in the working tree for review.
+</action_safety>
+
+<structured_output_contract>
+Report: (1) the root cause and your fix, (2) files touched, (3) pytest + ruff outcomes with counts,
+(4) anything you left open or want decided.
+</structured_output_contract>
+```
+
+Send this with `relay.mjs` (see [dispatch-and-poll.md](dispatch-and-poll.md)); review the result and
+commit it yourself (see [review-and-land.md](review-and-land.md)).

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

@@ -0,0 +1,188 @@
+---
+name: commandcode-delegate
+description: Delegate coding tasks to the Command Code CLI (`cmd`) only when the user
+  explicitly requests it, while the orchestrator retains review and landing responsibility.
+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 the Command Code CLI (`cmd`, or `cmdc` on Windows, from commandcode.ai)
+  installed and authenticated, Node 22+, and git. The orchestrating agent must be
+  able to run shell commands and read files. Shell examples assume bash/zsh (macOS/Linux).
+metadata:
+  version: 0.5.0
+---
+# Command Code Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `commandcode` implementer (`Command Code`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. This skill lets you hand a bounded coding task to a separate
+**implementer** — the Command Code CLI (`cmd`) — then review what it produced and land it yourself.
+You write the brief and own the judgment; Command Code does the typing in your working tree; you
+verify and commit.
+
+Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell
+command and read a file, so it works the same whether you are Claude Code, OpenCode with a selected
+model, or any comparable agent. (It is designed for and run on Claude Code; treat other orchestrators
+as designed-for, not yet proven.)
+
+## When NOT to use this
+
+- The task is small enough to just do inline — delegation overhead is not worth it.
+- The `cmd` CLI is not installed or not authenticated (run `cmd login`).
+- You want to write the code yourself, or you only need a review (Command Code has its own `/review`).
+- You are on native Windows and `cmdc --version` does not work. Upstream recommends WSL for stable Windows use.
+
+## Read this before the first dispatch: the autonomy model
+
+Command Code's headless mode has **exactly two states, with nothing in between**:
+
+- **Default (`-p` with no `--yolo`):** read, grep, and glob work. Every write, edit, and shell call is
+  refused by the CLI's permission layer, and headless mode has no prompt to grant them mid-run. This
+  is the relay's `--read-only`.
+- **`--yolo` (alias `--dangerously-skip-permissions`):** every tool is allowed, anywhere the process
+  can reach. There is no filesystem sandbox and no path restriction. This is what an implementation
+  run needs, so the relay passes it by default.
+
+`--permission-mode auto-accept` and `--tools-all` do **not** lift the headless write gate. Direct CLI
+probes refused write, edit, and shell with both. So an implementation run
+through Command Code is a full-trust run: scope it with a tight brief and a clean working tree, not
+with a sandbox. The brief is guidance, and a git worktree isolates a checkout without containing the
+process. If writes outside the target tree are unacceptable, use an OS-enforced sandbox such as
+`codex-delegate` or run this one inside a container.
+
+Before the first write-capable run, explain this unsandboxed full-trust mode and obtain explicit
+human acceptance. A request to delegate to Command Code is not by itself consent to host-wide access.
+
+## Prerequisites (check once)
+
+1. `cmd --version` succeeds and `cmd status` reports authenticated. If not, install Command Code and
+   run `cmd login`.
+2. **Confirm the CLI on PATH.** On macOS/Linux, `command -v cmd` shows the active `cmd`. On native
+   Windows, use `cmdc --version`; `cmd` is the system shell. The relay uses `cmdc` there and launches
+   its npm `.cmd` shim through `cmd.exe`. `COMMANDCODE_BIN` remains an absolute-path override and must
+   never point to the system command interpreter. The relay records the version it ran in
+   `result.json`, so a wrong binary is visible after the fact.
+3. You are in (or will point `--cd` at) the target git repository, and its tree is clean before you
+   dispatch — a full-trust run is much easier to review against a clean baseline.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+Command Code sees **only** the text you send — no repo memory, no chat history, no shared context
+(beyond the repo's own `AGENTS.md`, which it reads automatically). Everything the task needs goes in
+the brief: the goal, the current state, what to change, what to leave untouched, the project's
+**actual** gate commands (discover them from the repo's AGENTS.md/CLAUDE.md/Makefile — do not assume),
+and a report contract. Tell it that it will **not** commit (you will). Keep one task per brief. Full
+guidance and a template: [references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+Send the brief to Command Code with the bundled helper. It wraps `cmd -p`, captures the run, and
+writes a structured `result.json` — so your only job is "run a command, read a file." (`<skill-dir>`
+below is this skill's installed directory — the folder containing this `SKILL.md`, i.e. the directory
+you loaded the skill from. Claude Code prints it as "Base directory for this skill" when the skill
+loads; on other orchestrators use that same directory — if unsure where it landed, run
+`find ~ -name relay.mjs -path '*commandcode-delegate*'` and substitute the directory above it.)
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+# read-only (review/diagnosis, no edits):   add --read-only
+# continue the exact session:               add --session <sessionId>  (from result.json; send only the delta brief)
+# fallback when no session id is available: add --continue-last
+# hard time limit (watchdog):               add --timeout 2h  (default: off; implementation runs routinely need 1-2h)
+# see all options:                          node .../relay.mjs --help
+```
+
+The helper defaults to a write-capable (`--yolo`) run, which intentionally edits the target repository.
+Its temp directory keeps only relay artifacts out of that repository. The relay **never commits** —
+see step 5. Mechanics, flags, and the
+`result.json` shape: [references/dispatch-and-poll.md](references/dispatch-and-poll.md).
+
+### 3. Wait for completion
+
+The helper blocks until Command Code finishes, so back it with whatever your orchestrator offers and
+resume when it returns:
+
+- **Claude Code:** run the Bash call with `run_in_background: true`; you are notified on completion.
+- **Plain shell / other agents:** run it in the foreground for short tasks, or background it and poll
+  the result file — `… &` in bash/zsh, or your shell's equivalent. The run is done when `result.json`
+  exists with a `status`. (A pre-run usage error — bad args or an empty brief — instead exits with code
+  2 and a stderr message and writes no result file, so check the exit code too. A missing `cmd` binary
+  exits 127 but *does* write a `result.json` with status `commandcode_unavailable`.)
+
+Do not trust progress trackers over reality: a run is finished when `result.json` is written and the
+process has exited. Read the working tree, not a status line. The implementer's full report is the
+`finalMessage` field in `result.json` (also printed in full on stdout between the report markers).
+
+### 4. Review — do not trust the self-report
+
+`result.json` includes Command Code's own summary and gate claims. **Re-verify, don't accept:**
+
+- **Re-run the project's gates yourself** (the test/lint/build commands from step 1). Never take
+  "gates passed" on faith.
+- **Read the diff** against the brief: did it do what was asked, nothing more (scope creep) and
+  nothing less? `touchedFiles` in the result is your starting point — and because the run was
+  full-trust, check for edits *outside* the paths the brief named, not just inside them.
+- **Run the relevant guard skills** on the diff if you have them installed (clean-code-guard,
+  test-guard, etc. from `guard-skills`) — this skill produces the work; those skills judge it.
+- For schema/migration changes, round-trip them; for removals, grep for dangling references.
+
+Full checklist: [references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+The relay never commits, but it cannot stop Command Code under `--yolo` from writing `.git`. The brief
+forbids implementer commits, and the reviewer compares `HEAD` with the recorded pre-dispatch baseline
+before landing anything. **The orchestrator commits.** Only after the gates pass and the diff holds:
+
+- Commit the verified work yourself, with a clear message.
+- If it needs changes, send a delta brief with `--session <sessionId>` from the prior `result.json`
+  (use `--continue-last` only when no session id is available), and review again.
+
+## Read-only second opinions
+
+The relay doubles as a clean way to get an adversarial second opinion: dispatch `--read-only` with a
+brief that lists the agreed points, then each contested point with both positions, and ask Command
+Code to defend or concede each — deliverable in its final message, touching no files. The read-only
+guarantee here is the CLI's own permission layer rather than an OS sandbox, so the relay also checks
+it after the fact: `readOnlyViolation: false` means the Git-visible detector saw no change (ignored
+or outside-repository paths are not covered); `true` means it saw one; `null` means git could not tell.
+
+## 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 — that is the whole point. Two limits on that
+mandate: **surface, don't absorb** (report Command Code's design decisions, defensible-but-unasked
+turns, and non-blocking nitpicks rather than silently keeping them) and **stop for scope changes** (if
+correct completion needs going beyond the brief, ask — don't expand the mandate yourself). The full
+treatment is in [references/review-and-land.md](references/review-and-land.md).
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) — how to write a brief Command
+  Code can execute blind: structure, XML blocks, the report contract, embedding the real gate commands.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) — `relay.mjs` flags, the
+  `result.json` contract, backgrounding per orchestrator, and recovery when a run misbehaves.
+- [references/review-and-land.md](references/review-and-land.md) — the review checklist, the commit
+  boundary, and the exact-session rework cycle.
+- [references/multi-task-queues.md](references/multi-task-queues.md) — running a sequential queue:
+  carrying constraints forward, progress tracking, and the end-of-run coherence check.
+
+
+## Limitations
+
+- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `commandcode` CLI, Node 18+, git.
+- Relay never commits — it only returns structured result JSON; you review and land the commit.
+
+> Adapted from [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills) (MIT) — docs-only, runtime not bundled.