garrytan · ljodea · Jul 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -29,6 +29,7 @@ Invoke them by name (e.g., `/office-hours`).
 |-------|-------------|
 | `/review` | Pre-landing PR review. Finds bugs that pass CI but break in prod. |
 | `/codex` | Second opinion via OpenAI Codex. Review, challenge, or consult modes. |
+| `/grok` | Second opinion via xAI Grok. Review, challenge, or consult modes. |
 | `/investigate` | Systematic root-cause debugging. No fixes without investigation. |
 | `/design-review` | Live-site visual audit + fix loop with atomic commits. |
 | `/design-shotgun` | Generate multiple AI design variants, comparison board, iterate. |

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,43 @@
 # Changelog
 
+## [1.62.0.0] - 2026-07-11
+
+## **`/grok` is the symmetric counterpart to `/codex`.**
+## **Independent review, challenge, or consult from xAI Grok Build CLI.**
+
+Cross-model second opinion was a single provider. When you wanted a genuinely different model family than Claude or Codex, you had no first-class skill. `/grok` adds that voice with the same three-mode contract as `/codex`: **review** (diff-scoped `[P1]`/`[P2]` findings with a pass/fail gate), **challenge** (adversarial failure-mode hunt), and **consult** (open Q&A with session resume via `-r`/`-c`). Runs read-only via `--permission-mode plan`. Auth and hang protection live in `bin/gstack-grok-probe` (`~/.grok/auth.json` or `$XAI_API_KEY` / `$GROK_API_KEY`).
+
+The plan-file GSTACK REVIEW REPORT gains a `grok-review` row next to `codex-review`. External hosts (Codex, Cursor, Factory, etc.) skip generating `/grok` the same way they skip `/codex` — both are Claude-host wrappers around another CLI.
+
+### The numbers that matter
+
+Source: local free suite after port (`bun test test/grok-hardening.test.ts` + skill-validation / gen-skill-docs).
+
+| Metric | Value |
+|--------|-------|
+| Probe unit tests | 10/10 pass |
+| Default headless model | `grok-4.5` (`-m`, overridable) |
+| Hosts that skip `/grok` generation | all non-Claude hosts (parity with `/codex`) |
+
+### What this means for you
+
+After `./setup`, run `/grok review`, `/grok challenge security`, or `/grok Is this migration ordering safe?`. Requires `grok` on PATH and `grok login` or `$XAI_API_KEY`. Orthogonal to Grok-as-host work (#2028) and to the plan-review `llm` fallback chain (#1631).
+
+### Itemized changes
+
+#### Added
+
+- `grok/SKILL.md.tmpl` + generated `grok/SKILL.md` — three-mode outside-voice skill
+- `bin/gstack-grok-probe` — auth probe, timeout wrapper, telemetry, hang learning
+- `test/grok-hardening.test.ts` — probe + invocation-contract invariants
+- GSTACK REVIEW REPORT `grok-review` row and field docs in `scripts/resolvers/review.ts`
+- Docs inventory: `AGENTS.md`, `docs/skills.md`, `README.md`, `CLAUDE.md`, `gstack/llms.txt`
+- `scripts/proactive-suggestions.json` routing entry for `/grok`
+
+#### Changed
+
+- Non-Claude hosts: `skipSkills` includes `grok` alongside `codex` so generated host output never ships Claude-path `/grok` wrappers
+
 ## [1.60.1.0] - 2026-07-09
 
 ## **The /autoplan dual-voice eval is back on the board, catching real regressions.**

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -123,6 +123,7 @@ gstack/
 ├── benchmark/       # /benchmark skill (performance regression detection)
 ├── canary/          # /canary skill (post-deploy monitoring loop)
 ├── codex/           # /codex skill (multi-AI second opinion via OpenAI Codex CLI)
+├── grok/            # /grok skill (multi-AI second opinion via Grok Build CLI)
 ├── land-and-deploy/ # /land-and-deploy skill (merge → deploy → canary verify)
 ├── office-hours/    # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm)
 ├── investigate/     # /investigate skill (systematic root-cause debugging)

diff --git a/README.md b/README.md
@@ -223,6 +223,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
 | Skill | What it does |
 |-------|-------------|
 | `/codex` | **Second Opinion** — independent code review from OpenAI Codex CLI. Three modes: review (pass/fail gate), adversarial challenge, and open consultation. Cross-model analysis when both `/review` and `/codex` have run. |
+| `/grok` | **Second Opinion (xAI)** — independent code review from Grok Build CLI. Same three modes as `/codex` (review/challenge/consult) with read-only `--permission-mode plan`. Cross-model analysis when `/review`, `/codex`, and `/grok` have run. |
 | `/careful` | **Safety Guardrails** — warns before destructive commands (rm -rf, DROP TABLE, force-push). Say "be careful" to activate. Override any warning. |
 | `/freeze` | **Edit Lock** — restrict file edits to one directory. Prevents accidental changes outside scope while debugging. |
 | `/guard` | **Full Safety** — `/careful` + `/freeze` in one command. Maximum safety for prod work. |

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-1.60.1.0
+1.62.0.0
diff --git a/bin/gstack-grok-probe b/bin/gstack-grok-probe
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# gstack-grok-probe: shared helper for /grok skills.
+# Sourced from template bash blocks; never execute directly.
+#
+# Functions (all prefixed with _gstack_grok_ for namespace hygiene):
+#   _gstack_grok_auth_probe      — multi-signal auth check (env + file)
+#   _gstack_grok_version_check   — emit installed Grok CLI version (non-blocking)
+#   _gstack_grok_timeout_wrapper — gtimeout -> timeout -> unwrapped fallback
+#   _gstack_grok_log_event       — telemetry emission to ~/.gstack/analytics/
+#
+# Hygiene rules (enforced by test/grok-hardening.test.ts):
+#   - Never set -e / set -u / trap / IFS= / PATH= in this file.
+#   - All internal vars prefix with _GSTACK_GROK_.
+#   - All functions prefix with _gstack_grok_.
+#   - No command execution at source time (only function defs).
+
+# --- Auth probe -------------------------------------------------------------
+
+_gstack_grok_auth_probe() {
+  # Multi-signal: env vars OR auth file. Avoids false negatives for env-auth
+  # users (CI, platform engineers) that a file-only check would reject.
+  local _grok_home="${GROK_HOME:-$HOME/.grok}"
+  local _k1 _k2
+  _k1=$(printf '%s' "${XAI_API_KEY:-}" | tr -d '[:space:]')
+  _k2=$(printf '%s' "${GROK_API_KEY:-}" | tr -d '[:space:]')
+  if [ -n "$_k1" ] || [ -n "$_k2" ] || [ -f "$_grok_home/auth.json" ]; then
+    echo "AUTH_OK"
+    return 0
+  fi
+  echo "AUTH_FAILED"
+  return 1
+}
+
+# --- Version check ----------------------------------------------------------
+
+_gstack_grok_version_check() {
+  local _ver
+  _ver=$(grok --version 2>/dev/null | head -1)
+  [ -z "$_ver" ] && return 0
+  echo "GROK_VERSION: $_ver"
+}
+
+# --- Timeout wrapper --------------------------------------------------------
+
+_gstack_grok_timeout_wrapper() {
+  local _duration="$1"
+  shift
+  local _to
+  _to=$(command -v gtimeout 2>/dev/null || command -v timeout 2>/dev/null || echo "")
+  if [ -n "$_to" ]; then
+    "$_to" "$_duration" "$@"
+  else
+    "$@"
+  fi
+}
+
+# --- Telemetry event --------------------------------------------------------
+
+_gstack_grok_log_event() {
+  local _event="$1"
+  local _duration="${2:-0}"
+  [ "${_TEL:-off}" = "off" ] && return 0
+  mkdir -p "$HOME/.gstack/analytics" 2>/dev/null || return 0
+  local _ts
+  _ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)
+  printf '{"skill":"grok","event":"%s","duration_s":"%s","ts":"%s"}\n' \
+    "$_event" "$_duration" "$_ts" \
+    >> "$HOME/.gstack/analytics/skill-usage.jsonl" 2>/dev/null || true
+}
+
+# --- Learnings log on hang --------------------------------------------------
+
+_gstack_grok_log_hang() {
+  local _mode="${1:-unknown}"
+  local _prompt_size="${2:-0}"
+  local _log_bin="$HOME/.claude/skills/gstack/bin/gstack-learnings-log"
+  [ -x "$_log_bin" ] || return 0
+  local _key="grok-hang-$(date +%s 2>/dev/null || echo unknown)"
+  "$_log_bin" "$(printf '{"skill":"grok","type":"operational","key":"%s","insight":"Grok timed out during [%s] invocation. Prompt size: %s. Consider splitting prompt or checking network.","confidence":8,"source":"observed","files":["grok/SKILL.md.tmpl"]}' "$_key" "$_mode" "$_prompt_size")" \
+    >/dev/null 2>&1 || true
+}
diff --git a/codex/SKILL.md b/codex/SKILL.md
@@ -1135,6 +1135,8 @@ Parse each JSONL entry. Each skill logs different fields:
   → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
 - **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
   → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
+- **grok-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
+  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
 
 All fields needed for the Findings column are now present in the JSONL entries.
 For the review you just completed, you may use richer details from your own Completion
@@ -1148,17 +1150,19 @@ Produce this markdown table:
 | Review | Trigger | Why | Runs | Status | Findings |
 |--------|---------|-----|------|--------|----------|
 | CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
-| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
+| Codex Review | \`/codex review\` | Independent 2nd opinion (OpenAI) | {runs} | {status} | {findings} |
+| Grok Review | \`/grok review\` | Independent 2nd opinion (xAI) | {runs} | {status} | {findings} |
 | Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
 | Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
 | DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
 \`\`\`
 
-Below the table, add these lines. **CODEX** and **CROSS-MODEL** are optional (omit when
-empty); **VERDICT** is always present:
+Below the table, add these lines. **CODEX**, **GROK**, and **CROSS-MODEL** are optional
+(omit when empty); **VERDICT** is always present:
 
 - **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
-- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
+- **GROK:** (only if grok-review ran) — one-line summary of grok fixes
+- **CROSS-MODEL:** (only if two or more outside-voice reviews exist) — overlap analysis
 - **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
   If Eng Review is not CLEAR and not skipped globally, append "eng review required".
 

diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md
@@ -1127,7 +1127,7 @@ After completing the review, read the review log and config to display the dashb
 ~/.claude/skills/gstack/bin/gstack-review-read
 ```
 
-Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
+Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, grok-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
 
 **Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
 
@@ -1199,6 +1199,8 @@ Parse each JSONL entry. Each skill logs different fields:
   → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
 - **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
   → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
+- **grok-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
+  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
 
 All fields needed for the Findings column are now present in the JSONL entries.
 For the review you just completed, you may use richer details from your own Completion
@@ -1212,17 +1214,19 @@ Produce this markdown table:
 | Review | Trigger | Why | Runs | Status | Findings |
 |--------|---------|-----|------|--------|----------|
 | CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
-| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
+| Codex Review | \`/codex review\` | Independent 2nd opinion (OpenAI) | {runs} | {status} | {findings} |
+| Grok Review | \`/grok review\` | Independent 2nd opinion (xAI) | {runs} | {status} | {findings} |
 | Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
 | Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
 | DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
 \`\`\`
 
-Below the table, add these lines. **CODEX** and **CROSS-MODEL** are optional (omit when
-empty); **VERDICT** is always present:
+Below the table, add these lines. **CODEX**, **GROK**, and **CROSS-MODEL** are optional
+(omit when empty); **VERDICT** is always present:
 
 - **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
-- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
+- **GROK:** (only if grok-review ran) — one-line summary of grok fixes
+- **CROSS-MODEL:** (only if two or more outside-voice reviews exist) — overlap analysis
 - **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
   If Eng Review is not CLEAR and not skipped globally, append "eng review required".
 

diff --git a/docs/skills.md b/docs/skills.md
@@ -43,6 +43,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
 | | | |
 | **Multi-AI** | | |
 | [`/codex`](#codex) | **Second Opinion** | Independent review from OpenAI Codex CLI. Three modes: code review (pass/fail gate), adversarial challenge, and open consultation with session continuity. Cross-model analysis when both `/review` and `/codex` have run. |
+| [`/grok`](#grok) | **Second Opinion (xAI)** | Independent review from Grok Build CLI. Same three modes as `/codex` with read-only `--permission-mode plan`. Cross-model analysis when `/review`, `/codex`, and `/grok` have run. |
 | [`/pair-agent`](#pair-agent) | **Remote Agent Bridge** | Pair a remote AI agent (OpenClaw, Codex, Cursor, Hermes) with your browser. Scoped tunnel, locked allowlist, session token. |
 | [`/setup-gbrain`](#setup-gbrain) | **Memory Sync** | Set up gbrain for cross-machine session memory sync. One command from zero to live. |
 | [`/sync-gbrain`](#sync-gbrain) | **Keep Brain Current** | Refresh gbrain against this repo's code; teach the agent when to use `gbrain search`/`code-def` over Grep. Idempotent; safe to re-run. |
@@ -1056,6 +1057,31 @@ Claude: Running independent Codex review...
 
 ---
 
+
+## `/grok`
+
+This is the **xAI second opinion** — the symmetric counterpart to `/codex`.
+
+When you're in Claude Code and want a perspective from Grok (different training, different blind spots), `/grok` wraps the Grok Build CLI in read-only `--permission-mode plan` and runs the same three-mode contract as `/codex`: review (with `[P1]`/`[P2]` gate), adversarial challenge, and consult with session resume via `-r` / `-c`.
+
+Requires `grok` on PATH and auth via `grok login` or `$XAI_API_KEY`. Install: Grok Build CLI from xAI.
+
+```
+You:   /grok review
+
+Claude: Running independent Grok review...
+
+        GROK SAYS (code review):
+        GATE: PASS
+        [P2] Missing timeout on outbound HTTP client — hung requests block worker pool
+
+        Cross-model analysis (vs /codex review):
+        UNIQUE TO GROK: HTTP client timeout
+        UNIQUE TO CODEX: race in session cleanup
+```
+
+---
+
 ## Safety & Guardrails
 
 Four skills that add safety rails to any Claude Code session. They work via Claude Code's PreToolUse hooks — transparent, session-scoped, no configuration files.