sauron-cli 1.3.0 → 1.4.1

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

@@ -1,398 +0,0 @@
-# cli-artifact-workflow Specification
-
-## Purpose
-Define artifact workflow CLI behavior (`status`, `instructions`, `templates`, and setup flows) for scaffolded and active changes.
-## Requirements
-### Requirement: Status Command
-
-The system SHALL display artifact completion status for a change, including scaffolded (empty) changes.
-
-> **Fixes bug**: Previously required `proposal.md` to exist via `getActiveChangeIds()`.
-
-#### Scenario: Show status with all states
-
-- **WHEN** user runs `openspec status --change <id>`
-- **THEN** the system displays each artifact with status indicator:
-  - `[x]` for completed artifacts
-  - `[ ]` for ready artifacts
-  - `[-]` for blocked artifacts (with missing dependencies listed)
-
-#### Scenario: Status shows completion summary
-
-- **WHEN** user runs `openspec status --change <id>`
-- **THEN** output includes completion percentage and count (e.g., "2/4 artifacts complete")
-
-#### Scenario: Status JSON output
-
-- **WHEN** user runs `openspec status --change <id> --json`
-- **THEN** the system outputs JSON with changeName, schemaName, isComplete, and artifacts array
-
-#### Scenario: Status JSON includes apply requirements
-
-- **WHEN** user runs `openspec status --change <id> --json`
-- **THEN** the system outputs JSON with:
-  - `changeName`, `schemaName`, `isComplete`, `artifacts` array
-  - `applyRequires`: array of artifact IDs needed for apply phase
-
-#### Scenario: Status on scaffolded change
-
-- **WHEN** user runs `openspec status --change <id>` on a change with no artifacts
-- **THEN** system displays all artifacts with their status
-- **AND** root artifacts (no dependencies) show as ready `[ ]`
-- **AND** dependent artifacts show as blocked `[-]`
-
-#### Scenario: Missing change parameter
-
-- **WHEN** user runs `openspec status` without `--change`
-- **THEN** the system displays an error with list of available changes
-- **AND** includes scaffolded changes (directories without proposal.md)
-
-#### Scenario: Unknown change
-
-- **WHEN** user runs `openspec status --change unknown-id`
-- **AND** directory `openspec/changes/unknown-id/` does not exist
-- **THEN** the system displays an error listing all available change directories
-
-### Requirement: Next Artifact Discovery
-
-The workflow SHALL use `openspec status` output to determine what can be created next, rather than a separate next-command surface.
-
-#### Scenario: Discover next artifacts from status output
-
-- **WHEN** a user needs to know which artifact to create next
-- **THEN** `openspec status --change <id>` identifies ready artifacts with `[ ]`
-- **AND** no dedicated "next command" is required to continue the workflow
-
-### Requirement: Instructions Command
-
-The system SHALL output enriched instructions for creating an artifact, including for scaffolded changes.
-
-#### Scenario: Show enriched instructions
-
-- **WHEN** user runs `openspec instructions <artifact> --change <id>`
-- **THEN** the system outputs:
-  - Artifact metadata (ID, output path, description)
-  - Template content
-  - Dependency status (done/missing)
-  - Unlocked artifacts (what becomes available after completion)
-
-#### Scenario: Instructions JSON output
-
-- **WHEN** user runs `openspec instructions <artifact> --change <id> --json`
-- **THEN** the system outputs JSON matching ArtifactInstructions interface
-
-#### Scenario: Unknown artifact
-
-- **WHEN** user runs `openspec instructions unknown-artifact --change <id>`
-- **THEN** the system displays an error listing valid artifact IDs for the schema
-
-#### Scenario: Artifact with unmet dependencies
-
-- **WHEN** user requests instructions for a blocked artifact
-- **THEN** the system displays instructions with a warning about missing dependencies
-
-#### Scenario: Instructions on scaffolded change
-
-- **WHEN** user runs `openspec instructions proposal --change <id>` on a scaffolded change
-- **THEN** system outputs template and metadata for creating the proposal
-- **AND** does not require any artifacts to already exist
-
-### Requirement: Templates Command
-The system SHALL show resolved template paths for all artifacts in a schema.
-
-#### Scenario: List template paths with default schema
-- **WHEN** user runs `openspec templates`
-- **THEN** the system displays each artifact with its resolved template path using the default schema
-
-#### Scenario: List template paths with custom schema
-- **WHEN** user runs `openspec templates --schema tdd`
-- **THEN** the system displays template paths for the specified schema
-
-#### Scenario: Templates JSON output
-- **WHEN** user runs `openspec templates --json`
-- **THEN** the system outputs JSON mapping artifact IDs to template paths
-
-#### Scenario: Template resolution source
-- **WHEN** displaying template paths
-- **THEN** the system indicates whether each template is from user override or package built-in
-
-### Requirement: New Change Command
-The system SHALL create new change directories with validation.
-
-#### Scenario: Create valid change
-- **WHEN** user runs `openspec new change add-feature`
-- **THEN** the system creates `openspec/changes/add-feature/` directory
-
-#### Scenario: Invalid change name
-- **WHEN** user runs `openspec new change "Add Feature"` with invalid name
-- **THEN** the system displays validation error with guidance
-
-#### Scenario: Duplicate change name
-- **WHEN** user runs `openspec new change existing-change` for an existing change
-- **THEN** the system displays an error indicating the change already exists
-
-#### Scenario: Create with description
-- **WHEN** user runs `openspec new change add-feature --description "Add new feature"`
-- **THEN** the system creates the change directory with description in README.md
-
-### Requirement: Workspace Setup Commands
-The CLI artifact workflow SHALL expose workspace setup commands before change creation.
-
-#### Scenario: Preparing workspace planning before a change
-- **WHEN** a user needs to prepare workspace planning across repos or folders
-- **THEN** the CLI SHALL provide commands to set up, list, link, relink, and doctor workspaces
-- **AND** those commands SHALL not require an active workspace change
-
-#### Scenario: Listing workspaces with a short command
-- **WHEN** a user wants a concise workspace list command
-- **THEN** the CLI SHALL support `openspec workspace ls`
-- **AND** it SHALL behave the same as `openspec workspace list`
-
-#### Scenario: Keeping setup separate from agent launch
-- **WHEN** a user completes workspace setup
-- **THEN** the setup workflow SHALL leave agent launch and workspace open behavior to a later workflow
-- **AND** setup SHALL not require a preferred agent choice
-
-#### Scenario: Avoiding public direct creation
-- **WHEN** users create a workspace in the first workspace setup flow
-- **THEN** the CLI SHALL use `openspec workspace setup`
-- **AND** it SHALL not expose `openspec workspace create` as the public creation path
-
-### Requirement: Schema Selection
-The system SHALL support custom schema selection for workflow commands.
-
-#### Scenario: Default schema
-- **WHEN** user runs workflow commands without `--schema`
-- **THEN** the system uses the "spec-driven" schema
-
-#### Scenario: Custom schema
-- **WHEN** user runs `openspec status --change <id> --schema tdd`
-- **THEN** the system uses the specified schema for artifact graph
-
-#### Scenario: Unknown schema
-- **WHEN** user specifies an unknown schema
-- **THEN** the system displays an error listing available schemas
-
-### Requirement: Output Formatting
-The system SHALL provide consistent output formatting.
-
-#### Scenario: Color output
-- **WHEN** terminal supports colors
-- **THEN** status indicators use colors: green (done), yellow (ready), red (blocked)
-
-#### Scenario: No color output
-- **WHEN** `--no-color` flag is used or NO_COLOR environment variable is set
-- **THEN** output uses text-only indicators without ANSI colors
-
-#### Scenario: Progress indication
-- **WHEN** loading change state takes time
-- **THEN** the system displays a spinner during loading
-
-### Requirement: Experimental Isolation
-The system SHALL implement artifact workflow commands in isolation for easy removal.
-
-#### Scenario: Single file implementation
-- **WHEN** artifact workflow feature is implemented
-- **THEN** all commands are in `src/commands/artifact-workflow.ts`
-
-#### Scenario: Help text marking
-- **WHEN** user runs `--help` on any artifact workflow command
-- **THEN** help text indicates the command is experimental
-
-### Requirement: Schema Apply Block
-
-The system SHALL support an `apply` block in schema definitions that controls when and how implementation begins.
-
-#### Scenario: Schema with apply block
-
-- **WHEN** a schema defines an `apply` block
-- **THEN** the system uses `apply.requires` to determine which artifacts must exist before apply
-- **AND** uses `apply.tracks` to identify the file for progress tracking (or null if none)
-- **AND** uses `apply.instruction` for guidance shown to the agent
-
-#### Scenario: Schema without apply block
-
-- **WHEN** a schema has no `apply` block
-- **THEN** the system requires all artifacts to exist before apply is available
-- **AND** uses default instruction: "All artifacts complete. Proceed with implementation."
-
-### Requirement: Apply Instructions Command
-
-The system SHALL generate schema-aware apply instructions via `openspec instructions apply`.
-
-#### Scenario: Generate apply instructions
-
-- **WHEN** user runs `openspec instructions apply --change <id>`
-- **AND** all required artifacts (per schema's `apply.requires`) exist
-- **THEN** the system outputs:
-  - `contextFiles` mapping artifact IDs to arrays of concrete paths for all existing artifacts
-  - Schema-specific instruction text
-  - Progress tracking file path (if `apply.tracks` is set)
-
-#### Scenario: Apply blocked by missing artifacts
-
-- **WHEN** user runs `openspec instructions apply --change <id>`
-- **AND** required artifacts are missing
-- **THEN** the system indicates apply is blocked
-- **AND** lists which artifacts must be created first
-
-#### Scenario: Apply instructions JSON output
-
-- **WHEN** user runs `openspec instructions apply --change <id> --json`
-- **THEN** the system outputs JSON with:
-  - `contextFiles`: object mapping artifact IDs to arrays of concrete paths for existing artifacts
-  - `instruction`: the apply instruction text
-  - `tracks`: path to progress file or null
-  - `applyRequires`: list of required artifact IDs
-
-### 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>"
-
-### Requirement: Status JSON provides planning context
-The status command SHALL provide machine-readable planning context for repo-local and workspace changes.
-
-#### Scenario: Reporting planning home
-- **WHEN** a user runs `openspec status --change <id> --json`
-- **THEN** the output SHALL identify whether the change is repo-local or workspace-scoped
-- **AND** it SHALL include the planning home root and change root
-
-#### Scenario: Reporting concrete artifact paths
-- **WHEN** a user runs `openspec status --change <id> --json`
-- **THEN** the output SHALL include concrete paths for existing artifacts
-- **AND** agents SHALL be able to read those paths without assuming `openspec/changes/<id>/`
-- **AND** workspace-scoped nested spec paths SHALL be reported without flattening the area or capability path
-
-#### Scenario: Reporting workspace affected areas
-- **GIVEN** the change is workspace-scoped
-- **WHEN** a user runs `openspec status --change <id> --json`
-- **THEN** the output SHALL include known affected areas
-- **AND** it SHALL indicate when affected areas remain unresolved without requiring an additional area manifest artifact
-
-#### Scenario: Reporting next steps
-- **WHEN** a user runs `openspec status --change <id> --json`
-- **THEN** the output SHALL include next step guidance for agents
-- **AND** the guidance SHALL use plain action language
-
-### Requirement: Status JSON action context
-The status command SHALL expose action context that lets agents act without hardcoded filesystem assumptions.
-
-#### Scenario: Planning action context
-- **WHEN** a workspace change is still in planning
-- **THEN** status JSON SHALL identify the planning artifacts agents may read or update
-- **AND** it SHALL indicate that linked repos and folders are context for exploration
-
-#### Scenario: Implementation action context
-- **WHEN** a workspace change has a selected affected area for implementation
-- **THEN** status JSON SHALL include the allowed edit root for that area
-- **AND** it SHALL avoid authorizing edits outside that selected area
-
-#### Scenario: Repo-local action context
-- **GIVEN** the change is repo-local
-- **WHEN** a user runs `openspec status --change <id> --json`
-- **THEN** status JSON SHALL preserve existing artifact status behavior
-- **AND** it SHALL report a repo-local planning home for agents that use action context
-
-### Requirement: Instructions use resolved planning paths
-Artifact and apply instructions SHALL use resolved planning paths rather than hardcoded repo-local change paths.
-
-#### Scenario: Workspace artifact instructions
-- **GIVEN** the change is workspace-scoped
-- **WHEN** a user runs `openspec instructions <artifact> --change <id> --json`
-- **THEN** instruction output SHALL point to the artifact path under the workspace change root
-- **AND** it SHALL not instruct the agent to write under a linked repo unless an explicit implementation context allows it
-
-#### Scenario: Repo-local artifact instructions
-- **GIVEN** the change is repo-local
-- **WHEN** a user runs `openspec instructions <artifact> --change <id> --json`
-- **THEN** instruction output SHALL preserve existing repo-local paths
-
-### Requirement: Workflow skills use CLI artifact context
-Generated workflow skills SHALL use OpenSpec CLI output as the source of truth for artifact locations.
-
-#### Scenario: Skills inspect status before artifact work
-- **WHEN** a generated workflow skill needs to inspect or create artifacts for a change
-- **THEN** it SHALL instruct the agent to run `openspec status --change <id> --json`
-- **AND** it SHALL use returned planning context and artifact paths rather than assuming a repo-local change path
-
-#### Scenario: Skills use instructions before writing artifacts
-- **WHEN** a generated workflow skill is about to create or update an artifact
-- **THEN** it SHALL instruct the agent to run `openspec instructions <artifact> --change <id> --json`
-- **AND** it SHALL write to the resolved artifact path returned by the command
-
-#### Scenario: Skills avoid hardcoded repo-local paths
-- **WHEN** generated workflow skills describe artifact locations
-- **THEN** they SHALL avoid hardcoded examples that require changes to live under `openspec/changes/<id>/`
-- **AND** any examples SHALL defer to CLI-reported paths for repo-local and workspace-scoped changes
-
-#### Scenario: Skills guard unsupported workspace workflows
-- **GIVEN** a generated workflow skill is selected by the global profile
-- **AND** the workflow does not yet have full workspace-scoped behavior in this slice
-- **WHEN** the skill is used for a workspace-scoped change
-- **THEN** it SHALL tell the agent that the workspace action is not supported yet
-- **AND** it SHALL not instruct the agent to fall back to repo-local paths or edit linked repos without an explicit allowed edit root
-
-### Requirement: Workspace schema instructions
-Workflow commands SHALL use the workspace planning schema instructions for workspace-scoped changes that use that schema.
-
-#### Scenario: Workspace planning artifact order
-- **GIVEN** a workspace-scoped change uses schema `workspace-planning`
-- **WHEN** a user runs `openspec status --change <id> --json`
-- **THEN** the artifact list SHALL reflect the workspace planning schema
-- **AND** it SHALL include the normal proposal, specs, design, and tasks artifacts
-
-#### Scenario: Workspace specs instructions
-- **GIVEN** a workspace-scoped change uses schema `workspace-planning`
-- **WHEN** a user requests instructions for the specs artifact
-- **THEN** instruction output SHALL guide the agent to organize area-specific requirements under workspace-scoped `specs/` paths
-- **AND** it SHALL not require all affected areas to be finalized before planning can continue
-- **AND** it SHALL not instruct the agent to create repo-local spec files while the change is still in workspace planning

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

@@ -1,92 +0,0 @@
-# cli-change Specification
-
-## Purpose
-Define `openspec change` command behavior for showing, listing, and validating change proposals and deltas.
-
-## Requirements
-### Requirement: Change Command
-
-The system SHALL provide a `change` command with subcommands for displaying, listing, and validating change proposals.
-
-#### Scenario: Show change as JSON
-
-- **WHEN** executing `openspec change show update-error --json`
-- **THEN** parse the markdown change file
-- **AND** extract change structure and deltas
-- **AND** output valid JSON to stdout
-
-#### Scenario: List all changes
-
-- **WHEN** executing `openspec change list`
-- **THEN** scan the openspec/changes directory
-- **AND** return list of all pending changes
-- **AND** support JSON output with `--json` flag
-
-#### Scenario: Show only requirement changes
-
-- **WHEN** executing `openspec change show update-error --requirements-only`
-- **THEN** display only the requirement changes (ADDED/MODIFIED/REMOVED/RENAMED)
-- **AND** exclude why and what changes sections
-
-#### Scenario: Validate change structure
-
-- **WHEN** executing `openspec change validate update-error`
-- **THEN** parse the change file
-- **AND** validate against Zod schema
-- **AND** ensure deltas are well-formed
-
-### Requirement: Legacy Compatibility
-
-The system SHALL maintain backward compatibility with the existing `list` command while showing deprecation notices.
-
-#### Scenario: Legacy list command
-
-- **WHEN** executing `openspec list`
-- **THEN** display current list of changes (existing behavior)
-- **AND** show deprecation notice: "Note: 'openspec list' is deprecated. Use 'openspec change list' instead."
-
-#### Scenario: Legacy list with --all flag
-
-- **WHEN** executing `openspec list --all`
-- **THEN** display all changes (existing behavior)
-- **AND** show same deprecation notice
-
-### Requirement: Interactive show selection
-
-The change show command SHALL support interactive selection when no change name is provided.
-
-#### Scenario: Interactive change selection for show
-
-- **WHEN** executing `openspec change show` without arguments
-- **THEN** display an interactive list of available changes
-- **AND** allow the user to select a change to show
-- **AND** display the selected change content
-- **AND** maintain all existing show options (--json, --deltas-only)
-
-#### 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 change show` without a change name
-- **THEN** do not prompt interactively
-- **AND** print the existing hint including available change IDs
-- **AND** set `process.exitCode = 1`
-
-### Requirement: Interactive validation selection
-
-The change validate command SHALL support interactive selection when no change name is provided.
-
-#### Scenario: Interactive change selection for validation
-
-- **WHEN** executing `openspec change validate` without arguments
-- **THEN** display an interactive list of available changes
-- **AND** allow the user to select a change to validate
-- **AND** validate the selected change
-
-#### 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 change validate` without a change name
-- **THEN** do not prompt interactively
-- **AND** print the existing hint including available change IDs
-- **AND** set `process.exitCode = 1`
-