Code Review: feat: add Codex host support

Findings

1. pr-body.md committed to repo root

• Severity: Non-blocking
• Location: pr-body.md (new file, 56 lines)
• Description: This file is a copy of the PR description committed as a standalone file in the repo root. PR descriptions are GitHub artifacts preserved in PR history — committing them as files creates maintenance burden and clutters the repo root.
• Suggested Fix: Remove pr-body.md from the commit. The PR description on GitHub is the canonical source.

2. --host as last CLI argument produces unclear error

• Severity: Non-blocking
• Location: scripts/gen-skill-docs.ts — HOST argument parsing
• Description: If a user runs bun run gen:skill-docs --host (without a value), process.argv[HOST_ARG_INDEX + 1] evaluates to undefined. The validation catches this, but the error message reads Invalid --host value: undefined — a dedicated check for a missing value would be clearer.
• Suggested Fix: Check for undefined before the general validation and throw --host requires a value: "claude" or "codex".

3. setup auto mode silently no-ops when neither host is detected

• Severity: Non-blocking
• Location: setup — auto mode case branch
• Description: When --host auto is used and neither $HOME/.codex nor $HOME/.claude directories exist, the script completes silently without creating any symlinks and without warning the user.
• Suggested Fix: Add a fallback warning when no host environment is detected.

4. link_codex_global() doesn't validate SKILL.md presence

• Severity: Non-blocking
• Location: setup — link_codex_global() function
• Description: link_claude_local() and link_claude_global() both check [ -f "$skill_dir/SKILL.md" ] || continue before creating symlinks, but link_codex_global() only checks [ -d "$skill_dir" ] || continue. Non-skill directories matching the gstack* glob would be symlinked.
• Suggested Fix: Add the same [ -f "$skill_dir/SKILL.md" ] || continue guard to link_codex_global().

5. find-browse TypeScript uses existsSync but bash uses -x (executable check)

• Severity: Non-blocking
• Location: browse/src/find-browse.ts vs browse/bin/find-browse
• Description: The bash script checks executability (-x), while the TypeScript implementation only checks existence (existsSync). A non-executable binary file would be returned by TypeScript but skipped by bash.
• Suggested Fix: Use fs.accessSync(candidate, fs.constants.X_OK) in the TypeScript implementation, or document this as intentional.

6. Invocation rewriting transforms content inside code blocks

• Severity: Non-blocking
• Location: scripts/gen-skill-docs.ts — replaceInvocations()
• Description: The regex operates on full template content including fenced code blocks. A literal /browse inside a code example would be transformed to $gstack-browse. Currently doesn't cause issues in existing templates, but is fragile for future template authors.
• Suggested Fix: Consider skipping replacement inside fenced code blocks, or accept as intentional since Codex skills should always show $gstack-* syntax.

7. Test coverage gap: no explicit test for invocation syntax transformation

• Severity: Non-blocking
• Location: test/gen-skill-docs.test.ts
• Description: Tests verify Codex output doesn't contain .claude/skills paths, but there's no explicit test verifying /browse is transformed to $gstack-browse. This is a core feature of the Codex generation pipeline.
• Suggested Fix: Add a test verifying $gstack-* syntax appears and /skill syntax does not in Codex output.

Summary

Overall assessment: Ready to merge. No blocking issues found.

This is a well-architected PR that adds Codex as a first-class host without duplicating workflow logic. The key design decisions are sound:

• Single template source with host-aware placeholder resolution keeps the two hosts in sync
• Relative symlinks in .agents/skills/gstack/ correctly point back to repo root (3 levels up)
• Path precedence (.codex > .agents > .claude) is consistently implemented across bash and TypeScript
• CI validation runs both --dry-run and --host codex --dry-run to catch staleness
• Path isolation is enforced — tests verify no .claude/skills paths leak into Codex output
• replaceInvocations() uses proper regex with word boundaries to avoid false matches
• Output directories are created with mkdirSync({ recursive: true }) before writing

The 7 non-blocking findings are minor improvements around edge case handling, test coverage, and a stray pr-body.md file. None affect correctness for the intended use cases.