Rust CLI Application Architecture Template

## ROLE
You are a Rust developer who has built and maintained popular CLI tools used by thousands of developers. You understand the ergonomics of command-line interfaces, the importance of helpful error messages, and how to structure Rust projects for maintainability. Your tools are known for being fast, reliable, and pleasant to use.

## OBJECTIVE
Design the architecture for a CLI application called [APP NAME] that [CORE FUNCTIONALITY]. The tool targets [USERS: developers / sysadmins / data engineers / general users] and needs to run on [PLATFORMS: Linux / macOS / Windows / all].

## TASK

### Project Structure
- Cargo workspace layout: binary crate + library crate separation
- Module organization: commands, config, output, errors, utils
- Feature flags for optional functionality
- Build configuration: release profile optimization, LTO, strip
- Dependencies selection: clap, serde, tokio (if async), indicatif, colored

### Argument Parsing with Clap
- Top-level command structure using clap derive macros
- Subcommand design: verb-noun or noun-verb patterns
- Required vs. optional arguments with sensible defaults
- Global flags: --verbose, --quiet, --color, --output-format
- Environment variable fallback for all configuration options
- Argument validation: custom validators for paths, URLs, patterns
- Shell completion generation: bash, zsh, fish, PowerShell
- Man page generation from clap definitions

### Configuration System
- Configuration hierarchy: CLI args > env vars > config file > defaults
- Config file format: TOML (Rust ecosystem standard)
- Config file locations: XDG dirs on Linux, standard paths on macOS/Windows
- Config file discovery: current directory, user home, system-wide
- Configuration validation and error reporting on startup
- First-run setup: interactive configuration wizard
- Config subcommand: view, edit, reset configuration

### Output & Formatting
- Output modes: human-readable (default), JSON, plain text, table
- Color support: detect terminal capability, respect NO_COLOR env var
- Progress indicators: progress bars for long operations, spinners for indeterminate
- Table output: aligned columns, header formatting, truncation
- Logging levels: trace, debug, info, warn, error with --verbose/-v control
- Structured logging: optional JSON log output for machine consumption
- Quiet mode: suppress all output except errors and requested data

### Error Handling Strategy
- User-facing errors: clear message, suggested fix, error code
- Exit codes: define meaningful exit codes (0 success, 1 general error, 2 usage error, etc.)
- Error context: include file paths, line numbers, input values
- Recoverable vs. fatal errors: retry prompts for recoverable failures
- Panic handling: catch and convert to friendly error messages
- Debug mode: show full error chain and backtrace with --debug flag

### Cross-Platform Support
- Path handling: use std::path, avoid hardcoded separators
- Line endings: handle CRLF/LF appropriately
- Terminal detection: isatty for interactive vs. piped behavior
- Platform-specific features behind cfg attributes
- CI/CD matrix: build and test on Linux, macOS, Windows

### Testing Strategy
- Unit tests for core logic (library crate)
- Integration tests: run binary with assert_cmd and predicates
- Snapshot testing for output format verification (insta crate)
- Property testing for input parsing and validation
- Fixture files for complex test scenarios

### Distribution
- GitHub Releases with pre-built binaries (cross-compilation with cross)
- Homebrew formula for macOS
- Cargo install support
- AUR package for Arch Linux
- Docker image for containerized usage
- GitHub Actions CI/CD pipeline: test, build, release automation
- Version management and changelog generation