From eef9fd91835ebd375cd8ae770876557394e68dd4 Mon Sep 17 00:00:00 2001 From: ljodea Date: Mon, 15 Jun 2026 09:36:52 -0500 Subject: [PATCH 1/4] feat: add /grok skill for xAI second opinion from Claude Code Mirror the /codex outside-voice contract for Grok Build CLI: review (pass/fail on [P1]), adversarial challenge, and consult with session resume. Runs read-only via --permission-mode plan with gstack-grok-probe for auth, timeout, and telemetry. Includes grok-review rows in the GSTACK REVIEW REPORT resolver, docs, and grok-hardening unit tests. --- CLAUDE.md | 1 + README.md | 1 + bin/gstack-grok-probe | 81 + codex/SKILL.md | 12 +- devex-review/SKILL.md | 14 +- docs/skills.md | 25 + grok/SKILL.md | 1309 +++++++++++++++++ grok/SKILL.md.tmpl | 416 ++++++ gstack/llms.txt | 1 + plan-ceo-review/sections/review-sections.md | 14 +- .../sections/review-sections.md | 14 +- plan-devex-review/sections/review-sections.md | 14 +- plan-eng-review/sections/review-sections.md | 14 +- scripts/proactive-suggestions.json | 5 + scripts/resolvers/review.ts | 14 +- ship/SKILL.md | 2 +- test/grok-hardening.test.ts | 177 +++ 17 files changed, 2079 insertions(+), 35 deletions(-) create mode 100755 bin/gstack-grok-probe create mode 100644 grok/SKILL.md create mode 100644 grok/SKILL.md.tmpl create mode 100644 test/grok-hardening.test.ts diff --git a/CLAUDE.md b/CLAUDE.md index 9848449020..4b20c28000 100644 --- 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 index 4bb177c3a7..de34a77ced 100644 --- 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/bin/gstack-grok-probe b/bin/gstack-grok-probe new file mode 100755 index 0000000000..5738073389 --- /dev/null +++ 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 +} \ No newline at end of file diff --git a/codex/SKILL.md b/codex/SKILL.md index cd40e075d9..1f2c648504 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -1106,6 +1106,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 @@ -1119,17 +1121,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 index 990755b500..a959759920 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -1098,7 +1098,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. @@ -1170,6 +1170,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 @@ -1183,17 +1185,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 index 8e8cb7adcc..0d51038e5b 100644 --- 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,30 @@ 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. diff --git a/grok/SKILL.md b/grok/SKILL.md new file mode 100644 index 0000000000..ef414ce3c8 --- /dev/null +++ b/grok/SKILL.md @@ -0,0 +1,1309 @@ +--- +name: grok +preamble-tier: 3 +version: 1.0.0 +description: Grok Build CLI wrapper — three modes. (gstack) +triggers: + - grok review + - grok challenge + - ask grok +allowed-tools: + - Bash + - Read + - Write + - Glob + - Grep + - AskUserQuestion +--- + + + + +## When to invoke this skill + +Code review: independent diff review via +grok headless with pass/fail gate. Challenge: adversarial mode that tries to break +your code. Consult: ask Grok anything with session continuity for follow-ups. +Cross-model second opinion from xAI. Use when asked to "grok review", +"grok challenge", "ask grok", "second opinion from grok", or "consult grok". + +Voice triggers (speech-to-text aliases): "rock review", "get grok opinion", "outside voice grok". + +## Preamble (run first) + +```bash +_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true) +[ -n "$_UPD" ] && echo "$_UPD" || true +mkdir -p ~/.gstack/sessions +touch ~/.gstack/sessions/"$PPID" +_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') +find ~/.gstack/sessions -mmin +120 -type f -exec rm {} + 2>/dev/null || true +_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true") +_PROACTIVE_PROMPTED=$([ -f ~/.gstack/.proactive-prompted ] && echo "yes" || echo "no") +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" +_SKILL_PREFIX=$(~/.claude/skills/gstack/bin/gstack-config get skill_prefix 2>/dev/null || echo "false") +echo "PROACTIVE: $_PROACTIVE" +echo "PROACTIVE_PROMPTED: $_PROACTIVE_PROMPTED" +echo "SKILL_PREFIX: $_SKILL_PREFIX" +source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true +REPO_MODE=${REPO_MODE:-unknown} +echo "REPO_MODE: $REPO_MODE" +_SESSION_KIND=$(~/.claude/skills/gstack/bin/gstack-session-kind 2>/dev/null || echo "interactive") +case "$_SESSION_KIND" in spawned|headless|interactive) ;; *) _SESSION_KIND="interactive" ;; esac +echo "SESSION_KIND: $_SESSION_KIND" +_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no") +echo "LAKE_INTRO: $_LAKE_SEEN" +_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true) +_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no") +_TEL_START=$(date +%s) +_SESSION_ID="$$-$(date +%s)" +echo "TELEMETRY: ${_TEL:-off}" +echo "TEL_PROMPTED: $_TEL_PROMPTED" +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +_QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") +echo "QUESTION_TUNING: $_QUESTION_TUNING" +mkdir -p ~/.gstack/analytics +if [ "$_TEL" != "off" ]; then +echo '{"skill":"grok","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-unknown}")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true +fi +for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do + if [ -f "$_PF" ]; then + if [ "$_TEL" != "off" ] && [ -x "~/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then + ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true + fi + rm -f "$_PF" 2>/dev/null || true + fi + break +done +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +_LEARN_FILE="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/learnings.jsonl" +if [ -f "$_LEARN_FILE" ]; then + _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ') + echo "LEARNINGS: $_LEARN_COUNT entries loaded" + if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then + ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 3 2>/dev/null || true + fi +else + echo "LEARNINGS: 0" +fi +~/.claude/skills/gstack/bin/gstack-timeline-log '{"skill":"grok","event":"started","branch":"'"$_BRANCH"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null & +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" +_VENDORED="no" +if [ -d ".claude/skills/gstack" ] && [ ! -L ".claude/skills/gstack" ]; then + if [ -f ".claude/skills/gstack/VERSION" ] || [ -d ".claude/skills/gstack/.git" ]; then + _VENDORED="yes" + fi +fi +echo "VENDORED_GSTACK: $_VENDORED" +echo "MODEL_OVERLAY: claude" +_CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode 2>/dev/null || echo "explicit") +_CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") +echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" +echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" +[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true +``` + +## Plan Mode Safe Operations + +In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`codex review`, writes to `~/.gstack/`, writes to the plan file, and `open` for generated artifacts. + +## Skill Invocation During Plan Mode + +If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; the first AskUserQuestion is the workflow entering plan mode, not a violation of it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode. + +If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?" + +If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `~/.claude/skills/gstack/[skill-name]/SKILL.md`. + +If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). + +If output shows `JUST_UPGRADED `: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery. + +Feature discovery, max one prompt per session: +- Missing `~/.claude/skills/gstack/.feature-prompted-continuous-checkpoint`: AskUserQuestion for Continuous checkpoint auto-commits. If accepted, run `~/.claude/skills/gstack/bin/gstack-config set checkpoint_mode continuous`. Always touch marker. +- Missing `~/.claude/skills/gstack/.feature-prompted-model-overlay`: inform "Model overlays are active. MODEL_OVERLAY shows the patch." Always touch marker. + +After upgrade prompts, continue workflow. + +If `WRITING_STYLE_PENDING` is `yes`: ask once about writing style: + +> v1 prompts are simpler: first-use jargon glosses, outcome-framed questions, shorter prose. Keep default or restore terse? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +Skip if `WRITING_STYLE_PENDING` is `no`. + +If `LAKE_INTRO` is `no`: say "gstack follows the **Boil the Ocean** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open: + +```bash +open https://garryslist.org/posts/boil-the-ocean +touch ~/.gstack/.completeness-intro-seen +``` + +Only run `open` if yes. Always run `touch`. + +If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: ask telemetry once via AskUserQuestion: + +> Help gstack get better. Share usage data only: skill, duration, crashes, stable device ID. No code or file paths. Your repo name is recorded locally only and stripped before any upload. + +Options: +- A) Help gstack get better! (recommended) +- B) No thanks + +If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community` + +If B: ask follow-up: + +> Anonymous mode sends only aggregate usage, no unique ID. + +Options: +- A) Sure, anonymous is fine +- B) No thanks, fully off + +If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous` +If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off` + +Always run: +```bash +touch ~/.gstack/.telemetry-prompted +``` + +Skip if `TEL_PROMPTED` is `yes`. + +If `PROACTIVE_PROMPTED` is `no` AND `TEL_PROMPTED` is `yes`: ask once: + +> Let gstack proactively suggest skills, like /qa for "does this work?" or /investigate for bugs? + +Options: +- A) Keep it on (recommended) +- B) Turn it off — I'll type /commands myself + +If A: run `~/.claude/skills/gstack/bin/gstack-config set proactive true` +If B: run `~/.claude/skills/gstack/bin/gstack-config set proactive false` + +Always run: +```bash +touch ~/.gstack/.proactive-prompted +``` + +Skip if `PROACTIVE_PROMPTED` is `yes`. + +If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: +Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. + +Use AskUserQuestion: + +> gstack works best when your project's CLAUDE.md includes skill routing rules. + +Options: +- A) Add routing rules to CLAUDE.md (recommended) +- B) No thanks, I'll invoke skills manually + +If A: Append this section to the end of CLAUDE.md: + +```markdown + +## Skill routing + +When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill. + +Key routing rules: +- Product ideas/brainstorming → invoke /office-hours +- Strategy/scope → invoke /plan-ceo-review +- Architecture → invoke /plan-eng-review +- Design system/plan review → invoke /design-consultation or /plan-design-review +- Full review pipeline → invoke /autoplan +- Bugs/errors → invoke /investigate +- QA/testing site behavior → invoke /qa or /qa-only +- Code review/diff check → invoke /review +- Visual polish → invoke /design-review +- Ship/deploy/PR → invoke /ship or /land-and-deploy +- Save progress → invoke /context-save +- Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec +``` + +Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` + +If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` and say they can re-enable with `gstack-config set routing_declined false`. + +This only happens once per project. Skip if `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`. + +If `VENDORED_GSTACK` is `yes`, warn once via AskUserQuestion unless `~/.gstack/.vendoring-warned-$SLUG` exists: + +> This project has gstack vendored in `.claude/skills/gstack/`. Vendoring is deprecated. +> Migrate to team mode? + +Options: +- A) Yes, migrate to team mode now +- B) No, I'll handle it myself + +If A: +1. Run `git rm -r .claude/skills/gstack/` +2. Run `echo '.claude/skills/gstack/' >> .gitignore` +3. Run `~/.claude/skills/gstack/bin/gstack-team-init required` (or `optional`) +4. Run `git add .claude/ .gitignore CLAUDE.md && git commit -m "chore: migrate gstack from vendored to team mode"` +5. Tell the user: "Done. Each developer now runs: `cd ~/.claude/skills/gstack && ./setup --team`" + +If B: say "OK, you're on your own to keep the vendored copy up to date." + +Always run (regardless of choice): +```bash +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +touch ~/.gstack/.vendoring-warned-${SLUG:-unknown} +``` + +If marker exists, skip. + +If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an +AI orchestrator (e.g., OpenClaw). In spawned sessions: +- Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option. +- Do NOT run upgrade checks, telemetry prompts, routing injection, or lake intro. +- Focus on completing the task and reporting results via prose output. +- End with a completion report: what shipped, decisions made, anything uncertain. + +## AskUserQuestion Format + +### Tool resolution (read first) + +"AskUserQuestion" can resolve to two tools at runtime: the **host MCP variant** (e.g. `mcp__conductor__AskUserQuestion` — appears in your tool list when the host registers it) or the **native** Claude Code tool. + +**Rule:** if any `mcp__*__AskUserQuestion` variant is in your tool list, prefer it. Hosts may disable native AUQ via `--disallowedTools AskUserQuestion` (Conductor does, by default) and route through their MCP variant; calling native there silently fails. Same questions/options shape; same decision-brief format applies. + +If AskUserQuestion is unavailable (no variant in your tool list) OR a call to it fails, do NOT silently auto-decide or write the decision to the plan file as a substitute. Follow the **failure fallback** below. + +### When AskUserQuestion is unavailable or a call fails + +Tell three outcomes apart: + +1. **Auto-decide denial (NOT a failure).** The result contains `[plan-tune auto-decide] →