man pages for posix systems #491
Description
OpenSpec should provide man pages for POSIX systems to improve discoverability and usability of the CLI.
Motivation
Having man pages would enhance the maturity status of the openspec program. As a bonus: man pages would enable automatic completion of options and arguments in the fish shell, which uses man page parsing to generate completions. This would significantly improve the developer experience for fish users without requiring manual completion scripts.
Proposed Implementation
Add man pages for:
- openspec - Main command overview
- openspec-list - List active changes and specs
- openspec-show - Display change or spec details
- openspec-validate - Validate changes or specs
- openspec-archive - Archive completed changes
- openspec-init - Initialize OpenSpec
- openspec-update - Update instruction files
Additional Benefits
- Standard documentation format for UNIX/Linux users
- Offline documentation access via man openspec
- Integration with system help systems (apropos, whatis)
- Professional tool appearance and discoverability
Acceptance Criteria
- Man pages generated for all commands and subcommands
- Man pages installed to appropriate location (e.g., /usr/local/share/man/man1/)
- Fish shell can auto-complete OpenSpec commands, options, and flags
- Man pages include examples and all documented flags