@fission-ai/openspec 1.6.0 → 1.7.0

package/dist/core/update.js

@@ -10,20 +10,21 @@ import ora from 'ora';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { transformToHyphenCommands } from '../utils/command-references.js';
+import { getSkillReferenceTransformer, getTransformerForTool, transformToSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
 import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, } from './shared/index.js';
-import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatCleanupSummary, formatDetectionSummary, getToolsFromLegacyArtifacts, } from './legacy-cleanup.js';
+import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getGlobalConfig } from './global-config.js';
-import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
+import { getProfileWorkflows, ALL_WORKFLOWS, CORE_WORKFLOWS } from './profiles.js';
+import { getOnboardingCommands } from './onboarding-commands.js';
 import { getAvailableTools } from './available-tools.js';
-import { WORKFLOW_TO_SKILL_DIR, getCommandConfiguredTools, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
-import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, } from './migration.js';
+import { WORKFLOW_TO_SKILL_DIR, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
+import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, findLegacyToolMigrations, migrateLegacyToolDirs, describeLegacyMigration, legacyMigrationNotice, keptInPlaceNotice, hasMovableContent, } from './migration.js';
+import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
-const OLD_CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'archive'];
 /**
  * Scans installed workflow artifacts (skills and managed commands) across all configured tools.
  * Returns the union of detected workflow IDs that match ALL_WORKFLOWS.
@@ -41,6 +42,12 @@ export class UpdateCommand {
     constructor(options = {}) {
         this.force = options.force ?? false;
     }
+    /**
+     * Refreshes OpenSpec skills and commands for all configured tools,
+     * regenerating artifacts according to the effective profile and delivery mode.
+     *
+     * @param projectPath - Path to the project root containing the openspec directory
+     */
     async execute(projectPath) {
         const resolvedProjectPath = path.resolve(projectPath);
         const openspecPath = path.join(resolvedProjectPath, OPENSPEC_DIR_NAME);
@@ -48,7 +55,17 @@ export class UpdateCommand {
         if (!await FileSystemUtils.directoryExists(openspecPath)) {
             throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
         }
-        // 2. Perform one-time migration if needed before any legacy upgrade generation.
+        // 2. Migrate OpenSpec-managed skills left in renamed tool directories
+        // (e.g. .kimi -> .kimi-code) so they stay detected and get refreshed,
+        // then perform the one-time profile migration if needed before any
+        // legacy upgrade generation.
+        for (const migration of migrateLegacyToolDirs(resolvedProjectPath)) {
+            if (hasMovableContent(migration)) {
+                console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+            }
+            this.reportKeptInPlace(migration);
+        }
+        const declinedMigrations = await this.offerConsentedLegacyMigrations(resolvedProjectPath);
         // Use detected tool directories to preserve existing opsx skills/commands.
         const detectedTools = getAvailableTools(resolvedProjectPath);
         migrateIfNeededShared(resolvedProjectPath, detectedTools);
@@ -58,27 +75,35 @@ export class UpdateCommand {
         const delivery = globalConfig.delivery ?? 'both';
         const profileWorkflows = getProfileWorkflows(profile, globalConfig.workflows);
         const desiredWorkflows = profileWorkflows.filter((workflow) => ALL_WORKFLOWS.includes(workflow));
-        const shouldGenerateSkills = delivery !== 'commands';
-        const shouldGenerateCommands = delivery !== 'skills';
         // 4. Detect and handle legacy artifacts + upgrade legacy tools using effective config
-        const newlyConfiguredTools = await this.handleLegacyCleanup(resolvedProjectPath, desiredWorkflows, delivery);
+        const legacyUpgrade = await this.handleLegacyCleanup(resolvedProjectPath, desiredWorkflows, delivery);
+        const { newlyConfiguredTools, workflowOverrides: legacyWorkflowOverrides, deferredGlobalCleanup, } = legacyUpgrade;
         // 5. Find configured tools
         const configuredTools = getConfiguredToolsForProfileSync(resolvedProjectPath);
         if (configuredTools.length === 0 && newlyConfiguredTools.length === 0) {
+            if (deferredGlobalCleanup) {
+                await this.performDeferredGlobalPromptCleanup(resolvedProjectPath, deferredGlobalCleanup);
+            }
+            if (declinedMigrations.length > 0) {
+                // Not an unconfigured project — a configured one the user chose to
+                // leave in its former directory. Saying "run init" would be wrong.
+                for (const migration of declinedMigrations) {
+                    console.log(chalk.yellow(`Nothing to update: this project's OpenSpec files are still in ${migration.from}/, ` +
+                        `which OpenSpec no longer writes.`));
+                    console.log(chalk.dim(`Re-run "openspec update" and accept the move to ${migration.to}/ to resume updates.`));
+                }
+                return;
+            }
             console.log(chalk.yellow('No configured tools found.'));
             console.log(chalk.dim('Run "openspec init" to set up tools.'));
             return;
         }
-        // 6. Check version status for all configured tools
-        const commandConfiguredTools = getCommandConfiguredTools(resolvedProjectPath);
-        const commandConfiguredSet = new Set(commandConfiguredTools);
-        const toolStatuses = configuredTools.map((toolId) => {
-            const status = getToolVersionStatus(resolvedProjectPath, toolId, OPENSPEC_VERSION);
-            if (!status.configured && commandConfiguredSet.has(toolId)) {
-                return { ...status, configured: true };
-            }
-            return status;
-        });
+        // 6. Check version status for all configured tools, against the same workflow set
+        //    the generation loop below writes — otherwise a legacy-upgraded tool would be
+        //    fingerprinted against commands it was never given.
+        const toolStatuses = configuredTools.map((toolId) => getToolVersionStatus(resolvedProjectPath, toolId, OPENSPEC_VERSION, {
+            workflows: legacyWorkflowOverrides[toolId] ?? desiredWorkflows,
+        }));
         const statusByTool = new Map(toolStatuses.map((status) => [status.toolId, status]));
         // 7. Smart update detection
         const toolsNeedingVersionUpdate = toolStatuses
@@ -90,30 +115,38 @@ export class UpdateCommand {
             ...toolsNeedingConfigSync,
         ]);
         const toolsUpToDate = toolStatuses.filter((s) => !toolsToUpdateSet.has(s.toolId));
-        if (!this.force && toolsToUpdateSet.size === 0) {
+        if (!this.force && toolsToUpdateSet.size === 0 && newlyConfiguredTools.length === 0) {
+            if (deferredGlobalCleanup) {
+                await this.performDeferredGlobalPromptCleanup(resolvedProjectPath, deferredGlobalCleanup);
+            }
             // All tools are up to date
             this.displayUpToDateMessage(toolStatuses);
             // Still check for new tool directories and extra workflows
             this.detectNewTools(resolvedProjectPath, configuredTools);
             this.displayExtraWorkflowsNote(resolvedProjectPath, configuredTools, desiredWorkflows);
-            this.displayOldCoreCustomProfileNote(profile, globalConfig.workflows);
+            this.displayMissingCoreWorkflowsNote(profile, globalConfig.workflows);
+            this.displaySetupNotes(configuredTools);
             return;
         }
         // 8. Display update plan
         if (this.force) {
             console.log(`Force updating ${configuredTools.length} tool(s): ${configuredTools.join(', ')}`);
         }
+        else if (toolsToUpdateSet.size === 0) {
+            console.log('No additional refresh needed after legacy migration.');
+        }
         else {
             this.displayUpdatePlan([...toolsToUpdateSet], statusByTool, toolsUpToDate);
         }
         console.log();
         // 9. Determine what to generate based on delivery
-        const skillTemplates = shouldGenerateSkills ? getSkillTemplates(desiredWorkflows) : [];
-        const commandContents = shouldGenerateCommands ? getCommandContents(desiredWorkflows) : [];
+        const deliveryIncludesCommands = delivery !== 'skills';
         // 10. Update tools (all if force, otherwise only those needing update)
         const toolsToUpdate = this.force ? configuredTools : [...toolsToUpdateSet];
         const updatedTools = [];
         const failedTools = [];
+        const skillsInvocableCommandSkips = [];
+        const zeroArtifactTools = [];
         let removedCommandCount = 0;
         let removedSkillCount = 0;
         let removedDeselectedCommandCount = 0;
@@ -125,21 +158,32 @@ export class UpdateCommand {
             const spinner = ora(`Updating ${tool.name}...`).start();
             try {
                 const skillsDir = path.join(resolvedProjectPath, tool.skillsDir, 'skills');
+                const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
+                const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                const toolWorkflows = legacyWorkflowOverrides[tool.value] ?? desiredWorkflows;
+                const skillTemplates = getSkillTemplates(toolWorkflows);
+                const commandContents = getCommandContents(toolWorkflows);
                 // Generate skill files if delivery includes skills
                 if (shouldGenerateSkills) {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
-                        // Use hyphen-based command references for tools where filename === command name (oh-my-pi, opencode, pi)
-                        const transformer = (tool.value === 'opencode' || tool.value === 'pi' || tool.value === 'oh-my-pi') ? transformToHyphenCommands : undefined;
+                        const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
-                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsDir, desiredWorkflows);
+                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsDir, toolWorkflows);
                 }
                 // Delete skill directories if delivery is commands-only
-                if (!shouldGenerateSkills) {
+                if (shouldRemoveSkillsForTool(tool.value, delivery)) {
                     removedSkillCount += await this.removeSkillDirs(skillsDir);
+                    // A tool with no command adapter now has zero OpenSpec artifacts;
+                    // say so like init does, rather than deleting its skills silently
+                    // and letting tool detection re-suggest an init that would also
+                    // generate nothing under this delivery setting.
+                    if (!shouldGenerateCommandsForTool(tool.value, delivery)) {
+                        zeroArtifactTools.push(tool.name);
+                    }
                 }
                 // Generate commands if delivery includes commands
                 if (shouldGenerateCommands) {
@@ -150,11 +194,14 @@ export class UpdateCommand {
                             const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(resolvedProjectPath, cmd.path);
                             await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
                         }
-                        removedDeselectedCommandCount += await this.removeUnselectedCommandFiles(resolvedProjectPath, toolId, desiredWorkflows);
+                        removedDeselectedCommandCount += await this.removeUnselectedCommandFiles(resolvedProjectPath, toolId, toolWorkflows);
                     }
                 }
+                else if (deliveryIncludesCommands && resolveCommandSurfaceCapability(tool.value) === 'skills-invocable') {
+                    skillsInvocableCommandSkips.push(tool.value);
+                }
                 // Delete command files if delivery is skills-only
-                if (!shouldGenerateCommands) {
+                if (shouldReconcileCommandFilesForTool(tool.value, delivery)) {
                     removedCommandCount += await this.removeCommandFiles(resolvedProjectPath, toolId);
                 }
                 spinner.succeed(`Updated ${tool.name}`);
@@ -168,6 +215,9 @@ export class UpdateCommand {
                 });
             }
         }
+        if (deferredGlobalCleanup) {
+            await this.performDeferredGlobalPromptCleanup(resolvedProjectPath, deferredGlobalCleanup);
+        }
         // 11. Summary
         console.log();
         if (updatedTools.length > 0) {
@@ -176,26 +226,60 @@ export class UpdateCommand {
         if (failedTools.length > 0) {
             console.log(chalk.red(`✗ Failed: ${failedTools.map(f => `${f.name} (${f.error})`).join(', ')}`));
         }
+        if (skillsInvocableCommandSkips.length > 0) {
+            console.log(chalk.dim(`Commands skipped for: ${skillsInvocableCommandSkips.join(', ')} (uses skills)`));
+        }
         if (removedCommandCount > 0) {
             console.log(chalk.dim(`Removed: ${removedCommandCount} command files (delivery: skills)`));
         }
         if (removedSkillCount > 0) {
             console.log(chalk.dim(`Removed: ${removedSkillCount} skill directories (delivery: commands)`));
         }
+        if (zeroArtifactTools.length > 0) {
+            const names = zeroArtifactTools.join(', ');
+            console.log(chalk.yellow(`No skills or commands remain for ${names}: delivery is set to 'commands' but ` +
+                `${zeroArtifactTools.length === 1 ? 'it supports' : 'they support'} only skills. ` +
+                `Run 'openspec config set delivery both' to generate skills.`));
+        }
         if (removedDeselectedCommandCount > 0) {
             console.log(chalk.dim(`Removed: ${removedDeselectedCommandCount} command files (deselected workflows)`));
         }
         if (removedDeselectedSkillCount > 0) {
             console.log(chalk.dim(`Removed: ${removedDeselectedSkillCount} skill directories (deselected workflows)`));
         }
-        // 12. Show onboarding message for newly configured tools from legacy upgrade
+        // 12. Show onboarding message for newly configured tools from legacy upgrade.
+        // Command tools get the command name their files answer to, skill-only
+        // tools their documented skill invocation, and disagreements fall back to
+        // naming the skill.
         if (newlyConfiguredTools.length > 0) {
+            const referenceFor = (command) => {
+                const neutralForm = `the ${transformToSkillReferences(command).slice(1)} skill`;
+                const forms = new Set(newlyConfiguredTools.map((toolId) => {
+                    if (shouldGenerateCommandsForTool(toolId, delivery)) {
+                        // Name the command the tool's files actually answer to:
+                        // /opsx-<id> where the filename is the command name.
+                        const transformer = getTransformerForTool(toolId, delivery, resolveCommandSurfaceCapability(toolId), resolveCommandInvocation(toolId));
+                        return transformer ? transformer(command) : command;
+                    }
+                    return getSkillReferenceTransformer(toolId)(command);
+                }));
+                return forms.size === 1 ? [...forms][0] : neutralForm;
+            };
+            // Only hint at workflows these tools actually received. A legacy upgrade
+            // can install a narrower set than the profile (inferred Codex prompts).
+            const installedWorkflows = [
+                ...new Set(newlyConfiguredTools.flatMap((toolId) => legacyWorkflowOverrides[toolId] ?? desiredWorkflows)),
+            ];
+            const entries = getOnboardingCommands(installedWorkflows).map(({ command, description }) => [referenceFor(command), description]);
             console.log();
-            console.log(chalk.bold('Getting started:'));
-            console.log('  /opsx:new       Start a new change');
-            console.log('  /opsx:continue  Create the next artifact');
-            console.log('  /opsx:apply     Implement tasks');
-            console.log();
+            if (entries.length > 0) {
+                const width = Math.max(...entries.map(([reference]) => reference.length));
+                console.log(chalk.bold('Getting started:'));
+                for (const [reference, description] of entries) {
+                    console.log(`  ${reference.padEnd(width)}  ${description}`);
+                }
+                console.log();
+            }
             console.log(`Learn more: ${chalk.cyan('https://github.com/Fission-AI/OpenSpec')}`);
         }
         const configuredAndNewTools = [...new Set([...configuredTools, ...newlyConfiguredTools])];
@@ -203,7 +287,8 @@ export class UpdateCommand {
         this.detectNewTools(resolvedProjectPath, configuredAndNewTools);
         // 14. Display note about extra workflows not in profile
         this.displayExtraWorkflowsNote(resolvedProjectPath, configuredAndNewTools, desiredWorkflows);
-        this.displayOldCoreCustomProfileNote(profile, globalConfig.workflows);
+        this.displayMissingCoreWorkflowsNote(profile, globalConfig.workflows);
+        this.displaySetupNotes(configuredAndNewTools);
         // 15. List affected tools
         if (updatedTools.length > 0) {
             const toolDisplayNames = updatedTools;
@@ -240,6 +325,18 @@ export class UpdateCommand {
             console.log(chalk.dim(`Already up to date: ${upToDateNames.join(', ')}`));
         }
     }
+    /**
+     * Shows manual setup notes for configured tools that need extra
+     * configuration before they pick up generated files.
+     */
+    displaySetupNotes(toolIds) {
+        for (const toolId of toolIds) {
+            const tool = AI_TOOLS.find((t) => t.value === toolId);
+            if (tool?.setupNote) {
+                console.log(chalk.yellow(`Setup required for ${tool.name}: ${tool.setupNote}`));
+            }
+        }
+    }
     /**
      * Detects new tool directories that aren't currently configured and displays a hint.
      */
@@ -268,21 +365,23 @@ export class UpdateCommand {
         }
     }
     /**
-     * Suggest opting back into core when a custom profile still matches the old
-     * pre-sync core set. Keep custom profiles user-owned; do not mutate them.
+     * Point out core workflows a custom profile is missing, so releases that
+     * grow CORE_WORKFLOWS stay discoverable. Keep custom profiles user-owned;
+     * do not mutate them.
      */
-    displayOldCoreCustomProfileNote(profile, workflows) {
+    displayMissingCoreWorkflowsNote(profile, workflows) {
         if (profile !== 'custom' || !workflows) {
             return;
         }
         const workflowSet = new Set(workflows);
-        const matchesOldCore = workflowSet.size === OLD_CORE_WORKFLOWS.length &&
-            OLD_CORE_WORKFLOWS.every((workflow) => workflowSet.has(workflow));
-        if (!matchesOldCore) {
+        const missing = CORE_WORKFLOWS.filter((workflow) => !workflowSet.has(workflow));
+        if (missing.length === 0) {
             return;
         }
-        console.log(chalk.dim('Note: The core profile now includes sync. Your custom profile is preserving the old core workflow set.'));
-        console.log(chalk.dim('Run `openspec config profile core` and then `openspec update` to add sync.'));
+        const label = missing.length === 1 ? 'workflow' : 'workflows';
+        const pronoun = missing.length === 1 ? 'it' : 'them';
+        console.log(chalk.dim(`Note: Your custom profile is missing ${missing.length} core ${label}: ${missing.join(', ')}`));
+        console.log(chalk.dim(`Run \`openspec config profile\` to add ${pronoun}, or \`openspec config profile core\` to use the core set.`));
     }
     /**
      * Removes skill directories for workflows when delivery changed to commands-only.
@@ -384,6 +483,72 @@ export class UpdateCommand {
         }
         return removed;
     }
+    /**
+     * Offers to move OpenSpec content out of a renamed tool's former directory
+     * when the old location might still be the live one — today, Windsurf's
+     * `.windsurf/` after the Devin Desktop rebrand.
+     *
+     * Interactive runs are asked, because nothing on disk distinguishes a user
+     * who took the rebrand from one still on a pre-rebrand Windsurf build that
+     * reads only `.windsurf/`. `--force` and non-interactive runs migrate, which
+     * is what an unattended upgrade wants.
+     */
+    /** Surfaces files the move left behind rather than overwriting. */
+    reportKeptInPlace(migration) {
+        const notice = keptInPlaceNotice(migration);
+        if (notice)
+            console.log(chalk.dim(notice));
+    }
+    async offerConsentedLegacyMigrations(projectPath) {
+        const pending = findLegacyToolMigrations(projectPath).filter((m) => m.needsConsent);
+        const declined = [];
+        if (pending.length === 0)
+            return declined;
+        for (const migration of pending) {
+            // Nothing movable: every legacy file differs from its counterpart, so
+            // there is no move to offer. Still say so — silence would leave two
+            // divergent copies the user never hears about.
+            if (!hasMovableContent(migration)) {
+                this.reportKeptInPlace(migration);
+                console.log();
+                continue;
+            }
+            console.log(chalk.yellow(legacyMigrationNotice(migration)));
+            if (!this.force && isInteractive()) {
+                const { confirm } = await import('@inquirer/prompts');
+                let shouldMigrate;
+                try {
+                    shouldMigrate = await confirm({
+                        message: `Move ${describeLegacyMigration(migration)} from ${migration.from}/ to ${migration.to}/?`,
+                        default: true,
+                    });
+                }
+                catch {
+                    // Closed stdin is not consent, and it must not abort the update.
+                    shouldMigrate = false;
+                }
+                if (!shouldMigrate) {
+                    // Say what declining costs. OpenSpec writes the current root now, so
+                    // the files keep working where they are, but OpenSpec stops managing
+                    // them — it no longer looks in the former directory.
+                    console.log(chalk.dim(`Left in place. OpenSpec writes ${migration.to}/ now and will not manage ` +
+                        `${migration.from}/, so those files stay as they are until you move them. ` +
+                        `You will be asked again next run.`));
+                    console.log();
+                    declined.push(migration);
+                    continue;
+                }
+            }
+            for (const applied of migrateLegacyToolDirs(projectPath, [migration.toolId])) {
+                if (hasMovableContent(applied)) {
+                    console.log(chalk.dim(`Migrated ${describeLegacyMigration(applied)}: ${applied.from} → ${applied.to}`));
+                }
+                this.reportKeptInPlace(applied);
+            }
+            console.log();
+        }
+        return declined;
+    }
     /**
      * Detect and handle legacy OpenSpec artifacts.
      * Unlike init, update warns but continues if legacy files found in non-interactive mode.
@@ -393,25 +558,37 @@ export class UpdateCommand {
         // Detect legacy artifacts
         const detection = await detectLegacyArtifacts(projectPath);
         if (!detection.hasLegacyArtifacts) {
-            return []; // No legacy artifacts found
+            return { newlyConfiguredTools: [], workflowOverrides: {} }; // No legacy artifacts found
         }
         // Show what was detected
-        console.log();
-        console.log(formatDetectionSummary(detection));
-        console.log();
+        const immediateSummary = formatDetectionSummary(omitGlobalLegacyPromptFiles(detection));
+        const deferredSummary = formatDeferredGlobalPromptSummary(detection);
+        if (immediateSummary || deferredSummary) {
+            console.log();
+            if (immediateSummary) {
+                console.log(immediateSummary);
+                console.log();
+            }
+            if (deferredSummary) {
+                console.log(deferredSummary);
+                console.log();
+            }
+        }
         const canPrompt = isInteractive();
         if (this.force) {
-            // --force flag: proceed with cleanup automatically
-            await this.performLegacyCleanup(projectPath, detection);
-            // Then upgrade legacy tools to new skills
-            return this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
+            const legacyUpgrade = await this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
+            await this.performImmediateLegacyCleanup(projectPath, detection);
+            return {
+                ...legacyUpgrade,
+                deferredGlobalCleanup: pickGlobalLegacyPromptFiles(detection, detection.globalSlashCommandFiles),
+            };
         }
         if (!canPrompt) {
             // Non-interactive mode without --force: warn and continue
             // (Unlike init, update doesn't abort - user may just want to update skills)
             console.log(chalk.yellow('⚠ Run with --force to auto-cleanup legacy files, or run interactively.'));
             console.log();
-            return [];
+            return { newlyConfiguredTools: [], workflowOverrides: {} };
         }
         // Interactive mode: prompt for confirmation
         const { confirm } = await import('@inquirer/prompts');
@@ -420,14 +597,47 @@ export class UpdateCommand {
             default: true,
         });
         if (shouldCleanup) {
-            await this.performLegacyCleanup(projectPath, detection);
-            // Then upgrade legacy tools to new skills
-            return this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
+            const legacyUpgrade = await this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
+            await this.performImmediateLegacyCleanup(projectPath, detection);
+            return {
+                ...legacyUpgrade,
+                deferredGlobalCleanup: pickGlobalLegacyPromptFiles(detection, detection.globalSlashCommandFiles),
+            };
         }
         else {
             console.log(chalk.dim('Skipping legacy cleanup. Continuing with skill update...'));
             console.log();
-            return [];
+            return { newlyConfiguredTools: [], workflowOverrides: {} };
+        }
+    }
+    /**
+     * Cleans approved repo-local legacy artifacts before configured tools refresh.
+     */
+    async performImmediateLegacyCleanup(projectPath, detection) {
+        const immediateDetection = omitGlobalLegacyPromptFiles(detection);
+        if (immediateDetection.hasLegacyArtifacts) {
+            await this.performLegacyCleanup(projectPath, immediateDetection);
+        }
+    }
+    /**
+     * Cleans approved global Codex prompts after configured tools refresh so newly
+     * installed replacement skills can retire their prompts in the same run.
+     */
+    async performDeferredGlobalPromptCleanup(projectPath, detection) {
+        const availableCodexWorkflows = new Set(scanInstalledWorkflows(projectPath, ['codex']));
+        const removableMatches = getLegacyGlobalPromptMatches(detection)
+            .filter((prompt) => prompt.workflowIds.every((workflowId) => availableCodexWorkflows.has(workflowId)));
+        if (removableMatches.length > 0) {
+            await this.performLegacyCleanup(projectPath, pickGlobalLegacyPromptFiles(detection, removableMatches.map((prompt) => prompt.path)));
+        }
+        const blockedMatches = getLegacyGlobalPromptMatches(detection)
+            .filter((prompt) => !removableMatches.some((match) => match.path === prompt.path));
+        if (blockedMatches.length > 0) {
+            console.log(chalk.yellow('Preserved deferred global prompts without replacement skills:'));
+            for (const prompt of blockedMatches) {
+                console.log(chalk.dim(`  - ${prompt.toolId}: ${prompt.path}`));
+            }
+            console.log();
         }
     }
     /**
@@ -445,14 +655,14 @@ export class UpdateCommand {
         console.log();
     }
     /**
-     * Upgrade legacy tools to new skills system.
-     * Returns array of tool IDs that were newly configured.
+     * Upgrades unconfigured legacy tools into the skills-based setup and carries
+     * workflow overrides for migrations that should mirror legacy Codex prompts.
      */
     async upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery) {
         // Get tools that had legacy artifacts
         const legacyTools = getToolsFromLegacyArtifacts(detection);
         if (legacyTools.length === 0) {
-            return [];
+            return { newlyConfiguredTools: [], workflowOverrides: {} };
         }
         // Get currently configured tools
         const configuredTools = getConfiguredToolsForProfileSync(projectPath);
@@ -460,13 +670,13 @@ export class UpdateCommand {
         // Filter to tools that aren't already configured
         const unconfiguredLegacyTools = legacyTools.filter((t) => !configuredSet.has(t));
         if (unconfiguredLegacyTools.length === 0) {
-            return [];
+            return { newlyConfiguredTools: [], workflowOverrides: {} };
         }
         // Get valid tools (those with skillsDir)
         const validToolIds = new Set(getToolsWithSkillsDir());
         const validUnconfiguredTools = unconfiguredLegacyTools.filter((t) => validToolIds.has(t));
         if (validUnconfiguredTools.length === 0) {
-            return [];
+            return { newlyConfiguredTools: [], workflowOverrides: {} };
         }
         // Show what tools were detected from legacy artifacts
         console.log(chalk.bold('Tools detected from legacy artifacts:'));
@@ -502,15 +712,13 @@ export class UpdateCommand {
             if (selectedTools.length === 0) {
                 console.log(chalk.dim('Skipping tool setup.'));
                 console.log();
-                return [];
+                return { newlyConfiguredTools: [], workflowOverrides: {} };
             }
         }
+        const inferredCodexWorkflows = getLegacyWorkflowIdsForTool(detection, 'codex');
         // Create skills/commands for selected tools using effective profile+delivery.
         const newlyConfigured = [];
-        const shouldGenerateSkills = delivery !== 'commands';
-        const shouldGenerateCommands = delivery !== 'skills';
-        const skillTemplates = shouldGenerateSkills ? getSkillTemplates(desiredWorkflows) : [];
-        const commandContents = shouldGenerateCommands ? getCommandContents(desiredWorkflows) : [];
+        const workflowOverrides = {};
         for (const toolId of selectedTools) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (!tool?.skillsDir)
@@ -518,13 +726,22 @@ export class UpdateCommand {
             const spinner = ora(`Setting up ${tool.name}...`).start();
             try {
                 const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
+                const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
+                const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                const toolWorkflows = (tool.value === 'codex' && inferredCodexWorkflows.length > 0
+                    ? inferredCodexWorkflows
+                    : desiredWorkflows);
+                if (tool.value === 'codex' && inferredCodexWorkflows.length > 0) {
+                    workflowOverrides[tool.value] = inferredCodexWorkflows;
+                }
+                const skillTemplates = getSkillTemplates(toolWorkflows);
+                const commandContents = getCommandContents(toolWorkflows);
                 // Create skill files when delivery includes skills
                 if (shouldGenerateSkills) {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
-                        // Use hyphen-based command references for tools where filename === command name (oh-my-pi, opencode, pi)
-                        const transformer = (tool.value === 'opencode' || tool.value === 'pi' || tool.value === 'oh-my-pi') ? transformToHyphenCommands : undefined;
+                        const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
@@ -551,7 +768,7 @@ export class UpdateCommand {
         if (newlyConfigured.length > 0) {
             console.log();
         }
-        return newlyConfigured;
+        return { newlyConfiguredTools: newlyConfigured, workflowOverrides };
     }
 }
 //# sourceMappingURL=update.js.map

package/dist/core/validation/constants.d.ts

@@ -19,6 +19,9 @@ export declare const VALIDATION_MESSAGES: {
     readonly CHANGE_WHY_TOO_LONG: "Why section should not exceed 1000 characters";
     readonly CHANGE_WHAT_EMPTY: "What Changes section cannot be empty";
     readonly CHANGE_NO_DELTAS: "Change must have at least one delta";
+    readonly CHANGE_SKIP_SPECS_CONFLICT: "skip_specs is set in .openspec.yaml but spec files exist under specs/. Remove skip_specs or delete the delta spec files";
+    readonly CHANGE_SKIP_SPECS_ACCEPTED: "skip_specs is set in .openspec.yaml: change declares no spec-level behavior changes, zero deltas accepted";
+    readonly CHANGE_SKIP_SPECS_INVALID_METADATA: "skip_specs is set but .openspec.yaml is not valid change metadata, so the marker is not honored. Fix the metadata";
     readonly CHANGE_TOO_MANY_DELTAS: "Consider splitting changes with more than 10 deltas";
     readonly DELTA_SPEC_EMPTY: "Spec name cannot be empty";
     readonly DELTA_DESCRIPTION_EMPTY: "Delta description cannot be empty";
@@ -26,7 +29,7 @@ export declare const VALIDATION_MESSAGES: {
     readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Consider breaking it down.";
     readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta description is too brief";
     readonly DELTA_MISSING_REQUIREMENTS: "Delta should include requirements";
-    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
+    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. If this change intentionally modifies no specs (pure refactor, tooling, docs), set \"skip_specs: true\" in the change's .openspec.yaml instead. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
     readonly GUIDE_MISSING_SPEC_SECTIONS: "Missing required sections. Expected headers: \"## Purpose\" and \"## Requirements\". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...";
     readonly GUIDE_MISSING_CHANGE_SECTIONS: "Missing required sections. Expected headers: \"## Why\" and \"## What Changes\". Ensure deltas are documented in specs/ using delta headers.";
     readonly GUIDE_SCENARIO_FORMAT: "Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...";

package/dist/core/validation/constants.js

@@ -23,6 +23,9 @@ export const VALIDATION_MESSAGES = {
     CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
     CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
     CHANGE_NO_DELTAS: 'Change must have at least one delta',
+    CHANGE_SKIP_SPECS_CONFLICT: 'skip_specs is set in .openspec.yaml but spec files exist under specs/. Remove skip_specs or delete the delta spec files',
+    CHANGE_SKIP_SPECS_ACCEPTED: 'skip_specs is set in .openspec.yaml: change declares no spec-level behavior changes, zero deltas accepted',
+    CHANGE_SKIP_SPECS_INVALID_METADATA: 'skip_specs is set but .openspec.yaml is not valid change metadata, so the marker is not honored. Fix the metadata',
     CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
     DELTA_SPEC_EMPTY: 'Spec name cannot be empty',
     DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
@@ -32,7 +35,7 @@ export const VALIDATION_MESSAGES = {
     DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
     DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
     // Guidance snippets (appended to primary messages for remediation)
-    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
+    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. If this change intentionally modifies no specs (pure refactor, tooling, docs), set "skip_specs: true" in the change\'s .openspec.yaml instead. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
     GUIDE_MISSING_SPEC_SECTIONS: 'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
     GUIDE_MISSING_CHANGE_SECTIONS: 'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
     GUIDE_SCENARIO_FORMAT: 'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',