prizmkit 1.1.58 → 1.1.61

package/src/config.js

@@ -31,8 +31,11 @@ import {
   installProjectMemory,
   installPipeline,
   installGitignore,
+  installGitHook,
+  installPrizmkitScripts,
   resolveSkillList,
   resolvePipelineFileList,
+  resolveRuleNamesForRuntime,
 } from './scaffold.js';
 import {
   removeSkillFiles,
@@ -44,11 +47,14 @@ import { detectPlatform } from './detect-platform.js';
 import {
   selectPlatform,
   selectAiCli,
+  selectRuntime,
   selectSkillSuite,
   selectRulesPreset,
   confirmTeamMode,
   confirmPipeline,
 } from './prompts.js';
+import { expandPlatforms, isKnownPlatform, platformLabel, projectMemoryFile } from './platforms.js';
+import { normalizeRuntime, runtimeLabel } from './runtimes.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -57,36 +63,53 @@ const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-
 // Helpers
 // ============================================================
 
+async function removeGeneratedCodexConfig(projectRoot, dryRun) {
+  const configPath = path.join(projectRoot, '.codex', 'config.toml');
+  if (!await fs.pathExists(configPath)) return;
+
+  const content = await fs.readFile(configPath, 'utf8');
+  if (!content.includes('Generated by PrizmKit for Codex CLI project configuration')) {
+    return;
+  }
+
+  if (dryRun) {
+    console.log(chalk.gray('      [dry-run] remove .codex/config.toml'));
+  } else {
+    await fs.remove(configPath);
+    console.log(chalk.red('      ✗ removed .codex/config.toml'));
+  }
+}
+
 /**
  * Detect which platforms are actually installed on filesystem.
  */
 async function detectInstalledPlatforms(projectRoot) {
-  const hasClaude = await fs.pathExists(path.join(projectRoot, '.claude', 'commands'))
-                    || await fs.pathExists(path.join(projectRoot, '.claude', 'agents'));
-  const hasCodeBuddy = await fs.pathExists(path.join(projectRoot, '.codebuddy', 'skills'))
-                       || await fs.pathExists(path.join(projectRoot, '.codebuddy', 'agents'));
+  const hasPlatformFiles = async (dir) => {
+    if (!await fs.pathExists(dir)) return false;
+    try {
+      return (await fs.readdir(dir)).length > 0;
+    } catch {
+      return false;
+    }
+  };
 
+  const hasClaude = await hasPlatformFiles(path.join(projectRoot, '.claude', 'commands'))
+                    || await hasPlatformFiles(path.join(projectRoot, '.claude', 'agents'));
+  const hasCodeBuddy = await hasPlatformFiles(path.join(projectRoot, '.codebuddy', 'skills'))
+                       || await hasPlatformFiles(path.join(projectRoot, '.codebuddy', 'agents'));
+  const hasCodex = await hasPlatformFiles(path.join(projectRoot, '.agents', 'skills'))
+                   || await hasPlatformFiles(path.join(projectRoot, '.codex', 'agents'));
+
+  if (hasClaude && hasCodeBuddy && hasCodex) return 'all';
   if (hasClaude && hasCodeBuddy) return 'both';
+  if (hasCodex) return 'codex';
   if (hasCodeBuddy) return 'codebuddy';
   if (hasClaude) return 'claude';
   return null;
 }
 
-/**
- * Expand a platform string to an array of individual platforms.
- */
-function expandPlatforms(platform) {
-  return platform === 'both' ? ['codebuddy', 'claude'] : [platform];
-}
-
 function getProjectMemoryFile(platform) {
-  if (platform === 'claude') return 'CLAUDE.md';
-  if (platform === 'codebuddy') return 'CODEBUDDY.md';
-  return null;
-}
-
-function getCounterpartPlatform(platform) {
-  return platform === 'claude' ? 'codebuddy' : platform === 'codebuddy' ? 'claude' : null;
+  return projectMemoryFile(platform);
 }
 
 async function migrateProjectMemoryOnPlatformDrop(droppedPlatform, newPlatforms, projectRoot, dryRun) {
@@ -96,10 +119,7 @@ async function migrateProjectMemoryOnPlatformDrop(droppedPlatform, newPlatforms,
   const sourcePath = path.join(projectRoot, sourceFile);
   if (!await fs.pathExists(sourcePath)) return;
 
-  const counterpart = getCounterpartPlatform(droppedPlatform);
-  const targetPlatform = (counterpart && newPlatforms.includes(counterpart))
-    ? counterpart
-    : newPlatforms.find(p => p !== droppedPlatform);
+  const targetPlatform = newPlatforms.find(p => p !== droppedPlatform) || newPlatforms[0];
 
   if (!targetPlatform || targetPlatform === droppedPlatform) return;
 
@@ -138,9 +158,6 @@ async function migrateProjectMemoryOnPlatformDrop(droppedPlatform, newPlatforms,
   console.log(chalk.green(`      ✓ merged ${sourceFile} content into ${targetFile}`));
 }
 
-const platformLabel = (p) => p === 'both' ? 'CodeBuddy + Claude Code'
-  : p === 'codebuddy' ? 'CodeBuddy' : 'Claude Code';
-
 /**
  * Remove all PrizmKit-owned platform-specific files for a single platform.
  * Selective removal — only removes known PrizmKit files, leaves user-created files intact.
@@ -166,15 +183,28 @@ async function removePlatformFiles(platform, projectRoot, manifest, dryRun) {
   }
 
   // Settings
-  const settingsFile = platform === 'claude'
-    ? path.join(projectRoot, '.claude', 'settings.json')
-    : path.join(projectRoot, '.codebuddy', 'settings.json');
-  if (await fs.pathExists(settingsFile)) {
-    if (dryRun) {
-      console.log(chalk.gray(`      [dry-run] remove ${path.relative(projectRoot, settingsFile)}`));
-    } else {
-      await fs.remove(settingsFile);
-      console.log(chalk.red(`      ✗ removed ${path.relative(projectRoot, settingsFile)}`));
+  if (platform === 'codex') {
+    await removeGeneratedCodexConfig(projectRoot, dryRun);
+    const legacySettingsFile = path.join(projectRoot, '.codex', 'prizmkit-settings.json');
+    if (await fs.pathExists(legacySettingsFile)) {
+      if (dryRun) {
+        console.log(chalk.gray('      [dry-run] remove .codex/prizmkit-settings.json (legacy)'));
+      } else {
+        await fs.remove(legacySettingsFile);
+        console.log(chalk.red('      ✗ removed .codex/prizmkit-settings.json (legacy)'));
+      }
+    }
+  } else {
+    const settingsFile = platform === 'claude'
+      ? path.join(projectRoot, '.claude', 'settings.json')
+      : path.join(projectRoot, '.codebuddy', 'settings.json');
+    if (await fs.pathExists(settingsFile)) {
+      if (dryRun) {
+        console.log(chalk.gray(`      [dry-run] remove ${path.relative(projectRoot, settingsFile)}`));
+      } else {
+        await fs.remove(settingsFile);
+        console.log(chalk.red(`      ✗ removed ${path.relative(projectRoot, settingsFile)}`));
+      }
     }
   }
 
@@ -200,10 +230,21 @@ async function removePlatformFiles(platform, projectRoot, manifest, dryRun) {
         console.log(chalk.red('      ✗ removed ~/.codebuddy/teams/prizm-dev-team/'));
       }
     }
+  } else if (platform === 'codex') {
+    const teamInfo = path.join(projectRoot, '.codex', 'team-info.json');
+    if (await fs.pathExists(teamInfo)) {
+      if (dryRun) {
+        console.log(chalk.gray('      [dry-run] remove .codex/team-info.json'));
+      } else {
+        await fs.remove(teamInfo);
+        console.log(chalk.red('      ✗ removed .codex/team-info.json'));
+      }
+    }
   }
 
   // Project memory file
-  const memoryFile = platform === 'claude' ? 'CLAUDE.md' : 'CODEBUDDY.md';
+  const memoryFile = projectMemoryFile(platform);
+  if (!memoryFile) return;
   const memoryPath = path.join(projectRoot, memoryFile);
   if (await fs.pathExists(memoryPath)) {
     if (dryRun) {
@@ -225,6 +266,48 @@ async function removePlatformFiles(platform, projectRoot, manifest, dryRun) {
         console.log(chalk.red('      ✗ removed .claude/command-assets/'));
       }
     }
+  } else if (platform === 'codex') {
+    const agentsSkillsDir = path.join(projectRoot, '.agents', 'skills');
+    if (await fs.pathExists(agentsSkillsDir)) {
+      if (dryRun) {
+        console.log(chalk.gray('      [dry-run] remove .agents/skills/ if empty'));
+      } else if ((await fs.readdir(agentsSkillsDir)).length === 0) {
+        await fs.remove(agentsSkillsDir);
+        console.log(chalk.red('      ✗ removed .agents/skills/'));
+      }
+    }
+    const agentsDir = path.join(projectRoot, '.agents');
+    if (await fs.pathExists(agentsDir)) {
+      if (dryRun) {
+        console.log(chalk.gray('      [dry-run] remove .agents/ if empty'));
+      } else if ((await fs.readdir(agentsDir)).length === 0) {
+        await fs.remove(agentsDir);
+        console.log(chalk.red('      ✗ removed .agents/'));
+      }
+    }
+
+    const codexAgentsDir = path.join(projectRoot, '.codex', 'agents');
+    if (await fs.pathExists(codexAgentsDir)) {
+      if (dryRun) {
+        console.log(chalk.gray('      [dry-run] remove .codex/agents/ if empty'));
+      } else if ((await fs.readdir(codexAgentsDir)).length === 0) {
+        await fs.remove(codexAgentsDir);
+        console.log(chalk.red('      ✗ removed .codex/agents/'));
+      }
+    }
+
+    const codexDir = path.join(projectRoot, '.codex');
+    if (await fs.pathExists(codexDir)) {
+      if (dryRun) {
+        console.log(chalk.gray('      [dry-run] remove .codex/ if empty'));
+      } else {
+        const remaining = await fs.readdir(codexDir);
+        if (remaining.length === 0) {
+          await fs.remove(codexDir);
+          console.log(chalk.red('      ✗ removed .codex/'));
+        }
+      }
+    }
   }
 }
 
@@ -265,11 +348,13 @@ export async function runConfig(directory, options = {}) {
     try { userConfig = await fs.readJSON(configPath); } catch { /* ignore */ }
   }
 
-  // Filesystem-based platform detection (overrides manifest)
-  const detectedPlatform = await detectInstalledPlatforms(projectRoot) || oldManifest.platform || 'claude';
+  // Existing manifests are the source of truth. Filesystem detection is only a
+  // legacy fallback for manifests created before platform was recorded.
+  const detectedPlatform = oldManifest.platform || await detectInstalledPlatforms(projectRoot) || 'claude';
 
   const currentConfig = {
     platform: detectedPlatform,
+    runtime: normalizeRuntime(oldManifest.runtime || 'unix'),
     suite: oldManifest.suite || 'core',
     rules: oldManifest.options?.rules || 'recommended',
     team: oldManifest.options?.team ?? true,
@@ -277,9 +362,14 @@ export async function runConfig(directory, options = {}) {
     aiCli: userConfig.ai_cli || oldManifest.options?.aiCli || '',
   };
 
+  if (options.platform !== undefined && !isKnownPlatform(options.platform)) {
+    throw new Error(`Unknown platform "${options.platform}". Expected codebuddy, claude, codex, or all.`);
+  }
+
   // Display current config
   console.log(chalk.bold('  当前配置:'));
   console.log(`    平台:     ${chalk.cyan(platformLabel(currentConfig.platform))}`);
+  console.log(`    运行系统: ${chalk.cyan(runtimeLabel(currentConfig.runtime))}`);
   console.log(`    AI CLI:   ${currentConfig.aiCli ? chalk.cyan(currentConfig.aiCli) : chalk.gray('(未设置)')}`);
   console.log(`    技能套件: ${chalk.cyan(currentConfig.suite)}`);
   console.log(`    规则:     ${chalk.cyan(currentConfig.rules)}`);
@@ -290,18 +380,20 @@ export async function runConfig(directory, options = {}) {
   // ── Phase 2: PROMPT for new config ───────────────────────────────────────
 
   let newConfig;
+  const optionRuntime = options.runtime !== undefined ? normalizeRuntime(options.runtime) : undefined;
 
   if (nonInteractive) {
     // Non-interactive: only change what's explicitly specified via CLI options
-    if (!options.platform && !options.skills && !options.rules
+    if (!options.platform && !options.skills && !options.rules && options.runtime === undefined
         && options.aiCli === undefined && options.team === undefined && options.pipeline === undefined) {
       console.log(chalk.yellow('  ⚠ 非交互式模式下未指定任何变更。'));
-      console.log(chalk.gray('    使用 --platform, --skills, --rules, --ai-cli, --team/--no-team, --pipeline/--no-pipeline'));
+      console.log(chalk.gray('    使用 --platform, --runtime, --skills, --rules, --ai-cli, --team/--no-team, --pipeline/--no-pipeline'));
       return;
     }
 
     newConfig = {
       platform: options.platform || currentConfig.platform,
+      runtime: optionRuntime || currentConfig.runtime,
       suite: options.skills || currentConfig.suite,
       rules: options.rules || currentConfig.rules,
       team: options.team !== undefined ? options.team : currentConfig.team,
@@ -315,6 +407,7 @@ export async function runConfig(directory, options = {}) {
     try {
       console.log(chalk.bold('  选择新配置（按 Enter 保持当前值）:\n'));
 
+      const newRuntime = optionRuntime || await selectRuntime(currentConfig.runtime);
       const newPlatform = await selectPlatform(currentConfig.platform, detected);
       const newAiCli = await selectAiCli(currentConfig.aiCli, detected);
 
@@ -326,6 +419,7 @@ export async function runConfig(directory, options = {}) {
 
       newConfig = {
         platform: newPlatform,
+        runtime: newRuntime,
         suite: newSuite,
         rules: newRules,
         team: newTeam,
@@ -341,12 +435,19 @@ export async function runConfig(directory, options = {}) {
     }
   }
 
+  if (!isKnownPlatform(newConfig.platform)) {
+    throw new Error(`Unknown platform "${newConfig.platform}". Expected codebuddy, claude, codex, or all.`);
+  }
+
   // ── Phase 3: COMPUTE DIFF ────────────────────────────────────────────────
 
   const changes = [];
   if (newConfig.platform !== currentConfig.platform) {
     changes.push(`平台: ${platformLabel(currentConfig.platform)} → ${platformLabel(newConfig.platform)}`);
   }
+  if (newConfig.runtime !== currentConfig.runtime) {
+    changes.push(`运行系统: ${runtimeLabel(currentConfig.runtime)} → ${runtimeLabel(newConfig.runtime)}`);
+  }
   if (newConfig.aiCli !== currentConfig.aiCli) {
     changes.push(`AI CLI: ${currentConfig.aiCli || '(未设置)'} → ${newConfig.aiCli || '(未设置)'}`);
   }
@@ -419,9 +520,8 @@ export async function runConfig(directory, options = {}) {
   const agentsDir = getAgentsDir();
   const newAgentFiles = (await fs.readdir(agentsDir)).filter(f => f.endsWith('.md'));
   const rulesMeta = await loadRulesMetadata();
-  const rulesPresetDef = rulesMeta.presets[newConfig.rules] || rulesMeta.presets.recommended;
-  const newRuleFiles = (rulesPresetDef?.rules || []).map(name => `${name}.md`);
-  const newPipelineFiles = newConfig.pipeline ? resolvePipelineFileList() : [];
+  const newRuleFiles = resolveRuleNamesForRuntime(rulesMeta, newConfig.rules, newConfig.runtime).map(name => `${name}.md`);
+  const newPipelineFiles = newConfig.pipeline ? resolvePipelineFileList(newConfig.runtime) : [];
 
   // 5a. Migrate project memory before removing dropped platforms
   for (const p of platformsToRemove) {
@@ -434,13 +534,15 @@ export async function runConfig(directory, options = {}) {
     await removePlatformFiles(p, projectRoot, oldManifest, false);
   }
 
-  // 5c. Handle skill/rule diff for existing platforms (suite or rules changed)
-  if (newConfig.suite !== currentConfig.suite || newConfig.rules !== currentConfig.rules) {
+  // 5c. Handle skill/rule diff for existing platforms (suite, rules, or runtime changed)
+  if (newConfig.suite !== currentConfig.suite
+      || newConfig.rules !== currentConfig.rules
+      || newConfig.runtime !== currentConfig.runtime) {
     const newTempManifest = buildManifest({
       version: pkg.version, platform: newConfig.platform, suite: newConfig.suite,
       skills: newSkillList, agents: newAgentFiles, rules: newRuleFiles,
       pipeline: newPipelineFiles, team: newConfig.team, aiCli: newConfig.aiCli,
-      rulesPreset: newConfig.rules, extras: oldManifest?.files?.extras || [],
+      runtime: newConfig.runtime, rulesPreset: newConfig.rules, extras: oldManifest?.files?.extras || [],
     });
     const diff = diffManifest(oldManifest, newTempManifest);
 
@@ -460,6 +562,7 @@ export async function runConfig(directory, options = {}) {
   // 5d. Install/update files for new + existing platforms
   const allTargetPlatforms = [...platformsToAdd, ...platformsToUpdate];
   const needsReinstall = newConfig.platform !== currentConfig.platform
+    || newConfig.runtime !== currentConfig.runtime
     || newConfig.suite !== currentConfig.suite
     || newConfig.rules !== currentConfig.rules
     || newConfig.team !== currentConfig.team;
@@ -471,13 +574,13 @@ export async function runConfig(directory, options = {}) {
       console.log(chalk.bold(`\n  ${isNew ? '安装' : '更新'} ${platformLabel(p)} 环境...\n`));
 
       console.log(chalk.blue('    Skills:'));
-      await installSkills(p, newSkillList, projectRoot, false);
+      await installSkills(p, newSkillList, projectRoot, false, newConfig.runtime);
 
       console.log(chalk.blue('\n    Agents:'));
       await installAgents(p, projectRoot, false);
 
       console.log(chalk.blue('\n    Settings & Rules:'));
-      await installSettings(p, projectRoot, { pipeline: newConfig.pipeline, rules: newConfig.rules }, false);
+      await installSettings(p, projectRoot, { pipeline: newConfig.pipeline, rules: newConfig.rules }, false, newConfig.runtime);
 
       if (isNew) {
         console.log(chalk.blue('\n    Project Memory:'));
@@ -492,10 +595,13 @@ export async function runConfig(directory, options = {}) {
   }
 
   // 5e. Pipeline changes
-  if (newConfig.pipeline !== currentConfig.pipeline) {
+  if (newConfig.pipeline !== currentConfig.pipeline || (newConfig.pipeline && newConfig.runtime !== currentConfig.runtime)) {
     if (newConfig.pipeline) {
       console.log(chalk.blue('\n    安装 Pipeline:'));
-      await installPipeline(projectRoot, false);
+      await installPipeline(projectRoot, false, {
+        runtime: newConfig.runtime,
+        previousRuntime: currentConfig.runtime,
+      });
     } else {
       console.log(chalk.blue('\n    移除 Pipeline 框架文件（保留 state/）:'));
       const oldPipelineFiles = oldManifest?.files?.pipeline || [];
@@ -509,7 +615,16 @@ export async function runConfig(directory, options = {}) {
   console.log(chalk.blue('\n    Gitignore:'));
   await installGitignore(projectRoot, { pipeline: newConfig.pipeline }, false);
 
-  // 5g. Update .prizmkit/config.json (ai_cli)
+  // 5g. Runtime-aware git hook and PrizmKit helper scripts
+  if (newConfig.runtime !== currentConfig.runtime) {
+    console.log(chalk.blue('\n    Git Hook:'));
+    await installGitHook(projectRoot, false, newConfig.runtime);
+
+    console.log(chalk.blue('\n    PrizmKit Scripts:'));
+    await installPrizmkitScripts(projectRoot, false, newConfig.runtime);
+  }
+
+  // 5h. Update .prizmkit/config.json (ai_cli)
   if (newConfig.aiCli !== currentConfig.aiCli) {
     const prizmkitDir = path.join(projectRoot, '.prizmkit');
     await fs.ensureDir(prizmkitDir);
@@ -530,6 +645,7 @@ export async function runConfig(directory, options = {}) {
   const newManifest = buildManifest({
     version: pkg.version,
     platform: newConfig.platform,
+    runtime: newConfig.runtime,
     suite: newConfig.suite,
     skills: newSkillList,
     agents: newAgentFiles,
@@ -559,6 +675,7 @@ export async function runConfig(directory, options = {}) {
 
   console.log(chalk.gray('  新配置:'));
   console.log(chalk.gray(`    平台:     ${platformLabel(newConfig.platform)}`));
+  console.log(chalk.gray(`    运行系统: ${runtimeLabel(newConfig.runtime)}`));
   console.log(chalk.gray(`    AI CLI:   ${newConfig.aiCli || '(未设置)'}`));
   console.log(chalk.gray(`    技能套件: ${newConfig.suite}`));
   console.log(chalk.gray(`    规则:     ${newConfig.rules}`));

package/src/detect-platform.js

@@ -4,11 +4,12 @@
  */
 
 import { execFileSync } from 'child_process';
+import os from 'os';
 
 /**
  * 允许检测的命令白名单（仅用于 which 检测）
  */
-const ALLOWED_COMMANDS = ['cbc', 'claude'];
+const ALLOWED_COMMANDS = ['cbc', 'claude', 'codex'];
 
 /**
  * 检查命令是否存在于 PATH 中
@@ -18,7 +19,8 @@ function commandExists(cmd) {
     throw new Error(`Unknown command: ${cmd}`);
   }
   try {
-    execFileSync('which', [cmd], { stdio: 'ignore' });
+    const isWindows = os.platform() === 'win32';
+    execFileSync(isWindows ? 'where.exe' : 'which', [cmd], { stdio: 'ignore' });
     return true;
   } catch {
     return false;
@@ -31,26 +33,30 @@ function commandExists(cmd) {
  * 注意：platform 控制目录结构（.codebuddy/ 或 .claude/），
  *       suggestedCli 是实际运行的可执行命令，二者相互独立。
  *
- * @returns {{ cbc: boolean, claude: boolean, claudeInternal: boolean, suggested: string, suggestedCli: string }}
+ * @returns {{ cbc: boolean, claude: boolean, codex: boolean, suggested: string, suggestedCli: string }}
  */
 export function detectPlatform() {
   const cbc = commandExists('cbc');
   const claude = commandExists('claude');
+  const codex = commandExists('codex');
 
-  // platform 建议：基于目录结构，优先 both
+  // platform 建议：基于目录结构
   let suggested = 'codebuddy';
-  if ((cbc) && (claude)) {
-    suggested = 'both';
+  if (cbc && claude && codex) {
+    suggested = 'all';
+  } else if (codex && !cbc && !claude) {
+    suggested = 'codex';
   } else if ((claude) && !cbc) {
     suggested = 'claude';
   } else if (cbc && !claude) {
     suggested = 'codebuddy';
   }
 
-  // CLI 命令建议：优先 cbc，其次 claude-internal，再次 claude
+  // CLI 命令建议：优先 cbc，其次 claude，再次 codex
   let suggestedCli = '';
   if (cbc) suggestedCli = 'cbc';
   else if (claude) suggestedCli = 'claude';
+  else if (codex) suggestedCli = 'codex';
 
-  return { cbc, claude, suggested, suggestedCli };
-}
+  return { cbc, claude, codex, suggested, suggestedCli };
+}

package/src/external-skills.js

@@ -7,20 +7,21 @@
  *   - Install all:  installs all skills from a repo (e.g. pbakaus/impeccable)
  *
  * When run non-interactively (stdio: 'pipe'), npx skills writes canonical
- * .agents/skills/<name>/SKILL.md files. We copy those to the selected
- * platform dir(s), then clean up .agents/ and skills-lock.json.
+ * .agents/skills/<name>/SKILL.md files. Codex uses that location directly;
+ * other platforms get copied into their platform-specific skill directories.
  */
 
 import { execSync } from 'node:child_process';
 import path from 'path';
 import fs from 'fs-extra';
+import { expandPlatforms } from './platforms.js';
 
 /**
  * @param {Object} skill        - Skill definition from external_skills.known
  *   skill.repo       {string}  - GitHub short ref (e.g. "pbakaus/impeccable") or full URL
  *   skill.name       {string}  - Skill name (used for display / single-skill mode)
  *   skill.installAll {boolean} - If true, install all skills from the repo
- * @param {string} platform     - 'claude' | 'codebuddy' | 'both'
+ * @param {string} platform     - 'claude' | 'codebuddy' | 'codex' | 'all' ('both' supported only for legacy manifests)
  * @param {string} projectRoot  - Target project root
  * @param {boolean} dryRun
  */
@@ -64,6 +65,9 @@ export async function installExternalSkill(skill, platform, projectRoot, dryRun)
       for (const skillName of skillDirs) {
         const srcDir = path.join(agentsSkillsDir, skillName);
         const destDir = path.join(targetDir, skillName);
+        if (path.resolve(srcDir) === path.resolve(destDir)) {
+          continue;
+        }
         await fs.remove(destDir).catch(() => {});
         await fs.copy(srcDir, destDir);
       }
@@ -79,14 +83,20 @@ export async function installExternalSkill(skill, platform, projectRoot, dryRun)
 
     for (const targetDir of getTargetDirs(platform, projectRoot)) {
       const skillDir = path.join(targetDir, skill.name);
+      if (path.resolve(skillDir) === path.resolve(path.dirname(canonicalSkillMd))) {
+        continue;
+      }
       await fs.remove(skillDir).catch(() => {});
       await fs.ensureDir(skillDir);
       await fs.writeFile(path.join(skillDir, 'SKILL.md'), content);
     }
   }
 
-  // Clean up npx skills artifacts after copying
-  await fs.remove(path.join(projectRoot, '.agents')).catch(() => {});
+  // Clean up npx skills artifacts after copying. Preserve .agents/skills when
+  // Codex is selected because it is the official repository skill location.
+  if (!expandPlatforms(platform).includes('codex')) {
+    await fs.remove(path.join(projectRoot, '.agents')).catch(() => {});
+  }
   await fs.remove(path.join(projectRoot, 'skills-lock.json')).catch(() => {});
 }
 
@@ -95,21 +105,23 @@ export async function installExternalSkill(skill, platform, projectRoot, dryRun)
  * Call this once after all external skills have been installed.
  *
  * @param {string} projectRoot
- * @param {string} platform - 'claude' | 'codebuddy' | 'both'
+ * @param {string} platform - 'claude' | 'codebuddy' | 'codex' | 'all' ('both' supported only for legacy manifests)
  */
 export async function cleanExternalSkillArtifacts(projectRoot, platform) {
   const keepDirs = new Set(
     getTargetDirs(platform, projectRoot).map(d => path.resolve(d))
   );
 
+  const selectedPlatforms = expandPlatforms(platform);
   const dirsToCheck = [
-    '.agents',
+    selectedPlatforms.includes('codex') ? null : '.agents',
     '.agent',
     '.trae',
     'skills',
     '.claude/skills',
     '.codebuddy/skills',
-  ];
+    '.codex/skills',
+  ].filter(Boolean);
 
   for (const dir of dirsToCheck) {
     const abs = path.join(projectRoot, dir);
@@ -135,7 +147,7 @@ export async function cleanExternalSkillArtifacts(projectRoot, platform) {
   }
 
   // Remove empty parent dirs left behind (e.g. .codebuddy/ after removing .codebuddy/skills)
-  const parentDirs = ['.claude', '.codebuddy', '.trae', '.agent'];
+  const parentDirs = ['.claude', '.codebuddy', '.codex', '.trae', '.agent'];
   for (const dir of parentDirs) {
     const abs = path.join(projectRoot, dir);
     if (!await fs.pathExists(abs)) continue;
@@ -155,14 +167,9 @@ export async function cleanExternalSkillArtifacts(projectRoot, platform) {
 }
 
 function getTargetDirs(platform, projectRoot) {
-  if (platform === 'both') {
-    return [
-      path.join(projectRoot, '.claude', 'skills'),
-      path.join(projectRoot, '.codebuddy', 'skills'),
-    ];
-  }
-  if (platform === 'codebuddy') {
-    return [path.join(projectRoot, '.codebuddy', 'skills')];
-  }
-  return [path.join(projectRoot, '.claude', 'skills')];
+  return expandPlatforms(platform).map(p => {
+    if (p === 'codebuddy') return path.join(projectRoot, '.codebuddy', 'skills');
+    if (p === 'codex') return path.join(projectRoot, '.agents', 'skills');
+    return path.join(projectRoot, '.claude', 'skills');
+  });
 }