OpenSpec/openspec/specs/command-generation/spec.md

command-generation Specification

Purpose

Define tool-agnostic command content and adapter contracts for generating tool-specific OpenSpec command files.

Requirements

Requirement: CommandContent interface

The system SHALL define a tool-agnostic CommandContent interface for command data.

Scenario: CommandContent structure

• WHEN defining a command to generate
• THEN CommandContent SHALL include:
  • id: string identifier (e.g., 'explore', 'apply')
  • name: human-readable name (e.g., 'OpenSpec Explore')
  • description: brief description of command purpose
  • category: grouping category (e.g., 'OpenSpec')
  • tags: array of tag strings
  • body: the command instruction content

Requirement: ToolCommandAdapter interface

The system SHALL define a ToolCommandAdapter interface for per-tool formatting.

Scenario: Adapter interface structure

• WHEN implementing a tool adapter
• THEN ToolCommandAdapter SHALL require:
  • toolId: string identifier matching AIToolOption.value
  • getFilePath(commandId: string): returns file path for command (relative from project root, or absolute for global-scoped tools like Codex)
  • formatFile(content: CommandContent): returns complete file content with frontmatter

Scenario: Claude adapter formatting

• WHEN formatting a command for Claude Code
• THEN the adapter SHALL output YAML frontmatter with name, description, category, tags fields
• AND file path SHALL follow pattern .claude/commands/opsx/<id>.md

Scenario: Cursor adapter formatting

• WHEN formatting a command for Cursor
• THEN the adapter SHALL output YAML frontmatter with name as /opsx-<id>, id, category, description fields
• AND file path SHALL follow pattern .cursor/commands/opsx-<id>.md

Scenario: Windsurf adapter formatting

• WHEN formatting a command for Windsurf
• THEN the adapter SHALL output YAML frontmatter with name, description, category, tags fields
• AND file path SHALL follow pattern .windsurf/workflows/opsx-<id>.md

Requirement: Command generator function

The system SHALL provide a generateCommand function that combines content with adapter.

Scenario: Generate command file

• WHEN calling generateCommand(content, adapter)
• THEN it SHALL return an object with:
  • path: the file path from adapter.getFilePath(content.id)
  • fileContent: the formatted content from adapter.formatFile(content)

Scenario: Generate multiple commands

• WHEN generating all opsx commands for a tool
• THEN the system SHALL iterate over command contents and generate each using the tool's adapter

Requirement: CommandAdapterRegistry

The system SHALL provide a registry for looking up tool adapters.

Scenario: Get adapter by tool ID

• WHEN calling CommandAdapterRegistry.get('cursor')
• THEN it SHALL return the Cursor adapter or undefined if not registered

Scenario: Get all adapters

• WHEN calling CommandAdapterRegistry.getAll()
• THEN it SHALL return array of all registered adapters

Scenario: Adapter not found

• WHEN looking up an adapter for unregistered tool
• THEN CommandAdapterRegistry.get() SHALL return undefined
• AND caller SHALL handle missing adapter appropriately

Requirement: Shared command body content

The body content of commands SHALL be shared across all tools.

Scenario: Same instructions across tools

• WHEN generating the 'explore' command for Claude and Cursor
• THEN both SHALL use the same body content
• AND only the frontmatter and file path SHALL differ