@codewalla_india/openspec 1.3.0 → 1.3.2

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

@@ -1,25 +1,30 @@
 /**
  * Qwen Code Command Adapter
  *
- * Formats commands for Qwen Code following its TOML specification.
+ * Formats commands for Qwen Code following its Markdown custom command
+ * specification. Qwen Code has deprecated TOML commands in favor of
+ * Markdown files with YAML frontmatter.
+ *
+ * @see https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/#markdown-file-format-specification-recommended
  */
 import path from 'path';
+import { escapeYamlValue } from '../yaml.js';
 /**
  * Qwen adapter for command generation.
- * File path: .qwen/commands/opsx-<id>.toml
- * Format: TOML with description and prompt fields
+ * File path: .qwen/commands/opsx-<id>.md
+ * Format: Markdown with description frontmatter
  */
 export const qwenAdapter = {
     toolId: 'qwen',
     getFilePath(commandId) {
-        return path.join('.qwen', 'commands', `opsx-${commandId}.toml`);
+        return path.join('.qwen', 'commands', `opsx-${commandId}.md`);
     },
     formatFile(content) {
-        return `description = "${content.description}"
-
-prompt = """
-${content.body}
-"""
+        return `---
+description: ${escapeYamlValue(content.description)}
+---
+
+${content.body}
 `;
     },
 };

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

@@ -1,12 +1,12 @@
 /**
- * RooCode Command Adapter
+ * Zoo Code Command Adapter
  *
- * Formats commands for RooCode following its workflow specification.
- * RooCode uses markdown headers instead of YAML frontmatter.
+ * Formats commands for Zoo Code following its workflow specification.
+ * Zoo Code uses markdown headers instead of YAML frontmatter.
  */
 import type { ToolCommandAdapter } from '../types.js';
 /**
- * RooCode adapter for command generation.
+ * Zoo Code adapter for command generation.
  * File path: .roo/commands/opsx-<id>.md
  * Format: Markdown header with description
  */

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

@@ -1,12 +1,12 @@
 /**
- * RooCode Command Adapter
+ * Zoo Code Command Adapter
  *
- * Formats commands for RooCode following its workflow specification.
- * RooCode uses markdown headers instead of YAML frontmatter.
+ * Formats commands for Zoo Code following its workflow specification.
+ * Zoo Code uses markdown headers instead of YAML frontmatter.
  */
 import path from 'path';
 /**
- * RooCode adapter for command generation.
+ * Zoo Code adapter for command generation.
  * File path: .roo/commands/opsx-<id>.md
  * Format: Markdown header with description
  */
@@ -16,11 +16,11 @@ export const roocodeAdapter = {
         return path.join('.roo', 'commands', `opsx-${commandId}.md`);
     },
     formatFile(content) {
-        return `# ${content.name}
-
-${content.description}
-
-${content.body}
+        return `# ${content.name}
+
+${content.description}
+
+${content.body}
 `;
     },
 };

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

@@ -0,0 +1,13 @@
+/**
+ * Trae Command Adapter
+ *
+ * Formats commands for Trae IDE following its command specification.
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * Trae adapter for command generation.
+ * File path: .trae/commands/opsx-<id>.md
+ * Frontmatter: name, description
+ */
+export declare const traeAdapter: ToolCommandAdapter;
+//# sourceMappingURL=trae.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * Trae Command Adapter
+ *
+ * Formats commands for Trae IDE following its command specification.
+ */
+import path from 'path';
+import { escapeYamlValue } from '../yaml.js';
+/**
+ * Trae adapter for command generation.
+ * File path: .trae/commands/opsx-<id>.md
+ * Frontmatter: name, description
+ */
+export const traeAdapter = {
+    toolId: 'trae',
+    getFilePath(commandId) {
+        return path.join('.trae', 'commands', `opsx-${commandId}.md`);
+    },
+    formatFile(content) {
+        return `---
+name: ${escapeYamlValue(content.name)}
+description: ${escapeYamlValue(content.description)}
+---
+
+${content.body}
+`;
+    },
+};
+//# sourceMappingURL=trae.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * ZCode Command Adapter
+ *
+ * Formats commands for ZCode following its frontmatter specification.
+ * ZCode shares Claude Code's command format conventions.
+ * File path: .zcode/commands/opsx/<id>.md
+ * Frontmatter: name, description, category, tags
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * ZCode adapter for command generation.
+ * File path: .zcode/commands/opsx/<id>.md
+ * Frontmatter: name, description, category, tags
+ */
+export declare const zcodeAdapter: ToolCommandAdapter;
+//# sourceMappingURL=zcode.d.ts.map

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

@@ -0,0 +1,33 @@
+/**
+ * ZCode Command Adapter
+ *
+ * Formats commands for ZCode following its frontmatter specification.
+ * ZCode shares Claude Code's command format conventions.
+ * File path: .zcode/commands/opsx/<id>.md
+ * Frontmatter: name, description, category, tags
+ */
+import path from 'path';
+import { escapeYamlValue, formatTagsArray } from '../yaml.js';
+/**
+ * ZCode adapter for command generation.
+ * File path: .zcode/commands/opsx/<id>.md
+ * Frontmatter: name, description, category, tags
+ */
+export const zcodeAdapter = {
+    toolId: 'zcode',
+    getFilePath(commandId) {
+        return path.join('.zcode', 'commands', 'opsx', `${commandId}.md`);
+    },
+    formatFile(content) {
+        return `---
+name: ${escapeYamlValue(content.name)}
+description: ${escapeYamlValue(content.description)}
+category: ${escapeYamlValue(content.category)}
+tags: ${formatTagsArray(content.tags)}
+---
+
+${content.body}
+`;
+    },
+};
+//# sourceMappingURL=zcode.js.map

package/dist/core/command-generation/generator.d.ts

@@ -6,6 +6,14 @@
 import type { CommandContent, ToolCommandAdapter, GeneratedCommand } from './types.js';
 /**
  * Generate a single command file using the provided adapter.
+ *
+ * Command bodies are authored with `/opsx:<id>` references. Tools whose command
+ * files are invoked by filename register `/opsx-<id>` instead, and Amazon Q
+ * surfaces them in its prompt library as `@opsx-<id>`, so the body is rewritten
+ * to the form that tool answers to before the adapter formats it. Doing it here
+ * rather than per adapter keeps every tool in step (#727, #1307); adapters stay
+ * pure formatters.
+ *
  * @param content - The tool-agnostic command content
  * @param adapter - The tool-specific adapter
  * @returns Generated command with path and file content

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

@@ -3,16 +3,30 @@
  *
  * Functions for generating command files using tool adapters.
  */
+import { getInvocationForAdapter, needsInvocationRewrite } from './invocation.js';
+import { transformCommandInvocations } from '../../utils/command-references.js';
 /**
  * Generate a single command file using the provided adapter.
+ *
+ * Command bodies are authored with `/opsx:<id>` references. Tools whose command
+ * files are invoked by filename register `/opsx-<id>` instead, and Amazon Q
+ * surfaces them in its prompt library as `@opsx-<id>`, so the body is rewritten
+ * to the form that tool answers to before the adapter formats it. Doing it here
+ * rather than per adapter keeps every tool in step (#727, #1307); adapters stay
+ * pure formatters.
+ *
  * @param content - The tool-agnostic command content
  * @param adapter - The tool-specific adapter
  * @returns Generated command with path and file content
  */
 export function generateCommand(content, adapter) {
+    const invocation = getInvocationForAdapter(adapter);
+    const formatted = needsInvocationRewrite(invocation)
+        ? { ...content, body: transformCommandInvocations(content.body, invocation) }
+        : content;
     return {
         path: adapter.getFilePath(content.id),
-        fileContent: adapter.formatFile(content),
+        fileContent: adapter.formatFile(formatted),
     };
 }
 /**

package/dist/core/command-generation/index.d.ts

@@ -18,5 +18,5 @@
 export type { CommandContent, ToolCommandAdapter, GeneratedCommand, } from './types.js';
 export { CommandAdapterRegistry } from './registry.js';
 export { generateCommand, generateCommands } from './generator.js';
-export { claudeAdapter, cursorAdapter, windsurfAdapter } from './adapters/index.js';
+export { claudeAdapter, cursorAdapter, devinAdapter } from './adapters/index.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -20,5 +20,5 @@ export { CommandAdapterRegistry } from './registry.js';
 // Generator functions
 export { generateCommand, generateCommands } from './generator.js';
 // Adapters (for direct access if needed)
-export { claudeAdapter, cursorAdapter, windsurfAdapter } from './adapters/index.js';
+export { claudeAdapter, cursorAdapter, devinAdapter } from './adapters/index.js';
 //# sourceMappingURL=index.js.map

package/dist/core/command-generation/invocation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Command Invocation
+ *
+ * How a tool spells an OpenSpec command has two parts, and only one of them
+ * can be read off the file the adapter writes:
+ *
+ * - The *name* comes from the file. `.../commands/opsx/<id>.md` is namespaced
+ *   by its directory, so the tool registers `opsx:<id>` (Claude Code, Gemini,
+ *   Crush, ...). `.../commands/opsx-<id>.md` names the command with the
+ *   filename, so the tool registers `opsx-<id>` (Cursor, GitHub Copilot,
+ *   OpenCode, ...).
+ * - The *prefix* is the tool's own and cannot be derived. Almost every tool
+ *   uses `/`; Amazon Q loads these files into its prompt library, which is
+ *   invoked with `@` (`@opsx-propose`), so its adapter declares that prefix.
+ *
+ * Deriving the name from `getFilePath` keeps generated cross-references and
+ * onboarding hints in step with the files OpenSpec actually writes. A
+ * hand-maintained list drifted before: only OpenCode was rewritten when the
+ * hyphen form was introduced (#727), and Cursor still advertised `/opsx:`
+ * commands its palette never registered (#1307). Carrying the prefix as
+ * adapter metadata rather than inferring it keeps the one tool that does not
+ * use a slash from being advertised as if it did.
+ */
+import type { ToolCommandAdapter } from './types.js';
+export type CommandInvocationStyle = 'namespaced' | 'flat';
+/**
+ * Everything needed to spell one of a tool's OpenSpec commands.
+ */
+export interface CommandInvocation {
+    /** How the command file names the command. */
+    style: CommandInvocationStyle;
+    /** What the user types before the name, e.g. `/` or Amazon Q's `@`. */
+    prefix: string;
+}
+/** The form these docs, command bodies, and skill templates are authored in. */
+export declare const CANONICAL_INVOCATION: CommandInvocation;
+/**
+ * Classifies a generated command file by the name the tool will answer to.
+ *
+ * The test is the filename, not the directory: an `opsx-` prefix means the
+ * filename is the command. Every other shape is treated as namespaced, which
+ * is what all seven `opsx/<id>.*` adapters need. An adapter that neither
+ * prefixes the filename nor nests under `opsx/` would land here too — none
+ * does, and the registry-wide test in invocation.test.ts fails if one appears.
+ *
+ * @param commandFilePath - Path returned by an adapter's `getFilePath`
+ * @returns 'flat' when the filename carries the `opsx-` prefix, otherwise
+ *          'namespaced'
+ */
+export declare function getInvocationStyleForPath(commandFilePath: string): CommandInvocationStyle;
+/**
+ * Resolves how a tool's generated commands are invoked: the name from the
+ * files its adapter writes, the prefix from the adapter's own declaration.
+ *
+ * @param adapter - The tool-specific command adapter
+ * @returns The invocation shared by every command that adapter generates
+ */
+export declare function getInvocationForAdapter(adapter: ToolCommandAdapter): CommandInvocation;
+/**
+ * Spells one command the way the tool registers it.
+ *
+ * @param invocation - The tool's invocation, from getInvocationForAdapter()
+ * @param commandId - The command identifier (e.g. 'apply')
+ * @returns What the user types, e.g. `/opsx:apply`, `/opsx-apply`, `@opsx-apply`
+ */
+export declare function formatCommandInvocation(invocation: CommandInvocation, commandId: string): string;
+/**
+ * Whether a tool's invocation differs from the canonical `/opsx:<id>` that
+ * command bodies and skill templates are authored in — that is, whether
+ * generated text has to be rewritten for that tool at all.
+ */
+export declare function needsInvocationRewrite(invocation: CommandInvocation): boolean;
+//# sourceMappingURL=invocation.d.ts.map

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

@@ -0,0 +1,77 @@
+/**
+ * Command Invocation
+ *
+ * How a tool spells an OpenSpec command has two parts, and only one of them
+ * can be read off the file the adapter writes:
+ *
+ * - The *name* comes from the file. `.../commands/opsx/<id>.md` is namespaced
+ *   by its directory, so the tool registers `opsx:<id>` (Claude Code, Gemini,
+ *   Crush, ...). `.../commands/opsx-<id>.md` names the command with the
+ *   filename, so the tool registers `opsx-<id>` (Cursor, GitHub Copilot,
+ *   OpenCode, ...).
+ * - The *prefix* is the tool's own and cannot be derived. Almost every tool
+ *   uses `/`; Amazon Q loads these files into its prompt library, which is
+ *   invoked with `@` (`@opsx-propose`), so its adapter declares that prefix.
+ *
+ * Deriving the name from `getFilePath` keeps generated cross-references and
+ * onboarding hints in step with the files OpenSpec actually writes. A
+ * hand-maintained list drifted before: only OpenCode was rewritten when the
+ * hyphen form was introduced (#727), and Cursor still advertised `/opsx:`
+ * commands its palette never registered (#1307). Carrying the prefix as
+ * adapter metadata rather than inferring it keeps the one tool that does not
+ * use a slash from being advertised as if it did.
+ */
+import path from 'path';
+/** The form these docs, command bodies, and skill templates are authored in. */
+export const CANONICAL_INVOCATION = { style: 'namespaced', prefix: '/' };
+/**
+ * Classifies a generated command file by the name the tool will answer to.
+ *
+ * The test is the filename, not the directory: an `opsx-` prefix means the
+ * filename is the command. Every other shape is treated as namespaced, which
+ * is what all seven `opsx/<id>.*` adapters need. An adapter that neither
+ * prefixes the filename nor nests under `opsx/` would land here too — none
+ * does, and the registry-wide test in invocation.test.ts fails if one appears.
+ *
+ * @param commandFilePath - Path returned by an adapter's `getFilePath`
+ * @returns 'flat' when the filename carries the `opsx-` prefix, otherwise
+ *          'namespaced'
+ */
+export function getInvocationStyleForPath(commandFilePath) {
+    return path.basename(commandFilePath).startsWith('opsx-') ? 'flat' : 'namespaced';
+}
+/**
+ * Resolves how a tool's generated commands are invoked: the name from the
+ * files its adapter writes, the prefix from the adapter's own declaration.
+ *
+ * @param adapter - The tool-specific command adapter
+ * @returns The invocation shared by every command that adapter generates
+ */
+export function getInvocationForAdapter(adapter) {
+    return {
+        // Any command id works: every adapter applies one naming rule to all of them.
+        style: getInvocationStyleForPath(adapter.getFilePath('explore')),
+        prefix: adapter.invocationPrefix ?? CANONICAL_INVOCATION.prefix,
+    };
+}
+/**
+ * Spells one command the way the tool registers it.
+ *
+ * @param invocation - The tool's invocation, from getInvocationForAdapter()
+ * @param commandId - The command identifier (e.g. 'apply')
+ * @returns What the user types, e.g. `/opsx:apply`, `/opsx-apply`, `@opsx-apply`
+ */
+export function formatCommandInvocation(invocation, commandId) {
+    const separator = invocation.style === 'namespaced' ? ':' : '-';
+    return `${invocation.prefix}opsx${separator}${commandId}`;
+}
+/**
+ * Whether a tool's invocation differs from the canonical `/opsx:<id>` that
+ * command bodies and skill templates are authored in — that is, whether
+ * generated text has to be rewritten for that tool at all.
+ */
+export function needsInvocationRewrite(invocation) {
+    return (invocation.style !== CANONICAL_INVOCATION.style ||
+        invocation.prefix !== CANONICAL_INVOCATION.prefix);
+}
+//# sourceMappingURL=invocation.js.map

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

@@ -10,7 +10,7 @@ import { auggieAdapter } from './adapters/auggie.js';
 import { bobAdapter } from './adapters/bob.js';
 import { claudeAdapter } from './adapters/claude.js';
 import { clineAdapter } from './adapters/cline.js';
-import { codexAdapter } from './adapters/codex.js';
+import { devinAdapter } from './adapters/devin.js';
 import { codebuddyAdapter } from './adapters/codebuddy.js';
 import { continueAdapter } from './adapters/continue.js';
 import { costrictAdapter } from './adapters/costrict.js';
@@ -23,13 +23,15 @@ import { iflowAdapter } from './adapters/iflow.js';
 import { junieAdapter } from './adapters/junie.js';
 import { kilocodeAdapter } from './adapters/kilocode.js';
 import { kiroAdapter } from './adapters/kiro.js';
+import { ohMyPiAdapter } from './adapters/oh-my-pi.js';
 import { opencodeAdapter } from './adapters/opencode.js';
 import { piAdapter } from './adapters/pi.js';
 import { qoderAdapter } from './adapters/qoder.js';
 import { lingmaAdapter } from './adapters/lingma.js';
 import { qwenAdapter } from './adapters/qwen.js';
 import { roocodeAdapter } from './adapters/roocode.js';
-import { windsurfAdapter } from './adapters/windsurf.js';
+import { traeAdapter } from './adapters/trae.js';
+import { zcodeAdapter } from './adapters/zcode.js';
 /**
  * Registry for looking up tool command adapters.
  */
@@ -43,7 +45,7 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(bobAdapter);
         CommandAdapterRegistry.register(claudeAdapter);
         CommandAdapterRegistry.register(clineAdapter);
-        CommandAdapterRegistry.register(codexAdapter);
+        CommandAdapterRegistry.register(devinAdapter);
         CommandAdapterRegistry.register(codebuddyAdapter);
         CommandAdapterRegistry.register(continueAdapter);
         CommandAdapterRegistry.register(costrictAdapter);
@@ -56,13 +58,15 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(junieAdapter);
         CommandAdapterRegistry.register(kilocodeAdapter);
         CommandAdapterRegistry.register(kiroAdapter);
+        CommandAdapterRegistry.register(ohMyPiAdapter);
         CommandAdapterRegistry.register(opencodeAdapter);
         CommandAdapterRegistry.register(piAdapter);
         CommandAdapterRegistry.register(qoderAdapter);
         CommandAdapterRegistry.register(lingmaAdapter);
         CommandAdapterRegistry.register(qwenAdapter);
         CommandAdapterRegistry.register(roocodeAdapter);
-        CommandAdapterRegistry.register(windsurfAdapter);
+        CommandAdapterRegistry.register(traeAdapter);
+        CommandAdapterRegistry.register(zcodeAdapter);
     }
     /**
      * Register a tool command adapter.

package/dist/core/command-generation/types.d.ts

@@ -34,9 +34,16 @@ export interface ToolCommandAdapter {
      * Returns the file path for a command.
      * @param commandId - The command identifier (e.g., 'explore')
      * @returns Path from project root (e.g., '.claude/commands/opsx/explore.md').
-     *          May be absolute for tools with global-scoped prompts (e.g., Codex).
+     *          May be absolute for tools with global-scoped command files.
      */
     getFilePath(commandId: string): string;
+    /**
+     * What the user types before the command name, when it is not the default
+     * `/`. Amazon Q loads these files into its prompt library, which is invoked
+     * with `@` (`@opsx-propose`), so its adapter sets '@'. The name itself is
+     * still derived from getFilePath — see invocation.ts.
+     */
+    invocationPrefix?: string;
     /**
      * Formats the complete file content including frontmatter.
      * @param content - The tool-agnostic command content
@@ -48,7 +55,7 @@ export interface ToolCommandAdapter {
  * Result of generating a command file.
  */
 export interface GeneratedCommand {
-    /** File path from project root, or absolute for global-scoped tools */
+    /** File path from project root, or absolute for global-scoped command files */
     path: string;
     /** Complete file content (frontmatter + body) */
     fileContent: string;

package/dist/core/command-generation/yaml.d.ts

@@ -9,14 +9,28 @@
 /**
  * Escapes a string value for safe YAML output.
  *
- * Quotes the value with double quotes when it contains characters that
- * carry special meaning in YAML (or leading/trailing whitespace), and
- * escapes the characters that are not representable verbatim inside a
- * double-quoted scalar: backslash, double quote, line feed and carriage
- * return. Values without special characters are returned unquoted.
+ * Always emits a double-quoted scalar. Quoting unconditionally keeps the
+ * value a string no matter what it holds: an unquoted `true`, `null` or
+ * `123` would round-trip as a boolean, null or number, and an unquoted
+ * value opening with a block indicator (`|`, `>`) or containing `: `
+ * is not valid YAML at all.
+ *
+ * Inside the quotes it escapes everything that cannot appear verbatim in a
+ * double-quoted scalar: backslash, double quote, line feed, carriage
+ * return, and the non-printable characters YAML's `c-printable` production
+ * excludes (C0 controls, DEL and C1 controls). Lenient parsers accept a raw
+ * control byte, but strict ones reject the document outright, so escaping
+ * them here keeps the generated file portable across every tool's parser.
  *
  * @param value - The raw string to embed in YAML frontmatter.
- * @returns The value, double-quoted and escaped when necessary.
+ * @returns The value as an escaped, double-quoted YAML scalar.
  */
 export declare function escapeYamlValue(value: string): string;
+/**
+ * Formats a tags array as a YAML array with proper escaping.
+ *
+ * @param tags - Array of tag strings.
+ * @returns Formatted YAML array string, e.g. '[tag1, tag2]'.
+ */
+export declare function formatTagsArray(tags: string[]): string;
 //# sourceMappingURL=yaml.d.ts.map

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

@@ -9,30 +9,40 @@
 /**
  * Escapes a string value for safe YAML output.
  *
- * Quotes the value with double quotes when it contains characters that
- * carry special meaning in YAML (or leading/trailing whitespace), and
- * escapes the characters that are not representable verbatim inside a
- * double-quoted scalar: backslash, double quote, line feed and carriage
- * return. Values without special characters are returned unquoted.
+ * Always emits a double-quoted scalar. Quoting unconditionally keeps the
+ * value a string no matter what it holds: an unquoted `true`, `null` or
+ * `123` would round-trip as a boolean, null or number, and an unquoted
+ * value opening with a block indicator (`|`, `>`) or containing `: `
+ * is not valid YAML at all.
+ *
+ * Inside the quotes it escapes everything that cannot appear verbatim in a
+ * double-quoted scalar: backslash, double quote, line feed, carriage
+ * return, and the non-printable characters YAML's `c-printable` production
+ * excludes (C0 controls, DEL and C1 controls). Lenient parsers accept a raw
+ * control byte, but strict ones reject the document outright, so escaping
+ * them here keeps the generated file portable across every tool's parser.
  *
  * @param value - The raw string to embed in YAML frontmatter.
- * @returns The value, double-quoted and escaped when necessary.
+ * @returns The value as an escaped, double-quoted YAML scalar.
  */
 export function escapeYamlValue(value) {
-    // Check if value needs quoting (contains special YAML characters or starts/ends with whitespace)
-    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
-    if (needsQuoting) {
-        // Use double quotes and escape characters that are not safe to emit
-        // verbatim inside a double-quoted YAML scalar. Carriage returns must be
-        // escaped too: a literal CR inside double quotes is subject to YAML line
-        // folding/normalization and would silently corrupt the round-tripped value.
-        const escaped = value
-            .replace(/\\/g, '\\\\')
-            .replace(/"/g, '\\"')
-            .replace(/\n/g, '\\n')
-            .replace(/\r/g, '\\r');
-        return `"${escaped}"`;
-    }
-    return value;
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        // Remaining non-printables have no dedicated escape; emit them as \xHH.
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`);
+    return `"${escaped}"`;
+}
+/**
+ * Formats a tags array as a YAML array with proper escaping.
+ *
+ * @param tags - Array of tag strings.
+ * @returns Formatted YAML array string, e.g. '[tag1, tag2]'.
+ */
+export function formatTagsArray(tags) {
+    const escapedTags = tags.map((tag) => escapeYamlValue(tag));
+    return `[${escapedTags.join(', ')}]`;
 }
 //# sourceMappingURL=yaml.js.map

package/dist/core/command-surface.d.ts

@@ -0,0 +1,15 @@
+import { type CommandInvocation } from './command-generation/invocation.js';
+import type { Delivery } from './global-config.js';
+export type CommandSurfaceCapability = 'adapter-backed' | 'skills-invocable' | 'none';
+/**
+ * How the tool spells its OpenSpec commands: the name from the command files
+ * its adapter writes, the prefix the adapter declares. Returns undefined for
+ * tools with no command adapter, which have no command names to spell.
+ */
+export declare function resolveCommandInvocation(toolId: string): CommandInvocation | undefined;
+export declare function resolveCommandSurfaceCapability(toolId: string): CommandSurfaceCapability;
+export declare function shouldGenerateSkillsForTool(toolId: string, delivery: Delivery): boolean;
+export declare function shouldRemoveSkillsForTool(toolId: string, delivery: Delivery): boolean;
+export declare function shouldGenerateCommandsForTool(toolId: string, delivery: Delivery): boolean;
+export declare function shouldReconcileCommandFilesForTool(toolId: string, delivery: Delivery): boolean;
+//# sourceMappingURL=command-surface.d.ts.map

package/dist/core/command-surface.js

@@ -0,0 +1,33 @@
+import { CommandAdapterRegistry } from './command-generation/index.js';
+import { getInvocationForAdapter } from './command-generation/invocation.js';
+/**
+ * How the tool spells its OpenSpec commands: the name from the command files
+ * its adapter writes, the prefix the adapter declares. Returns undefined for
+ * tools with no command adapter, which have no command names to spell.
+ */
+export function resolveCommandInvocation(toolId) {
+    const adapter = CommandAdapterRegistry.get(toolId);
+    return adapter ? getInvocationForAdapter(adapter) : undefined;
+}
+export function resolveCommandSurfaceCapability(toolId) {
+    if (CommandAdapterRegistry.has(toolId)) {
+        return 'adapter-backed';
+    }
+    if (toolId === 'codex') {
+        return 'skills-invocable';
+    }
+    return 'none';
+}
+export function shouldGenerateSkillsForTool(toolId, delivery) {
+    return delivery !== 'commands' || resolveCommandSurfaceCapability(toolId) === 'skills-invocable';
+}
+export function shouldRemoveSkillsForTool(toolId, delivery) {
+    return delivery === 'commands' && resolveCommandSurfaceCapability(toolId) !== 'skills-invocable';
+}
+export function shouldGenerateCommandsForTool(toolId, delivery) {
+    return delivery !== 'skills' && resolveCommandSurfaceCapability(toolId) === 'adapter-backed';
+}
+export function shouldReconcileCommandFilesForTool(toolId, delivery) {
+    return delivery === 'skills' && resolveCommandSurfaceCapability(toolId) === 'adapter-backed';
+}
+//# sourceMappingURL=command-surface.js.map