# Project Constitution: Rust CLI Development with Claude Code
## Project Overview
We are building a command-line interface (CLI) tool in Rust. This constitution defines our development practices, code quality standards, and deployment procedures to ensure a robust, secure, and maintainable codebase.
## Branching Strategy
- **Main Branch**: Production-ready code only. Never commit directly to `main`.
- **Feature Branches**: All development work happens in feature branches named `feature/descriptive-name`.
- **Hotfix Branches**: Critical production fixes use `hotfix/descriptive-name` branches.
- **Branch Protection**: The `main` branch is protected and requires pull request reviews before merging.
## Security & Code Quality
- **Automatic Security Scanning**: All pushes to feature branches trigger automated security scanning using `cargo audit` and SAST tools.
- **PR Security Checks**: Security scanning runs automatically when opening pull requests to `main`.
- **Dependency Audits**: We audit all dependencies for known vulnerabilities before every merge to `main`.
- **Code Review Required**: At least two approvals required before merging to `main`.
## Development Workflow
1. Create a feature branch from `main`: `git checkout -b feature/your-feature`
2. Implement changes following Rust best practices and idioms
3. Run local tests: `cargo test`
4. Push to feature branch (triggers automatic security scanning)
5. Open a pull request to `main`
6. Address any security or code review comments
7. Merge after approval and all checks pass
## Code Standards
- **Formatting**: All code must pass `cargo fmt` without modifications
- **Linting**: All code must pass `cargo clippy` with no warnings
- **Testing**: Minimum 70% code coverage required; all public APIs must have tests
- **Documentation**: All public items must have rustdoc comments with examples
- **Error Handling**: Use `Result` types; prefer `anyhow` or `thiserror` for error handling
- **Performance**: Benchmark critical paths; avoid unnecessary allocations
## Build & Test Requirements
- All tests must pass: `cargo test --all`
- All documentation must build: `cargo doc --no-deps`
- Benchmarks must complete without regression (if applicable)
- Cross-platform compatibility tested before merge to `main`
## Commit Guidelines
- Use descriptive commit messages with the format: `type(scope): description`
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
- Example: `feat(parser): add support for config file loading`
- Keep commits atomic and focused on a single logical change
- Use conventional commits to enable automated changelog generation
## Release & Deployment
- Releases are tagged from `main` using semantic versioning: `v1.0.0`
- `CHANGELOG.md` is updated with each release
- Published to crates.io after tag creation
- All releases must pass final security audit
## Tools & Dependencies
- **Package Manager**: Cargo
- **Build System**: Cargo workspaces for mono-repo structure
- **Testing Framework**: Built-in `cargo test`
- **Security**: `cargo audit`, `cargo-deny`
- **Formatting**: `cargo fmt`
- **Linting**: `cargo clippy`
- **Documentation**: Rustdoc
## Roles & Responsibilities
- **All Developers**: Follow branching strategy, write tests, ensure code quality
- **Code Reviewers**: Verify security, code quality, and test coverage
- **Maintainers**: Merge PRs, manage releases, handle CI/CD