@fission-ai/openspec 1.6.0 → 1.8.0

package/dist/utils/change-metadata.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
 import { ChangeMetadataSchema } from '../core/change-metadata/index.js';
-import { listSchemas } from '../core/artifact-graph/resolver.js';
+import { listSchemas, resolveSchema } from '../core/artifact-graph/resolver.js';
 import { readProjectConfig } from '../core/project-config.js';
 export const METADATA_FILENAME = '.openspec.yaml';
 /**
@@ -126,16 +126,132 @@ export function resolveSchemaForChange(changeDir, explicitSchema, projectRootOve
         return metadata.schema;
     }
     // 3. Try reading from project config when metadata is absent.
-    try {
-        const config = readProjectConfig(projectRoot);
-        if (config?.schema) {
-            return config.schema;
+    if (options.projectConfig !== undefined) {
+        if (options.projectConfig?.schema) {
+            return options.projectConfig.schema;
         }
     }
-    catch {
-        // If config read fails, fall back to default
+    else {
+        try {
+            const config = readProjectConfig(projectRoot);
+            if (config?.schema) {
+                return config.schema;
+            }
+        }
+        catch {
+            // If config read fails, fall back to default
+        }
     }
     // 4. Default
     return 'spec-driven';
 }
+/**
+ * Non-throwing read of the skip_specs marker. The marker only counts when the
+ * metadata would load for status/instructions: the file parses under
+ * ChangeMetadataSchema, its schema name passes readChangeMetadata's
+ * listSchemas membership check, AND the schema itself loads via resolveSchema
+ * (a schema.yaml that exists but does not parse fails status just the same).
+ * Validate and archive must never honor metadata the rest of the CLI rejects,
+ * in either direction. The project root for schema resolution is derived from
+ * changeDir exactly like resolveSchemaForChange (changeDir is
+ * <root>/openspec/changes/<name> for every root type, including store roots).
+ * Missing metadata means "not declared"; a marker that cannot be honored
+ * yields invalidReason so callers can say why.
+ */
+export function readSkipSpecsMarker(changeDir) {
+    return readBooleanMarker(changeDir, 'skip_specs');
+}
+/**
+ * Non-throwing read of the retire_capabilities marker, with exactly the
+ * semantics `readSkipSpecsMarker` documents above.
+ *
+ * Gates the one archive action that removes a file from `openspec/specs/`: when
+ * a change's REMOVED entries take a capability's last requirement, archive
+ * deletes the emptied main spec rather than aborting on a spec it cannot write
+ * (#1302). Declared rather than inferred because the delete is recoverable only
+ * from git, so it is the author's call.
+ */
+export function readRetireCapabilitiesMarker(changeDir) {
+    return readBooleanMarker(changeDir, 'retire_capabilities');
+}
+/**
+ * Shared implementation for the boolean change-metadata markers, keyed by field
+ * name. One body rather than two, so a marker can never drift into honoring
+ * metadata the other rejects - the whole point of the contract described above.
+ */
+function readBooleanMarker(changeDir, key) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(changeDir, METADATA_FILENAME), 'utf-8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return { declared: false };
+        }
+        // The file exists but cannot be read (EACCES, EISDIR, ...). Status and
+        // instructions reject the change outright here, and whether a marker is
+        // set cannot be determined - fail closed rather than let archive treat
+        // the change as unmarked while every metadata-reading surface errors.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            declared: false,
+            invalidReason: `the metadata file cannot be read (${message})`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        // Anchored so a comment like "# maybe add skip_specs later" does not
+        // claim the marker was set.
+        const mentioned = new RegExp(`^\\s*(['"]?)${key}\\1\\s*:`, 'm').test(raw);
+        return mentioned
+            ? { declared: false, invalidReason: 'the file is not valid YAML' }
+            : { declared: false };
+    }
+    const result = ChangeMetadataSchema.safeParse(parsed);
+    if (result.success) {
+        if (result.data[key] !== true) {
+            return { declared: false };
+        }
+        // Schema loading is checked only when the marker is set: a broken schema
+        // on an ordinary change is status's problem to report, but honoring a
+        // marker that status rejects would let validate/archive pass what the
+        // rest of the CLI refuses to load. The membership check mirrors
+        // readChangeMetadata (which rejects names like 'spec-driven.yaml' that
+        // resolveSchema alone would normalize and accept); resolveSchema then
+        // proves the schema actually parses. Any failure fails closed.
+        try {
+            const projectRoot = path.resolve(changeDir, '../../..');
+            if (!listSchemas(projectRoot).includes(result.data.schema)) {
+                return {
+                    declared: false,
+                    invalidReason: `schema: unknown schema '${result.data.schema}'`,
+                };
+            }
+            resolveSchema(result.data.schema, projectRoot);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { declared: false, invalidReason: message };
+        }
+        return { declared: true };
+    }
+    // Key presence, not value: skip_specs: "yes" must surface as unhonorable,
+    // not vanish while the zero-delta guidance tells the user to set the very
+    // marker they set. An explicit skip_specs: false is the opposite of setting
+    // the marker, so it must not drag unrelated metadata problems into
+    // validate - the change simply is not marked.
+    const markerMentioned = typeof parsed === 'object' &&
+        parsed !== null &&
+        key in parsed &&
+        parsed[key] !== false;
+    if (markerMentioned) {
+        const first = result.error.issues[0];
+        const where = first.path.length > 0 ? `${first.path.join('.')}: ` : '';
+        return { declared: false, invalidReason: `${where}${first.message}` };
+    }
+    return { declared: false };
+}
 //# sourceMappingURL=change-metadata.js.map

package/dist/utils/change-utils.d.ts

@@ -31,17 +31,23 @@ export interface ValidationResult {
 /**
  * Validates that a change name follows kebab-case conventions.
  *
- * Valid names:
- * - Start with a lowercase letter
+ * Uses OpenSpec's shared kebab-id grammar (the same one store ids and change
+ * metadata ids use), so a change name may:
+ * - Start with a lowercase letter or a digit
  * - Contain only lowercase letters, numbers, and hyphens
- * - Do not start or end with a hyphen
- * - Do not contain consecutive hyphens
+ * - Not start or end with a hyphen
+ * - Not contain consecutive hyphens
+ *
+ * A leading digit is allowed so ordering conventions like `100-add-feature` or
+ * `00001-add-auth` work; archive already treats such prefixes as a supported
+ * convention (see ARCHIVE_DATE_PREFIX_PATTERN).
  *
  * @param name - The change name to validate
  * @returns Validation result with `valid: true` or `valid: false` with an error message
  *
  * @example
  * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('100-add-feature') // { valid: true }
  * validateChangeName('Add-Auth') // { valid: false, error: '...' }
  */
 export declare function validateChangeName(name: string): ValidationResult;

package/dist/utils/change-utils.js

@@ -1,32 +1,43 @@
 import path from 'path';
 import { FileSystemUtils } from './file-system.js';
 import { writeChangeMetadata, validateSchemaName } from './change-metadata.js';
+import { formatLocalDate } from './date.js';
 import { readProjectConfig } from '../core/project-config.js';
+import { isKebabId } from '../core/id.js';
 const DEFAULT_SCHEMA = 'spec-driven';
 /**
  * Validates that a change name follows kebab-case conventions.
  *
- * Valid names:
- * - Start with a lowercase letter
+ * Uses OpenSpec's shared kebab-id grammar (the same one store ids and change
+ * metadata ids use), so a change name may:
+ * - Start with a lowercase letter or a digit
  * - Contain only lowercase letters, numbers, and hyphens
- * - Do not start or end with a hyphen
- * - Do not contain consecutive hyphens
+ * - Not start or end with a hyphen
+ * - Not contain consecutive hyphens
+ *
+ * A leading digit is allowed so ordering conventions like `100-add-feature` or
+ * `00001-add-auth` work; archive already treats such prefixes as a supported
+ * convention (see ARCHIVE_DATE_PREFIX_PATTERN).
  *
  * @param name - The change name to validate
  * @returns Validation result with `valid: true` or `valid: false` with an error message
  *
  * @example
  * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('100-add-feature') // { valid: true }
  * validateChangeName('Add-Auth') // { valid: false, error: '...' }
  */
 export function validateChangeName(name) {
-    // Pattern: starts with lowercase letter, followed by lowercase letters/numbers,
-    // optionally followed by hyphen + lowercase letters/numbers (repeatable)
-    const kebabCasePattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
     if (!name) {
         return { valid: false, error: 'Change name cannot be empty' };
     }
-    if (!kebabCasePattern.test(name)) {
+    // Filesystem directory components cap at 255 bytes and archive prepends a
+    // date prefix; bounding here turns the failure into a validation message
+    // instead of a raw ENAMETOOLONG from mkdir.
+    if (name.length > 200) {
+        return { valid: false, error: 'Change name is too long (200 characters max)' };
+    }
+    if (!isKebabId(name)) {
         // Provide specific error messages for common mistakes
         if (/[A-Z]/.test(name)) {
             return { valid: false, error: 'Change name must be lowercase (use kebab-case)' };
@@ -49,9 +60,6 @@ export function validateChangeName(name) {
         if (/[^a-z0-9-]/.test(name)) {
             return { valid: false, error: 'Change name can only contain lowercase letters, numbers, and hyphens' };
         }
-        if (/^[0-9]/.test(name)) {
-            return { valid: false, error: 'Change name must start with a letter' };
-        }
         return { valid: false, error: 'Change name must follow kebab-case convention (e.g., add-auth, refactor-db)' };
     }
     return { valid: true };
@@ -127,10 +135,9 @@ export async function createChange(projectRoot, name, options = {}) {
         await FileSystemUtils.writeFile(configPath, `schema: ${defaultSchema}\n`);
     }
     // Write metadata file with schema and creation date
-    const today = new Date().toISOString().split('T')[0];
     writeChangeMetadata(changeDir, {
         schema: schemaName,
-        created: today,
+        created: formatLocalDate(),
         ...options.metadata,
     }, projectRoot);
     return { schema: schemaName, changeDir };

package/dist/utils/ci.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CI environment detection shared by telemetry and the version check.
+ *
+ * Providers set CI to "true", "1", "yes", etc. Only an explicit off-value
+ * counts as "not CI", so an unknown value still suppresses outbound requests
+ * rather than surprising a build.
+ */
+/**
+ * True when `CI` is set to anything other than an explicit off-value.
+ */
+export declare function isCiEnvironment(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=ci.d.ts.map

package/dist/utils/ci.js

@@ -0,0 +1,16 @@
+/**
+ * CI environment detection shared by telemetry and the version check.
+ *
+ * Providers set CI to "true", "1", "yes", etc. Only an explicit off-value
+ * counts as "not CI", so an unknown value still suppresses outbound requests
+ * rather than surprising a build.
+ */
+const CI_DISABLED_VALUES = new Set(['', 'false', '0', 'no', 'off']);
+/**
+ * True when `CI` is set to anything other than an explicit off-value.
+ */
+export function isCiEnvironment(env = process.env) {
+    const value = env.CI;
+    return value !== undefined && !CI_DISABLED_VALUES.has(value.trim().toLowerCase());
+}
+//# sourceMappingURL=ci.js.map

package/dist/utils/command-references.d.ts

@@ -3,16 +3,102 @@
  *
  * Utilities for transforming command references to tool-specific formats.
  */
+import type { CommandSurfaceCapability } from '../core/command-surface.js';
+import type { CommandInvocation } from '../core/command-generation/invocation.js';
 /**
- * Transforms colon-based command references to hyphen-based format.
- * Converts `/opsx:` patterns to `/opsx-` for tools that use hyphen syntax.
+ * Rewrites the canonical `/opsx:<command>` references that command bodies and
+ * skill templates are authored with into the form one tool actually registers
+ * — `/opsx-<command>` for tools that name the command by filename,
+ * `@opsx-<command>` for Amazon Q's prompt library.
+ *
+ * Only known command ids are rewritten, matching how
+ * `transformToSkillReferences` leaves unrecognized references alone, so a
+ * mistyped or invented `/opsx:<something>` is left as written rather than
+ * silently reshaped into a command that does not exist either.
  *
  * @param text - The text containing command references
- * @returns Text with command references transformed to hyphen format
+ * @param invocation - The tool's invocation, from resolveCommandInvocation()
+ * @returns Text with command references spelled the tool's way
  *
  * @example
- * transformToHyphenCommands('/opsx:new') // returns '/opsx-new'
- * transformToHyphenCommands('Use /opsx:apply to implement') // returns 'Use /opsx-apply to implement'
+ * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '/' }) // '/opsx-new'
+ * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '@' }) // '@opsx-new'
+ */
+export declare function transformCommandInvocations(text: string, invocation: CommandInvocation): string;
+/**
+ * Whether a tool references skills by natural language rather than a slash
+ * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
+ */
+export declare function usesNaturalLanguageSkillReferences(toolId: string): boolean;
+/**
+ * Keeps Codex's `$<name>` spelling first while making its canonical shared
+ * `.agents` tree usable by agents that invoke the same skills with `/<name>`.
+ */
+export declare function transformToCodexCompatibleSkillReferences(text: string): string;
+/**
+ * Transforms command references to skill references using the default `/`
+ * invocation prefix. Converts `/opsx:<command>` patterns to
+ * `/openspec-<skill>` so that generated skills do not reference commands
+ * that were never generated. Used for channels that are not tied to one
+ * tool (e.g. the skills.sh distribution); tool-targeted generation should
+ * go through getSkillReferenceTransformer instead.
+ *
+ * Unknown command references are left unchanged.
+ *
+ * @param text - The text containing command references
+ * @returns Text with command references transformed to skill references
+ *
+ * @example
+ * transformToSkillReferences('/opsx:apply') // returns '/openspec-apply-change'
+ * transformToSkillReferences('Use /opsx:archive next') // returns 'Use /openspec-archive-change next'
+ */
+export declare function transformToSkillReferences(text: string): string;
+/**
+ * Returns the skill-reference transformer for a specific tool, honoring the
+ * tool's documented skill invocation syntax (e.g. Kimi Code's
+ * `/skill:openspec-propose`). Tools with no slash surface (e.g. Rovo Dev) get
+ * natural-language references ("the openspec-propose skill"); everything else
+ * falls back to the default `/openspec-*` form.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe', 'rovodev')
+ * @returns A transformer converting `/opsx:*` references to skill invocations
+ */
+export declare function getSkillReferenceTransformer(toolId: string): (text: string) => string;
+/**
+ * Selects the command-reference transformer for a skill generation target.
+ *
+ * Skill references are used whenever the tool ends up without `/opsx:*`
+ * commands — because delivery is skills-only, because the tool has no command
+ * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
+ * because the tool invokes skills directly and OpenSpec generates no command
+ * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * never point at commands that were not generated.
+ *
+ * When commands are generated, the spelling follows the tool's invocation: a
+ * `flat` adapter names the command by filename (`.cursor/commands/opsx-apply.md`
+ * → `/opsx-apply`), a `namespaced` adapter puts it in an `opsx/` directory
+ * (`.claude/commands/opsx/apply.md` → `/opsx:apply`), and a non-slash prefix
+ * wraps it further (`.amazonq/prompts/opsx-apply.md` → `@opsx-apply`). Passing
+ * the invocation in keeps this module free of a hand-maintained tool list —
+ * the list drifted and left 16 tools advertising commands their palettes never
+ * registered (#727, #1307).
+ *
+ * Devin is the one tool that takes skill references even though its commands
+ * are generated: only Devin Desktop reads `.devin/workflows/`, so a workflow
+ * reference is dead text for anyone on Devin Local, while the `/openspec-*`
+ * skills work on both agents. Under commands-only delivery there are no Devin
+ * skills to point at, so it falls through to the invocation rewrite below and
+ * gets the `/opsx-<id>` form its workflow filenames register.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'claude', 'opencode', 'pi')
+ * @param delivery - The configured delivery mode
+ * @param capability - The tool's command surface capability
+ * @param invocation - How the tool's generated commands are invoked, from
+ *        resolveCommandInvocation(); undefined for tools with no command
+ *        adapter. Required rather than optional so a caller that forgets it
+ *        fails to compile instead of silently getting the canonical form.
+ * @returns The transformer to pass to generateSkillContent, or undefined when
+ *          the tool already answers to the canonical `/opsx:<id>`
  */
-export declare function transformToHyphenCommands(text: string): string;
+export declare function getTransformerForTool(toolId: string, delivery: 'both' | 'skills' | 'commands', capability: CommandSurfaceCapability, invocation: CommandInvocation | undefined): ((text: string) => string) | undefined;
 //# sourceMappingURL=command-references.d.ts.map

package/dist/utils/command-references.js

@@ -3,18 +3,191 @@
  *
  * Utilities for transforming command references to tool-specific formats.
  */
+// Value import of a pure, dependency-free helper: invocation.ts imports only
+// `path` and a type, so this does not close the cycle the note above guards.
+import { formatCommandInvocation, needsInvocationRewrite, } from '../core/command-generation/invocation.js';
 /**
- * Transforms colon-based command references to hyphen-based format.
- * Converts `/opsx:` patterns to `/opsx-` for tools that use hyphen syntax.
+ * Rewrites the canonical `/opsx:<command>` references that command bodies and
+ * skill templates are authored with into the form one tool actually registers
+ * — `/opsx-<command>` for tools that name the command by filename,
+ * `@opsx-<command>` for Amazon Q's prompt library.
+ *
+ * Only known command ids are rewritten, matching how
+ * `transformToSkillReferences` leaves unrecognized references alone, so a
+ * mistyped or invented `/opsx:<something>` is left as written rather than
+ * silently reshaped into a command that does not exist either.
+ *
+ * @param text - The text containing command references
+ * @param invocation - The tool's invocation, from resolveCommandInvocation()
+ * @returns Text with command references spelled the tool's way
+ *
+ * @example
+ * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '/' }) // '/opsx-new'
+ * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '@' }) // '@opsx-new'
+ */
+export function transformCommandInvocations(text, invocation) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => commandId in COMMAND_TO_SKILL_NAME
+        ? formatCommandInvocation(invocation, commandId)
+        : match);
+}
+/**
+ * Maps command short names to their skill names.
+ * Keep in sync with WORKFLOW_TO_SKILL_DIR, which exists in both
+ * src/core/profile-sync-drift.ts (exported) and src/core/init.ts (local copy).
+ */
+const COMMAND_TO_SKILL_NAME = {
+    'explore': 'openspec-explore',
+    'new': 'openspec-new-change',
+    'continue': 'openspec-continue-change',
+    'apply': 'openspec-apply-change',
+    'update': 'openspec-update-change',
+    'ff': 'openspec-ff-change',
+    'sync': 'openspec-sync-specs',
+    'archive': 'openspec-archive-change',
+    'bulk-archive': 'openspec-bulk-archive-change',
+    'verify': 'openspec-verify-change',
+    'onboard': 'openspec-onboard',
+    'propose': 'openspec-propose',
+};
+/**
+ * Tools whose skill invocation uses a non-default prefix. The default is `/`
+ * (e.g. `/openspec-propose`); Kimi Code invokes skills as `/skill:<name>` and
+ * Codex CLI as `$<name>` — a `/<name>` form Codex does not recognize
+ * (see docs/supported-tools.md).
+ */
+const SKILL_INVOCATION_PREFIX = {
+    kimi: '/skill:',
+    codex: '$',
+};
+/**
+ * Tools that have no slash-command surface at all: skills are matched
+ * automatically or invoked by natural-language prompts, never by typing a
+ * `/<name>` command. Rovo Dev CLI is such a tool — `/skills` only manages
+ * skills, and any `/openspec-*` form would be a dead command (see
+ * docs/supported-tools.md). References for these tools are spelled as prose
+ * ("the openspec-propose skill") so generated content never tells the user to
+ * type a command their CLI does not register.
+ */
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev']);
+/**
+ * Whether a tool references skills by natural language rather than a slash
+ * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
+ */
+export function usesNaturalLanguageSkillReferences(toolId) {
+    return NATURAL_LANGUAGE_SKILL_TOOLS.has(toolId);
+}
+function replaceCommandsWithNaturalLanguageSkillReferences(text) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined ? match : `the ${skillName} skill`;
+    });
+}
+function replaceCommandsWithSkillReferences(text, prefix) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined ? match : `${prefix}${skillName}`;
+    });
+}
+/**
+ * Keeps Codex's `$<name>` spelling first while making its canonical shared
+ * `.agents` tree usable by agents that invoke the same skills with `/<name>`.
+ */
+export function transformToCodexCompatibleSkillReferences(text) {
+    return text.replace(/\/opsx:([a-z-]+)/g, (match, commandId) => {
+        const skillName = COMMAND_TO_SKILL_NAME[commandId];
+        return skillName === undefined
+            ? match
+            : `$${skillName} (Codex) or /${skillName} (other agents)`;
+    });
+}
+/**
+ * Transforms command references to skill references using the default `/`
+ * invocation prefix. Converts `/opsx:<command>` patterns to
+ * `/openspec-<skill>` so that generated skills do not reference commands
+ * that were never generated. Used for channels that are not tied to one
+ * tool (e.g. the skills.sh distribution); tool-targeted generation should
+ * go through getSkillReferenceTransformer instead.
+ *
+ * Unknown command references are left unchanged.
  *
  * @param text - The text containing command references
- * @returns Text with command references transformed to hyphen format
+ * @returns Text with command references transformed to skill references
  *
  * @example
- * transformToHyphenCommands('/opsx:new') // returns '/opsx-new'
- * transformToHyphenCommands('Use /opsx:apply to implement') // returns 'Use /opsx-apply to implement'
+ * transformToSkillReferences('/opsx:apply') // returns '/openspec-apply-change'
+ * transformToSkillReferences('Use /opsx:archive next') // returns 'Use /openspec-archive-change next'
+ */
+export function transformToSkillReferences(text) {
+    return replaceCommandsWithSkillReferences(text, '/');
+}
+/**
+ * Returns the skill-reference transformer for a specific tool, honoring the
+ * tool's documented skill invocation syntax (e.g. Kimi Code's
+ * `/skill:openspec-propose`). Tools with no slash surface (e.g. Rovo Dev) get
+ * natural-language references ("the openspec-propose skill"); everything else
+ * falls back to the default `/openspec-*` form.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe', 'rovodev')
+ * @returns A transformer converting `/opsx:*` references to skill invocations
+ */
+export function getSkillReferenceTransformer(toolId) {
+    if (usesNaturalLanguageSkillReferences(toolId)) {
+        return replaceCommandsWithNaturalLanguageSkillReferences;
+    }
+    const prefix = SKILL_INVOCATION_PREFIX[toolId];
+    if (prefix === undefined) {
+        return transformToSkillReferences;
+    }
+    return (text) => replaceCommandsWithSkillReferences(text, prefix);
+}
+/**
+ * Selects the command-reference transformer for a skill generation target.
+ *
+ * Skill references are used whenever the tool ends up without `/opsx:*`
+ * commands — because delivery is skills-only, because the tool has no command
+ * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
+ * because the tool invokes skills directly and OpenSpec generates no command
+ * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * never point at commands that were not generated.
+ *
+ * When commands are generated, the spelling follows the tool's invocation: a
+ * `flat` adapter names the command by filename (`.cursor/commands/opsx-apply.md`
+ * → `/opsx-apply`), a `namespaced` adapter puts it in an `opsx/` directory
+ * (`.claude/commands/opsx/apply.md` → `/opsx:apply`), and a non-slash prefix
+ * wraps it further (`.amazonq/prompts/opsx-apply.md` → `@opsx-apply`). Passing
+ * the invocation in keeps this module free of a hand-maintained tool list —
+ * the list drifted and left 16 tools advertising commands their palettes never
+ * registered (#727, #1307).
+ *
+ * Devin is the one tool that takes skill references even though its commands
+ * are generated: only Devin Desktop reads `.devin/workflows/`, so a workflow
+ * reference is dead text for anyone on Devin Local, while the `/openspec-*`
+ * skills work on both agents. Under commands-only delivery there are no Devin
+ * skills to point at, so it falls through to the invocation rewrite below and
+ * gets the `/opsx-<id>` form its workflow filenames register.
+ *
+ * @param toolId - The AI tool identifier (e.g. 'claude', 'opencode', 'pi')
+ * @param delivery - The configured delivery mode
+ * @param capability - The tool's command surface capability
+ * @param invocation - How the tool's generated commands are invoked, from
+ *        resolveCommandInvocation(); undefined for tools with no command
+ *        adapter. Required rather than optional so a caller that forgets it
+ *        fails to compile instead of silently getting the canonical form.
+ * @returns The transformer to pass to generateSkillContent, or undefined when
+ *          the tool already answers to the canonical `/opsx:<id>`
  */
-export function transformToHyphenCommands(text) {
-    return text.replace(/\/opsx:/g, '/opsx-');
+export function getTransformerForTool(toolId, delivery, capability, invocation) {
+    if (delivery === 'skills' || capability !== 'adapter-backed') {
+        return toolId === 'codex'
+            ? transformToCodexCompatibleSkillReferences
+            : getSkillReferenceTransformer(toolId);
+    }
+    if (toolId === 'devin' && delivery === 'both') {
+        return getSkillReferenceTransformer(toolId);
+    }
+    if (invocation !== undefined && needsInvocationRewrite(invocation)) {
+        return (text) => transformCommandInvocations(text, invocation);
+    }
+    return undefined;
 }
 //# sourceMappingURL=command-references.js.map

package/dist/utils/date.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats a date using the effective local time zone of the Node.js process.
+ *
+ * The result is locale-independent and suitable for date-only metadata and
+ * path prefixes.
+ */
+export declare function formatLocalDate(date?: Date): string;
+//# sourceMappingURL=date.d.ts.map

package/dist/utils/date.js

@@ -0,0 +1,13 @@
+/**
+ * Formats a date using the effective local time zone of the Node.js process.
+ *
+ * The result is locale-independent and suitable for date-only metadata and
+ * path prefixes.
+ */
+export function formatLocalDate(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+//# sourceMappingURL=date.js.map

package/dist/utils/file-system.d.ts

@@ -9,6 +9,16 @@ export declare class FileSystemUtils {
      * Falls back to path.resolve() so callers can still produce a stable absolute path.
      */
     static canonicalizeExistingPath(targetPath: string): string;
+    /**
+     * Refuses a target that leaves an allowed directory, including through an
+     * existing symlink in either the target or one of its parent directories.
+     * Missing suffixes are resolved from their nearest existing ancestor.
+     */
+    static assertPathWithin(allowedDirectory: string, targetPath: string): void;
+    static resolveProjectArtifactPath(projectPath: string, artifactPath: string): string;
+    static assertProjectArtifactPath(projectPath: string, targetPath: string): void;
+    private static isPathWithin;
+    private static canonicalizePotentialPath;
     private static isWindowsBasePath;
     private static normalizeSegments;
     static joinPath(basePath: string, ...segments: string[]): string;