mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00

Files

T

Tabish Bidiwale fa5df9a329 feat: apply structured spec format to all specifications

- Add Specification Format section to openspec-conventions with:
  - Requirement headers for consistent structure
  - Scenario headers with bold WHEN/THEN/AND keywords
  - Format flexibility for different content types

- Update all CLI command specs to use structured format:
  - cli-init: Convert all behavioral sections
  - cli-list: Apply structured format throughout
  - cli-update: Restructure requirements and edge cases
  - cli-diff: Update all behavior sections
  - cli-archive: Convert complex behaviors to scenarios

- Update openspec-conventions spec itself to follow its own format
- Mark all tasks as completed

2025-08-13 22:26:03 +10:00

3.0 KiB

Raw Permalink Blame History

CLI Diff Command Specification

Purpose

The openspec diff command provides developers with a visual comparison between proposed spec changes and the current deployed specs.

Command Syntax

openspec diff [change-name]

Behavior

Requirement: Without Arguments

The command SHALL provide an interactive selection when no change is specified.

Scenario: Running without arguments

WHEN running openspec diff without arguments
THEN list all available changes in the changes/ directory (excluding archive)
AND prompt user to select a change

Requirement: With Change Name

The command SHALL compare specs when a specific change is provided.

Scenario: Running with change name

WHEN running openspec diff <change-name>
THEN compare all spec files in changes/<change-name>/specs/ with corresponding files in specs/

Requirement: Diff Output

The command SHALL generate appropriate diff output for all spec changes.

Scenario: Comparing existing files

WHEN file exists in both locations
THEN show unified diff

Scenario: New files

WHEN file only exists in change
THEN show as new file (all lines with +)

Scenario: Deleted files

WHEN file only exists in current specs
THEN show as deleted (all lines with -)

Requirement: Display Format

The command SHALL use standard unified diff format for consistency with existing tools.

Scenario: Formatting diff output

WHEN displaying diff output
THEN use standard unified diff format:
- Lines prefixed with - for removed content
- Lines prefixed with + for added content
- Lines without prefix for unchanged context
- File headers showing the paths being compared

Requirement: Color Support

The command SHALL enhance readability with colors when supported.

Scenario: Terminal with color support

WHEN terminal supports colors
THEN display:
- Removed lines in red
- Added lines in green
- File headers in bold
- Context lines in default color

Requirement: Error Handling

The command SHALL provide clear error messages for various failure conditions.

Scenario: Change not found

WHEN specified change doesn't exist
THEN display error "Change '' not found"

Scenario: No specs in change

WHEN no specs directory in change
THEN display "No spec changes found for ''"

Scenario: Missing changes directory

WHEN changes directory doesn't exist
THEN display "No OpenSpec changes directory found"

Examples

# View diff for specific change
$ openspec diff add-auth-feature

--- specs/user-auth/spec.md
+++ changes/add-auth-feature/specs/user-auth/spec.md
@@ -10,6 +10,8 @@
 Users SHALL authenticate with email and password.
 
+Users MAY authenticate with OAuth providers.
+
 WHEN credentials are valid THEN issue JWT token.

# List all changes and select
$ openspec diff
Available changes:
  1. add-auth-feature
  2. update-payment-flow
  3. add-status-command
Select a change (1-3):

3.0 KiB Raw Permalink Blame History