fix(3562): generate Codex skill surface; $gsd-* commands discoverable after install

Closes #3562

Codex CLI 0.130.0 only registers commands from skills/<name>/SKILL.md; it
does NOT auto-discover from get-shit-done/workflows/*.md or agents/*.md.
Prior installer logic (#3427/#3433) removed the gsd-* skill copies under the
assumption that Codex would discover the official skills directly. That
assumption does not hold — users ended up with workflows on disk and zero
$gsd-* entrypoints after restart.

Fix: re-wire copyCommandsAsCodexSkills() (line 5519, already present) into
the Codex install dispatch path (line 8090). Generates one
~/.codex/skills/gsd-<name>/SKILL.md per commands/gsd/*.md — same shape the
Copilot/Antigravity/Cursor/Windsurf/Augment/Trae installs use.

Behaviour change: the pre-existing test in bug-3427-3433-codex-install-shape
asserted "does not regenerate gsd-* skill copies". Updated it to assert
the new behaviour (regenerate gsd-* with refreshed body, preserve non-gsd
user skills).

Tests:
- New tests/bug-3562-codex-install-skill-surface.test.cjs (4 cases):
  - skills/gsd-help/SKILL.md exists
  - SKILL.md has YAML frontmatter with name: gsd-help
  - >= 10 gsd-* skill directories produced (lower-bound, currently 67)
  - Pre-existing custom-user-skill directory preserved
- tests/bug-3427-3433-codex-install-shape.test.cjs: updated to assert
  regeneration + body refresh + unrelated-skill preservation.

Verified by re-running the issue's repro: `node bin/install.js --codex
--global --config-dir <tmp>` now produces 67 gsd-* skills and the target
~/.codex/skills/gsd-help/SKILL.md exists with valid frontmatter.

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

.changeset/3562-codex-install-skill-surface.md

@@ -0,0 +1,6 @@
+---
+type: Fixed
+pr: 0
+---
+
+**Codex global install now produces discoverable `$gsd-*` skill surface** — `npx get-shit-done-cc@latest --codex --global` was leaving Codex CLI users with `get-shit-done/workflows/*.md` and `agents/gsd-*` on disk but no `~/.codex/skills/gsd-*/SKILL.md` files, so Codex 0.130.0 silently exposed zero `$gsd-*` commands after restart. The installer had been bypassing skill generation under the assumption that Codex auto-discovers from workflow/agent files; that assumption does not hold for the current Codex CLI. Re-wired the existing `copyCommandsAsCodexSkills()` helper into the Codex install dispatch path so it produces the same skill-shape as the Claude / Copilot / Antigravity / Cursor / Windsurf / Augment / Trae installs already do (one `skills/gsd-<name>/SKILL.md` per `commands/gsd/*.md`). Pre-existing user-owned non-`gsd-*` skill directories are preserved. Closes #3562.

bin/install.js

@@ -8088,23 +8088,27 @@ function install(isGlobal, runtime = 'claude', options = {}) {
       failures.push('command/gsd-*');
     }
   } else if (isCodex) {
+    // Codex CLI (0.130.0 at time of #3562) does NOT auto-discover commands
+    // from get-shit-done/workflows/*.md or agents/*.md. It only registers
+    // commands from skills/<name>/SKILL.md. The earlier "Codex discovers
+    // official skills directly" branch left users with workflows on disk and
+    // no $gsd-* entrypoints. Regenerate the skill surface the same way the
+    // other runtimes do — copyCommandsAsCodexSkills() rewrites each
+    // commands/gsd/*.md as ~/.codex/skills/gsd-<name>/SKILL.md and converts
+    // Claude-flavored command frontmatter into Codex skill frontmatter.
     const skillsDir = path.join(targetDir, 'skills');
-    // Codex now discovers repo/user/admin/system skills from .agents/skills and
-    // warns if a layer mixes redundant hook/skill representations. Legacy
-    // gsd-* copies under ~/.codex/skills are therefore removed and no longer
-    // regenerated.
-    let removedLegacyCodexSkills = 0;
+    const gsdSrc = _stageSkills(_commandsDir);
+    copyCommandsAsCodexSkills(gsdSrc, skillsDir, 'gsd', pathPrefix, runtime);
     if (fs.existsSync(skillsDir)) {
-      for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-        if (!entry.isDirectory() || !entry.name.startsWith('gsd-')) continue;
-        fs.rmSync(path.join(skillsDir, entry.name), { recursive: true, force: true });
-        removedLegacyCodexSkills += 1;
+      const count = fs.readdirSync(skillsDir, { withFileTypes: true })
+        .filter(e => e.isDirectory() && e.name.startsWith('gsd-')).length;
+      if (count > 0) {
+        console.log(`  ${green}✓${reset} Installed ${count} skills to skills/`);
+      } else {
+        failures.push('skills/gsd-*');
       }
-    }
-    if (removedLegacyCodexSkills > 0) {
-      console.log(`  ${green}✓${reset} Removed ${removedLegacyCodexSkills} legacy Codex gsd-* skill copies from skills/`);
     } else {
-      console.log(`  ${dim}↳${reset} Skipped Codex skill-copy generation (Codex discovers official skills directly)`);
+      failures.push('skills/gsd-*');
     }
   } else if (isCopilot) {
     const skillsDir = path.join(targetDir, 'skills');

tests/bug-3427-3433-codex-install-shape.test.cjs

@@ -55,7 +55,9 @@ describe('#3427 + #3433 — Codex installer avoids duplicate skills and mixed ho
     cleanup(tmpRoot);
   });
 
-  test('removes legacy gsd-* copies from ~/.codex/skills and does not regenerate them', () => {
+  test('regenerates managed gsd-* skill copies and preserves unrelated user skills (#3562 reverses prior #3427/#3433 behaviour)', () => {
+    // Stale legacy body — fresh install must overwrite this so Codex sees the
+    // current SKILL.md, not whatever was last on disk.
     const legacySkillBody = '# old managed\n';
     fs.mkdirSync(path.join(codexHome, 'skills', 'gsd-help'), { recursive: true });
     fs.writeFileSync(path.join(codexHome, 'skills', 'gsd-help', 'SKILL.md'), legacySkillBody);
@@ -77,7 +79,15 @@ describe('#3427 + #3433 — Codex installer avoids duplicate skills and mixed ho
       ? fs.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)
       : [];
 
-    assert.equal(entries.some((name) => name.startsWith('gsd-')), false);
+    // #3562: $gsd-* commands are discoverable only when skills/gsd-*/SKILL.md
+    // exists. The installer must regenerate (not remove) the managed gsd-*
+    // directories.
+    assert.equal(entries.includes('gsd-help'), true);
+    const refreshedBody = fs.readFileSync(path.join(skillsDir, 'gsd-help', 'SKILL.md'), 'utf8');
+    assert.notEqual(refreshedBody, legacySkillBody, 'stale legacy body must be overwritten');
+    assert.ok(refreshedBody.startsWith('---'), 'refreshed SKILL.md must be valid frontmatter shape');
+
+    // Unrelated user skills are preserved — the regen scope is `gsd-*` only.
     assert.equal(entries.includes('custom-user-skill'), true);
   });
 

tests/bug-3562-codex-install-skill-surface.test.cjs

@@ -0,0 +1,128 @@
+'use strict';
+
+process.env.GSD_TEST_MODE = '1';
+
+/**
+ * Regression test for bug #3562 — Codex global install must create a
+ * discoverable $gsd-* skill surface.
+ *
+ * Codex CLI 0.130.0 (the version in the issue report) does NOT auto-discover
+ * commands from get-shit-done/workflows/*.md or agents/*.md. It only registers
+ * commands from skills/<name>/SKILL.md. Prior installer logic ("Codex now
+ * discovers official skills from .agents/skills") was based on an assumption
+ * that does not match the shipping Codex CLI behavior, leaving users with
+ * workflows on disk and no $gsd-* entrypoints after `npx get-shit-done-cc
+ * --codex --global`.
+ *
+ * Fix: re-wire copyCommandsAsCodexSkills() back into the install dispatch path
+ * so the same skill-shape that Claude / Copilot / Antigravity / Cursor /
+ * Windsurf / Augment / Trae installs produce is also produced for Codex.
+ */
+
+const { describe, test, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { install } = require('../bin/install.js');
+const { createTempDir, cleanup } = require('./helpers.cjs');
+
+const HOOKS_DIST = path.join(__dirname, '..', 'hooks', 'dist');
+const BUILD_HOOKS_SCRIPT = path.join(__dirname, '..', 'scripts', 'build-hooks.js');
+
+function withCodexHome(codexHome, fn) {
+  const prev = process.env.CODEX_HOME;
+  process.env.CODEX_HOME = codexHome;
+  try {
+    return fn();
+  } finally {
+    if (prev == null) delete process.env.CODEX_HOME;
+    else process.env.CODEX_HOME = prev;
+  }
+}
+
+describe('#3562 — Codex install produces discoverable $gsd-* skill surface', { concurrency: false }, () => {
+  let tmpRoot;
+  let codexHome;
+
+  beforeEach(() => {
+    if (!fs.existsSync(HOOKS_DIST) || fs.readdirSync(HOOKS_DIST).length === 0) {
+      execFileSync(process.execPath, [BUILD_HOOKS_SCRIPT], { stdio: 'pipe' });
+    }
+    tmpRoot = createTempDir('gsd-3562-');
+    codexHome = path.join(tmpRoot, '.codex');
+    fs.mkdirSync(codexHome, { recursive: true });
+  });
+
+  afterEach(() => {
+    cleanup(tmpRoot);
+  });
+
+  test('global install creates skills/gsd-help/SKILL.md', () => {
+    withCodexHome(codexHome, () => install(true, 'codex'));
+
+    const skillPath = path.join(codexHome, 'skills', 'gsd-help', 'SKILL.md');
+    assert.ok(
+      fs.existsSync(skillPath),
+      `Codex install must create ${skillPath} so $gsd-help is discoverable. ` +
+        'Without this, Codex CLI 0.130.0 does not expose any $gsd-* command.',
+    );
+  });
+
+  test('SKILL.md content has frontmatter expected by Codex skill discovery', () => {
+    withCodexHome(codexHome, () => install(true, 'codex'));
+
+    const skillPath = path.join(codexHome, 'skills', 'gsd-help', 'SKILL.md');
+    assert.ok(fs.existsSync(skillPath), 'precondition: SKILL.md exists');
+
+    const content = fs.readFileSync(skillPath, 'utf8');
+    // SKILL.md is YAML frontmatter then body; convertClaudeCommandToCodexSkill
+    // emits at minimum a `name:` field on the leading frontmatter block.
+    assert.ok(
+      content.startsWith('---'),
+      'SKILL.md must begin with YAML frontmatter (---) for Codex discovery',
+    );
+    assert.ok(
+      /^name:\s*["']?gsd-help["']?\s*$/m.test(content),
+      'SKILL.md frontmatter must declare name: gsd-help so $gsd-help resolves',
+    );
+  });
+
+  test('multiple core $gsd-* skills are produced (not just gsd-help)', () => {
+    withCodexHome(codexHome, () => install(true, 'codex'));
+
+    const skillsDir = path.join(codexHome, 'skills');
+    assert.ok(fs.existsSync(skillsDir), 'skills/ directory must exist after install');
+
+    const gsdSkills = fs
+      .readdirSync(skillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('gsd-'))
+      .map((e) => e.name);
+
+    // Lower bound — exact count depends on the current command surface. The
+    // commands/gsd/ directory holds dozens of *.md files; expecting more than
+    // 10 generated skills is a conservative floor that catches "we generated
+    // nothing" or "we only generated one accidentally" regressions.
+    assert.ok(
+      gsdSkills.length >= 10,
+      `Expected >= 10 generated gsd-* skill directories, found ${gsdSkills.length}: ${gsdSkills.join(', ')}`,
+    );
+  });
+
+  test('install preserves existing user skills (does not remove unrelated dirs)', () => {
+    fs.mkdirSync(path.join(codexHome, 'skills', 'custom-user-skill'), { recursive: true });
+    fs.writeFileSync(
+      path.join(codexHome, 'skills', 'custom-user-skill', 'SKILL.md'),
+      '---\nname: custom-user-skill\n---\n# user skill\n',
+    );
+
+    withCodexHome(codexHome, () => install(true, 'codex'));
+
+    const userSkill = path.join(codexHome, 'skills', 'custom-user-skill', 'SKILL.md');
+    assert.ok(
+      fs.existsSync(userSkill),
+      'Codex install must preserve existing non-gsd user skill directories',
+    );
+  });
+});