sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/specs/cli-init/spec.md

@@ -1,269 +0,0 @@
-# CLI Init Specification
-
-## Purpose
-
-The `openspec init` command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants.
-## Requirements
-### Requirement: Progress Indicators
-
-The command SHALL display progress indicators during initialization to provide clear feedback about each step.
-
-#### Scenario: Displaying initialization progress
-
-- **WHEN** executing initialization steps
-- **THEN** validate environment silently in background (no output unless error)
-- **AND** display progress with ora spinners:
-  - Show spinner: "⠋ Creating OpenSpec structure..."
-  - Then success: "✔ OpenSpec structure created"
-  - Show spinner: "⠋ Configuring AI tools..."
-  - Then success: "✔ AI tools configured"
-
-### Requirement: Directory Creation
-
-The command SHALL create the OpenSpec directory structure with config file.
-
-#### Scenario: Creating OpenSpec structure
-
-- **WHEN** `openspec init` is executed
-- **THEN** create the following directory structure:
-```
-openspec/
-├── config.yaml
-├── specs/
-└── changes/
-    └── archive/
-```
-
-### Requirement: AI Tool Configuration
-
-The command SHALL configure AI coding assistants with skills and slash commands using a searchable multi-select experience.
-
-#### Scenario: Prompting for AI tool selection
-
-- **WHEN** run interactively
-- **THEN** display animated welcome screen with OpenSpec logo
-- **AND** present a searchable multi-select that shows all available tools
-- **AND** mark already configured tools with "(configured ✓)" indicator
-- **AND** pre-select configured tools for easy refresh
-- **AND** sort configured tools to appear first in the list
-- **AND** allow filtering by typing to search
-
-#### Scenario: Selecting tools to configure
-
-- **WHEN** user selects tools and confirms
-- **THEN** generate skills in `.<tool>/skills/` directory for each selected tool
-- **AND** generate slash commands in `.<tool>/commands/opsx/` directory for each selected tool
-- **AND** create `openspec/config.yaml` with default schema setting
-
-### Requirement: Interactive Mode
-The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions.
-#### Scenario: Displaying interactive menu
-- **WHEN** run in fresh or extend mode
-- **THEN** present a looping select menu that lets users toggle tools with Space and review selections with Enter
-- **AND** when Enter is pressed on a highlighted selectable tool that is not already selected, automatically add it to the selection before moving to review so the highlighted tool is configured
-- **AND** label already configured tools with "(already configured)" while keeping disabled options marked "coming soon"
-- **AND** change the prompt copy in extend mode to "Which AI tools would you like to add or refresh?"
-- **AND** display inline instructions clarifying that Space toggles tools and Enter selects the highlighted tool before reviewing selections
-
-### Requirement: Safety Checks
-The command SHALL perform safety checks to prevent overwriting existing structures and ensure proper permissions.
-
-#### Scenario: Detecting existing initialization
-- **WHEN** the `openspec/` directory already exists
-- **THEN** inform the user that OpenSpec is already initialized, skip recreating the base structure, and enter an extend mode
-- **AND** continue to the AI tool selection step so additional tools can be configured
-- **AND** display the existing-initialization error message only when the user declines to add any AI tools
-
-### Requirement: Success Output
-
-The command SHALL provide clear, actionable next steps upon successful initialization.
-
-#### Scenario: Displaying success message
-
-- **WHEN** initialization completes successfully
-- **THEN** display categorized summary:
-  - "Created: <tools>" for newly configured tools
-  - "Refreshed: <tools>" for already-configured tools that were updated
-  - Count of skills and commands generated
-- **AND** display getting started section with:
-  - `/opsx:new` - Start a new change
-  - `/opsx:continue` - Create the next artifact
-  - `/opsx:apply` - Implement tasks
-- **AND** display links to documentation and feedback
-
-#### Scenario: Displaying restart instruction
-
-- **WHEN** initialization completes successfully and tools were created or refreshed
-- **THEN** display instruction to restart IDE for slash commands to take effect
-
-### Requirement: Exit Codes
-
-The command SHALL use consistent exit codes to indicate different failure modes.
-
-#### Scenario: Returning exit codes
-
-- **WHEN** the command completes
-- **THEN** return appropriate exit code:
-  - 0: Success
-  - 1: General error (including when OpenSpec directory already exists)
-  - 2: Insufficient permissions (reserved for future use)
-  - 3: User cancelled operation (reserved for future use)
-
-### Requirement: Additional AI Tool Initialization
-`openspec init` SHALL allow users to add configuration files for new AI coding assistants after the initial setup.
-
-#### Scenario: Configuring an extra tool after initial setup
-- **GIVEN** an `openspec/` directory already exists and at least one AI tool file is present
-- **WHEN** the user runs `openspec init` and selects a different supported AI tool
-- **THEN** generate that tool's configuration files with OpenSpec markers the same way as during first-time initialization
-- **AND** leave existing tool configuration files unchanged except for managed sections that need refreshing
-- **AND** exit with code 0 and display a success summary highlighting the newly added tool files
-
-### Requirement: Success Output Enhancements
-`openspec init` SHALL summarize tool actions when initialization or extend mode completes.
-
-#### Scenario: Showing tool summary
-- **WHEN** the command completes successfully
-- **THEN** display a categorized summary of tools that were created, refreshed, or skipped (including already-configured skips)
-- **AND** personalize the "Next steps" header using the names of the selected tools, defaulting to a generic label when none remain
-
-### Requirement: Exit Code Adjustments
-`openspec init` SHALL treat extend mode without new native tool selections as a successful refresh.
-
-#### Scenario: Allowing empty extend runs
-- **WHEN** OpenSpec is already initialized and the user selects no additional natively supported tools
-- **THEN** complete successfully without requiring additional tool setup
-- **AND** preserve the existing OpenSpec structure and config files
-- **AND** exit with code 0
-
-### Requirement: Non-Interactive Mode
-
-The command SHALL support non-interactive operation through command-line options.
-
-#### Scenario: Select all tools non-interactively
-
-- **WHEN** run with `--tools all`
-- **THEN** automatically select every available AI tool without prompting
-- **AND** proceed with skill and command generation
-
-#### Scenario: Select specific tools non-interactively
-
-- **WHEN** run with `--tools claude,cursor`
-- **THEN** parse the comma-separated tool IDs
-- **AND** generate skills and commands for specified tools only
-
-#### Scenario: Skip tool configuration non-interactively
-
-- **WHEN** run with `--tools none`
-- **THEN** create only the openspec directory structure
-- **AND** skip skill and command generation
-- **AND** create config only when config creation conditions are met
-
-#### Scenario: Invalid tool specification
-
-- **WHEN** run with `--tools invalid-tool`
-- **THEN** fail with exit code 1
-- **AND** display an error listing available values (`all`, `none`, and supported tool IDs)
-
-#### Scenario: Reserved value combined with tool IDs
-
-- **WHEN** run with `--tools all,claude` or `--tools none,cursor`
-- **THEN** fail with exit code 1
-- **AND** display an error explaining reserved values cannot be combined with specific tool IDs
-
-#### Scenario: Missing --tools in non-interactive mode
-
-- **GIVEN** prompts are unavailable in non-interactive execution
-- **WHEN** user runs `openspec init` without `--tools`
-- **THEN** fail with exit code 1
-- **AND** instruct to use `--tools all`, `--tools none`, or explicit tool IDs
-
-### Requirement: Skill Generation
-
-The command SHALL generate Agent Skills for selected AI tools.
-
-#### Scenario: Generating skills for a tool
-
-- **WHEN** a tool is selected during initialization
-- **THEN** create 9 skill directories under `.<tool>/skills/`:
-  - `openspec-explore/SKILL.md`
-  - `openspec-new-change/SKILL.md`
-  - `openspec-continue-change/SKILL.md`
-  - `openspec-apply-change/SKILL.md`
-  - `openspec-ff-change/SKILL.md`
-  - `openspec-verify-change/SKILL.md`
-  - `openspec-sync-specs/SKILL.md`
-  - `openspec-archive-change/SKILL.md`
-  - `openspec-bulk-archive-change/SKILL.md`
-- **AND** each SKILL.md SHALL contain YAML frontmatter with name and description
-- **AND** each SKILL.md SHALL contain the skill instructions
-
-### Requirement: Slash Command Generation
-
-The command SHALL generate opsx slash commands only for selected tools that have a registered command adapter, while keeping adapterless tools valid for skill generation.
-
-#### Scenario: Generating slash commands for a tool with a registered adapter
-
-- **WHEN** a tool with a registered command adapter is selected during initialization
-- **THEN** create 9 slash command files using the tool's command adapter:
-  - `/opsx:explore`
-  - `/opsx:new`
-  - `/opsx:continue`
-  - `/opsx:apply`
-  - `/opsx:ff`
-  - `/opsx:verify`
-  - `/opsx:sync`
-  - `/opsx:archive`
-  - `/opsx:bulk-archive`
-- **AND** use tool-specific path conventions (e.g., `.claude/commands/opsx/` for Claude)
-- **AND** include tool-specific frontmatter format
-
-#### Scenario: Selected tool has no command adapter
-
-- **GIVEN** a selected tool has `skillsDir` configured but no registered command adapter
-- **WHEN** initialization includes command generation
-- **THEN** skill generation for that tool SHALL still remain valid
-- **AND** command-file generation SHALL be skipped for that tool
-- **AND** the command output SHALL include `Commands skipped for: <tool-id> (no adapter)`
-
-#### Scenario: Kimi CLI skips command-file generation
-
-- **WHEN** the user selects Kimi CLI during initialization
-- **THEN** OpenSpec SHALL treat it as a supported tool with `skillsDir: '.kimi'`
-- **AND** command-file generation SHALL be skipped because no Kimi adapter is registered
-
-### Requirement: Config File Generation
-
-The command SHALL create an OpenSpec config file with schema settings.
-
-#### Scenario: Creating config.yaml
-
-- **WHEN** initialization completes
-- **AND** config.yaml does not exist
-- **THEN** create `openspec/config.yaml` with default schema setting
-- **AND** display config location in output
-
-#### Scenario: Preserving existing config.yaml
-
-- **WHEN** initialization runs in extend mode
-- **AND** `openspec/config.yaml` already exists
-- **THEN** preserve the existing config file
-- **AND** display "(exists)" indicator in output
-
-### Requirement: Experimental Command Alias
-
-The command SHALL maintain backward compatibility with the experimental command.
-
-#### Scenario: Running openspec experimental
-
-- **WHEN** user runs `openspec experimental`
-- **THEN** delegate to `openspec init`
-- **AND** the command SHALL be hidden from help output
-
-## Why
-
-Manual creation of OpenSpec structure is error-prone and creates adoption friction. A standardized init command ensures:
-- Consistent structure across all projects
-- Proper AI instruction files are always included
-- Quick onboarding for new projects
-- Clear conventions from the start

package/OpenSpec-main/openspec/specs/cli-list/spec.md

@@ -1,103 +0,0 @@
-# List Command Specification
-
-## Purpose
-
-The `openspec list` command SHALL provide developers with a quick overview of all active changes in the project, showing their names and task completion status.
-## Requirements
-### Requirement: Command Execution
-The command SHALL scan and analyze either active changes or specs based on the selected mode.
-
-#### Scenario: Scanning for changes (default)
-- **WHEN** `openspec list` is executed without flags
-- **THEN** scan the `openspec/changes/` directory for change directories
-- **AND** exclude the `archive/` subdirectory from results
-- **AND** parse each change's `tasks.md` file to count task completion
-
-#### Scenario: Scanning for specs
-- **WHEN** `openspec list --specs` is executed
-- **THEN** scan the `openspec/specs/` directory for capabilities
-- **AND** read each capability's `spec.md`
-- **AND** parse requirements to compute requirement counts
-
-### Requirement: Task Counting
-
-The command SHALL accurately count task completion status using standard markdown checkbox patterns.
-
-#### Scenario: Counting tasks in tasks.md
-
-- **WHEN** parsing a `tasks.md` file
-- **THEN** count tasks matching these patterns:
-  - Completed: Lines containing `- [x]`
-  - Incomplete: Lines containing `- [ ]`
-- **AND** calculate total tasks as the sum of completed and incomplete
-
-### Requirement: Output Format
-The command SHALL display items in a clear, readable table format with mode-appropriate progress or counts.
-
-#### Scenario: Displaying change list (default)
-- **WHEN** displaying the list of changes
-- **THEN** show a table with columns:
-  - Change name (directory name)
-  - Task progress (e.g., "3/5 tasks" or "✓ Complete")
-
-#### Scenario: Displaying spec list
-- **WHEN** displaying the list of specs
-- **THEN** show a table with columns:
-  - Spec id (directory name)
-  - Requirement count (e.g., "requirements 12")
-
-### Requirement: Flags
-The command SHALL accept flags to select the noun being listed.
-
-#### Scenario: Selecting specs
-- **WHEN** `--specs` is provided
-- **THEN** list specs instead of changes
-
-#### Scenario: Selecting changes
-- **WHEN** `--changes` is provided
-- **THEN** list changes explicitly (same as default behavior)
-
-### Requirement: Empty State
-The command SHALL provide clear feedback when no items are present for the selected mode.
-
-#### Scenario: Handling empty state (changes)
-- **WHEN** no active changes exist (only archive/ or empty changes/)
-- **THEN** display: "No active changes found."
-
-#### Scenario: Handling empty state (specs)
-- **WHEN** no specs directory exists or contains no capabilities
-- **THEN** display: "No specs found."
-
-### Requirement: Error Handling
-
-The command SHALL gracefully handle missing files and directories with appropriate messages.
-
-#### Scenario: Missing tasks.md file
-
-- **WHEN** a change directory has no `tasks.md` file
-- **THEN** display the change with "No tasks" status
-
-#### Scenario: Missing changes directory
-
-- **WHEN** `openspec/changes/` directory doesn't exist
-- **THEN** display error: "No OpenSpec changes directory found. Run 'openspec init' first."
-- **AND** exit with code 1
-
-### Requirement: Sorting
-
-The command SHALL maintain consistent ordering of changes for predictable output.
-
-#### Scenario: Ordering changes
-
-- **WHEN** displaying multiple changes
-- **THEN** sort them in alphabetical order by change name
-
-## Why
-
-Developers need a quick way to:
-- See what changes are in progress
-- Identify which changes are ready to archive
-- Understand the overall project evolution status
-- Get a bird's-eye view without opening multiple files
-
-This command provides that visibility with minimal effort, following OpenSpec's philosophy of simplicity and clarity.

package/OpenSpec-main/openspec/specs/cli-show/spec.md

@@ -1,86 +0,0 @@
-# cli-show Specification
-
-## Purpose
-Define top-level `openspec show` behavior for interactive and direct display of change and spec content.
-
-## Requirements
-### Requirement: Top-level show command
-
-The CLI SHALL provide a top-level `show` command for displaying changes and specs with intelligent selection.
-
-#### Scenario: Interactive show selection
-
-- **WHEN** executing `openspec show` without arguments
-- **THEN** prompt user to select type (change or spec)
-- **AND** display list of available items for selected type
-- **AND** show the selected item's content
-
-#### Scenario: Non-interactive environments do not prompt
-
-- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
-- **WHEN** executing `openspec show` without arguments
-- **THEN** do not prompt
-- **AND** print a helpful hint with examples for `openspec show <item>` or `openspec change/spec show`
-- **AND** exit with code 1
-
-#### Scenario: Direct item display
-
-- **WHEN** executing `openspec show <item-name>`
-- **THEN** automatically detect if item is a change or spec
-- **AND** display the item's content
-- **AND** use appropriate formatting based on item type
-
-#### Scenario: Type detection and ambiguity handling
-
-- **WHEN** executing `openspec show <item-name>`
-- **THEN** if `<item-name>` uniquely matches a change or a spec, show that item
-- **AND** if it matches both, print an ambiguity error and suggest `--type change|spec` or using `openspec change show`/`openspec spec show`
-- **AND** if it matches neither, print not-found with nearest-match suggestions
-
-#### Scenario: Explicit type override
-
-- **WHEN** executing `openspec show --type change <item>`
-- **THEN** treat `<item>` as a change ID and show it (skipping auto-detection)
-
-- **WHEN** executing `openspec show --type spec <item>`
-- **THEN** treat `<item>` as a spec ID and show it (skipping auto-detection)
-
-### Requirement: Output format options
-
-The show command SHALL support various output formats consistent with existing commands.
-
-#### Scenario: JSON output
-
-- **WHEN** executing `openspec show <item> --json`
-- **THEN** output the item in JSON format
-- **AND** include parsed metadata and structure
-- **AND** maintain format consistency with existing change/spec show commands
-
-#### Scenario: Flag scoping and delegation
-
-- **WHEN** showing a change or a spec via the top-level command
-- **THEN** accept common flags such as `--json`
-- **AND** pass through type-specific flags to the corresponding implementation
-  - Change-only flags: `--deltas-only` (alias `--requirements-only` deprecated)
-  - Spec-only flags: `--requirements`, `--no-scenarios`, `-r/--requirement`
-- **AND** ignore irrelevant flags for the detected type with a warning
-
-### Requirement: Interactivity controls
-
-- The CLI SHALL respect `--no-interactive` to disable prompts.
-- The CLI SHALL respect `OPEN_SPEC_INTERACTIVE=0` to disable prompts globally.
-- Interactive prompts SHALL only be shown when stdin is a TTY and interactivity is not disabled.
-
-#### Scenario: Change-specific options
-
-- **WHEN** showing a change with `openspec show <change-name> --deltas-only`
-- **THEN** display only the deltas in JSON format
-- **AND** maintain compatibility with existing change show options
-
-#### Scenario: Spec-specific options  
-
-- **WHEN** showing a spec with `openspec show <spec-id> --requirements`
-- **THEN** display only requirements in JSON format
-- **AND** support other spec options (--no-scenarios, -r)
-- **AND** maintain compatibility with existing spec show options
-

package/OpenSpec-main/openspec/specs/cli-spec/spec.md

@@ -1,88 +0,0 @@
-# cli-spec Specification
-
-## Purpose
-Define `openspec spec` command behavior for listing, showing, and validating source-of-truth specifications.
-
-## Requirements
-### Requirement: Interactive spec show
-
-The spec show command SHALL support interactive selection when no spec-id is provided.
-
-#### Scenario: Interactive spec selection for show
-
-- **WHEN** executing `openspec spec show` without arguments
-- **THEN** display an interactive list of available specs
-- **AND** allow the user to select a spec to show
-- **AND** display the selected spec content
-- **AND** maintain all existing show options (--json, --requirements, --no-scenarios, -r)
-
-#### Scenario: Non-interactive fallback keeps current behavior
-
-- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
-- **WHEN** executing `openspec spec show` without a spec-id
-- **THEN** do not prompt interactively
-- **AND** print the existing error message for missing spec-id
-- **AND** set non-zero exit code
-
-### Requirement: Spec Command
-
-The system SHALL provide a `spec` command with subcommands for displaying, listing, and validating specifications.
-
-#### Scenario: Show spec as JSON
-
-- **WHEN** executing `openspec spec show init --json`
-- **THEN** parse the markdown spec file
-- **AND** extract headings and content hierarchically
-- **AND** output valid JSON to stdout
-
-#### Scenario: List all specs
-
-- **WHEN** executing `openspec spec list`
-- **THEN** scan the openspec/specs directory
-- **AND** return list of all available capabilities
-- **AND** support JSON output with `--json` flag
-
-#### Scenario: Filter spec content
-
-- **WHEN** executing `openspec spec show init --requirements`
-- **THEN** display only requirement names and SHALL statements
-- **AND** exclude scenario content
-
-#### Scenario: Validate spec structure
-
-- **WHEN** executing `openspec spec validate init`
-- **THEN** parse the spec file
-- **AND** validate against Zod schema
-- **AND** report any structural issues
-
-### Requirement: JSON Schema Definition
-
-The system SHALL define Zod schemas that accurately represent the spec structure for runtime validation.
-
-#### Scenario: Schema validation
-
-- **WHEN** parsing a spec into JSON
-- **THEN** validate the structure using Zod schemas
-- **AND** ensure all required fields are present
-- **AND** provide clear error messages for validation failures
-
-### Requirement: Interactive spec validation
-
-The spec validate command SHALL support interactive selection when no spec-id is provided.
-
-#### Scenario: Interactive spec selection for validation
-
-- **WHEN** executing `openspec spec validate` without arguments
-- **THEN** display an interactive list of available specs
-- **AND** allow the user to select a spec to validate
-- **AND** validate the selected spec
-- **AND** maintain all existing validation options (--strict, --json)
-
-#### Scenario: Non-interactive fallback keeps current behavior
-
-- **GIVEN** stdin is not a TTY or `--no-interactive` is provided or environment variable `OPEN_SPEC_INTERACTIVE=0`
-- **WHEN** executing `openspec spec validate` without a spec-id
-- **THEN** do not prompt interactively
-- **AND** print the existing error message for missing spec-id
-- **AND** set non-zero exit code
-