docs(commands): teach Claude to extract PR refs and quote focus text

plugins/opencode/commands/adversarial-review.md

@@ -39,22 +39,38 @@ Argument handling:
 - The companion script handles `--adversarial` internally.
 - `--model <id>` overrides OpenCode's default model for this single review (e.g. `--model openrouter/anthropic/claude-opus-4-6`). Pass it through verbatim if the user supplied it.
 - `--pr <number>` reviews a GitHub pull request via `gh pr diff` instead of the local working tree. The cwd must be a git repo whose remote points at the PR's repository, and `gh` must be installed and authenticated.
-- If the user mentions a PR reference in the focus text (e.g. `on PR #390`), the companion script auto-detects it and strips the matched substring from the focus. You do not need to do anything special — just pass the user's text through verbatim. Prefer the explicit `--pr` flag for new commands.
+
+PR reference extraction (REQUIRED — read this carefully):
+- If the user's input contains a PR reference like `PR #390`, `pr #390`, `PR 390`, or `pr 390`, you MUST extract the number yourself and pass it as `--pr 390`. Then strip the matched PR phrase from whatever you put in the focus text.
+- Do **not** rely on the companion script's focus-text auto-detection for PR refs. Bash strips unquoted `#NNN` tokens as comments before they ever reach the companion script (e.g. `bash -c 'node ... adversarial-review on PR #390'` invokes node with argv `["adversarial-review", "on", "PR"]` — the `#390` is gone).
+- Example transformation:
+  - User input: `/opencode:adversarial-review on PR #390 challenge the caching strategy`
+  - Wrong: `node ... adversarial-review on PR #390 challenge the caching strategy` (the `#390` and everything after is silently dropped by bash)
+  - Right: `node ... adversarial-review --pr 390 'challenge the caching strategy'`
+
+Focus text quoting (REQUIRED):
+- When you invoke the companion script via Bash and the user's focus text contains shell metacharacters (`#`, `*`, `$`, `;`, `&`, `|`, `<`, `>`, parentheses, backticks, etc.), wrap the focus text in **single quotes** so bash passes it through unchanged. Single quotes preserve everything literally except the single-quote character itself.
+- If the focus text itself contains a single quote (e.g. `what's wrong here`), use the standard `'\''` escape: `'what'\''s wrong here'`.
+- Examples:
+  - `/opencode:adversarial-review challenge the design` → `node ... adversarial-review 'challenge the design'`
+  - `/opencode:adversarial-review --background look for race conditions in $RUNTIME` → `node ... adversarial-review --background 'look for race conditions in $RUNTIME'`
 
 Foreground flow:
-- Run:
+- First, transform `$ARGUMENTS` using the **PR reference extraction** and **Focus text quoting** rules above. Pass through `--wait`, `--background`, `--base`, `--scope`, `--model`, and `--pr` flags as-is; convert any `PR #N` reference in the user's text to `--pr N`; single-quote whatever free-form focus text remains.
+- Then run the resulting command (illustrative shape — substitute the actual transformed args):
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/opencode-companion.mjs" adversarial-review $ARGUMENTS
+node "${CLAUDE_PLUGIN_ROOT}/scripts/opencode-companion.mjs" adversarial-review <flags> [--pr N] ['<quoted focus text>']
 ```
 - Return the command stdout verbatim, exactly as-is.
 - Do not paraphrase, summarize, or add commentary before or after it.
 - Do not fix any issues mentioned in the review output.
 
 Background flow:
-- Launch the review with `Bash` in the background:
+- Apply the same `$ARGUMENTS` transformation as the foreground flow above (PR ref extraction + focus text single-quoting).
+- Then launch the resulting command with `Bash` in the background:
 ```typescript
 Bash({
-  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/opencode-companion.mjs" adversarial-review $ARGUMENTS`,
+  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/opencode-companion.mjs" adversarial-review <flags> [--pr N] ['<quoted focus text>']`,
   description: "OpenCode adversarial review",
   run_in_background: true
 })

plugins/opencode/commands/review.md

@@ -41,6 +41,7 @@ Argument handling:
 - If the user needs custom review instructions or more adversarial framing, they should use `/opencode:adversarial-review`.
 - `--model <id>` overrides OpenCode's default model for this single review (e.g. `--model openrouter/anthropic/claude-opus-4-6`). Pass it through verbatim if the user supplied it.
 - `--pr <number>` reviews a GitHub pull request via `gh pr diff` instead of the local working tree. The cwd must be a git repo whose remote points at the PR's repository, and `gh` must be installed and authenticated. Pass it through verbatim if the user supplied it.
+- **PR reference extraction (REQUIRED)**: if the user's input contains a PR reference like `PR #390`, `pr #390`, `PR 390`, or `pr 390` (e.g. `/opencode:review on PR #390`), you MUST extract the number yourself and pass it as `--pr 390`. Do not pass `PR #390` literally to bash — bash strips unquoted `#NNN` tokens as comments before they reach the companion script. Example: `node ... review --pr 390`, NOT `node ... review on PR #390`.
 
 Foreground flow:
 - Run: