Grok

grok — independent Grok review (expand + plan + code)

A universal, on-demand wrapper around the grok CLI that gives you an independent, web-enabled second opinion on your work. It is project-agnostic — it works in any directory, git repo or not — and not tied to any particular workflow. Invoke it directly when the user asks for a Grok review, or programmatically from another skill (e.g. gsd runs it at its plan-expansion and code checkpoints).

What makes Grok a different set of eyes: it has live web search/fetch. Point it at a plan or a diff and it can check current library versions, deprecations, CVEs, and best-practice shifts that a sandboxed, offline reviewer cannot. Lean on that — this skill is most valuable where outside, current knowledge matters.

Grok is advisory, never blocking. Every call is best-effort: if the grok CLI is missing, out of quota, or times out, the script prints a note and exits 0 — you report "Grok review skipped" and continue. Grok never gates completion. Treat its output as a strong outside opinion: adopt what's valid, briefly note what you reject with a reason, move on.

The driver is the grok.sh bundled with this skill — installed as a plugin it lives at ${CLAUDE_PLUGIN_ROOT}/grok.sh; copied as a plain skill folder, at <skill-dir>/grok.sh. It has three modes, expand, plan, and code. The examples below write grok.sh for brevity — substitute the bundled path. <root> = the project directory Grok is allowed to read.

Requirements: the grok CLI on PATH, authenticated (browser/session or XAI_API_KEY) with available quota. The driver runs Grok read-only on the filesystem (only read_file, grep, list_dir) but web-enabled (web_search, web_fetch), auto-approving tool calls so it never hangs headless. It uses model grok-4.5 by default; override with GROK_REVIEW_MODEL=<id> (see grok models) and reasoning with GROK_REVIEW_EFFORT (default high). Output is parsed from --output-format json via jq, falling back to plain when jq is absent. The input handed to Grok is capped at ~120k chars, but Grok has read access to the whole project and is told it may open full files.

---

Mode 1 — Expand (broaden a plan before code is written)

Grok's signature mode. Have Grok broaden a design/plan with web-informed proposals, rather than grade it. Output: PROPOSALS: <n> (or PROPOSALS: NONE) then a numbered list, each item tagged [missing-scope | alt-approach | external-risk | edge-case].

# Explicit plan file(s):
grok.sh expand <root> path/to/PLAN.md [more-plan-files...]

# Or, with no files given, auto-discover GSD plan artifacts under <root>/.gsd/
# (RESEARCH.md, REQUIREMENTS.md, ROADMAP.md, FORKS.md, S*-PLAN.md):
grok.sh expand <root>

Act on the proposals: for each, decide if it's a real gap. Fold the valid ones into the plan; where a proposal implies a genuine design choice, route it through your normal decision/fork flow rather than silently adopting it; briefly record anything you reject with a reason. This is additive — there is no pass/fail verdict.

---

Mode 2 — Plan review (evaluative, before code is written)

Have Grok critique a design/plan for weak points, the same shape as a codex-style plan review — useful standalone when you want Grok as the evaluator. Verdict: VERDICT: SOLID or VERDICT: WEAKNESSES + a numbered list.

grok.sh plan <root> [path/to/PLAN.md ...]   # same auto-discovery as expand

Act on the verdict: SOLID → note it and proceed. WEAKNESSES → apply the valid points to the plan, briefly record anything you deliberately reject. Re-run at most once; don't loop.

In a two-reviewer setup (e.g. gsd with both grok and codex), use expand for Grok and let the other reviewer own the plan critique — that avoids two overlapping critiques and puts Grok's web reach where it pays. Use plan when Grok is the only reviewer.

---

Mode 3 — Code review (after a round of changes)

Have Grok review a diff against the instruction it was meant to satisfy, with the lens tilted to security, dependency currency (web-checked), and a fresh correctness read. Verdict: VERDICT: APPROVE or VERDICT: COMMENTS + a numbered list.

1. Assemble the changed-file list (newline-separated absolute paths). Any accurate source works:

   # From git — changed tracked files AND new untracked ones, as absolute paths
   # (plain `git diff --name-only` alone would miss newly-created files):
   { git -C <root> diff --name-only; git -C <root> ls-files --others --exclude-standard; } \
     | sed "s#^#<root>/#" | sort -u > /tmp/grok-files.txt
   # For an already-committed range (e.g. a whole feature branch — pair with GROK_DIFF_BASE):
   #   git -C <root> diff --name-only <base>..HEAD | sed "s#^#<root>/#" > /tmp/grok-files.txt
   

2. Write the instruction the diff must satisfy (the user's request, a slice goal, the success criteria — the verdict is judged against it):

   printf '%s\n' "<the instruction / goal for this round>" > /tmp/grok-instr.md
   

3. Run the review:

   grok.sh code <root> /tmp/grok-instr.md /tmp/grok-files.txt
   

   • Non-git projects work out of the box (new files are diffed against /dev/null).
   • To review already-committed changes (where git diff HEAD is empty), set the base:

     GROK_DIFF_BASE=<base-commit-or-branch> \
       grok.sh code <root> /tmp/grok-instr.md /tmp/grok-files.txt
     

4. Act on the verdict: APPROVE → done. COMMENTS → treat each numbered item: fix what's valid, note anything you disagree with and why, then optionally re-run. Grok reviews only code/doc content, not repo hygiene or version-control practices.

---

Notes

• Out-of-quota / timeout / exec errors print to stderr and yield no verdict — the same non-blocking behavior in every mode. Report "review skipped" and continue.
• Web access is the point of using Grok — it stays on (web_search/web_fetch allowed). If you need a strictly offline review, that's a job for a sandboxed reviewer, not this.
• For diff-based code review in a git repo, prefer running git init early on greenfield projects so tracked-file diffs are available; non-git still works via --no-index.
• Pairs well with a second reviewer: run Grok's expand/code alongside another reviewer's critique and merge the findings, deduping where they overlap.