Merge pull request #3568 from gsd-build/fix/3562-codex-0-130-0-gsd-1-42-2-installs-workfl

fix(3562): generate Codex skill surface so $gsd-* commands resolve on Codex CLI 0.130.0+

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

@@ -10,7 +10,7 @@ const crypto = require('node:crypto');
 const { execFileSync } = require('node:child_process');
 
 const { install, uninstall, parseTomlToObject } = require('../bin/install.js');
-const { createTempDir, cleanup } = require('./helpers.cjs');
+const { createTempDir, cleanup, parseFrontmatter } = require('./helpers.cjs');
 
 const HOOKS_DIST = path.join(__dirname, '..', 'hooks', 'dist');
 const BUILD_HOOKS_SCRIPT = path.join(__dirname, '..', 'scripts', 'build-hooks.js');
@@ -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,16 @@ 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');
+    const frontmatter = parseFrontmatter(refreshedBody);
+    assert.equal(frontmatter.name, 'gsd-help', 'refreshed SKILL.md frontmatter must declare name: gsd-help');
+
+    // 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,120 @@
+'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, parseFrontmatter } = 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');
+    const frontmatter = parseFrontmatter(content);
+    assert.equal(frontmatter.name, 'gsd-help', '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',
+    );
+  });
+});

tests/install-minimal-all-runtimes.test.cjs

@@ -180,8 +180,12 @@ function expectedSkillSet() {
 }
 
 function expectedManifestSkillSet(runtime) {
-  // Codex no longer materializes gsd-* skill files in minimal mode.
-  if (runtime === 'codex') return new Set();
+  // Codex CLI 0.130.0 does not auto-discover commands from workflow / agent
+  // files (#3562) — it only registers commands from skills/<name>/SKILL.md.
+  // Codex installs therefore materialize the same minimal-allowlist skill
+  // surface as the other runtimes; the prior "Codex discovers official
+  // skills directly" assumption (which led to an empty Codex skill set
+  // here) does not hold in practice.
   return expectedSkillSet();
 }
 

tests/installer-migration-install-integration.test.cjs

@@ -209,11 +209,11 @@ function assertFreshInstallContract(runtime, targetDir) {
   );
 
   if (contract.surface === 'flat-skills') {
-    if (runtime === 'codex') {
-      assertNoGsdDirectoryEntries(targetDir, 'skills');
-    } else {
-      assertHasGsdDirectory(targetDir, 'skills');
-    }
+    // Pre-#3562: codex was special-cased to expect zero gsd-* skill dirs
+    // (assumption: Codex auto-discovers from workflows). That assumption
+    // does not hold for Codex CLI 0.130.0 — fresh installs now materialize
+    // the same flat-skills surface as the other runtimes.
+    assertHasGsdDirectory(targetDir, 'skills');
   } else if (contract.surface === 'hermes-skills') {
     assertHasGsdDirectory(targetDir, path.join('skills', 'gsd'));
     assert.ok(