The diff command added unnecessary complexity and duplicated functionality
already available through the show command. Users can now use:
- `openspec show <change>` for structured change viewing
- `openspec show <change> --json --deltas-only` for delta-only views
- Standard git diff or other tools for file comparisons
This change:
- Removes ~227 lines of code and the jest-diff dependency
- Simplifies the CLI interface
- Reduces maintenance burden
- Aligns with verb-first command structure
- Restructured README.md with three-stage workflow front-loaded
- Reduced from 575 to 298 lines while adding comprehensive content
- Added clear decision trees and removed ambiguous conditions
- Documented all CLI commands with examples and debugging tips
- Added critical scenario formatting guidance (most common error)
- Created troubleshooting section with error solutions
- Updated CLAUDE.md template with streamlined, focused content
- Added "Before Any Task" checklist for context gathering
- Added spec discovery workflow to prevent duplicates
- Included tool selection matrix and best practices
- Document all 9 primary OpenSpec commands with examples
- Add openspec list and list --specs prominently
- Add "Before Creating Specs" rule to check existing specs first
- Document all CLI flags (--json, --type, --skip-specs, etc.)
- Update tasks to include 9 CLI documentation items
- Add spec discovery workflow to prevent duplicate capabilities
This ensures AI agents have complete CLI knowledge and avoid spec fragmentation
- Add decision clarity improvements (decision trees, remove ambiguity)
- Include agent-specific sections (tool selection, error recovery, context management)
- Restructure with clear information hierarchy
- Add comprehensive implementation tasks (6 sections, 26 tasks)
- Update design with industry best practices rationale
Based on analysis of Claude Code, Cursor, and other coding agent patterns
- Documentation updates are tooling/infrastructure changes
- No specs needed for OpenSpec's own instructions
- Will use --skip-specs flag when archiving
- Replace any types with proper Change and Delta types from schemas
- Add error logging in catch blocks when DEBUG env var is set
- Include file paths in error messages for better debugging
- Extract regex patterns and magic strings as constants
- Improve code maintainability and type safety
- Add new `openspec change` command with three subcommands
- Implement JSON output capability for change proposals
- Add deprecation warning to legacy `openspec list` command
- Enable --requirements-only filtering for change show
- Support --strict mode and --json flags for validation
This provides programmatic access to change proposals through JSON output
and establishes a consistent resource-based command structure.
Tabish Bidiwale