_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 -delete 2>/dev/null || true
_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
echo "PROACTIVE: $_PROACTIVE"
_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"
mkdir -p ~/.gstack/analytics
echo '{"skill":"codex","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}'  >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
for _PF in ~/.gstack/analytics/.pending-*; do [ -f "$_PF" ] && ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true; break; done

PROACTIVE

"false"

UPGRADE_AVAILABLE <old> <new>

~/.claude/skills/gstack/gstack-upgrade/SKILL.md

JUST_UPGRADED <from> <to>

LAKE_INTRO

no

open https://garryslist.org/posts/boil-the-ocean
touch ~/.gstack/.completeness-intro-seen

open

touch

TEL_PROMPTED

no

LAKE_INTRO

yes

Help gstack get better! Community mode shares usage data (which skills you use, how long they take, crash info) with a stable device ID so we can track trends and fix bugs faster. No code, file paths, or repo names are ever sent. Change anytime with

gstack-config set telemetry off

.

• A) Help gstack get better! (recommended)
• B) No thanks

~/.claude/skills/gstack/bin/gstack-config set telemetry community

How about anonymous mode? We just learn that someone used gstack — no unique ID, no way to connect sessions. Just a counter that helps us know if anyone's out there.

• A) Sure, anonymous is fine
• B) No thanks, fully off

~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous

~/.claude/skills/gstack/bin/gstack-config set telemetry off

touch ~/.gstack/.telemetry-prompted

TEL_PROMPTED

yes

1. Re-ground: State the project, the current branch (use the

   _BRANCH

   value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
2. Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
3. Recommend:

   RECOMMENDATION: Choose [X] because [one-line reason]

   — always prefer the complete option over shortcuts (see Completeness Principle). Include

   Completeness: X/10

   for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.
4. Options: Lettered options:

   A) ... B) ... C) ...

   — when an option involves effort, show both scales:

   (human: ~X / CC: ~Y)

• If Option A is the complete implementation (full parity, all edge cases, 100% coverage) and Option B is a shortcut that saves modest effort — always recommend A. The delta between 80 lines and 150 lines is meaningless with CC+gstack. "Good enough" is the wrong instinct when "complete" costs minutes more.
• Lake vs. ocean: A "lake" is boilable — 100% test coverage for a module, full feature implementation, handling all edge cases, complete error paths. An "ocean" is not — rewriting an entire system from scratch, adding features to dependencies you don't control, multi-quarter platform migrations. Recommend boiling lakes. Flag oceans as out of scope.
• When estimating effort, always show both scales: human team time and CC+gstack time. The compression ratio varies by task type — use this reference:

• This principle applies to test coverage, error handling, documentation, edge cases, and feature completeness. Don't skip the last 10% to "save time" — with AI, that 10% costs seconds.

• BAD: "Choose B — it covers 90% of the value with less code." (If A is only 70 lines more, choose A.)
• BAD: "We can skip edge case handling to save time." (Edge case handling costs minutes with CC.)
• BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.)
• BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour CC.")

~/.claude/skills/gstack/ETHOS.md

• Layer 1 (tried and true — in distribution). Don't reinvent the wheel. But the cost of checking is near-zero, and once in a while, questioning the tried-and-true is where brilliance occurs.
• Layer 2 (new and popular — search for these). But scrutinize: humans are subject to mania. Search results are inputs to your thinking, not answers.
• Layer 3 (first principles — prize these above all). Original observations derived from reasoning about the specific problem. The most valuable of all.

jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true

1. {step}

• DONE — All steps completed successfully. Evidence provided for each claim.
• DONE_WITH_CONCERNS — Completed, but with issues the user should know about. List each concern.
• BLOCKED — Cannot proceed. State what is blocking and what was tried.
• NEEDS_CONTEXT — Missing information required to continue. State exactly what you need.

• If you have attempted a task 3 times without success, STOP and escalate.
• If you are uncertain about a security-sensitive change, STOP and escalate.
• If the scope of work exceeds what you can verify, STOP and escalate.

STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]

1. Check if a PR already exists for this branch:

   gh pr view --json baseRefName -q .baseRefName

   If this succeeds, use the printed branch name as the base branch.
2. If no PR exists (command fails), detect the repo's default branch:

   gh repo view --json defaultBranchRef -q .defaultBranchRef.name

3. If both commands fail, fall back to

   main

   .

git diff

git log

git fetch

git merge

gh pr create

1. /codex review

   or

   /codex review <instructions>

   — Review mode (Step 2A)

2. /codex challenge

   or

   /codex challenge <focus>

   — Challenge mode (Step 2B)

3. /codex

   with no arguments — Auto-detect:
   • Check for a diff (with fallback if origin isn't available):

     git diff origin/<base> --stat 2>/dev/null | tail -1 || git diff <base> --stat 2>/dev/null | tail -1

   • If a diff exists, use AskUserQuestion:

     Codex detected changes against the base branch. What should it do?
     A) Review the diff (code review with pass/fail gate)
     B) Challenge the diff (adversarial — try to break it)
     C) Something else — I'll provide a prompt

   • If no diff, check for plan files scoped to the current project:

     ls -t ~/.claude/plans/*.md 2>/dev/null | xargs grep -l "$(basename $(pwd))" 2>/dev/null | head -1

     If no project-scoped match, fall back to:

     ls -t ~/.claude/plans/*.md 2>/dev/null | head -1

     but warn the user: "Note: this plan may be from a different project."
   • If a plan file exists, offer to review it
   • Otherwise, ask: "What would you like to ask Codex?"

4. /codex <anything else>

   — Consult mode (Step 2C), where the remaining text is the prompt

1. Create temp files for output capture:

TMPERR=$(mktemp /tmp/codex-err-XXXXXX.txt)

1. Run the review (5-minute timeout):

codex review --base <base> -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR"

timeout: 300000

/codex review focus on security

codex review "focus on security" --base <base> -c 'model_reasoning_effort="xhigh"' --enable web_search_cached 2>"$TMPERR"

1. Capture the output. Then parse cost from stderr:

grep "tokens used" "$TMPERR" 2>/dev/null || echo "tokens: unknown"

1. Determine gate verdict by checking the review output for critical findings. If the output contains

   [P1]

   — the gate is FAIL. If no

   [P1]

   markers are found (only

   [P2]

   or no findings) — the gate is PASS.
2. Present the output:

CODEX SAYS (code review):
════════════════════════════════════════════════════════════
<full codex output, verbatim — do not truncate or summarize>
════════════════════════════════════════════════════════════
GATE: PASS                    Tokens: 14,331 | Est. cost: ~$0.12

GATE: FAIL (N critical findings)

1. Cross-model comparison: If

   /review

   (Claude's own review) was already run earlier in this conversation, compare the two sets of findings:

CROSS-MODEL ANALYSIS:
  Both found: [findings that overlap between Claude and Codex]
  Only Codex found: [findings unique to Codex]
  Only Claude found: [findings unique to Claude's /review]
  Agreement rate: X% (N/M total unique findings overlap)

1. Persist the review result:

~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-review","timestamp":"TIMESTAMP","status":"STATUS","gate":"GATE","findings":N,"findings_fixed":N}'

1. Clean up temp files:

rm -f "$TMPERR"

1. Check if there is an active plan file in this conversation (the host provides plan file paths in system messages — look for plan file references in the conversation context).
2. If not found, skip this section silently — not every review runs in plan mode.

• plan-ceo-review: `status`, `unresolved`, `critical_gaps`, `mode`, `scope_proposed`, `scope_accepted`, `scope_deferred`, `commit` → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred" → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
• plan-eng-review: `status`, `unresolved`, `critical_gaps`, `issues_found`, `mode`, `commit` → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
• plan-design-review: `status`, `initial_score`, `overall_score`, `unresolved`, `decisions_made`, `commit` → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
• codex-review: `status`, `gate`, `findings`, `findings_fixed` → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"

• CODEX: (only if codex-review ran) — one-line summary of codex fixes
• CROSS-MODEL: (only if both Claude and Codex reviews exist) — overlap analysis
• UNRESOLVED: total unresolved decisions across all reviews
• 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".

• Search the plan file for a `## GSTACK REVIEW REPORT` section anywhere in the file (not just at the end — content may have been added after it).
• If found, replace it entirely using the Edit tool. Match from `## GSTACK REVIEW REPORT` through either the next `## ` heading or end of file, whichever comes first. This ensures content added after the report section is preserved, not eaten. If the Edit fails (e.g., concurrent edit changed the content), re-read the plan file and retry once.
• If no such section exists, append it to the end of the plan file.
• Always place it as the very last section in the plan file. If it was found mid-file, move it: delete the old location and append at the end.

1. Construct the adversarial prompt. If the user provided a focus area (e.g.,

   /codex challenge security

   ), include it:

git diff origin/<base>

git diff origin/<base>

1. Run codex exec with JSONL output to capture reasoning traces and tool calls (5-minute timeout):

codex exec "<prompt>" -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached --json 2>/dev/null | python3 -c "
import sys, json
for line in sys.stdin:
    line = line.strip()
    if not line: continue
    try:
        obj = json.loads(line)
        t = obj.get('type','')
        if t == 'item.completed' and 'item' in obj:
            item = obj['item']
            itype = item.get('type','')
            text = item.get('text','')
            if itype == 'reasoning' and text:
                print(f'[codex thinking] {text}')
                print()
            elif itype == 'agent_message' and text:
                print(text)
            elif itype == 'command_execution':
                cmd = item.get('command','')
                if cmd: print(f'[codex ran] {cmd}')
        elif t == 'turn.completed':
            usage = obj.get('usage',{})
            tokens = usage.get('input_tokens',0) + usage.get('output_tokens',0)
            if tokens: print(f'\ntokens used: {tokens}')
    except: pass
"

[codex thinking]

1. Present the full streamed output:

CODEX SAYS (adversarial challenge):
════════════════════════════════════════════════════════════
<full output from above, verbatim>
════════════════════════════════════════════════════════════
Tokens: N | Est. cost: ~$X.XX

1. Check for existing session:

cat .context/codex-session-id 2>/dev/null || echo "NO_SESSION"

NO_SESSION

You have an active Codex conversation from earlier. Continue it or start fresh?
A) Continue the conversation (Codex remembers the prior context)
B) Start a new conversation

1. Create temp files:

TMPRESP=$(mktemp /tmp/codex-resp-XXXXXX.txt)
TMPERR=$(mktemp /tmp/codex-err-XXXXXX.txt)

1. Plan review auto-detection: If the user's prompt is about reviewing a plan, or if plan files exist and the user said

   /codex

   with no arguments:

ls -t ~/.claude/plans/*.md 2>/dev/null | xargs grep -l "$(basename $(pwd))" 2>/dev/null | head -1

ls -t ~/.claude/plans/*.md 2>/dev/null | head -1

1. Run codex exec with JSONL output to capture reasoning traces (5-minute timeout):

codex exec "<prompt>" -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached --json 2>"$TMPERR" | python3 -c "
import sys, json
for line in sys.stdin:
    line = line.strip()
    if not line: continue
    try:
        obj = json.loads(line)
        t = obj.get('type','')
        if t == 'thread.started':
            tid = obj.get('thread_id','')
            if tid: print(f'SESSION_ID:{tid}')
        elif t == 'item.completed' and 'item' in obj:
            item = obj['item']
            itype = item.get('type','')
            text = item.get('text','')
            if itype == 'reasoning' and text:
                print(f'[codex thinking] {text}')
                print()
            elif itype == 'agent_message' and text:
                print(text)
            elif itype == 'command_execution':
                cmd = item.get('command','')
                if cmd: print(f'[codex ran] {cmd}')
        elif t == 'turn.completed':
            usage = obj.get('usage',{})
            tokens = usage.get('input_tokens',0) + usage.get('output_tokens',0)
            if tokens: print(f'\ntokens used: {tokens}')
    except: pass
"

codex exec resume <session-id> "<prompt>" -s read-only -c 'model_reasoning_effort="xhigh"' --enable web_search_cached --json 2>"$TMPERR" | python3 -c "
<same python streaming parser as above>
"

1. Capture session ID from the streamed output. The parser prints

   SESSION_ID:<id>

   from the

   thread.started

   event. Save it for follow-ups:

mkdir -p .context

SESSION_ID:

.context/codex-session-id

1. Present the full streamed output:

CODEX SAYS (consult):
════════════════════════════════════════════════════════════
<full output, verbatim — includes [codex thinking] traces>
════════════════════════════════════════════════════════════
Tokens: N | Est. cost: ~$X.XX
Session saved — run /codex again to continue this conversation.

1. After presenting, note any points where Codex's analysis differs from your own understanding. If there is a disagreement, flag it: "Note: Claude Code disagrees on X because Y."

• Binary not found: Detected in Step 0. Stop with install instructions.
• Auth error: Codex prints an auth error to stderr. Surface the error: "Codex authentication failed. Run

  codex login

  in your terminal to authenticate via ChatGPT."
• Timeout: If the Bash call times out (5 min), tell the user: "Codex timed out after 5 minutes. The diff may be too large or the API may be slow. Try again or use a smaller scope."
• Empty response: If

  $TMPRESP

  is empty or doesn't exist, tell the user: "Codex returned no response. Check stderr for errors."
• Session resume failure: If resume fails, delete the session file and start fresh.

• Never modify files. This skill is read-only. Codex runs in read-only sandbox mode.
• Present output verbatim. Do not truncate, summarize, or editorialize Codex's output before showing it. Show it in full inside the CODEX SAYS block.
• Add synthesis after, not instead of. Any Claude commentary comes after the full output.
• 5-minute timeout on all Bash calls to codex (

  timeout: 300000

  ).
• No double-reviewing. If the user already ran

  /review

  , Codex provides a second independent opinion. Do not re-run Claude Code's own review.