sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/archive/2026-02-17-multi-provider-skill-generation/design.md

@@ -0,0 +1,144 @@
+## Context
+
+The `artifact-experimental-setup` command generates skill files and opsx slash commands for AI coding assistants. Currently it hardcodes paths to `.claude/skills` and `.claude/commands/opsx`.
+
+The existing `AI_TOOLS` array in `config.ts` lists 22 AI tools but lacks path information. There's also an existing `SlashCommandConfigurator` system for the old workflow commands, but it's tightly coupled to the old 3 commands (proposal, apply, archive) and can't be easily extended for the 9 opsx commands.
+
+Each AI tool has:
+- Different skill directory conventions (`.claude/skills/`, `.cursor/skills/`, etc.)
+- Different command file paths (`.claude/commands/opsx/`, `.cursor/commands/`, etc.)
+- Different frontmatter formats (YAML keys, structure varies by tool)
+
+## Goals / Non-Goals
+
+**Goals:**
+- Support skill generation for any AI tool following the Agent Skills spec
+- Support command generation with tool-specific formatting via adapters
+- Require explicit tool selection (no defaults)
+- Create a generic, extensible command generation system
+
+**Non-Goals:**
+- Global path installation for tools other than Codex (Codex uses absolute adapter paths today)
+- Multi-tool generation in single command (future enhancement)
+- Unifying with existing SlashCommandConfigurator (separate systems for now)
+
+## Decisions
+
+### 1. Add `skillsDir` to `AIToolOption` interface
+
+**Decision**: Add single `skillsDir` field to existing interface. No `commandsDir` or `globalSkillsDir`.
+
+```typescript
+interface AIToolOption {
+  name: string;
+  value: string;
+  available: boolean;
+  successLabel?: string;
+  skillsDir?: string;  // e.g., '.claude' - /skills suffix per Agent Skills spec
+}
+```
+
+**Rationale**:
+- Skills follow Agent Skills spec: `<toolDir>/skills/` - suffix is standard
+- Commands need per-tool formatting, handled by adapters (not a simple path)
+- Global paths supported — Codex adapter returns absolute paths via os.homedir()
+
+### 2. Strategy/Adapter pattern for command generation
+
+**Decision**: Create generic command generation with tool-specific adapters.
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│                      CommandContent                              │
+│  (tool-agnostic: id, name, description, category, tags, body)   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   generateCommand(content, adapter)              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+        ┌──────────┐   ┌──────────┐   ┌──────────┐
+        │  Claude  │   │  Cursor  │   │ Windsurf │
+        │ Adapter  │   │ Adapter  │   │ Adapter  │
+        └──────────┘   └──────────┘   └──────────┘
+```
+
+**Interfaces:**
+
+```typescript
+// Tool-agnostic command data
+interface CommandContent {
+  id: string;           // e.g., 'explore', 'new', 'apply'
+  name: string;         // e.g., 'OpenSpec Explore'
+  description: string;  // e.g., 'Enter explore mode...'
+  category: string;     // e.g., 'OpenSpec'
+  tags: string[];       // e.g., ['openspec', 'explore']
+  body: string;         // The command instructions
+}
+
+// Per-tool formatting strategy
+interface ToolCommandAdapter {
+  toolId: string;
+  getFilePath(commandId: string): string;
+  formatFile(content: CommandContent): string;
+}
+```
+
+**Rationale**:
+- Separates "what to generate" from "how to format it"
+- Each tool's frontmatter quirks encapsulated in its adapter
+- Easy to add new tools by implementing adapter interface
+- Body content shared across all tools
+
+**Alternative considered**: Extend existing SlashCommandConfigurator
+- Rejected: Tightly coupled to old 3 commands, significant refactor needed
+
+### 3. Adapter registry pattern
+
+**Decision**: Create `CommandAdapterRegistry` similar to existing `SlashCommandRegistry`.
+
+```typescript
+class CommandAdapterRegistry {
+  private static adapters: Map<string, ToolCommandAdapter> = new Map();
+
+  static get(toolId: string): ToolCommandAdapter | undefined;
+  static getAll(): ToolCommandAdapter[];
+}
+```
+
+**Rationale**:
+- Consistent with existing codebase patterns
+- Easy lookup by tool ID
+- Centralized registration
+
+### 4. Required tool flag
+
+**Decision**: Require `--tool` flag - error if omitted.
+
+**Rationale**:
+- Explicit tool selection avoids assumptions
+- Consistent with project convention of not providing defaults
+- Users must consciously choose their target tool
+
+## Risks / Trade-offs
+
+**[Risk] Adapter maintenance burden** → Each new tool needs an adapter. Mitigated by simple interface - most adapters are ~20 lines.
+
+**[Risk] Frontmatter format drift** → Tools may change their formats. Mitigated by encapsulating format in adapter - single place to update.
+
+**[Trade-off] Two command systems** → Old SlashCommandConfigurator and new CommandAdapterRegistry coexist. Acceptable for now - can unify later if needed.
+
+**[Trade-off] skillsDir optional** → Tools without skillsDir configured will error. Acceptable - we add paths as tools are tested.
+
+## Implementation Approach
+
+1. Add `skillsDir` to `AIToolOption` and populate for known tools
+2. Create `CommandContent` and `ToolCommandAdapter` interfaces
+3. Implement adapters for Claude, Cursor, Windsurf (start with 3)
+4. Create `CommandAdapterRegistry`
+5. Create `generateCommand()` function
+6. Update `artifact-experimental-setup` to use new system
+7. Add `--tool` flag with validation

package/OpenSpec-main/openspec/changes/archive/2026-02-17-multi-provider-skill-generation/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+The `artifact-experimental-setup` command currently hardcodes skill output paths to `.claude/skills` and `.claude/commands/opsx`. This prevents users of other AI coding tools (Cursor, Windsurf, Codex, etc.) from using OpenSpec's skill generation. We need to support the diverse ecosystem of AI coding assistants, each with their own conventions for skill/instruction file locations and command frontmatter formats.
+
+## What Changes
+
+- Add `skillsDir` path configuration to the existing `AIToolOption` interface in `config.ts`
+- Add required `--tool <tool-id>` flag to the `artifact-experimental-setup` command
+- Create a generic command generation system using Strategy/Adapter pattern:
+  - `CommandContent`: tool-agnostic command data (id, name, description, body)
+  - `ToolCommandAdapter`: per-tool formatting (file paths, frontmatter format)
+  - `CommandGenerator`: orchestrates generation using content + adapter
+- Require explicit tool selection (no default) for clarity
+
+## Capabilities
+
+### New Capabilities
+
+- `ai-tool-paths`: Configuration mapping AI tool IDs to their project-local skill directory paths
+- `command-generation`: Generic command generation system with tool adapters for formatting differences
+
+### Modified Capabilities
+
+- `cli-artifact-workflow`: Adding `--tool` flag to setup command for provider selection
+
+## Impact
+
+- **Files Modified**:
+  - `src/core/config.ts` - Extend `AIToolOption` interface with `skillsDir` field
+  - `src/commands/artifact-workflow.ts` - Add `--tool` flag, use provider paths and adapters
+- **New Files**:
+  - `src/core/command-generation/types.ts` - CommandContent, ToolCommandAdapter interfaces
+  - `src/core/command-generation/generator.ts` - Generic command generator
+  - `src/core/command-generation/adapters/*.ts` - Per-tool adapters
+- **Backward Compatibility**: Existing workflows unaffected - this is a new command setup feature
+- **User-Facing**: Required `--tool` flag on `artifact-experimental-setup` command for explicit tool selection

package/OpenSpec-main/openspec/changes/archive/2026-02-17-multi-provider-skill-generation/specs/ai-tool-paths/spec.md

@@ -0,0 +1,63 @@
+# ai-tool-paths Specification
+
+## Purpose
+
+Define the path configuration for AI coding tool skill directories, enabling skill generation to target different tools following the Agent Skills spec.
+
+## Requirements
+
+## ADDED Requirements
+
+### Requirement: AIToolOption skillsDir field
+
+The `AIToolOption` interface SHALL include an optional `skillsDir` field for skill generation path configuration.
+
+#### Scenario: Interface includes skillsDir field
+
+- **WHEN** a tool entry is defined in `AI_TOOLS` that supports skill generation
+- **THEN** it SHALL include a `skillsDir` field specifying the project-local base directory (e.g., `.claude`)
+
+#### Scenario: Skills path follows Agent Skills spec
+
+- **WHEN** generating skills for a tool with `skillsDir: '.claude'`
+- **THEN** skills SHALL be written to `<projectRoot>/<skillsDir>/skills/`
+- **AND** the `/skills` suffix is appended per Agent Skills specification
+
+### Requirement: Path configuration for supported tools
+
+The `AI_TOOLS` array SHALL include `skillsDir` for tools that support the Agent Skills specification.
+
+#### Scenario: Claude Code paths defined
+
+- **WHEN** looking up the `claude` tool
+- **THEN** `skillsDir` SHALL be `.claude`
+
+#### Scenario: Cursor paths defined
+
+- **WHEN** looking up the `cursor` tool
+- **THEN** `skillsDir` SHALL be `.cursor`
+
+#### Scenario: Windsurf paths defined
+
+- **WHEN** looking up the `windsurf` tool
+- **THEN** `skillsDir` SHALL be `.windsurf`
+
+#### Scenario: Tools without skillsDir
+
+- **WHEN** a tool has no `skillsDir` defined
+- **THEN** skill generation SHALL error with message indicating the tool is not supported
+
+### Requirement: Cross-platform path handling
+
+The system SHALL handle paths correctly across operating systems.
+
+#### Scenario: Path construction on Windows
+
+- **WHEN** constructing skill paths on Windows
+- **THEN** the system SHALL use `path.join()` for all path construction
+- **AND** SHALL NOT hardcode forward slashes
+
+#### Scenario: Path construction on Unix
+
+- **WHEN** constructing skill paths on macOS or Linux
+- **THEN** the system SHALL use `path.join()` for consistency

package/OpenSpec-main/openspec/changes/archive/2026-02-17-multi-provider-skill-generation/specs/cli-artifact-workflow/spec.md

@@ -0,0 +1,60 @@
+# cli-artifact-workflow Delta Specification
+
+## Purpose
+
+Add `--tool` flag to the `artifact-experimental-setup` command for multi-provider support.
+
+## ADDED Requirements
+
+### Requirement: Tool selection flag
+
+The `artifact-experimental-setup` command SHALL accept a `--tool <tool-id>` flag to specify the target AI tool.
+
+#### Scenario: Specify tool via flag
+
+- **WHEN** user runs `openspec artifact-experimental-setup --tool cursor`
+- **THEN** skill files are generated in `.cursor/skills/`
+- **AND** command files are generated using Cursor's frontmatter format
+
+#### Scenario: Missing tool flag
+
+- **WHEN** user runs `openspec artifact-experimental-setup` without `--tool`
+- **THEN** the system displays an error requiring the `--tool` flag
+- **AND** lists valid tool IDs in the error message
+
+#### Scenario: Unknown tool ID
+
+- **WHEN** user runs `openspec artifact-experimental-setup --tool unknown-tool`
+- **AND** the tool ID is not in `AI_TOOLS`
+- **THEN** the system displays an error listing valid tool IDs
+
+#### Scenario: Tool without skillsDir
+
+- **WHEN** user specifies a tool that has no `skillsDir` configured
+- **THEN** the system displays an error indicating skill generation is not supported for that tool
+
+#### Scenario: Tool without command adapter
+
+- **WHEN** user specifies a tool that has `skillsDir` but no command adapter registered
+- **THEN** skill files are generated successfully
+- **AND** command generation is skipped with informational message
+
+### Requirement: Output messaging
+
+The setup command SHALL display clear output about what was generated.
+
+#### Scenario: Show target tool in output
+
+- **WHEN** setup command runs successfully
+- **THEN** output includes the target tool name (e.g., "Setting up for Cursor...")
+
+#### Scenario: Show generated paths
+
+- **WHEN** setup command completes
+- **THEN** output lists all generated skill file paths
+- **AND** lists all generated command file paths (if applicable)
+
+#### Scenario: Show skipped commands message
+
+- **WHEN** command generation is skipped due to missing adapter
+- **THEN** output includes message: "Command generation skipped - no adapter for <tool>"

package/OpenSpec-main/openspec/changes/archive/2026-02-17-multi-provider-skill-generation/specs/command-generation/spec.md

@@ -0,0 +1,98 @@
+# command-generation Specification
+
+## Purpose
+
+Define a generic command generation system that supports multiple AI tools through a Strategy/Adapter pattern, separating command content from tool-specific formatting.
+
+## ADDED 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

package/OpenSpec-main/openspec/changes/archive/2026-02-17-multi-provider-skill-generation/tasks.md

@@ -0,0 +1,55 @@
+## 1. Extend AIToolOption Interface
+
+- [x] 1.1 Add `skillsDir?: string` field to `AIToolOption` interface in `src/core/config.ts`
+
+## 2. Add skillsDir to AI_TOOLS
+
+- [x] 2.1 Add `skillsDir: '.claude'` to Claude Code tool entry
+- [x] 2.2 Add `skillsDir: '.cursor'` to Cursor tool entry
+- [x] 2.3 Add `skillsDir: '.windsurf'` to Windsurf tool entry
+- [x] 2.4 Add skillsDir for other tools with known Agent Skills spec support (codex, opencode, roocode, kilocode, gemini, factory, github-copilot)
+
+## 3. Create Command Generation Types
+
+- [x] 3.1 Create `src/core/command-generation/types.ts` with `CommandContent` interface
+- [x] 3.2 Add `ToolCommandAdapter` interface to types.ts
+- [x] 3.3 Export types from module index
+
+## 4. Implement Tool Command Adapters
+
+- [x] 4.1 Create `src/core/command-generation/adapters/claude.ts` with Claude frontmatter format
+- [x] 4.2 Create `src/core/command-generation/adapters/cursor.ts` with Cursor frontmatter format
+- [x] 4.3 Create `src/core/command-generation/adapters/windsurf.ts` with Windsurf frontmatter format
+- [x] 4.4 Create base adapter or utility for shared YAML formatting logic (if applicable)
+
+## 5. Create Command Adapter Registry
+
+- [x] 5.1 Create `src/core/command-generation/registry.ts` with `CommandAdapterRegistry` class
+- [x] 5.2 Register Claude, Cursor, Windsurf adapters in static initializer
+- [x] 5.3 Add `get(toolId)` and `getAll()` methods
+
+## 6. Create Command Generator
+
+- [x] 6.1 Create `src/core/command-generation/generator.ts` with `generateCommand()` function
+- [x] 6.2 Add `generateCommands()` function for batch generation
+- [x] 6.3 Create module index `src/core/command-generation/index.ts` exporting public API
+
+## 7. Update artifact-experimental-setup Command
+
+- [x] 7.1 Add `--tool <tool-id>` option (required) to command in `src/commands/artifact-workflow.ts`
+- [x] 7.2 Add validation: `--tool` flag is required (error if missing with list of valid tools)
+- [x] 7.3 Add validation: tool exists in AI_TOOLS
+- [x] 7.4 Add validation: tool has skillsDir configured
+- [x] 7.5 Replace hardcoded `.claude` skill paths with `tool.skillsDir`
+- [x] 7.6 Replace hardcoded command generation with `CommandAdapterRegistry.get()` + `generateCommands()`
+- [x] 7.7 Handle missing adapter gracefully (skip commands with message)
+- [x] 7.8 Update output messages to show target tool name and paths
+
+## 8. Testing
+
+- [x] 8.1 Add unit tests for `CommandContent` and `ToolCommandAdapter` contracts
+- [x] 8.2 Add unit tests for Claude adapter (path + frontmatter format)
+- [x] 8.3 Add unit tests for Cursor adapter (path + frontmatter format)
+- [x] 8.4 Add unit tests for `CommandAdapterRegistry.get()` and missing adapter case
+- [x] 8.5 Add integration test for `--tool` flag validation
+- [x] 8.6 Verify cross-platform path handling uses `path.join()` throughout

package/OpenSpec-main/openspec/changes/archive/2026-02-17-project-config/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: "2025-01-13"