@fission-ai/openspec 1.6.0 → 1.8.0

package/dist/core/init.js

@@ -12,18 +12,21 @@ import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { classifyOpenSpecDir, storePointerProblem } from './project-config.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
-import { transformToHyphenCommands } from '../utils/command-references.js';
-import { AI_TOOLS, OPENSPEC_DIR_NAME, } from './config.js';
+import { getSkillReferenceTransformer, getTransformerForTool, usesNaturalLanguageSkillReferences } from '../utils/command-references.js';
+import { AI_TOOLS, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
 import { PALETTE } from './styles/palette.js';
 import { isInteractive } from '../utils/interactive.js';
 import { serializeConfig } from './config-prompts.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
-import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatCleanupSummary, formatDetectionSummary, } from './legacy-cleanup.js';
-import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandContents, generateSkillContent, } from './shared/index.js';
+import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatCleanupSummary, formatDeferredGlobalPromptSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, omitGlobalLegacyPromptFiles, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
+import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandContents, generateSkillContent, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/index.js';
 import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
 import { getAvailableTools } from './available-tools.js';
-import { migrateIfNeeded } from './migration.js';
+import { writeSharedSkillTarget } from './shared-skill-target.js';
+import { migrateIfNeeded, migrateLegacyToolDirs, describeLegacyMigration, keptInPlaceNotice, hasMovableContent, scanInstalledWorkflows as scanInstalledWorkflowsShared } from './migration.js';
+import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
+import { writeCopilotCloudFiles, readCopilotCloudOptIn, hasExistingManagedCloudFiles, persistCopilotCloudOptIn, removeCopilotCloudFiles, findUnmanagedCloudFiles, listManagedCloudFiles, } from './github-copilot/cloud-agent.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
 // -----------------------------------------------------------------------------
@@ -56,11 +59,15 @@ export class InitCommand {
     force;
     interactiveOption;
     profileOverride;
+    animation;
+    copilotCloudOption;
     constructor(options = {}) {
         this.toolsArg = options.tools;
         this.force = options.force ?? false;
         this.interactiveOption = options.interactive;
         this.profileOverride = options.profile;
+        this.animation = options.animation ?? true;
+        this.copilotCloudOption = options.copilotCloud;
     }
     async execute(targetPath) {
         const projectPath = path.resolve(targetPath);
@@ -91,36 +98,104 @@ export class InitCommand {
             }
         }
         // Check for legacy artifacts and handle cleanup
-        await this.handleLegacyCleanup(projectPath, extendMode);
+        const deferredLegacyCleanup = await this.handleLegacyCleanup(projectPath, extendMode);
+        // Migrate OpenSpec-managed skills left in renamed tool directories
+        // (e.g. .kimi -> .kimi-code) before detection so they stay recognized.
+        migrateLegacyToolDirs(projectPath);
         // Detect available tools in the project (task 7.1)
         const detectedTools = getAvailableTools(projectPath);
         // Migration check: migrate existing projects to profile system (task 7.3)
         if (extendMode) {
             migrateIfNeeded(projectPath, detectedTools);
         }
+        // Validate profile override early so invalid values fail before tool setup.
+        // The resolved value is consumed later when generation reads effective config.
+        // This runs ahead of the welcome screen so an invalid --profile does not make
+        // the user press Enter before seeing the error.
+        this.resolveProfileOverride();
         // Show animated welcome screen (interactive mode only)
         const canPrompt = this.canPromptInteractively();
         if (canPrompt) {
             const { showWelcomeScreen } = await import('../ui/welcome-screen.js');
-            await showWelcomeScreen();
+            await showWelcomeScreen(this.getActiveWorkflows(), { animate: this.animation });
         }
-        // Validate profile override early so invalid values fail before tool setup.
-        // The resolved value is consumed later when generation reads effective config.
-        this.resolveProfileOverride();
         // Get tool states before processing
         const toolStates = getToolStates(projectPath);
         // Get tool selection (pass detected tools for pre-selection)
         const selectedToolIds = await this.getSelectedTools(toolStates, extendMode, detectedTools, projectPath);
         // Validate selected tools
-        const validatedTools = this.validateTools(selectedToolIds, toolStates);
+        const validatedTools = this.validateTools(selectedToolIds, toolStates, projectPath);
+        // Selecting a renamed tool is consent to leave its former directory:
+        // init is about to write the current one, and leaving OpenSpec content
+        // behind would give the user two installs of the same tool.
+        for (const migration of migrateLegacyToolDirs(projectPath, validatedTools.map((tool) => tool.value))) {
+            if (hasMovableContent(migration)) {
+                console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+            }
+            const kept = keptInPlaceNotice(migration);
+            if (kept)
+                console.log(chalk.dim(kept));
+        }
+        // Decide whether to generate GitHub Copilot cloud files. This is opt-in
+        // (see cloud-agent.ts): selecting the Copilot tool no longer silently
+        // writes a GitHub Actions workflow into the user's .github/. The decision
+        // is made before generation so the write can be gated, and persisted after
+        // config.yaml exists so future non-interactive updates honor it.
+        const copilotDecision = await this.resolveCopilotCloudDecision(projectPath, validatedTools);
         // Create directory structure and config
         await this.createDirectoryStructure(openspecPath, extendMode);
         // Generate skills and commands for each tool
-        const results = await this.generateSkillsAndCommands(projectPath, validatedTools);
+        const results = await this.generateSkillsAndCommands(projectPath, validatedTools, copilotDecision.write);
+        // Legacy cleanup was deferred to avoid interfering with skill/command generation;
+        // now that outputs are written, finalize the cleanup (e.g. remove stale files).
+        if (deferredLegacyCleanup) {
+            await this.finalizeDeferredLegacyCleanup(projectPath, deferredLegacyCleanup);
+        }
         // Create config.yaml if needed
         const configStatus = await this.createConfig(openspecPath, extendMode);
+        // Persist an explicit Copilot cloud decision so `openspec update` (which
+        // never prompts) honors it. Best-effort: a config-write failure must not
+        // fail an otherwise-successful init.
+        if (copilotDecision.persist !== undefined) {
+            try {
+                await persistCopilotCloudOptIn(projectPath, copilotDecision.persist);
+            }
+            catch {
+                // Non-fatal: the files (if any) were still written correctly.
+            }
+        }
+        // An explicit opt-out means "no cloud files here": clean up any that a
+        // previous run (or an older OpenSpec) generated. Only OpenSpec-managed
+        // files are removed — a user-customized file is preserved.
+        let copilotRemoved = 0;
+        if (copilotDecision.optedOut) {
+            try {
+                copilotRemoved = await removeCopilotCloudFiles(projectPath);
+            }
+            catch {
+                // Non-fatal: removal targets files from a prior run; a failure here
+                // just leaves them for the next `openspec update` to clean up.
+            }
+        }
+        // Report the cloud outcome from what is actually on disk after the write,
+        // not from the decision alone: writing over a user-owned file is a no-op,
+        // and the alternate-agent path can remove a managed file — so list only
+        // managed files that exist, and separately flag any left-untouched ones.
+        const copilotSucceeded = [...results.createdTools, ...results.refreshedTools].some((tool) => tool.value === 'github-copilot');
+        const wroteCloud = copilotDecision.write && copilotSucceeded;
+        const copilotPresent = wroteCloud ? await listManagedCloudFiles(projectPath) : [];
+        const copilotCollisions = wroteCloud ? await findUnmanagedCloudFiles(projectPath) : [];
         // Display success message
-        this.displaySuccessMessage(projectPath, validatedTools, results, configStatus);
+        this.displaySuccessMessage(projectPath, validatedTools, results, configStatus, {
+            write: copilotDecision.write,
+            skippedUndecided: copilotDecision.skippedUndecided,
+            present: copilotPresent,
+            collisions: copilotCollisions,
+            removed: copilotRemoved,
+        });
+        if (results.failedTools.length > 0) {
+            throw new Error(`OpenSpec setup failed for: ${results.failedTools.map((tool) => tool.name).join(', ')}`);
+        }
     }
     // ═══════════════════════════════════════════════════════════
     // VALIDATION & SETUP
@@ -140,6 +215,59 @@ export class InitCommand {
             return false;
         return isInteractive({ interactive: this.interactiveOption });
     }
+    /**
+     * Decide whether to generate GitHub Copilot cloud files, and whether to
+     * persist that decision. Precedence:
+     *   1. `--copilot-cloud` / `--no-copilot-cloud` flag (explicit this run)
+     *   2. persisted opt-in in config.yaml
+     *   3. managed files already present (migration for pre-opt-in projects)
+     *   4. interactive confirm (default No)
+     *   5. non-interactive with no signal: skip, and don't persist a default
+     *
+     * @returns `write` — generate the files this run; `persist` — value to write
+     *   back to config (undefined = leave config untouched); `optedOut` — the user
+     *   explicitly declined, so any already-generated managed files should be
+     *   removed; `skippedUndecided` — selected but no signal and couldn't ask, so
+     *   the caller can hint that the opt-in exists.
+     */
+    async resolveCopilotCloudDecision(projectPath, tools) {
+        const copilotSelected = tools.some((tool) => tool.value === 'github-copilot');
+        if (!copilotSelected) {
+            // A flag that can't apply is a likely mistake — say so rather than no-op.
+            if (this.copilotCloudOption !== undefined) {
+                console.log(chalk.yellow('--copilot-cloud/--no-copilot-cloud was ignored because the github-copilot tool was not selected.'));
+            }
+            return { write: false, optedOut: false, skippedUndecided: false };
+        }
+        if (this.copilotCloudOption !== undefined) {
+            return {
+                write: this.copilotCloudOption,
+                persist: this.copilotCloudOption,
+                optedOut: !this.copilotCloudOption,
+                skippedUndecided: false,
+            };
+        }
+        const persistedOptIn = readCopilotCloudOptIn(projectPath);
+        if (typeof persistedOptIn === 'boolean') {
+            return { write: persistedOptIn, optedOut: !persistedOptIn, skippedUndecided: false };
+        }
+        if (await hasExistingManagedCloudFiles(projectPath)) {
+            return { write: true, optedOut: false, skippedUndecided: false };
+        }
+        if (this.canPromptInteractively()) {
+            const { confirm } = await import('@inquirer/prompts');
+            const answer = await confirm({
+                message: 'Set up GitHub Copilot cloud coding-agent files? This is for the GitHub-hosted ' +
+                    'Copilot coding agent (github.com), not Copilot in your editor. It writes two files: ' +
+                    '.github/workflows/copilot-setup-steps.yml and .github/agents/openspec.agent.md.',
+                default: false,
+            });
+            return { write: answer, persist: answer, optedOut: !answer, skippedUndecided: false };
+        }
+        // Non-interactive with no explicit signal: don't write, and leave the
+        // decision unpersisted so a later interactive run can still prompt.
+        return { write: false, optedOut: false, skippedUndecided: true };
+    }
     resolveProfileOverride() {
         if (this.profileOverride === undefined) {
             return undefined;
@@ -149,26 +277,50 @@ export class InitCommand {
         }
         throw new Error(`Invalid profile "${this.profileOverride}". Available profiles: core, custom`);
     }
+    /**
+     * Resolves the workflows the effective profile installs, so onboarding output
+     * only mentions commands that will actually exist.
+     */
+    getActiveWorkflows() {
+        const globalCfg = getGlobalConfig();
+        const activeProfile = this.resolveProfileOverride() ?? globalCfg.profile ?? 'core';
+        return [...getProfileWorkflows(activeProfile, globalCfg.workflows)];
+    }
     // ═══════════════════════════════════════════════════════════
     // LEGACY CLEANUP
     // ═══════════════════════════════════════════════════════════
+    /**
+     * Cleans repo-local legacy artifacts immediately and defers global Codex prompt
+     * cleanup until replacement skills have been installed.
+     */
     async handleLegacyCleanup(projectPath, extendMode) {
         // Detect legacy artifacts
         const detection = await detectLegacyArtifacts(projectPath);
         if (!detection.hasLegacyArtifacts) {
-            return; // No legacy artifacts found
+            return null; // No legacy artifacts found
         }
+        const immediateDetection = omitGlobalLegacyPromptFiles(detection);
         // Show what was detected
-        console.log();
-        console.log(formatDetectionSummary(detection));
-        console.log();
+        const immediateSummary = formatDetectionSummary(immediateDetection);
+        if (immediateSummary) {
+            console.log();
+            console.log(immediateSummary);
+            console.log();
+        }
+        // Show which global prompts are deferred — they'll only be removed once
+        // the corresponding replacement skills are installed during generation.
+        const deferredSummary = formatDeferredGlobalPromptSummary(detection);
+        if (deferredSummary) {
+            console.log(deferredSummary);
+            console.log();
+        }
         const canPrompt = this.canPromptInteractively();
         if (this.force || !canPrompt) {
             // --force flag or non-interactive mode: proceed with cleanup automatically.
             // Legacy slash commands are 100% OpenSpec-managed, and config file cleanup
             // only removes markers (never deletes files), so auto-cleanup is safe.
-            await this.performLegacyCleanup(projectPath, detection);
-            return;
+            await this.performImmediateLegacyCleanup(projectPath, detection);
+            return detection.globalSlashCommandFiles.length > 0 ? { detection } : null;
         }
         // Interactive mode: prompt for confirmation
         const { confirm } = await import('@inquirer/prompts');
@@ -181,7 +333,51 @@ export class InitCommand {
             console.log(chalk.dim('Run with --force to skip this prompt, or manually remove legacy files.'));
             process.exit(0);
         }
-        await this.performLegacyCleanup(projectPath, detection);
+        await this.performImmediateLegacyCleanup(projectPath, detection);
+        return detection.globalSlashCommandFiles.length > 0 ? { detection } : null;
+    }
+    /**
+     * Applies the safe subset of legacy cleanup that does not depend on newly
+     * generated Codex skills.
+     */
+    async performImmediateLegacyCleanup(projectPath, detection) {
+        const immediateDetection = omitGlobalLegacyPromptFiles(detection);
+        if (!immediateDetection.hasLegacyArtifacts) {
+            return;
+        }
+        await this.performLegacyCleanup(projectPath, immediateDetection);
+    }
+    /**
+     * Removes only the legacy global Codex prompts whose workflows now have
+     * replacement skills in the project.
+     */
+    async finalizeDeferredLegacyCleanup(projectPath, deferredCleanup) {
+        const availableCodexWorkflows = await this.getInstalledWorkflowsForTool(projectPath, 'codex');
+        const removableMatches = getLegacyGlobalPromptMatches(deferredCleanup.detection)
+            .filter((prompt) => prompt.workflowIds.every((workflowId) => availableCodexWorkflows.has(workflowId)));
+        if (removableMatches.length > 0) {
+            await this.performLegacyCleanup(projectPath, pickGlobalLegacyPromptFiles(deferredCleanup.detection, removableMatches.map((prompt) => prompt.path)));
+        }
+        const blockedMatches = getLegacyGlobalPromptMatches(deferredCleanup.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();
+        }
+    }
+    /**
+     * Reads the currently installed workflow IDs for a single tool from the
+     * generated skill layout on disk.
+     */
+    async getInstalledWorkflowsForTool(projectPath, toolId) {
+        const tool = AI_TOOLS.find((candidate) => candidate.value === toolId);
+        if (!tool) {
+            return new Set();
+        }
+        return new Set(scanInstalledWorkflowsShared(projectPath, [tool]));
     }
     async performLegacyCleanup(projectPath, detection) {
         const spinner = ora('Cleaning up legacy files...').start();
@@ -300,7 +496,9 @@ export class InitCommand {
         if (tokens.length === 0) {
             throw new Error('The --tools option requires at least one tool ID when not using "all" or "none".');
         }
-        const normalizedTokens = tokens.map((token) => token.toLowerCase());
+        // Retired ids resolve to their current tool, so a rebrand does not break
+        // an existing `--tools windsurf` in someone's setup script.
+        const normalizedTokens = tokens.map((token) => resolveToolIdAlias(token.toLowerCase()));
         if (normalizedTokens.some((token) => token === 'all' || token === 'none')) {
             throw new Error('Cannot combine reserved values "all" or "none" with specific tool IDs.');
         }
@@ -317,23 +515,34 @@ export class InitCommand {
         }
         return deduped;
     }
-    validateTools(toolIds, toolStates) {
+    validateTools(toolIds, toolStates, projectPath) {
         const validatedTools = [];
-        for (const toolId of toolIds) {
+        const reconciledToolIds = toolIds.includes('codex') && toolIds.includes('agents')
+            ? toolIds.filter((toolId) => toolId !== 'agents')
+            : toolIds;
+        if (reconciledToolIds.length !== toolIds.length) {
+            console.log(chalk.dim('Codex and agents share .agents/skills; writing one tree with Codex and generic skill references.'));
+        }
+        for (const toolId of reconciledToolIds) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (!tool) {
                 const validToolIds = getToolsWithSkillsDir();
                 throw new Error(`Unknown tool '${toolId}'. Valid tools:\n  ${validToolIds.join('\n  ')}`);
             }
-            if (!tool.skillsDir) {
+            if (!toolSupportsSkills(tool)) {
                 const validToolsWithSkills = getToolsWithSkillsDir();
                 throw new Error(`Tool '${toolId}' does not support skill generation.\nTools with skill generation support:\n  ${validToolsWithSkills.join('\n  ')}`);
             }
             const preState = toolStates.get(tool.value);
+            const skillsPath = resolveToolSkillsDir(projectPath, tool);
+            const isGlobalSkillTarget = hasGlobalSkillTarget(tool);
             validatedTools.push({
                 value: tool.value,
                 name: tool.name,
                 skillsDir: tool.skillsDir,
+                skillsPath,
+                skillsRoot: isGlobalSkillTarget ? skillsPath : projectPath,
+                isGlobalSkillTarget,
                 wasConfigured: preState?.configured ?? false,
             });
         }
@@ -352,6 +561,7 @@ export class InitCommand {
                 path.join(openspecPath, 'changes', 'archive'),
             ];
             for (const dir of directories) {
+                FileSystemUtils.assertProjectArtifactPath(path.dirname(openspecPath), dir);
                 await FileSystemUtils.createDirectory(dir);
             }
             return;
@@ -364,6 +574,7 @@ export class InitCommand {
             path.join(openspecPath, 'changes', 'archive'),
         ];
         for (const dir of directories) {
+            FileSystemUtils.assertProjectArtifactPath(path.dirname(openspecPath), dir);
             await FileSystemUtils.createDirectory(dir);
         }
         spinner.stopAndPersist({
@@ -374,11 +585,20 @@ export class InitCommand {
     // ═══════════════════════════════════════════════════════════
     // SKILL & COMMAND GENERATION
     // ═══════════════════════════════════════════════════════════
-    async generateSkillsAndCommands(projectPath, tools) {
+    /**
+     * Generates skill files and slash commands for each selected tool,
+     * honoring the configured delivery mode (skills, commands, or both).
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param tools - Selected tools with their skill directory metadata
+     * @returns Created, refreshed, and failed tools plus removed artifact counts
+     */
+    async generateSkillsAndCommands(projectPath, tools, writeCopilotCloud) {
         const createdTools = [];
         const refreshedTools = [];
         const failedTools = [];
         const commandsSkipped = [];
+        const skillsInvocableCommandSkips = [];
         let removedCommandCount = 0;
         let removedSkillCount = 0;
         // Read global config for profile and delivery settings (use --profile override if set)
@@ -387,33 +607,35 @@ export class InitCommand {
         const delivery = globalConfig.delivery ?? 'both';
         const workflows = getProfileWorkflows(profile, globalConfig.workflows);
         // Get skill and command templates filtered by profile workflows
-        const shouldGenerateSkills = delivery !== 'commands';
-        const shouldGenerateCommands = delivery !== 'skills';
-        const skillTemplates = shouldGenerateSkills ? getSkillTemplates(workflows) : [];
-        const commandContents = shouldGenerateCommands ? getCommandContents(workflows) : [];
+        const deliveryIncludesCommands = delivery !== 'skills';
+        const skillTemplates = getSkillTemplates(workflows);
+        const commandContents = getCommandContents(workflows);
         // Process each tool
         for (const tool of tools) {
             const spinner = ora(`Setting up ${tool.name}...`).start();
             try {
-                // Generate skill files if delivery includes skills
+                const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
+                const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                // Generate skill files if the selected delivery and tool capability allow skills
                 if (shouldGenerateSkills) {
-                    // Use tool-specific skillsDir
-                    const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
                     // Create skill directories and SKILL.md files
                     for (const { template, dirName } of skillTemplates) {
-                        const skillDir = path.join(skillsDir, dirName);
+                        const skillDir = path.join(tool.skillsPath, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         // Generate SKILL.md content with YAML frontmatter including generatedBy
-                        // 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);
                         // Write the skill file
+                        FileSystemUtils.assertPathWithin(tool.skillsRoot, skillFile);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
+                    writeSharedSkillTarget(projectPath, tool.value);
                 }
-                if (!shouldGenerateSkills) {
-                    const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
-                    removedSkillCount += await this.removeSkillDirs(skillsDir);
+                if (shouldRemoveSkillsForTool(tool.value, delivery) && !tool.isGlobalSkillTarget) {
+                    removedSkillCount += await this.removeSkillDirs(tool.skillsRoot, tool.skillsPath);
+                    // Retain an explicit selection even when this delivery mode produces
+                    // no skills, so a divergent legacy sibling cannot reclaim ownership.
+                    writeSharedSkillTarget(projectPath, tool.value);
                 }
                 // Generate commands if delivery includes commands
                 if (shouldGenerateCommands) {
@@ -421,17 +643,25 @@ export class InitCommand {
                     if (adapter) {
                         const generatedCommands = generateCommands(commandContents, adapter);
                         for (const cmd of generatedCommands) {
-                            const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectPath, cmd.path);
+                            const commandFile = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmd.path);
                             await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
                         }
                     }
+                }
+                else if (deliveryIncludesCommands) {
+                    if (resolveCommandSurfaceCapability(tool.value) === 'skills-invocable') {
+                        skillsInvocableCommandSkips.push(tool.value);
+                    }
                     else {
                         commandsSkipped.push(tool.value);
                     }
                 }
-                if (!shouldGenerateCommands) {
+                if (shouldReconcileCommandFilesForTool(tool.value, delivery)) {
                     removedCommandCount += await this.removeCommandFiles(projectPath, tool.value);
                 }
+                if (tool.value === 'github-copilot' && writeCopilotCloud) {
+                    await writeCopilotCloudFiles(projectPath);
+                }
                 spinner.succeed(`Setup complete for ${tool.name}`);
                 if (tool.wasConfigured) {
                     refreshedTools.push(tool);
@@ -445,11 +675,22 @@ export class InitCommand {
                 failedTools.push({ name: tool.name, error: error });
             }
         }
+        for (const tool of [...createdTools, ...refreshedTools]) {
+            for (const migration of migrateLegacyToolDirs(projectPath, [tool.value], 'after-generation')) {
+                if (hasMovableContent(migration)) {
+                    console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                }
+                const kept = keptInPlaceNotice(migration);
+                if (kept)
+                    console.log(chalk.dim(kept));
+            }
+        }
         return {
             createdTools,
             refreshedTools,
             failedTools,
             commandsSkipped,
+            skillsInvocableCommandSkips,
             removedCommandCount,
             removedSkillCount,
         };
@@ -467,6 +708,7 @@ export class InitCommand {
         }
         try {
             const yamlContent = serializeConfig({ schema: DEFAULT_SCHEMA });
+            FileSystemUtils.assertProjectArtifactPath(path.dirname(openspecPath), configPath);
             await FileSystemUtils.writeFile(configPath, yamlContent);
             return 'created';
         }
@@ -477,9 +719,9 @@ export class InitCommand {
     // ═══════════════════════════════════════════════════════════
     // UI & OUTPUT
     // ═══════════════════════════════════════════════════════════
-    displaySuccessMessage(projectPath, tools, results, configStatus) {
+    displaySuccessMessage(projectPath, tools, results, configStatus, copilot) {
         console.log();
-        console.log(chalk.bold('OpenSpec Setup Complete'));
+        console.log(chalk.bold(results.failedTools.length > 0 ? 'OpenSpec Setup Incomplete' : 'OpenSpec Setup Complete'));
         console.log();
         // Show created vs refreshed tools
         if (results.createdTools.length > 0) {
@@ -495,17 +737,56 @@ export class InitCommand {
             const profile = this.profileOverride ?? globalConfig.profile ?? 'core';
             const delivery = globalConfig.delivery ?? 'both';
             const workflows = getProfileWorkflows(profile, globalConfig.workflows);
-            const toolDirs = [...new Set(successfulTools.map((t) => t.skillsDir))].join(', ');
-            const skillCount = delivery !== 'commands' ? getSkillTemplates(workflows).length : 0;
-            const commandCount = delivery !== 'skills' ? getCommandContents(workflows).length : 0;
-            if (skillCount > 0 && commandCount > 0) {
-                console.log(`${skillCount} skills and ${commandCount} commands in ${toolDirs}/`);
-            }
-            else if (skillCount > 0) {
-                console.log(`${skillCount} skills in ${toolDirs}/`);
+            const usesGlobalSkillTarget = successfulTools.some((tool) => tool.isGlobalSkillTarget);
+            if (!usesGlobalSkillTarget) {
+                const toolDirs = [
+                    ...new Set(successfulTools
+                        .map((tool) => tool.skillsDir)
+                        .filter((skillsDir) => Boolean(skillsDir))),
+                ].join(', ');
+                const skillCount = successfulTools.some((tool) => shouldGenerateSkillsForTool(tool.value, delivery))
+                    ? getSkillTemplates(workflows).length
+                    : 0;
+                const commandCount = successfulTools.some((tool) => shouldGenerateCommandsForTool(tool.value, delivery))
+                    ? getCommandContents(workflows).length
+                    : 0;
+                if (skillCount > 0 && commandCount > 0) {
+                    console.log(`${skillCount} skills and ${commandCount} commands in ${toolDirs}/`);
+                }
+                else if (skillCount > 0) {
+                    console.log(`${skillCount} skills in ${toolDirs}/`);
+                }
+                else if (commandCount > 0) {
+                    console.log(`${commandCount} commands in ${toolDirs}/`);
+                }
             }
-            else if (commandCount > 0) {
-                console.log(`${commandCount} commands in ${toolDirs}/`);
+            else {
+                const skillTools = successfulTools.filter((tool) => shouldGenerateSkillsForTool(tool.value, delivery));
+                const skillCount = skillTools.length * getSkillTemplates(workflows).length;
+                if (skillCount > 0) {
+                    const skillDirs = [...new Set(skillTools.map((tool) => tool.skillsPath))];
+                    console.log(`${skillCount} skills in ${skillDirs.join(', ')}`);
+                }
+                const commandContents = getCommandContents(workflows);
+                const commandTools = successfulTools.filter((tool) => shouldGenerateCommandsForTool(tool.value, delivery));
+                const commandCount = commandTools.length * commandContents.length;
+                if (commandCount > 0) {
+                    const commandDirs = [
+                        ...new Set(commandTools.flatMap((tool) => {
+                            const adapter = CommandAdapterRegistry.get(tool.value);
+                            if (!adapter)
+                                return [];
+                            return commandContents.map((command) => {
+                                const commandPath = adapter.getFilePath(command.id);
+                                const absolutePath = path.isAbsolute(commandPath)
+                                    ? commandPath
+                                    : path.join(projectPath, commandPath);
+                                return path.dirname(absolutePath);
+                            });
+                        })),
+                    ];
+                    console.log(`${commandCount} commands in ${commandDirs.join(', ')}`);
+                }
             }
         }
         // Show failures
@@ -516,12 +797,42 @@ export class InitCommand {
         if (results.commandsSkipped.length > 0) {
             console.log(chalk.dim(`Commands skipped for: ${results.commandsSkipped.join(', ')} (no adapter)`));
         }
+        if (results.skillsInvocableCommandSkips.length > 0) {
+            console.log(chalk.dim(`Commands skipped for: ${results.skillsInvocableCommandSkips.join(', ')} (uses skills)`));
+        }
         if (results.removedCommandCount > 0) {
             console.log(chalk.dim(`Removed: ${results.removedCommandCount} command files (delivery: skills)`));
         }
         if (results.removedSkillCount > 0) {
             console.log(chalk.dim(`Removed: ${results.removedSkillCount} skill directories (delivery: commands)`));
         }
+        // GitHub Copilot cloud files are opt-in — report what is actually on disk:
+        // list the managed files that now exist (never files we didn't write), flag
+        // any user-owned file we left untouched, note an opt-out cleanup, or (when
+        // skipped for want of a signal) say how to turn them on.
+        const copilotSucceeded = successfulTools.some((tool) => tool.value === 'github-copilot');
+        if (copilotSucceeded && copilot.write) {
+            if (copilot.present.length > 0) {
+                console.log(`GitHub Copilot cloud files: ${copilot.present.join(', ')}`);
+            }
+            if (copilot.collisions.length > 0) {
+                console.log(chalk.dim(`Left your existing ${copilot.collisions.join(' and ')} untouched — add the OpenSpec ` +
+                    `install step by hand so the Copilot cloud agent can run openspec.`));
+            }
+        }
+        else if (copilotSucceeded && copilot.removed > 0) {
+            console.log(chalk.dim(`Removed: ${copilot.removed} Copilot cloud agent file(s) (opted out of cloud files)`));
+        }
+        else if (copilotSucceeded && copilot.skippedUndecided) {
+            console.log(chalk.dim("Skipped GitHub Copilot cloud files (opt-in). Enable with 'openspec init --copilot-cloud'."));
+        }
+        // Show manual setup notes for tools that need extra configuration
+        for (const tool of successfulTools) {
+            const setupNote = AI_TOOLS.find((t) => t.value === tool.value)?.setupNote;
+            if (setupNote) {
+                console.log(chalk.yellow(`Setup required for ${tool.name}: ${setupNote}`));
+            }
+        }
         // Config status
         if (configStatus === 'created') {
             console.log(`Config: openspec/config.yaml (schema: ${DEFAULT_SCHEMA})`);
@@ -537,17 +848,80 @@ export class InitCommand {
             console.log(chalk.dim(`Config: skipped (non-interactive mode)`));
         }
         // Getting started (task 7.6: show propose if in profile)
-        const globalCfg = getGlobalConfig();
-        const activeProfile = this.profileOverride ?? globalCfg.profile ?? 'core';
-        const activeWorkflows = [...getProfileWorkflows(activeProfile, globalCfg.workflows)];
-        console.log();
-        if (activeWorkflows.includes('propose')) {
+        const activeWorkflows = this.getActiveWorkflows();
+        // When no tool got /opsx:* commands, point at the skill instead of a
+        // command that does not exist.
+        const activeDelivery = getGlobalConfig().delivery ?? 'both';
+        const commandsGenerated = successfulTools.some((tool) => shouldGenerateCommandsForTool(tool.value, activeDelivery));
+        const skillsGenerated = successfulTools.some((tool) => shouldGenerateSkillsForTool(tool.value, activeDelivery));
+        // Each hint line must be a usable instruction for the tool it serves.
+        // Tools that generated commands are told the command name their files
+        // answer to (/opsx:* when namespaced under opsx/, /opsx-* when the
+        // filename is the command); tools that only got skills are told their
+        // documented skill invocation (Kimi Code: /skill:openspec-*; Codex CLI:
+        // $openspec-*; others: /openspec-*). Tools that got no artifacts are
+        // covered by the configuration correction instead. When the selection
+        // disagrees, print one line per distinct instruction, labeled with the
+        // tools it applies to.
+        const startHintLines = (command) => {
+            const hintToTools = new Map();
+            for (const tool of successfulTools) {
+                let hint;
+                if (shouldGenerateCommandsForTool(tool.value, activeDelivery)) {
+                    const transformer = getTransformerForTool(tool.value, activeDelivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
+                    hint = `Start your first change: ${transformer ? transformer(command) : command} "your idea"`;
+                }
+                else if (shouldGenerateSkillsForTool(tool.value, activeDelivery)) {
+                    const skillReference = getSkillReferenceTransformer(tool.value)(command);
+                    // Tools with no slash surface (e.g. Rovo Dev) reference skills as
+                    // prose ("the openspec-propose skill"); phrase the hint so it reads
+                    // as an instruction rather than a dead command with an argument.
+                    hint = usesNaturalLanguageSkillReferences(tool.value)
+                        ? `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`
+                        : `Start your first change: ${skillReference} "your idea"`;
+                }
+                else {
+                    continue;
+                }
+                hintToTools.set(hint, [...(hintToTools.get(hint) ?? []), tool.name]);
+            }
+            if (hintToTools.size === 0) {
+                // No successful tools: keep the generic command hint
+                return [`Start your first change: ${command} "your idea"`];
+            }
+            if (hintToTools.size === 1) {
+                return [[...hintToTools.keys()][0]];
+            }
+            return [...hintToTools.entries()].map(([hint, toolNames]) => `${hint} (${toolNames.join(', ')})`);
+        };
+        const printStartHints = (command) => {
             console.log(chalk.bold('Getting started:'));
-            console.log('  Start your first change: /opsx:propose "your idea"');
+            for (const line of startHintLines(command)) {
+                console.log(`  ${line}`);
+            }
+        };
+        console.log();
+        // delivery=commands with tools that only support skills: those tools get
+        // no artifacts at all, so print a per-tool configuration correction
+        // rather than leave them with a dead (or missing) instruction — even
+        // when other selected tools did get commands or skills.
+        const zeroArtifactTools = successfulTools.filter((tool) => !shouldGenerateSkillsForTool(tool.value, activeDelivery) &&
+            !shouldGenerateCommandsForTool(tool.value, activeDelivery));
+        if (zeroArtifactTools.length > 0) {
+            const names = zeroArtifactTools.map((tool) => tool.name).join(', ');
+            console.log(chalk.yellow(`No skills or commands were generated 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 (successfulTools.length > 0 && !commandsGenerated && !skillsGenerated) {
+            // Nothing was generated for any tool: the correction above is the
+            // whole story, so don't advertise an invocation that doesn't exist.
+        }
+        else if (activeWorkflows.includes('propose')) {
+            printStartHints('/opsx:propose');
         }
         else if (activeWorkflows.includes('new')) {
-            console.log(chalk.bold('Getting started:'));
-            console.log('  Start your first change: /opsx:new "your idea"');
+            printStartHints('/opsx:new');
         }
         else {
             console.log("Done. Run 'openspec config profile' to configure your workflows.");
@@ -556,10 +930,16 @@ export class InitCommand {
         console.log();
         console.log(`Learn more: ${chalk.cyan('https://github.com/Fission-AI/OpenSpec')}`);
         console.log(`Feedback:   ${chalk.cyan('https://github.com/Fission-AI/OpenSpec/issues')}`);
-        // Restart instruction if any tools were configured
-        if (results.createdTools.length > 0 || results.refreshedTools.length > 0) {
+        // Restart instruction if any tools were configured and got a surface
+        // (when nothing was generated there is nothing a restart would pick up);
+        // only mention commands when commands were actually generated. Not "slash
+        // commands": Amazon Q's generated files are prompt-library entries invoked
+        // with @, so a restart line promising slash commands would be wrong for it.
+        if ((results.createdTools.length > 0 || results.refreshedTools.length > 0) && (commandsGenerated || skillsGenerated)) {
             console.log();
-            console.log(chalk.white('Restart your IDE for slash commands to take effect.'));
+            console.log(chalk.white(commandsGenerated
+                ? 'Restart your IDE for the new commands to take effect.'
+                : 'Restart your IDE for the new skills to take effect.'));
         }
         console.log();
     }
@@ -571,18 +951,19 @@ export class InitCommand {
             spinner: PROGRESS_SPINNER,
         }).start();
     }
-    async removeSkillDirs(skillsDir) {
+    async removeSkillDirs(skillsRoot, skillsDir) {
         let removed = 0;
         for (const workflow of ALL_WORKFLOWS) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             if (!dirName)
                 continue;
             const skillDir = path.join(skillsDir, dirName);
+            if (!fs.existsSync(skillDir))
+                continue;
+            FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
             try {
-                if (fs.existsSync(skillDir)) {
-                    await fs.promises.rm(skillDir, { recursive: true, force: true });
-                    removed++;
-                }
+                await fs.promises.rm(skillDir, { recursive: true, force: true });
+                removed++;
             }
             catch {
                 // Ignore errors
@@ -597,7 +978,7 @@ export class InitCommand {
             return 0;
         for (const workflow of ALL_WORKFLOWS) {
             const cmdPath = adapter.getFilePath(workflow);
-            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            const fullPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
             try {
                 if (fs.existsSync(fullPath)) {
                     await fs.promises.unlink(fullPath);