feat: multi-agent support — gstack works on Codex, Gemini CLI, and Cursor (v0.9.0) (#226)

* refactor: host-aware gen-skill-docs + --host codex generation

Refactor gen-skill-docs.ts for multi-agent support:
- Add Host type, HostPaths interface, HOST_PATHS config
- Decompose generatePreamble() into 7 composable sub-functions
- Replace all hardcoded .claude/skills/gstack paths with ctx.paths
- Replace static findTemplates() list with dynamic filesystem scan
- Add --host codex|agents flag (aliases, same output)
- Add processTemplate host routing to .agents/skills/gstack-*/
- Add codexSkillName() with double-prefix prevention
- Add transformFrontmatter() — keeps only name + description for Codex
- Add extractHookSafetyProse() — converts hooks to inline advisory
- Add body text path rewriting for remaining hardcoded paths
- Exclude /codex skill from Codex generation (self-referential)

Claude output is unchanged (verified via --dry-run).
SKILL.md is an open standard: .agents/skills/ works on Codex, Gemini CLI, and Cursor.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: generate Codex/Gemini/Cursor skills into .agents/skills/

Generated 21 skill files for the open SKILL.md standard:
- Output: .agents/skills/gstack-*/SKILL.md (one per skill)
- Frontmatter: name + description only (no allowed-tools/version)
- No .claude/skills/ paths in any generated file
- /codex skill excluded (Claude wrapper, self-referential on Codex)
- Hook skills (careful/freeze/guard) get inline safety prose
- Build script generates both hosts: bun run build

Supported agents (all read .agents/skills/):
- Codex CLI
- Gemini CLI
- Cursor

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: dual-host setup + find-browse for Codex/Gemini/Cursor

- setup: add --host codex|claude|auto flag, install to ~/.codex/skills/
  when targeting Codex, auto-detect installed agents
- find-browse: priority chain .codex > .agents > .claude (both
  workspace-local and global)
- dev-setup/teardown: create .agents/skills/gstack symlinks for dev mode

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: Codex generation tests + CI + docs for multi-agent support

Tests (28 new):
- Codex output path routing, frontmatter validation (name+description only)
- No .claude/skills/ path leaks in Codex output (regression guard)
- /codex skill exclusion, hook→prose conversion, multiline YAML
- --host agents alias, dynamic template discovery
- Codex skill validation + $B command validation
- find-browse priority chain verification
- Replace static ALL_SKILLS list with dynamic filesystem scan

CI:
- Add Codex freshness check to skill-docs workflow

Docs:
- AGENTS.md: Codex-facing project instructions
- README: multi-agent installation section
- CONTRIBUTING: dual-host development workflow
- CHANGELOG: v0.9.0 multi-agent support entry

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: Codex E2E test harness — verify skills work on Codex CLI

New test infrastructure:
- CodexSessionRunner: spawns codex exec, parses JSONL stream, returns
  structured results (output, reasoning, toolCalls, tokens)
- JSONL parser ported from Python (codex/SKILL.md.tmpl) to TypeScript
- Temp HOME skill installation for Codex discovery testing

E2E tests (gated behind EVALS=1 + codex + OPENAI_API_KEY):
- codex-discover-skill: installs skill, verifies Codex finds it
- codex-review-findings: runs gstack-review via Codex, validates output

Integrates with existing eval infrastructure:
- Diff-based test selection via touchfiles
- Eval persistence via EvalCollector
- bun run test:codex / test:codex:all convenience scripts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: bump VERSION to 0.9.0 to match CHANGELOG

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Codex sidecar paths + setup installs generated skills

Two bugs found by Codex adversarial review:

1. Sidecar path mismatch: generated Codex skills referenced
   .agents/skills/gstack-review/checklist.md but setup creates
   sidecars at .agents/skills/gstack/review/. Fixed path rewriter
   to emit .agents/skills/gstack/review/ (matching setup layout).

2. Setup installed Claude-format source dirs for Codex global
   install instead of the generated Codex-format skills. Split
   link_skill_dirs into link_claude_skill_dirs (source dirs for
   Claude) and link_codex_skill_dirs (generated .agents/skills/
   gstack-* dirs for Codex).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: comprehensive Codex path rewriting + setup install tests

17 new tests covering:
- Sidecar path rewriting: .claude/skills/review → .agents/skills/gstack/review/
  (catches the bug where checklist.md was unreachable at gstack-review/)
- All 4 path rewrite rules tested individually across all skills
- Greptile triage sidecar path correctness
- Ship skill sidecar paths for pre-landing review
- Claude output regression guard: zero Codex paths in any Claude skill
- Setup script validation: separate link functions for Claude vs Codex,
  link_codex_skill_dirs reads from .agents/skills/, create_agents_sidecar
  links runtime assets (bin, browse, review, qa)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: regenerate Codex skills after investigate rename merge

Remove stale gstack-debug, add gstack-investigate, regenerate all
Codex skills to pick up changes merged from main (investigate rename,
platform-agnostic templates, review helpers).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: Codex E2E uses ~/.codex/ auth, not OPENAI_API_KEY

- Remove OPENAI_API_KEY gate from test prerequisites
- Copy real ~/.codex/ auth config into temp HOME so codex can authenticate
- Increase review test timeout to 540s (codex does thorough 60+ tool call reviews)
- Document in CLAUDE.md that Codex uses its own auth config

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

test/skill-validation.test.ts

@@ -1257,3 +1257,70 @@ describe('Skill trigger phrases', () => {
     });
   }
 });
+
+// ─── Codex Skill Validation ──────────────────────────────────
+
+describe('Codex skill validation', () => {
+  const AGENTS_DIR = path.join(ROOT, '.agents', 'skills');
+
+  // Discover all Claude skills with templates (except /codex which is Claude-only)
+  const CLAUDE_SKILLS_WITH_TEMPLATES = (() => {
+    const skills: string[] = [];
+    for (const entry of fs.readdirSync(ROOT, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      if (entry.name === 'codex') continue; // Claude-only skill
+      if (fs.existsSync(path.join(ROOT, entry.name, 'SKILL.md.tmpl'))) {
+        skills.push(entry.name);
+      }
+    }
+    return skills;
+  })();
+
+  test('all skills (except /codex) have both Claude and Codex variants', () => {
+    for (const skillDir of CLAUDE_SKILLS_WITH_TEMPLATES) {
+      // Claude variant
+      const claudeMd = path.join(ROOT, skillDir, 'SKILL.md');
+      expect(fs.existsSync(claudeMd)).toBe(true);
+
+      // Codex variant
+      const codexName = skillDir.startsWith('gstack-') ? skillDir : `gstack-${skillDir}`;
+      const codexMd = path.join(AGENTS_DIR, codexName, 'SKILL.md');
+      expect(fs.existsSync(codexMd)).toBe(true);
+    }
+    // Root template has both too
+    expect(fs.existsSync(path.join(ROOT, 'SKILL.md'))).toBe(true);
+    expect(fs.existsSync(path.join(AGENTS_DIR, 'gstack', 'SKILL.md'))).toBe(true);
+  });
+
+  test('/codex skill is Claude-only — no Codex variant', () => {
+    // Claude variant should exist
+    expect(fs.existsSync(path.join(ROOT, 'codex', 'SKILL.md'))).toBe(true);
+    // Codex variant must NOT exist
+    expect(fs.existsSync(path.join(AGENTS_DIR, 'gstack-codex', 'SKILL.md'))).toBe(false);
+  });
+
+  test('Codex skill names follow gstack-{name} convention', () => {
+    const codexDirs = fs.readdirSync(AGENTS_DIR);
+    for (const dir of codexDirs) {
+      // Every directory should start with gstack
+      expect(dir.startsWith('gstack')).toBe(true);
+      // Root is just 'gstack', others are 'gstack-{name}'
+      if (dir !== 'gstack') {
+        expect(dir.startsWith('gstack-')).toBe(true);
+      }
+    }
+  });
+
+  test('$B commands in Codex SKILL.md files are valid browse commands', () => {
+    const codexDirs = fs.readdirSync(AGENTS_DIR);
+    for (const dir of codexDirs) {
+      const skillMd = path.join(AGENTS_DIR, dir, 'SKILL.md');
+      if (!fs.existsSync(skillMd)) continue;
+      const content = fs.readFileSync(skillMd, 'utf-8');
+      // Only validate if the skill contains $B commands
+      if (!content.includes('$B ')) continue;
+      const result = validateSkill(skillMd);
+      expect(result.invalid).toHaveLength(0);
+    }
+  });
+});