@codewalla_india/openspec 1.3.1 → 1.3.2

package/dist/core/root-selection.js

@@ -7,8 +7,11 @@
  * - `--store <id>` selects a registered store's root.
  * - Without `--store`, the nearest ancestor containing `openspec/` wins.
  *   Leftover workspace view state is never considered a root here.
- * - With no nearest root, registered stores produce a selection hint error;
- *   otherwise commands may treat the current directory as an implicit root.
+ * - With no nearest root, a global `defaultStore` (if set) is the last
+ *   machine-level fallback before the selection hint error.
+ * - With no nearest root and no default, registered stores produce a
+ *   selection hint error; otherwise commands may treat the current
+ *   directory as an implicit root.
  *
  * Diagnostic codes reuse the store taxonomy where an error passes
  * through unchanged (`invalid_store_id`, metadata parse failures);
@@ -26,6 +29,7 @@ import { getStoreRootForBackend } from './store/registry.js';
 import { inspectOpenSpecRoot } from './openspec-root.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
 import { classifyOpenSpecDir, storePointerProblem } from './project-config.js';
+import { getGlobalConfig } from './global-config.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 export class RootSelectionError extends Error {
     diagnostic;
@@ -221,6 +225,32 @@ async function resolveNearestOrDeclaredRoot(nearestRoot, globalDataDir) {
         throw error;
     }
 }
+/**
+ * The machine-level fallback: the global `defaultStore` resolved as a root,
+ * with its own provenance (`global_default`) so JSON surfaces can tell a
+ * machine-wide default from a repo's `store:` pointer. Mirrors the
+ * declared-pointer catch — a stale or unregistered id degrades to the
+ * underlying error, reshaped to point at clearing the global default
+ * rather than passing --store.
+ */
+async function resolveDefaultStoreRoot(id, globalDataDir) {
+    try {
+        return await resolveStoreRoot(id, globalDataDir, 'global_default');
+    }
+    catch (error) {
+        if (error instanceof RootSelectionError) {
+            const staleFix = error.diagnostic.code === 'unknown_store' ||
+                error.diagnostic.code === 'no_registered_stores'
+                ? `Register the store (openspec store register <path> --id ${id}) or clear the stale global default (openspec config unset defaultStore).`
+                : error.diagnostic.fix;
+            throw new RootSelectionError(`Global defaultStore '${id}': ${error.message}`, error.diagnostic.code, {
+                ...(error.diagnostic.target ? { target: error.diagnostic.target } : {}),
+                ...(staleFix ? { fix: staleFix } : {}),
+            });
+        }
+        throw error;
+    }
+}
 export async function resolveOpenSpecRoot(options = {}) {
     if (options.storePath !== undefined) {
         throw new RootSelectionError('--store-path is not supported. Register the path with openspec store register <path>, then select it with --store <id>.', 'store_path_not_supported', {
@@ -236,6 +266,13 @@ export async function resolveOpenSpecRoot(options = {}) {
     if (nearestRoot) {
         return resolveNearestOrDeclaredRoot(nearestRoot, options.globalDataDir);
     }
+    // Machine-level fallback: a global defaultStore is consulted only after
+    // --store, the nearest local root, and project-level pointers have all
+    // failed to resolve — it changes the failure path, never the precedence.
+    const defaultStore = getGlobalConfig().defaultStore;
+    if (defaultStore) {
+        return resolveDefaultStoreRoot(defaultStore, options.globalDataDir);
+    }
     let registry;
     try {
         registry = await readStoreRegistryState(options.globalDataDir ? { globalDataDir: options.globalDataDir } : {});
@@ -265,9 +302,9 @@ export function toRootOutput(root) {
     };
 }
 /**
- * A store-selected root — explicit `--store` or the declared fallback.
- * Cross-root behavior (absolute paths, --store hints, suppressed
- * noun-form suggestions) keys on this, never on `source` directly.
+ * A store-selected root — explicit `--store`, a declared pointer, or the
+ * global default. Cross-root behavior (absolute paths, --store hints,
+ * suppressed noun-form suggestions) keys on this, never on `source` directly.
  */
 export function isStoreSelectedRoot(root) {
     return root.storeId !== undefined;

package/dist/core/schemas/base.schema.js

@@ -4,9 +4,14 @@ export const ScenarioSchema = z.object({
     rawText: z.string().min(1, VALIDATION_MESSAGES.SCENARIO_EMPTY),
 });
 export const RequirementSchema = z.object({
+    // SHALL/MUST body-keyword enforcement lives in the imperative validator
+    // (Validator.applySpecRules), not here: the parser collapses the requirement
+    // header into `text`, so a Zod refine on `text` cannot tell "keyword in header
+    // only" from "keyword in body" and emits a misleading generic error. The
+    // validator recovers the header and emits the targeted hint for both the
+    // main-spec and change-delta paths (#1156).
     text: z.string()
-        .min(1, VALIDATION_MESSAGES.REQUIREMENT_EMPTY)
-        .refine((text) => text.includes('SHALL') || text.includes('MUST'), VALIDATION_MESSAGES.REQUIREMENT_NO_SHALL),
+        .min(1, VALIDATION_MESSAGES.REQUIREMENT_EMPTY),
     scenarios: z.array(ScenarioSchema)
         .min(1, VALIDATION_MESSAGES.REQUIREMENT_NO_SCENARIOS),
 });

package/dist/core/shared/allowed-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-approved tools for generated skills and slash commands, emitted as the
+ * `allowed-tools` frontmatter field (Agent Skills standard for SKILL.md;
+ * same field for Claude Code slash commands). Scoped to the OpenSpec CLI so
+ * agents that honor it stop prompting on each `openspec` call; the field
+ * only pre-approves — it does not restrict — so any other tool a skill or
+ * command needs (Read, Write, arbitrary Bash for builds/tests) stays
+ * available under the user's normal permission settings. Tools that don't
+ * recognize the field ignore it.
+ */
+export declare const OPENSPEC_CLI_ALLOWED_TOOLS = "Bash(openspec:*)";
+//# sourceMappingURL=allowed-tools.d.ts.map

package/dist/core/shared/allowed-tools.js

@@ -0,0 +1,12 @@
+/**
+ * Pre-approved tools for generated skills and slash commands, emitted as the
+ * `allowed-tools` frontmatter field (Agent Skills standard for SKILL.md;
+ * same field for Claude Code slash commands). Scoped to the OpenSpec CLI so
+ * agents that honor it stop prompting on each `openspec` call; the field
+ * only pre-approves — it does not restrict — so any other tool a skill or
+ * command needs (Read, Write, arbitrary Bash for builds/tests) stays
+ * available under the user's normal permission settings. Tools that don't
+ * recognize the field ignore it.
+ */
+export const OPENSPEC_CLI_ALLOWED_TOOLS = 'Bash(openspec:*)';
+//# sourceMappingURL=allowed-tools.js.map

package/dist/core/shared/index.d.ts

@@ -5,4 +5,5 @@
  */
 export { SKILL_NAMES, type SkillName, COMMAND_IDS, type CommandId, type ToolSkillStatus, type ToolVersionStatus, getToolsWithSkillsDir, getToolSkillStatus, getToolStates, extractGeneratedByVersion, getToolVersionStatus, getConfiguredTools, getAllToolVersionStatus, } from './tool-detection.js';
 export { type SkillTemplateEntry, type CommandTemplateEntry, getSkillTemplates, getCommandTemplates, getCommandContents, generateSkillContent, } from './skill-generation.js';
+export { type SkillCapableTool, toolSupportsSkills, getSkillCapableTools, hasGlobalSkillTarget, resolveToolSkillsDir, } from './skill-paths.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/shared/index.js

@@ -5,4 +5,5 @@
  */
 export { SKILL_NAMES, COMMAND_IDS, getToolsWithSkillsDir, getToolSkillStatus, getToolStates, extractGeneratedByVersion, getToolVersionStatus, getConfiguredTools, getAllToolVersionStatus, } from './tool-detection.js';
 export { getSkillTemplates, getCommandTemplates, getCommandContents, generateSkillContent, } from './skill-generation.js';
+export { toolSupportsSkills, getSkillCapableTools, hasGlobalSkillTarget, resolveToolSkillsDir, } from './skill-paths.js';
 //# sourceMappingURL=index.js.map

package/dist/core/shared/skill-content-equivalence.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns whether a legacy Codex skill differs from the current canonical
+ * replacement only by generated version, checkout line endings/BOM, or the
+ * known Codex/generic dual-reference expansion.
+ */
+export declare function isLegacyCodexSkillEquivalentToCurrent(legacyContent: string, currentContent: string): boolean;
+//# sourceMappingURL=skill-content-equivalence.d.ts.map

package/dist/core/shared/skill-content-equivalence.js

@@ -0,0 +1,41 @@
+import { OPENSPEC_SKILL_NAMES } from '../config.js';
+const GENERATED_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const OPENSPEC_SKILL_NAME_SET = new Set(OPENSPEC_SKILL_NAMES);
+/**
+ * Normalizes checkout line endings and a valid generated version inside the
+ * YAML frontmatter. Free-form `generatedBy` text in the instructions remains
+ * material.
+ */
+function normalizeGeneratedSkill(content) {
+    const normalized = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const frontmatter = normalized.match(/^---\n[\s\S]*?\n---(?:\n|$)/)?.[0];
+    if (!frontmatter)
+        return normalized;
+    const versionLine = /^(\s*generatedBy:\s*)(?:"([^"\n]+)"|'([^'\n]+)'|([^\s"'#]+))\s*$/m;
+    const normalizedFrontmatter = frontmatter.replace(versionLine, (line, prefix, doubleQuoted, singleQuoted, bare) => {
+        const version = doubleQuoted ?? singleQuoted ?? bare;
+        return version && GENERATED_VERSION.test(version)
+            ? `${prefix}"<generated-version>"`
+            : line;
+    });
+    return normalizedFrontmatter + normalized.slice(frontmatter.length);
+}
+/**
+ * Converts only known generated dual references in current Codex content back
+ * to the direct syntax used by legacy `.codex` output.
+ */
+function toLegacyCodexReferences(content) {
+    return content.replace(/\$(openspec-[a-z0-9-]+) \(Codex\) or \/\1 \(other agents\)/g, (match, skillName) => OPENSPEC_SKILL_NAME_SET.has(skillName) ? `$${skillName}` : match);
+}
+/**
+ * Returns whether a legacy Codex skill differs from the current canonical
+ * replacement only by generated version, checkout line endings/BOM, or the
+ * known Codex/generic dual-reference expansion.
+ */
+export function isLegacyCodexSkillEquivalentToCurrent(legacyContent, currentContent) {
+    const normalizedLegacy = normalizeGeneratedSkill(legacyContent);
+    const normalizedCurrent = normalizeGeneratedSkill(currentContent);
+    return (normalizedLegacy === normalizedCurrent ||
+        normalizedLegacy === toLegacyCodexReferences(normalizedCurrent));
+}
+//# sourceMappingURL=skill-content-equivalence.js.map

package/dist/core/shared/skill-generation.js

@@ -3,7 +3,8 @@
  *
  * Shared utilities for generating skill and command files.
  */
-import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getBulkArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOnboardSkillTemplate, getOpsxProposeSkillTemplate, getModifyChangeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxBulkArchiveCommandTemplate, getOpsxVerifyCommandTemplate, getOpsxOnboardCommandTemplate, getOpsxProposeCommandTemplate, getOpsxModifyCommandTemplate, } from '../templates/skill-templates.js';
+import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getUpdateChangeSkillTemplate, getModifyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getBulkArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOnboardSkillTemplate, getOpsxProposeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxUpdateCommandTemplate, getOpsxModifyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxBulkArchiveCommandTemplate, getOpsxVerifyCommandTemplate, getOpsxOnboardCommandTemplate, getOpsxProposeCommandTemplate, } from '../templates/skill-templates.js';
+import { OPENSPEC_CLI_ALLOWED_TOOLS } from './allowed-tools.js';
 /**
  * Gets skill templates with their directory names, optionally filtered by workflow IDs.
  *
@@ -15,6 +16,7 @@ export function getSkillTemplates(workflowFilter) {
         { template: getNewChangeSkillTemplate(), dirName: 'openspec-new-change', workflowId: 'new' },
         { template: getContinueChangeSkillTemplate(), dirName: 'openspec-continue-change', workflowId: 'continue' },
         { template: getApplyChangeSkillTemplate(), dirName: 'openspec-apply-change', workflowId: 'apply' },
+        { template: getUpdateChangeSkillTemplate(), dirName: 'openspec-update-change', workflowId: 'update' },
         { template: getModifyChangeSkillTemplate(), dirName: 'openspec-modify-change', workflowId: 'modify' },
         { template: getFfChangeSkillTemplate(), dirName: 'openspec-ff-change', workflowId: 'ff' },
         { template: getSyncSpecsSkillTemplate(), dirName: 'openspec-sync-specs', workflowId: 'sync' },
@@ -40,6 +42,7 @@ export function getCommandTemplates(workflowFilter) {
         { template: getOpsxNewCommandTemplate(), id: 'new' },
         { template: getOpsxContinueCommandTemplate(), id: 'continue' },
         { template: getOpsxApplyCommandTemplate(), id: 'apply' },
+        { template: getOpsxUpdateCommandTemplate(), id: 'update' },
         { template: getOpsxModifyCommandTemplate(), id: 'modify' },
         { template: getOpsxFfCommandTemplate(), id: 'ff' },
         { template: getOpsxSyncCommandTemplate(), id: 'sync' },
@@ -81,18 +84,19 @@ export function generateSkillContent(template, generatedByVersion, transformInst
     const instructions = transformInstructions
         ? transformInstructions(template.instructions)
         : template.instructions;
-    return `---
-name: ${template.name}
-description: ${template.description}
-license: ${template.license || 'MIT'}
-compatibility: ${template.compatibility || 'Requires openspec CLI.'}
-metadata:
-  author: ${template.metadata?.author || 'openspec'}
-  version: "${template.metadata?.version || '1.0'}"
-  generatedBy: "${generatedByVersion}"
----
-
-${instructions}
+    return `---
+name: ${template.name}
+description: ${template.description}
+allowed-tools: ${OPENSPEC_CLI_ALLOWED_TOOLS}
+license: ${template.license || 'MIT'}
+compatibility: ${template.compatibility || 'Requires openspec CLI.'}
+metadata:
+  author: ${template.metadata?.author || 'openspec'}
+  version: "${template.metadata?.version || '1.0'}"
+  generatedBy: "${generatedByVersion}"
+---
+
+${instructions}
 `;
 }
 //# sourceMappingURL=skill-generation.js.map

package/dist/core/shared/skill-paths.d.ts

@@ -0,0 +1,13 @@
+import { type AIToolOption } from '../config.js';
+export type SkillCapableTool = AIToolOption & ({
+    skillsDir: string;
+} | {
+    globalSkillsDir: string;
+});
+export declare function toolSupportsSkills(tool: AIToolOption): tool is SkillCapableTool;
+export declare function getSkillCapableTools(): SkillCapableTool[];
+export declare function hasGlobalSkillTarget(tool: AIToolOption): boolean;
+export declare function resolveToolSkillsDir(projectRoot: string, tool: SkillCapableTool, options?: {
+    homeDir?: string;
+}): string;
+//# sourceMappingURL=skill-paths.d.ts.map

package/dist/core/shared/skill-paths.js

@@ -0,0 +1,23 @@
+import os from 'node:os';
+import path from 'node:path';
+import { AI_TOOLS } from '../config.js';
+export function toolSupportsSkills(tool) {
+    return Boolean(tool.skillsDir || tool.globalSkillsDir);
+}
+export function getSkillCapableTools() {
+    return AI_TOOLS.filter(toolSupportsSkills);
+}
+export function hasGlobalSkillTarget(tool) {
+    return Boolean(tool.globalSkillsDir);
+}
+export function resolveToolSkillsDir(projectRoot, tool, options = {}) {
+    if (tool.globalSkillsDir) {
+        const homeDir = options.homeDir ?? process.env.USERPROFILE ?? process.env.HOME ?? os.homedir();
+        return path.join(homeDir, tool.globalSkillsDir, 'skills');
+    }
+    if (tool.skillsDir) {
+        return path.join(projectRoot, tool.skillsDir, 'skills');
+    }
+    throw new Error(`Tool '${tool.value}' does not support skill generation.`);
+}
+//# sourceMappingURL=skill-paths.js.map

package/dist/core/shared/tool-detection.d.ts

@@ -6,12 +6,12 @@
 /**
  * Names of skill directories created by openspec init.
  */
-export declare const SKILL_NAMES: readonly ["openspec-explore", "openspec-new-change", "openspec-continue-change", "openspec-modify-change", "openspec-apply-change", "openspec-ff-change", "openspec-sync-specs", "openspec-archive-change", "openspec-bulk-archive-change", "openspec-verify-change", "openspec-onboard", "openspec-propose"];
+export declare const SKILL_NAMES: readonly ["openspec-explore", "openspec-new-change", "openspec-continue-change", "openspec-apply-change", "openspec-update-change", "openspec-ff-change", "openspec-sync-specs", "openspec-archive-change", "openspec-bulk-archive-change", "openspec-verify-change", "openspec-onboard", "openspec-propose"];
 export type SkillName = (typeof SKILL_NAMES)[number];
 /**
  * IDs of command templates created by openspec init.
  */
-export declare const COMMAND_IDS: readonly ["explore", "new", "continue", "modify", "apply", "ff", "sync", "archive", "bulk-archive", "verify", "onboard", "propose"];
+export declare const COMMAND_IDS: readonly ["explore", "new", "continue", "apply", "update", "ff", "sync", "archive", "bulk-archive", "verify", "onboard", "propose"];
 export type CommandId = (typeof COMMAND_IDS)[number];
 /**
  * Status of skill configuration for a tool.
@@ -32,9 +32,13 @@ export interface ToolVersionStatus {
     toolId: string;
     /** The tool's display name */
     toolName: string;
-    /** Whether the tool has any skills configured */
+    /** Whether the tool has any skills or commands configured */
     configured: boolean;
-    /** The generatedBy version found in the skill files, or null if not found */
+    /**
+     * The generatedBy version recorded in the tool's skill files. For a tool that
+     * has commands but no skills, the current version when the command files match
+     * what would be generated now. Null when neither says the files are current.
+     */
     generatedByVersion: string | null;
     /** Whether the tool needs updating (version mismatch or missing) */
     needsUpdate: boolean;
@@ -47,6 +51,19 @@ export declare function getToolsWithSkillsDir(): string[];
  * Checks which skill files exist for a tool.
  */
 export declare function getToolSkillStatus(projectRoot: string, toolId: string): ToolSkillStatus;
+/**
+ * Checks whether a tool has at least one generated OpenSpec command file.
+ */
+export declare function toolHasAnyConfiguredCommand(projectPath: string, toolId: string): boolean;
+/**
+ * Checks whether command files for a tool on disk match current generated command contents.
+ *
+ * Command files carry no version stamp, so content equality is the only available
+ * "is this current?" signal for a commands-only install.
+ */
+export declare function areCommandFilesUpToDate(projectRoot: string, toolId: string, options?: {
+    workflows?: readonly string[];
+}): boolean;
 /**
  * Gets the skill status for all tools with skillsDir configured.
  */
@@ -57,11 +74,14 @@ export declare function getToolStates(projectRoot: string): Map<string, ToolSkil
  */
 export declare function extractGeneratedByVersion(skillFilePath: string): string | null;
 /**
- * Gets version status for a tool by reading the first available skill file.
+ * Gets version status for a tool by reading its skill files, falling back to a
+ * command-content fingerprint for installs that have commands but no skills.
  */
-export declare function getToolVersionStatus(projectRoot: string, toolId: string, currentVersion: string): ToolVersionStatus;
+export declare function getToolVersionStatus(projectRoot: string, toolId: string, currentVersion: string, options?: {
+    workflows?: readonly string[];
+}): ToolVersionStatus;
 /**
- * Gets all configured tools in the project.
+ * Gets all configured tools in the project (configured via skills or commands).
  */
 export declare function getConfiguredTools(projectRoot: string): string[];
 /**

package/dist/core/shared/tool-detection.js

@@ -5,24 +5,18 @@
  */
 import path from 'path';
 import * as fs from 'fs';
-import { AI_TOOLS } from '../config.js';
+import { AI_TOOLS, OPENSPEC_SKILL_NAMES } from '../config.js';
+import { CommandAdapterRegistry, generateCommands } from '../command-generation/index.js';
+import { getCommandContents } from './skill-generation.js';
+import { getGlobalConfig } from '../global-config.js';
+import { getProfileWorkflows, ALL_WORKFLOWS } from '../profiles.js';
+import { isSharedSkillTargetActive, readSharedSkillTarget, reconcileSharedSkillTargets, } from '../shared-skill-target.js';
+import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, } from '../command-surface.js';
+import { getSkillCapableTools, resolveToolSkillsDir, toolSupportsSkills, } from './skill-paths.js';
 /**
  * Names of skill directories created by openspec init.
  */
-export const SKILL_NAMES = [
-    'openspec-explore',
-    'openspec-new-change',
-    'openspec-continue-change',
-    'openspec-modify-change',
-    'openspec-apply-change',
-    'openspec-ff-change',
-    'openspec-sync-specs',
-    'openspec-archive-change',
-    'openspec-bulk-archive-change',
-    'openspec-verify-change',
-    'openspec-onboard',
-    'openspec-propose',
-];
+export const SKILL_NAMES = OPENSPEC_SKILL_NAMES;
 /**
  * IDs of command templates created by openspec init.
  */
@@ -30,8 +24,8 @@ export const COMMAND_IDS = [
     'explore',
     'new',
     'continue',
-    'modify',
     'apply',
+    'update',
     'ff',
     'sync',
     'archive',
@@ -44,21 +38,26 @@ export const COMMAND_IDS = [
  * Gets the list of tools with skillsDir configured.
  */
 export function getToolsWithSkillsDir() {
-    return AI_TOOLS.filter((t) => t.skillsDir).map((t) => t.value);
+    return getSkillCapableTools().map((tool) => tool.value);
 }
 /**
  * Checks which skill files exist for a tool.
  */
 export function getToolSkillStatus(projectRoot, toolId) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
-    if (!tool?.skillsDir) {
+    if (!tool || !toolSupportsSkills(tool)) {
+        return { configured: false, fullyConfigured: false, skillCount: 0 };
+    }
+    if (tool.skillsDir && !isSharedSkillTargetActive(projectRoot, toolId)) {
         return { configured: false, fullyConfigured: false, skillCount: 0 };
     }
-    const skillsDir = path.join(projectRoot, tool.skillsDir, 'skills');
+    const skillsDirs = [
+        resolveToolSkillsDir(projectRoot, tool),
+        ...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectRoot, root, 'skills')),
+    ];
     let skillCount = 0;
     for (const skillName of SKILL_NAMES) {
-        const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
-        if (fs.existsSync(skillFile)) {
+        if (skillsDirs.some((skillsDir) => fs.existsSync(path.join(skillsDir, skillName, 'SKILL.md')))) {
             skillCount++;
         }
     }
@@ -68,14 +67,108 @@ export function getToolSkillStatus(projectRoot, toolId) {
         skillCount,
     };
 }
+/**
+ * Checks whether a tool has at least one generated OpenSpec command file.
+ */
+export function toolHasAnyConfiguredCommand(projectPath, toolId) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    if (!adapter)
+        return false;
+    for (const commandId of COMMAND_IDS) {
+        const cmdPath = adapter.getFilePath(commandId);
+        const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+        if (fs.existsSync(fullPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Normalizes checkout artifacts that are not real content drift: a UTF-8 BOM and
+ * CRLF line endings, which a Windows clone with `core.autocrlf` reintroduces on
+ * every checkout of committed command files.
+ */
+function normalizeCommandContent(content) {
+    return content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+}
+/**
+ * Checks whether command files for a tool on disk match current generated command contents.
+ *
+ * Command files carry no version stamp, so content equality is the only available
+ * "is this current?" signal for a commands-only install.
+ */
+export function areCommandFilesUpToDate(projectRoot, toolId, options) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    if (!adapter)
+        return false;
+    let workflows;
+    if (options?.workflows) {
+        workflows = options.workflows;
+    }
+    else {
+        try {
+            const globalCfg = getGlobalConfig();
+            const profile = globalCfg.profile ?? 'core';
+            workflows = getProfileWorkflows(profile, globalCfg.workflows);
+        }
+        catch {
+            workflows = ALL_WORKFLOWS;
+        }
+    }
+    const knownWorkflows = workflows.filter((w) => ALL_WORKFLOWS.includes(w));
+    const commandContents = getCommandContents(knownWorkflows);
+    const generatedCommands = generateCommands(commandContents, adapter);
+    if (generatedCommands.length === 0) {
+        return false;
+    }
+    for (const cmd of generatedCommands) {
+        const cmdPath = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectRoot, cmd.path);
+        if (!fs.existsSync(cmdPath)) {
+            return false;
+        }
+        try {
+            const existingContent = fs.readFileSync(cmdPath, 'utf-8');
+            if (normalizeCommandContent(existingContent) !== normalizeCommandContent(cmd.fileContent)) {
+                return false;
+            }
+        }
+        catch {
+            return false;
+        }
+    }
+    // Also check no extra command files exist for deselected workflows
+    const desiredWorkflowSet = new Set(knownWorkflows);
+    for (const workflow of ALL_WORKFLOWS) {
+        if (desiredWorkflowSet.has(workflow))
+            continue;
+        const cmdPath = adapter.getFilePath(workflow);
+        const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectRoot, cmdPath);
+        if (fs.existsSync(fullPath)) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
  * Gets the skill status for all tools with skillsDir configured.
  */
 export function getToolStates(projectRoot) {
     const states = new Map();
-    const toolIds = AI_TOOLS.filter((t) => t.skillsDir).map((t) => t.value);
-    for (const toolId of toolIds) {
-        states.set(toolId, getToolSkillStatus(projectRoot, toolId));
+    const tools = getSkillCapableTools();
+    for (const tool of tools) {
+        const skillStatus = getToolSkillStatus(projectRoot, tool.value);
+        const markerConfigured = Boolean(tool.skillsDir) &&
+            readSharedSkillTarget(projectRoot, tool.skillsDir) === tool.value;
+        states.set(tool.value, markerConfigured
+            ? { ...skillStatus, configured: true }
+            : skillStatus);
+    }
+    const configuredTools = tools.filter((tool) => tool.skillsDir && states.get(tool.value)?.configured);
+    const activeSharedTargets = new Set(reconcileSharedSkillTargets(projectRoot, configuredTools).map((tool) => tool.value));
+    for (const tool of configuredTools) {
+        if (!activeSharedTargets.has(tool.value)) {
+            states.set(tool.value, { configured: false, fullyConfigured: false, skillCount: 0 });
+        }
     }
     return states;
 }
@@ -109,11 +202,12 @@ export function extractGeneratedByVersion(skillFilePath) {
     }
 }
 /**
- * Gets version status for a tool by reading the first available skill file.
+ * Gets version status for a tool by reading its skill files, falling back to a
+ * command-content fingerprint for installs that have commands but no skills.
  */
-export function getToolVersionStatus(projectRoot, toolId, currentVersion) {
+export function getToolVersionStatus(projectRoot, toolId, currentVersion, options) {
     const tool = AI_TOOLS.find((t) => t.value === toolId);
-    if (!tool?.skillsDir) {
+    if (!tool || !toolSupportsSkills(tool)) {
         return {
             toolId,
             toolName: toolId,
@@ -122,17 +216,43 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion) {
             needsUpdate: false,
         };
     }
-    const skillsDir = path.join(projectRoot, tool.skillsDir, 'skills');
+    const skillsDirs = [
+        resolveToolSkillsDir(projectRoot, tool),
+        ...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectRoot, root, 'skills')),
+    ];
     let generatedByVersion = null;
-    // Find the first skill file that exists and read its version
+    let foundSkill = false;
+    // 1. Find the first skill file that exists and read its version
     for (const skillName of SKILL_NAMES) {
-        const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
-        if (fs.existsSync(skillFile)) {
-            generatedByVersion = extractGeneratedByVersion(skillFile);
+        for (const skillsDir of skillsDirs) {
+            const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
+            if (fs.existsSync(skillFile)) {
+                generatedByVersion = extractGeneratedByVersion(skillFile);
+                foundSkill = true;
+                break;
+            }
+        }
+        if (foundSkill)
             break;
+    }
+    const skillConfigured = getToolSkillStatus(projectRoot, toolId).configured;
+    const commandConfigured = toolHasAnyConfiguredCommand(projectRoot, toolId);
+    const markerConfigured = Boolean(tool.skillsDir) &&
+        readSharedSkillTarget(projectRoot, tool.skillsDir) === toolId;
+    const configured = skillConfigured || commandConfigured || markerConfigured;
+    // 2. Commands-only installs have no skill file to read a version from, so fall
+    //    back to comparing the generated command content. Deliberately skipped when
+    //    skill files exist: an unreadable version there must still force a rewrite.
+    if (!skillConfigured && commandConfigured && areCommandFilesUpToDate(projectRoot, toolId, options)) {
+        generatedByVersion = currentVersion;
+    }
+    if (!skillConfigured && !commandConfigured && markerConfigured) {
+        const delivery = getGlobalConfig().delivery ?? 'both';
+        if (!shouldGenerateSkillsForTool(toolId, delivery) &&
+            !shouldGenerateCommandsForTool(toolId, delivery)) {
+            generatedByVersion = currentVersion;
         }
     }
-    const configured = getToolSkillStatus(projectRoot, toolId).configured;
     const needsUpdate = configured && (generatedByVersion === null || generatedByVersion !== currentVersion);
     return {
         toolId,
@@ -143,12 +263,22 @@ export function getToolVersionStatus(projectRoot, toolId, currentVersion) {
     };
 }
 /**
- * Gets all configured tools in the project.
+ * Gets all configured tools in the project (configured via skills or commands).
  */
 export function getConfiguredTools(projectRoot) {
-    return AI_TOOLS
-        .filter((t) => t.skillsDir && getToolSkillStatus(projectRoot, t.value).configured)
-        .map((t) => t.value);
+    const configured = AI_TOOLS
+        .filter((t) => {
+        if (!toolSupportsSkills(t))
+            return false;
+        return (getToolSkillStatus(projectRoot, t.value).configured ||
+            toolHasAnyConfiguredCommand(projectRoot, t.value) ||
+            (Boolean(t.skillsDir) &&
+                readSharedSkillTarget(projectRoot, t.skillsDir) === t.value));
+    });
+    const activeProjectTools = new Set(reconcileSharedSkillTargets(projectRoot, configured.filter((tool) => tool.skillsDir)).map((tool) => tool.value));
+    return configured
+        .filter((tool) => tool.globalSkillsDir || activeProjectTools.has(tool.value))
+        .map((tool) => tool.value);
 }
 /**
  * Gets version status for all configured tools.

package/dist/core/shared-skill-target.d.ts

@@ -0,0 +1,16 @@
+import { type AIToolOption } from './config.js';
+/** Reads a valid-looking marker value without letting linked roots escape. */
+export declare function readSharedSkillTarget(projectPath: string, skillsDir: string): string | undefined;
+/**
+ * A shared skill root can only hold one rendered variant of each skill.
+ * Keep the writer recorded so later updates do not infer every tool that
+ * happens to use the same directory.
+ */
+export declare function reconcileSharedSkillTargets(projectPath: string, tools: AIToolOption[]): AIToolOption[];
+/**
+ * Returns whether a tool is the active writer for its physical skills root.
+ * Non-shared roots are always active.
+ */
+export declare function isSharedSkillTargetActive(projectPath: string, toolId: string): boolean;
+export declare function writeSharedSkillTarget(projectPath: string, toolId: string): void;
+//# sourceMappingURL=shared-skill-target.d.ts.map