Skip to content

Commit eb53fe6

Browse files
ljodealjodea
committed
feat: add /grok skill for xAI second opinion from Claude Code
Symmetric counterpart to /codex: review (pass/fail on [P1]), adversarial challenge, and consult with session resume. Runs read-only via --permission-mode plan with bin/gstack-grok-probe for auth, timeout, and telemetry. Default headless model: grok-4.5. Also wires a grok-review row into GSTACK REVIEW REPORT, documents the skill in AGENTS.md / docs/skills.md / README, and skips /grok on non-Claude hosts (same convention as /codex). Unit tests cover the probe and host-exclusion. VERSION 1.62.0.0 (avoids open title claim on 1.61.0.0). Supersedes #2016.
1 parent 7c9df1c commit eb53fe6

37 files changed

Lines changed: 2226 additions & 57 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Invoke them by name (e.g., `/office-hours`).
2929
|-------|-------------|
3030
| `/review` | Pre-landing PR review. Finds bugs that pass CI but break in prod. |
3131
| `/codex` | Second opinion via OpenAI Codex. Review, challenge, or consult modes. |
32+
| `/grok` | Second opinion via xAI Grok. Review, challenge, or consult modes. |
3233
| `/investigate` | Systematic root-cause debugging. No fixes without investigation. |
3334
| `/design-review` | Live-site visual audit + fix loop with atomic commits. |
3435
| `/design-shotgun` | Generate multiple AI design variants, comparison board, iterate. |

‎CHANGELOG.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,43 @@
11
# Changelog
22

3+
## [1.62.0.0] - 2026-07-11
4+
5+
## **`/grok` is the symmetric counterpart to `/codex`.**
6+
## **Independent review, challenge, or consult from xAI Grok Build CLI.**
7+
8+
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`).
9+
10+
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.
11+
12+
### The numbers that matter
13+
14+
Source: local free suite after port (`bun test test/grok-hardening.test.ts` + skill-validation / gen-skill-docs).
15+
16+
| Metric | Value |
17+
|--------|-------|
18+
| Probe unit tests | 10/10 pass |
19+
| Default headless model | `grok-4.5` (`-m`, overridable) |
20+
| Hosts that skip `/grok` generation | all non-Claude hosts (parity with `/codex`) |
21+
22+
### What this means for you
23+
24+
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).
25+
26+
### Itemized changes
27+
28+
#### Added
29+
30+
- `grok/SKILL.md.tmpl` + generated `grok/SKILL.md` — three-mode outside-voice skill
31+
- `bin/gstack-grok-probe` — auth probe, timeout wrapper, telemetry, hang learning
32+
- `test/grok-hardening.test.ts` — probe + invocation-contract invariants
33+
- GSTACK REVIEW REPORT `grok-review` row and field docs in `scripts/resolvers/review.ts`
34+
- Docs inventory: `AGENTS.md`, `docs/skills.md`, `README.md`, `CLAUDE.md`, `gstack/llms.txt`
35+
- `scripts/proactive-suggestions.json` routing entry for `/grok`
36+
37+
#### Changed
38+
39+
- Non-Claude hosts: `skipSkills` includes `grok` alongside `codex` so generated host output never ships Claude-path `/grok` wrappers
40+
341
## [1.60.1.0] - 2026-07-09
442

543
## **The /autoplan dual-voice eval is back on the board, catching real regressions.**

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ gstack/
123123
├── benchmark/ # /benchmark skill (performance regression detection)
124124
├── canary/ # /canary skill (post-deploy monitoring loop)
125125
├── codex/ # /codex skill (multi-AI second opinion via OpenAI Codex CLI)
126+
├── grok/ # /grok skill (multi-AI second opinion via Grok Build CLI)
126127
├── land-and-deploy/ # /land-and-deploy skill (merge → deploy → canary verify)
127128
├── office-hours/ # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm)
128129
├── investigate/ # /investigate skill (systematic root-cause debugging)

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
223223
| Skill | What it does |
224224
|-------|-------------|
225225
| `/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. |
226+
| `/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. |
226227
| `/careful` | **Safety Guardrails** — warns before destructive commands (rm -rf, DROP TABLE, force-push). Say "be careful" to activate. Override any warning. |
227228
| `/freeze` | **Edit Lock** — restrict file edits to one directory. Prevents accidental changes outside scope while debugging. |
228229
| `/guard` | **Full Safety** — `/careful` + `/freeze` in one command. Maximum safety for prod work. |

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.60.1.0
1+
1.62.0.0

‎bin/gstack-grok-probe‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
#!/usr/bin/env bash
2+
# gstack-grok-probe: shared helper for /grok skills.
3+
# Sourced from template bash blocks; never execute directly.
4+
#
5+
# Functions (all prefixed with _gstack_grok_ for namespace hygiene):
6+
# _gstack_grok_auth_probe — multi-signal auth check (env + file)
7+
# _gstack_grok_version_check — emit installed Grok CLI version (non-blocking)
8+
# _gstack_grok_timeout_wrapper — gtimeout -> timeout -> unwrapped fallback
9+
# _gstack_grok_log_event — telemetry emission to ~/.gstack/analytics/
10+
#
11+
# Hygiene rules (enforced by test/grok-hardening.test.ts):
12+
# - Never set -e / set -u / trap / IFS= / PATH= in this file.
13+
# - All internal vars prefix with _GSTACK_GROK_.
14+
# - All functions prefix with _gstack_grok_.
15+
# - No command execution at source time (only function defs).
16+
17+
# --- Auth probe -------------------------------------------------------------
18+
19+
_gstack_grok_auth_probe() {
20+
# Multi-signal: env vars OR auth file. Avoids false negatives for env-auth
21+
# users (CI, platform engineers) that a file-only check would reject.
22+
local _grok_home="${GROK_HOME:-$HOME/.grok}"
23+
local _k1 _k2
24+
_k1=$(printf '%s' "${XAI_API_KEY:-}" | tr -d '[:space:]')
25+
_k2=$(printf '%s' "${GROK_API_KEY:-}" | tr -d '[:space:]')
26+
if [ -n "$_k1" ] || [ -n "$_k2" ] || [ -f "$_grok_home/auth.json" ]; then
27+
echo "AUTH_OK"
28+
return 0
29+
fi
30+
echo "AUTH_FAILED"
31+
return 1
32+
}
33+
34+
# --- Version check ----------------------------------------------------------
35+
36+
_gstack_grok_version_check() {
37+
local _ver
38+
_ver=$(grok --version 2>/dev/null | head -1)
39+
[ -z "$_ver" ] && return 0
40+
echo "GROK_VERSION: $_ver"
41+
}
42+
43+
# --- Timeout wrapper --------------------------------------------------------
44+
45+
_gstack_grok_timeout_wrapper() {
46+
local _duration="$1"
47+
shift
48+
local _to
49+
_to=$(command -v gtimeout 2>/dev/null || command -v timeout 2>/dev/null || echo "")
50+
if [ -n "$_to" ]; then
51+
"$_to" "$_duration" "$@"
52+
else
53+
"$@"
54+
fi
55+
}
56+
57+
# --- Telemetry event --------------------------------------------------------
58+
59+
_gstack_grok_log_event() {
60+
local _event="$1"
61+
local _duration="${2:-0}"
62+
[ "${_TEL:-off}" = "off" ] && return 0
63+
mkdir -p "$HOME/.gstack/analytics" 2>/dev/null || return 0
64+
local _ts
65+
_ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)
66+
printf '{"skill":"grok","event":"%s","duration_s":"%s","ts":"%s"}\n' \
67+
"$_event" "$_duration" "$_ts" \
68+
>> "$HOME/.gstack/analytics/skill-usage.jsonl" 2>/dev/null || true
69+
}
70+
71+
# --- Learnings log on hang --------------------------------------------------
72+
73+
_gstack_grok_log_hang() {
74+
local _mode="${1:-unknown}"
75+
local _prompt_size="${2:-0}"
76+
local _log_bin="$HOME/.claude/skills/gstack/bin/gstack-learnings-log"
77+
[ -x "$_log_bin" ] || return 0
78+
local _key="grok-hang-$(date +%s 2>/dev/null || echo unknown)"
79+
"$_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")" \
80+
>/dev/null 2>&1 || true
81+
}

‎codex/SKILL.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1135,6 +1135,8 @@ Parse each JSONL entry. Each skill logs different fields:
11351135
→ Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
11361136
- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
11371137
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
1138+
- **grok-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
1139+
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
11381140

11391141
All fields needed for the Findings column are now present in the JSONL entries.
11401142
For the review you just completed, you may use richer details from your own Completion
@@ -1148,17 +1150,19 @@ Produce this markdown table:
11481150
| Review | Trigger | Why | Runs | Status | Findings |
11491151
|--------|---------|-----|------|--------|----------|
11501152
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
1151-
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
1153+
| Codex Review | \`/codex review\` | Independent 2nd opinion (OpenAI) | {runs} | {status} | {findings} |
1154+
| Grok Review | \`/grok review\` | Independent 2nd opinion (xAI) | {runs} | {status} | {findings} |
11521155
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
11531156
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
11541157
| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
11551158
\`\`\`
11561159

1157-
Below the table, add these lines. **CODEX** and **CROSS-MODEL** are optional (omit when
1158-
empty); **VERDICT** is always present:
1160+
Below the table, add these lines. **CODEX**, **GROK**, and **CROSS-MODEL** are optional
1161+
(omit when empty); **VERDICT** is always present:
11591162

11601163
- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
1161-
- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
1164+
- **GROK:** (only if grok-review ran) — one-line summary of grok fixes
1165+
- **CROSS-MODEL:** (only if two or more outside-voice reviews exist) — overlap analysis
11621166
- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
11631167
If Eng Review is not CLEAR and not skipped globally, append "eng review required".
11641168

‎devex-review/SKILL.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1127,7 +1127,7 @@ After completing the review, read the review log and config to display the dashb
11271127
~/.claude/skills/gstack/bin/gstack-review-read
11281128
```
11291129

1130-
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.
1130+
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.
11311131

11321132
**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.
11331133

@@ -1199,6 +1199,8 @@ Parse each JSONL entry. Each skill logs different fields:
11991199
→ Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
12001200
- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
12011201
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
1202+
- **grok-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
1203+
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
12021204

12031205
All fields needed for the Findings column are now present in the JSONL entries.
12041206
For the review you just completed, you may use richer details from your own Completion
@@ -1212,17 +1214,19 @@ Produce this markdown table:
12121214
| Review | Trigger | Why | Runs | Status | Findings |
12131215
|--------|---------|-----|------|--------|----------|
12141216
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
1215-
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
1217+
| Codex Review | \`/codex review\` | Independent 2nd opinion (OpenAI) | {runs} | {status} | {findings} |
1218+
| Grok Review | \`/grok review\` | Independent 2nd opinion (xAI) | {runs} | {status} | {findings} |
12161219
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
12171220
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
12181221
| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
12191222
\`\`\`
12201223

1221-
Below the table, add these lines. **CODEX** and **CROSS-MODEL** are optional (omit when
1222-
empty); **VERDICT** is always present:
1224+
Below the table, add these lines. **CODEX**, **GROK**, and **CROSS-MODEL** are optional
1225+
(omit when empty); **VERDICT** is always present:
12231226

12241227
- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
1225-
- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
1228+
- **GROK:** (only if grok-review ran) — one-line summary of grok fixes
1229+
- **CROSS-MODEL:** (only if two or more outside-voice reviews exist) — overlap analysis
12261230
- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
12271231
If Eng Review is not CLEAR and not skipped globally, append "eng review required".
12281232

‎docs/skills.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
4343
| | | |
4444
| **Multi-AI** | | |
4545
| [`/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. |
46+
| [`/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. |
4647
| [`/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. |
4748
| [`/setup-gbrain`](#setup-gbrain) | **Memory Sync** | Set up gbrain for cross-machine session memory sync. One command from zero to live. |
4849
| [`/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...
10561057

10571058
---
10581059

1060+
1061+
## `/grok`
1062+
1063+
This is the **xAI second opinion** — the symmetric counterpart to `/codex`.
1064+
1065+
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`.
1066+
1067+
Requires `grok` on PATH and auth via `grok login` or `$XAI_API_KEY`. Install: Grok Build CLI from xAI.
1068+
1069+
```
1070+
You: /grok review
1071+
1072+
Claude: Running independent Grok review...
1073+
1074+
GROK SAYS (code review):
1075+
GATE: PASS
1076+
[P2] Missing timeout on outbound HTTP client — hung requests block worker pool
1077+
1078+
Cross-model analysis (vs /codex review):
1079+
UNIQUE TO GROK: HTTP client timeout
1080+
UNIQUE TO CODEX: race in session cleanup
1081+
```
1082+
1083+
---
1084+
10591085
## Safety & Guardrails
10601086

10611087
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.

0 commit comments

Comments
 (0)