gstack: Add Codex compatibility layer without forking workflows

[mneves75]

Summary

This PR adds a Codex-compatible host layer to gstack without rewriting the project or forking the workflow logic.

The core idea is to split the repo into two concerns:

• Portable core: the browser/QA binary in browse/, the shared setup/build/version flow, and the workflow content itself.
• Host glue: Claude-specific registration/instructions on one side, Codex-native packaging and guidance on the other.

That keeps one upstream codebase, one browser runtime, and one set of workflow contracts while making gstack usable from Codex in a way that matches Codex's actual model instead of trying to fake Claude slash-command infrastructure.

Why this version is stronger

The initial Codex pass was installable, but some shared helper paths still implicitly preferred Claude conventions. This version hardens the seams that matter in production:

• Codex gets native .codex/skills/* packaging and AGENTS.md guidance instead of Claude emulation.
• Shared helper blocks were updated to resolve Codex, .agents, and Claude installs instead of assuming .claude roots.
• The upgrade and review helper paths now work for Codex installs too.
• The Codex path is validated through the real codex exec --json runtime, not just static file checks.

That makes this a real dual-host integration layer rather than a docs-only compatibility story.

Design goals

• Keep the browser binary interface unchanged.
• Keep Claude support intact.
• Add Codex as a parallel host, not a rewrite.
• Minimize host drift by centralizing reusable workflow content.
• Preserve existing gstack command UX through thin compatibility wrappers, not new infrastructure.

What changed

1. Added a Codex-native host layer

• Added AGENTS.md with the Codex operator contract and slash-to-skill compatibility mapping.
• Added .codex/skills/* for:
  • gstack-browse
  • gstack-qa
  • gstack-review
  • gstack-plan-ceo-review
  • gstack-plan-eng-review
  • gstack-browser-cookies
  • gstack-ship
  • gstack-retro
• Added YAML frontmatter to every Codex skill so they load cleanly in the real Codex CLI.

2. Split reusable workflow content from host glue

• Added shared, host-neutral workflow references under references/workflows/.
• Kept Claude-facing assets in place.
• Pointed the Codex skill layer at shared workflow references instead of duplicating long instructions.

3. Made setup host-aware

• ./setup now supports:
  • --host claude
  • --host codex
  • --host auto
• The setup flow still builds the browser binary and installs browser dependencies.
• Only the host registration/linking behavior changes by target host.
• Re-running setup is idempotent for both Claude and Codex installs.

4. Preserved gstack command ergonomics with thin wrappers

Added compatibility wrappers in bin/:

• gstack-browse
• gstack-qa
• gstack-review
• gstack-plan-ceo-review
• gstack-plan-eng-review
• gstack-browser-cookies
• gstack-ship
• gstack-retro

These are intentionally thin. They document and expose the Codex-facing workflow names without trying to recreate Claude's native slash-command registration behavior.

5. Hardened shared helper path resolution

The second pass fixed the places where the repo was still subtly Claude-shaped:

• browse/src/find-browse.ts and browse/bin/find-browse now search Codex, .agents, and Claude-style install roots.
• scripts/gen-skill-docs.ts now generates helper blocks that resolve Codex and .agents installs too.
• gstack-upgrade/SKILL.md.tmpl and generated output now detect Codex installs and vendored copies.
• review/greptile-triage.md now resolves shared install paths through Codex and .agents roots as well.
• bin/gstack-config no longer uses BSD-only sed -i ''; it now works on Linux too.

6. Added Codex-focused validation

Added tests for:

• Codex skill packaging correctness
• alias wrapper behavior
• generated skill docs and frontmatter validity
• host-aware browse binary discovery
• Codex JSONL session parsing helpers
• live Codex smoke execution via codex exec --json

Validation

Current validation run on this branch:

bash -n setup browse/bin/find-browse bin/gstack-config bin/gstack-alias \
  bin/gstack-browse bin/gstack-qa bin/gstack-review \
  bin/gstack-plan-ceo-review bin/gstack-plan-eng-review \
  bin/gstack-browser-cookies bin/gstack-ship bin/gstack-retro

git diff --check upstream/main...HEAD

bun test browse/test/find-browse.test.ts \
  test/codex-compat.test.ts \
  test/gen-skill-docs.test.ts \
  test/helpers/codex-session-runner.test.ts

CODEX_EVALS=1 bun test test/codex-e2e.test.ts

All passed.

Additional install smoke coverage was also completed during development for:

• ./setup --host codex
• re-running ./setup --host codex for idempotency
• ./setup --host claude

Non-goals

• This PR does not try to recreate Claude slash-command registration inside Codex.
• This PR does not replace the browser binary with host-native browser tooling.
• This PR does not rename the project or fork workflow content into separate Claude/Codex trees.

Risks / follow-ups

• The Codex layer depends on keeping shared workflow references under references/workflows/ as the source of truth; future workflow edits should continue to update shared docs first to avoid drift.
• Codex E2E coverage is currently smoke-level and focused on loadability/runtime viability. It can be expanded later if heavier Codex-side behavioral coverage becomes necessary.

Outcome

After this PR, a Codex user can clone the same repo, run host-aware setup, use the same browser/QA engine, and trigger the same cognitive modes from Codex with minimal host-specific drift.

That is the portability win: one repo, one runtime core, thin host glue.