@ask-llm/plugin 0.14.0 → 0.16.2

package/skills/brainstorm/SKILL.md

@@ -1,63 +1,89 @@
 ---
 name: brainstorm
-description: Send a topic to multiple LLM providers concurrently after the current host model forms an independent view, then synthesize all findings. Usage /brainstorm [providers] <topic>. External providers default to antigravity,codex. Example /brainstorm antigravity,codex,ollama "review this architecture"
+description: Send a topic to an explicit multi-model panel, then synthesize findings with truthful provider, harness, and model attribution. Usage /brainstorm [participants] <topic>. Defaults to antigravity,codex. Preferred Grok route uses Cursor Agent with an exact catalog ID.
 ---
 
 <!-- PORTABLE-CONTRACT:START -->
 ## Portable contract
 
-The current host model must form and record an independent analysis before seeing external answers. Then send the same bounded topic and Context Brief concurrently to the selected providers, cross-check claims against source where possible, and synthesize consensus, unique insights, contradictions, rejected false positives, and confidence. Report the actual host model/providers and disclose possible same-family overlap.
+For the standard workflow, the current host model records an independent analysis before seeing external answers, then sends the same bounded topic and Context Brief concurrently to the selected providers. For the exact Grok + GPT-5.6 Sol workflow, the host is a non-voting evidence verifier/synthesizer: the brainstorming panel has exactly those two requested participants. Cross-check source where possible and synthesize consensus, unique insights, contradictions, rejected false positives, failures, and confidence. Keep provider, harness, requested model ID, independently observed served model ID, and Cursor's reported display label separate. Only direct xAI API / Grok CLI routes can report a served ID, and only when the provider/CLI payload actually carries one; a disclosed same-product alias/snapshot resolution (for example `grok-4.6` or `grok-4-latest` served as a dated `grok-4-<snapshot>`) stays eligible, while a different model is a mismatch and ineligible. A direct route whose payload omits the model stays selected-only. Cursor Agent and Codex CLI echo the requested ID, so that attribution is selected-only and unverifiable—never call a requested or selected ID the actual model. Never select Cursor Auto, infer a requested ID from a display label, silently change a model, or pivot to another harness/provider.
 <!-- PORTABLE-CONTRACT:END -->
 
 ## Host adapters
 
 ### Pi adapter
 
-The current Pi host model completes its independent view first, records its actual provider/model, and only then calls native `ask-multi`. Do not claim the host is Claude Opus or that the coordinator has an isolated context.
+The current Pi host model completes its independent evidence memo first. Standard provider lists use native `ask-multi`. A routed participant uses the matching native tool instead: `provider@cursor-agent:model` calls `ask-cursor-agent` with separate `provider` and exact `model`; direct Grok calls `ask-grok` with the explicit `harness` and exact model. A participant list mixing routed `provider@harness:exact-model-id` entries with bare provider names is refused before any tool call; nothing is dispatched or substituted. For the exact Grok + Sol panel, issue only these two consultations (concurrently when the host supports it):
+
+- `ask-cursor-agent({ provider: "grok", model: "cursor-grok-4.6-high", prompt })`
+- `ask-cursor-agent({ provider: "codex", model: "gpt-5.6-sol-high", prompt })`
+
+Do not call `ask-multi` for that panel because it cannot express Cursor harness identity, and do not call Gemini. Treat the host memo as non-voting verification evidence, not a third panel answer. If either participant fails, label the run partial and do not claim two-model consensus.
 
 <!-- HOST-ADAPTER:CLAUDE-CODE:START -->
 ### Claude Code adapter
 
 The existing detailed workflow below is the Claude Code adapter. Its Agent, MCP, hook, `CLAUDE_PLUGIN_ROOT`, and `AskUserQuestion` mechanics apply only on Claude Code; they do not override the Pi adapter above.
 
-
-
 # Multi-LLM Brainstorm
 
-Consult multiple external LLM providers simultaneously on a topic while Claude Opus performs its own independent research in parallel, then synthesize the findings from all participants.
+Consult an explicitly selected panel on a topic, then synthesize the responses against source-grounded host research.
 
 ## Instructions
 
-### Phase 1: Parse arguments
+### Phase 1: Parse arguments and freeze participant identity
+
+- The first argument may be a comma-separated participant list.
+- Compatible bare provider names remain supported: `gemini`, `codex`, `grok`, `ollama`, `antigravity`. If omitted, default to `antigravity,codex`.
+- Bare `grok` retains the existing direct canonical runner and its explicit `ASK_GROK_HARNESS` selection (`xai-api` default or `grok-cli`) for compatibility. That direct route never falls back.
+- Preferred explicit syntax is `provider@harness:exact-model-id`. Supported routed participants are:
+  - `grok@cursor-agent:<exact ID from agent --list-models>` (preferred Grok route)
+  - `codex@cursor-agent:<exact GPT-5.6 Sol ID from agent --list-models>`
+  - `grok@grok-cli:<exact ID from grok models>` (explicit Grok Build alternative)
+  - `grok@xai-api:<exact ID from GET /v1/models>`
+  - `codex@codex-cli:gpt-5.6-sol` (explicit direct Codex alternative; any reported fallback makes the exact panel partial)
+- Never accept `Auto`, map a display label to an ID, or substitute a route. A missing registration/harness, unavailable model, auth failure, or unsupported provider/harness pair is a participant failure with its actionable error preserved.
+- A participant list must be either all bare provider names or all routed `provider@harness:exact-model-id` specs. A mixed list (for example `grok@cursor-agent:cursor-grok-4.6-high,antigravity`) is refused before any dispatch with the "Mixed brainstorm participant lists are not supported" error; no participant is rerouted to a bare runner, substituted, or dispatched. Generalized mixed panels are deferred to a future ADR.
+- Everything after the participant list is the topic.
+- In standard mode, Claude Opus remains a participant. In the exact Grok + Sol mode below, Claude is only the non-voting evidence verifier/synthesizer so the panel has exactly two participants.
+
+**Architect workflow — exactly Grok + GPT-5.6 Sol, no Gemini:**
+
+```text
+/brainstorm grok@cursor-agent:cursor-grok-4.6-high,codex@cursor-agent:gpt-5.6-sol-high "review this architecture"
+```
+
+These IDs are exact catalog examples verified for this workflow; account catalogs can change, so use `agent --list-models` and replace an unavailable ID explicitly. The coordinator must not call Gemini, the direct Grok runner, xAI API, Grok Build, or Codex CLI for this invocation.
+
+**Explicit Grok Build alternative (still no Gemini):**
 
-- If the first argument looks like a comma-separated provider list (e.g., `antigravity,codex` or `gemini,codex,grok,ollama`), use those as the external providers
-- If no provider list is given, default to `antigravity,codex`
-- Valid external providers: `gemini`, `codex`, `grok`, `ollama`, `antigravity`
-- `grok` requires `XAI_API_KEY` for the default API harness or official Grok Build auth with `ASK_GROK_HARNESS=grok-cli`; it may consume metered/plan usage and never falls back
-- `antigravity` requires `agy` installed + logged in; if it's unavailable the coordinator surfaces that and continues with the other providers
-- Everything after the provider list (or all args if no list) is the topic
-- Claude Opus is always a participant — it's not in the provider list because it runs inside the coordinator
+```text
+/brainstorm grok@grok-cli:grok-build,codex@cursor-agent:gpt-5.6-sol-high "review this architecture"
+```
+
+This route is valid only when the installed Grok Build contract supports Ask LLM's headless JSON/read-only flags. Failure is terminal for the Grok participant; do not pivot to Cursor or xAI.
 
 ### Phase 2: Determine and prepare the brainstorm topic
 
-- If the user provided a topic directly, use it
-- If the context is about code changes, gather the relevant diff:
-  - `git status --short` first to see what's modified/added/deleted
-  - `git add -N <new-files>` for untracked files the user wants included
-  - `git diff` + `git diff --cached` combined
-  - **Filter noise**: exclude `:!docs/` `:!apps/docs/` `:!*.md` `:!yarn.lock` `:!*.lock` `:!*.png` from the pathspec — providers don't need to review your ADR/doc additions
-  - **Size-check**: if combined diff > 150KB, ask the user before sending (the providers will take 5–15 min on payloads that large)
-- If the context is a design/plan, gather the relevant documentation or conversation context
-- If no topic is clear, ask the user what they'd like to brainstorm about
-- Create a compact **Context Brief** before launching the coordinator. Keep it tiny for simple topics; add detail when the request is architecture/design/security/concurrency/migration related, spans packages, references external specs, or depends on conversation context external providers cannot see.
+- If the user provided a topic directly, use it.
+- For code changes, gather relevant context:
+  - Run `git status --short` first.
+  - Use `git add -N <new-files>` for untracked files the user wants included.
+  - Combine `git diff` and `git diff --cached`.
+  - Exclude noise with `:!docs/` `:!apps/docs/` `:!*.md` `:!yarn.lock` `:!*.lock` `:!*.png`.
+  - If the combined diff exceeds 150KB, ask before sending.
+- For a design/plan, gather relevant documentation and conversation context.
+- If no topic is clear, ask what to brainstorm.
+- Create a compact **Context Brief**. It must list the exact requested participant identities, not just display names:
 
 ```markdown
 ## Context Brief
 
 Intent:
 - User request:
-- Brainstorm mode:
-- Providers: <list the selected providers for this run>
+- Brainstorm mode: <standard | exact-grok-sol>
+- Participants: <provider via harness, exact requested model for each>
+- Explicitly excluded: <for exact-grok-sol: Gemini and every unselected route>
 
 Scope:
 - Changed/referenced files:
@@ -83,24 +109,21 @@ Open questions:
 
 ### Phase 3: Launch the brainstorm-coordinator agent
 
-Launch with: the topic, the selected external providers list, the Context Brief, and any gathered context (diff/files/docs).
+Pass the topic, exact participant specs, Context Brief, and gathered context. The coordinator:
 
-The coordinator handles:
-- Phase 3B: its own Claude Opus research (reads actual files, traces code, uses WebFetch/WebSearch on referenced external docs) — runs FIRST so Claude doesn't anchor on external responses
-- Context Brief update: after Phase 3B, records verified files/docs and unverified assumptions before external dispatch
-- Phase 3A: external provider dispatch via a single blocking foreground Bash call (ADR-050 dispatch pattern)
-- Phase 4: synthesis — consensus, unique insights, contradictions across all participants
-- Verified findings (backed by Claude's file reads) are weighted higher than inferred ones
-- Failed providers are surfaced inline with their stderr, not silently dropped
+- researches independently before dispatch and records any unverified assumptions;
+- treats that research as non-voting verification evidence in exact two-model mode;
+- uses the packaged `dist/brainstorm-run.js` for the exact Grok + Sol panel so both requests start concurrently within one blocking foreground process;
+- uses only the selected routes and exact IDs;
+- surfaces every failure and preserves provider/harness/model attribution; and
+- synthesizes only after dispatch completes.
 
-### Phase 4: Present the coordinator's synthesis
+### Phase 4: Present synthesis truthfully
 
-Pass through the coordinator's structured output. If the coordinator returned a partial result (some providers failed), present what landed and explicitly note what's missing — don't paraphrase or hide compromises.
+Pass through the coordinator's structured output. Attribute each participant by provider, harness, and requested ID; add the observed served ID only for direct xAI API / Grok CLI routes (noting a disclosed alias/snapshot), and describe Cursor and Codex CLI attributions as selected-only and unverifiable with any Cursor display label shown as a label, not a catalog ID. A two-model consensus exists only when both requested participants succeeded and independently support the point. If one fails, label the run **partial**, attribute surviving insights to the model that produced them, and never describe them as consensus. If both fail, report failure and provide no panel synthesis. The host's verification memo may verify or reject claims, but it cannot turn one participant's answer into two-model agreement.
 
 ## Important — verification matters
 
-Confidence scores are not an oracle. The coordinator's Phase 3B exists specifically because external LLMs can return high-confidence findings that turn out to be factually wrong (a real example from 2026-04-17: Gemini returned 95/100-confidence claims that were contradicted by the actual `.d.ts` file). Claude's "Verified" findings carry more weight than external "Inferred" findings precisely for this reason.
-
-If you want a code-review-specific version of this with explicit per-finding source verification, use `/multi-review` instead.
+Confidence scores are not an oracle. External LLMs can return high-confidence claims contradicted by source. Verified findings carry more weight than inferred findings, while participant counts and consensus eligibility remain mechanical and cannot be upgraded by confidence. For code-review-specific per-finding verification, use `/multi-review`.
 
 <!-- HOST-ADAPTER:CLAUDE-CODE:END -->

package/skills/codex-pair/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: codex-pair
-description: Show codex-pair status and set up the per-edit Codex review hook for this project. Detects whether codex-pair is active, paused, or not yet configured. On first run (no marker), offers interactive setup with auto-detected project context. On subsequent runs, shows current state, recent review activity, and toggle instructions. The per-edit hook itself runs automatically; this command is the human-facing dashboard for it.
+description: Pair with Codex using the host's supported lifecycle. On Claude Code and Pi, manages the proven opt-in per-edit review flow; on Cursor Agent, runs an explicit consent-gated iterative reviewer session through an exact ask-codex leaf or fully pinned unified ask-llm without assuming Claude hooks or namespaces.
 ---
 
 <!-- PORTABLE-CONTRACT:START -->
 ## Portable contract
 
-Set up and report status for recall-first per-edit Codex review. The repository marker carries review context but is not, by itself, authorization on Pi. Preserve bounded file context, debounce, pause/resume, acknowledgement, deduplication, failure disclosure, and explicit host lifecycle limitations.
+Use Codex as an explicit read-only reviewer while the host remains the editor. Apply `../pairing-contract.md`. Where the host supports the established per-edit integration, set up and report its status: the repository marker carries review context but is not, by itself, authorization on Pi. Preserve bounded file context, include-directory handling, reasoning effort, session continuity where supported, consent, cancellation, actionable relay, failure disclosure, and explicit host lifecycle limitations.
 <!-- PORTABLE-CONTRACT:END -->
 
 ## Host adapters
@@ -15,6 +15,48 @@ Set up and report status for recall-first per-edit Codex review. The repository
 
 Pi requires project trust, this repository marker, and explicit user-owned allowlist consent through `/codex-pair`. Pairing is asynchronous in TUI/RPC/long-lived JSON modes, uses `tool_result`, and surfaces findings non-blockingly. One-shot print mode, blocking Stop-gate parity, and nested Fable execution are unsupported.
 
+### Cursor Agent adapter
+
+Cursor discovers this `SKILL.md` through its supported Agent Skills surface; `/codex-pair` attaches it as an explicit command. Do **not** use Claude Code's `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `CLAUDE_PLUGIN_ROOT`, `AskUserQuestion`, or plugin tool namespaces. This adapter is an on-demand iterative pairing session, not a claim that Claude hooks were registered in Cursor.
+
+1. Read `../pairing-contract.md`. The Cursor plugin bundle registers only the unified `ask-llm` server; if the user separately installed `@ask-llm/codex-mcp`, prefer that deterministic `ask-codex` leaf. Resolve an exposed MCP tool whose exact leaf is `ask-codex`; do not assume its server prefix. When only the unified `ask-llm` leaf is registered, it may serve as the transport with `provider: "codex"` and every option (model, reasoning effort, include directories, session) pinned explicitly; its schema rejects unsupported combinations instead of stripping them and Codex runs read-only by default. Never make an unpinned generic call. If neither tool is exposed, stop with the recommended user-installed unified server:
+   ```json
+   {"mcpServers":{"ask-llm":{"command":"npx","args":["-y","@ask-llm/mcp"]}}}
+   ```
+   Save that as project `.cursor/mcp.json` or user `~/.cursor/mcp.json`, ensure `codex` is authenticated, reload the server from Cursor Settings → Tools & MCP or restart Cursor Agent, and invoke `/codex-pair` again. A split `codex` entry using `@ask-llm/codex-mcp` is an explicit user-installed alternative when only the `ask-codex` leaf is desired; keep one registration per server (the plugin already provides `ask-llm`, so do not add a second `ask-llm` entry merely to duplicate it).
+2. Require both `model=<exact ID>` and `effort=low|medium|high|xhigh|max`; parse optional `include=dir1,dir2`. If model or effort is omitted, ask the user to choose it and stop before reading extra context, requesting consent, or calling a provider. Do not infer either value from the Cursor host environment: the MCP server may resolve different `ASK_CODEX_MODEL` or `ASK_CODEX_REASONING_EFFORT` values. Reject absolute, `..`, and `~` include paths; cap at 32. Build a bounded context manifest (20 KB/file, 100 KB/request) from task requirements, relevant project instructions, changed files, and tests. Do not send secrets or unrelated files.
+3. Before the first provider call, show host=`Cursor Agent`, reviewer provider=`codex`, selected transport=`ask-codex` or unified `ask-llm`, exact user-supplied model, exact user-supplied reasoning effort, include directories, read-only behavior, data/quota boundary, and fresh persisted-session intent. Ask for explicit confirmation using Cursor's normal conversational approval surface. Refusal ends `cancelled` with no provider call.
+4. First call exactly one of these protocol shapes, substituting the already disclosed explicit choices:
+   ```json
+   [
+     {
+       "tool": "ask-codex",
+       "arguments": {
+         "prompt": "<bounded reviewer prompt>",
+         "model": "<required exact ID>",
+         "reasoningEffort": "<required effort>",
+         "includeDirs": ["<validated relative directory>"],
+         "sessionId": "",
+         "sandbox": "read-only"
+       }
+     },
+     {
+       "tool": "ask-llm",
+       "arguments": {
+         "provider": "codex",
+         "prompt": "<bounded reviewer prompt>",
+         "model": "<required exact ID>",
+         "reasoningEffort": "<required effort>",
+         "includeDirs": ["<validated relative directory>"],
+         "sessionId": ""
+       }
+     }
+   ]
+   ```
+   The prompt assigns Codex the independent reviewer role and requests actionable severity/file/line evidence. Capture the returned structured `sessionId`/Thread ID and actual model. Relay feedback before changing code; verify every finding against source and label it accepted, rejected, or deferred.
+5. At meaningful checkpoints, call the same tool with the captured `sessionId`, same model/effort, and bounded delta. On `ask-codex`, keep `sandbox: "read-only"`; unified `ask-llm` has no sandbox input and is read-only by default, so do not send an unsupported sandbox field. Omit `includeDirs` on resumed calls because `codex exec resume` does not support them (every Codex transport — split `ask-codex`, unified `ask-llm`, and Pi — rejects that combination at the shared executor instead of dropping the directories); never silently strip them from the first call. If no session ID was returned, stop with a session diagnostic instead of pretending continuity.
+6. A Cursor interrupt cancels the MCP request. Report `cancelled` and never retry another tool/model/provider. Preserve earlier feedback on later failure and report `failed (partial)`. On success report `completed` with host, provider, requested/actual model, effort, session reuse count, context/include directories, accepted/rejected/deferred actions, and any reported Codex quota fallback. Never conceal fallback or rewrite a model.
+
 <!-- HOST-ADAPTER:CLAUDE-CODE:START -->
 ### Claude Code adapter
 

package/skills/gemini-review/SKILL.md

@@ -6,7 +6,7 @@ description: Get a second opinion from Gemini on your current code changes. Anal
 <!-- PORTABLE-CONTRACT:START -->
 ## Portable contract
 
-Gather the relevant staged, unstaged, and untracked code changes; build a bounded context brief; request a Gemini review; verify each reported finding against source; and return only prioritized, source-supported findings. Preserve provider fallback, timeout, and explicit failure disclosure.
+Gather the relevant staged, unstaged, and untracked code changes; build a bounded context brief; request a Gemini review; verify each reported finding against source; and return only prioritized, source-supported findings. Preserve the canonical `gemini-3.1-pro-preview` → `gemini-3.8-flash` quota fallback, timeout, and explicit failure disclosure.
 <!-- PORTABLE-CONTRACT:END -->
 
 ## Host adapters

package/skills/grok-pair/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: grok-pair
+description: Pair with Grok as an explicit independent reviewer while the host edits. Use when the user asks for /grok-pair, Grok pair programming, iterative Grok feedback, or Grok through Cursor Agent. Selects one exact route/model with consent and never falls back.
+---
+
+<!-- PORTABLE-CONTRACT:START -->
+## Portable contract
+
+Apply `../pairing-contract.md`. The host is the editor and Grok is the explicit read-only reviewer. Share bounded context only after consent, relay and verify actionable feedback at checkpoints, preserve exact route/model attribution, reuse a returned Cursor session where supported, propagate cancellation, and terminate clearly without silent provider, harness, or model fallback.
+<!-- PORTABLE-CONTRACT:END -->
+
+## Host adapters
+
+### Cursor Agent adapter
+
+When Cursor itself hosts this skill, do not recursively launch `ask-cursor-agent`. Offer only the explicit direct routes (`xai-api` or `grok-cli`) through an exact `ask-grok` leaf or a fully pinned unified `ask-llm` leaf, and follow the same consent and no-fallback contract. The Cursor plugin bundle registers only the unified `ask-llm` server; a separately user-installed `grok` entry (`@ask-llm/grok-mcp`) exposes the deterministic `ask-grok` leaf and is preferred when exposed. A unified call must specify `provider: "grok"`, exact `harness`, exact `model`, and `reasoningEffort`; direct Grok is one-shot and does not accept include directories or sessions.
+
+If neither leaf is exposed, stop and give this Cursor-native setup (never `claude mcp add`):
+
+```json
+{"mcpServers":{"ask-llm":{"command":"npx","args":["-y","@ask-llm/mcp"]}}}
+```
+
+Save it as project `.cursor/mcp.json` or user `~/.cursor/mcp.json`. For `xai-api`, ensure `XAI_API_KEY` is present in the MCP server process environment; keep any literal secret in the user-level config and never commit it. For `grok-cli`, install/authenticate Grok Build and verify `grok --help` advertises headless JSON support. Reload the server from **Cursor Settings → Tools & MCP** or restart Cursor Agent, verify that `ask-llm` is exposed, then invoke `/grok-pair` again. The split alternative is the same entry named `grok` with package `@ask-llm/grok-mcp`, which exposes `ask-grok`; keep one registration per server and do not configure both merely to create fallback.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:START -->
+### Claude Code adapter
+
+# `/grok-pair`
+
+Run an iterative pair-programming session in which Claude remains the sole editor and Grok is the independent reviewer.
+
+## 1. Parse and lock the route
+
+Accept optional command text in this form (ask for any missing choice):
+
+```text
+/grok-pair route=cursor-agent model=cursor-grok-4.6-high include=packages/api,packages/shared <task>
+/grok-pair route=xai-api model=grok-4.6 effort=xhigh <task>
+/grok-pair route=grok-cli model=grok-build effort=high <task>
+```
+
+Supported routes:
+
+1. `cursor-agent` — preferred **only when** an `ask-cursor-agent` MCP tool is actually exposed and the user supplies an exact Grok-family ID from `agent --list-models`. Use `provider: "grok"`; never use Auto. Reasoning effort remains part of the exact Cursor catalog ID, not a separate generic option.
+2. `xai-api` — call `ask-grok` with `harness: "xai-api"`, exact model, and explicit `reasoningEffort`. Requires `XAI_API_KEY`; metered xAI API pricing is separate from consumer subscriptions.
+3. `grok-cli` — call `ask-grok` with `harness: "grok-cli"`, an exact ID from `grok models`, and explicit `reasoningEffort`. Uses the authenticated official Grok Build plan.
+
+Inspect the current tool surface by leaf capability. The Claude plugin bundles only Codex; Cursor and Grok tools come from user-scoped registrations such as `mcp__ask-llm__ask-cursor-agent`, `mcp__ask-llm__ask-llm`, or `mcp__grok__ask-grok`, so match on the `__ask-cursor-agent`, `__ask-grok`, or `__ask-llm` leaf and never on one assumed prefix. When no `ask-grok` leaf exists but the unified `ask-llm` leaf does, a direct route may use `ask-llm({ provider: "grok", harness, model, reasoningEffort, prompt })` only with every one of those fields pinned explicitly; the unified schema rejects unsupported combinations instead of stripping them. An unpinned generic call or a raw CLI never replaces a missing selected tool.
+
+If both Cursor and direct tools exist and no route was given, recommend Cursor Agent and show the direct alternatives, then use `AskUserQuestion` to obtain an explicit selection. Once selected, route/model/effort are immutable. A failure is terminal for that route.
+
+## 2. Bound context and obtain consent
+
+Read `../pairing-contract.md`. Determine the task, changed files, project instructions, tests, and requested relative include directories. Reject absolute, `..`, and `~` paths and cap the list at 32. Prepare a context manifest before reading extra directories:
+
+```text
+Host: Claude Code
+Reviewer provider: grok
+Harness: cursor-agent | xai-api | grok-cli
+Requested model: <exact ID>
+Reported model: pending
+Reasoning: <exact Cursor model ID carries tier | low|medium|high|xhigh>
+Shared context: <files/directories and byte bounds>
+Session: fresh resumable Cursor conversation | one-shot
+Cost/credential boundary: <Cursor plan/spend | xAI API | Grok Build plan>
+```
+
+Use `AskUserQuestion` with **Start pairing** and **Cancel**. Do not invoke a tool or widen filesystem reads on refusal. For direct API/CLI routes, `includeDirs` is unsupported: offer to inline bounded excerpts or omit them; never silently discard the request.
+
+## 3. First reviewer checkpoint
+
+Build a prompt under 100 KB containing the reviewer role, task/acceptance criteria, relevant project invariants, bounded diff/excerpts, tests already run, and focused questions. Require concise findings with severity, file/line evidence, consequence, and a proposed next action; require `NO CONCERNS` when appropriate.
+
+Call exactly one selected tool:
+
+- Cursor: `ask-cursor-agent({ provider: "grok", model, prompt, includeDirs })`.
+- Direct: `ask-grok({ harness, model, reasoningEffort, prompt })`, or the fully pinned `ask-llm({ provider: "grok", harness, model, reasoningEffort, prompt })` when only the unified tool is registered.
+
+For Cursor, capture `sessionId`, exact `model`, `harness`, and optional `reportedModel` from structured output. Treat a cross-provider label, a requested Auto/noncanonical ID, a changed exact model, or an absent final result as failure. If an unclassifiable display label such as `Auto` is merely reported, preserve it separately and flag the uncertainty; do not guess that it replaced the exact requested ID. Direct Grok transports are one-shot and return no session.
+
+## 4. Relay, act, and re-check
+
+Relay Grok's feedback before editing. Verify each finding against source and label it accepted, rejected, or deferred with reason. Claude makes the edits. At meaningful checkpoints, send only the bounded delta plus outcomes of prior findings:
+
+- Cursor route: reuse the returned `sessionId`, preserving the same provider/model and include directories.
+- Direct route: make a new one-shot call through the same harness/model/effort and disclose that continuity comes from the bounded recap, not a provider session.
+
+Do not hide partial success. If checkpoint 1 succeeded and checkpoint 2 fails, retain checkpoint 1's feedback and report `failed (partial)` with the failed stage.
+
+## 5. Cancellation and final report
+
+If the user cancels or interrupts, stop the in-flight MCP call and report `cancelled`; never retry another route. On completion report:
+
+```text
+grok-pair completed | cancelled | failed | failed (partial)
+Host / provider / harness: Claude Code / grok / <route>
+Requested model: <exact ID>
+Reported model: <label or not reported>
+Reasoning: <explicit effort semantics>
+Session: <ID reused N times | one-shot>
+Context shared: <bounded files/include dirs>
+Accepted / rejected / deferred findings: <counts and actions>
+Fallback: none
+```
+
+## Setup failures
+
+Give guidance for the selected route only:
+
+- Missing Cursor tool: `claude mcp add --scope user ask-llm -- npx -y @ask-llm/mcp` (exposes `ask-cursor-agent` and the unified `ask-llm` tool); authenticate `agent`, run `agent --list-models`, and restart Claude Code.
+- Missing direct tool: `claude mcp add --scope user grok -- npx -y @ask-llm/grok-mcp` for the `ask-grok` leaf, or the same `@ask-llm/mcp` registration for the fully pinned unified form, then restart.
+- Cursor unavailable/trust/model errors: follow the returned `agent --version`, explicit workspace trust, or `agent --list-models` guidance. Never pass `--trust` automatically.
+- xAI/API or Grok CLI auth/model/quota errors: preserve the redacted diagnostic and state that no fallback was attempted.
+<!-- HOST-ADAPTER:CLAUDE-CODE:END -->

package/skills/pairing-contract.md

@@ -0,0 +1,40 @@
+# Portable pair-programming contract
+
+This contract is shared by `/codex-pair` on Cursor Agent and `/grok-pair` on Claude Code. Host adapters may use different registration and lifecycle APIs, but must preserve these guarantees.
+
+## Roles and lifecycle
+
+The host remains the only editor. The consulted model is an explicit, read-only reviewer that challenges correctness, tests assumptions, and returns actionable findings. Run one state machine:
+
+`idle -> consented -> active -> completed | cancelled | failed`
+
+Before `active`, resolve and show the user the provider, harness, exact requested model, reasoning effort, directories/files to be shared, credential/cost boundary, and whether a resumable provider session will be created. If the host cannot read the provider process's configured model and effort deterministically, require the user to supply both rather than inferring defaults that may differ across environments. Missing choices stop before extra context reads, consent, or provider invocation. Refusal returns `cancelled` without creating a marker, reading extra directories, or invoking a provider.
+
+During `active`, relay each reviewer response before acting on it, verify findings against source, state accepted/rejected/deferred actions, and send only the bounded delta needed for the next checkpoint. The user or host interrupt cancels the in-flight MCP call; do not retry it under another tool, harness, model, or provider. End with one explicit `completed`, `cancelled`, or `failed` report.
+
+## Bounded context and include directories
+
+Default bounds are 20 KB per file and 100 KB per provider request. Prefer diffs, task requirements, project instructions, relevant tests, and narrow excerpts over whole repositories. Never send secrets, credential files, unrelated untracked files, or ignored paths.
+
+Additional directories must be explicit relative workspace paths: no absolute paths, `..`, or `~`; at most 32. Pass `includeDirs` only to a tool that supports it. If a selected route cannot expose extra directories, say so and ask whether to inline bounded excerpts or continue without them. Never silently drop a requested directory.
+
+## Transport, options, and attribution
+
+Select one route before the first call and keep it immutable for the run. Resolve tools by their exact leaf capability (`ask-codex`, `ask-grok`, or `ask-cursor-agent`), not by assuming a Claude plugin namespace. The unified `ask-llm` tool is an acceptable transport only when the call pins provider, harness where applicable, exact model, reasoning effort, include directories, and session explicitly and its schema rejects unsupported combinations rather than stripping them; it is never an unpinned generic call and never a fallback for a failed split tool. A missing tool is a setup failure, never permission to use a generic call.
+
+Every call and final report must keep these separate:
+
+- host harness;
+- provider;
+- execution harness/transport;
+- exact requested model ID;
+- provider-native reasoning effort (or, for Cursor catalogs, the exact effort-bearing model ID);
+- optional upstream display label (`reportedModel`).
+
+Never choose Cursor Auto, rewrite a model ID, suppress a requested option, or claim fallback when none occurred. Any cross-provider reported label is terminal.
+
+## Sessions, partial failure, and diagnostics
+
+Create and reuse a provider session only when the selected tool returns a session ID. Capture the ID from structured output, never scrape prose. On resumed Codex calls, omit `includeDirs` because `codex exec resume` does not support them; the initial call must establish that context. One-shot transports receive bounded deltas and are reported as one-shot.
+
+Preserve successful feedback if a later checkpoint fails, label the run `failed (partial)`, and report the failed checkpoint. Distinguish tool missing, provider unavailable, authentication, model unavailable, quota/spend, trust, timeout, cancellation, malformed output, and cross-provider substitution. Include exact setup guidance for the selected route and explicitly say that no fallback was attempted.