.clinerules

# Cline Rules for Goose Load Testing Framework

## Project Context
Goose is a powerful, fast, and scalable load testing framework built with Rust. This document provides guidelines for AI-assisted development and maintenance of the Goose project, including patterns for code implementation, documentation, and project management.

## Critical Implementation Notes

### Code Modification Guidelines
**Focus on requested changes only**:
- Only modify what was explicitly requested
- Do not rename variables for "consistency" unless asked
- Do not add error handling where it wasn't requested
- Do not refactor unrelated code during feature implementation
- Maintain existing code style and patterns

### Implementation Workflow
**Follow incremental development**:
1. Implement one feature or fix at a time
2. Test each change before moving to the next
3. Update relevant documentation with each change
4. Ensure backward compatibility unless breaking changes are explicitly approved

## Documentation Standards

### Comprehensive Documentation Locations
**Documentation exists in multiple places - ALL must be kept current**:
- **Primary docs**: `./src/docs/goose-book/src/` (mdBook documentation)
- **Project overview**: `README.md` (project introduction and quick start)
- **Change tracking**: `CHANGELOG.md` (user-facing changes and releases)
- **Development context**: `/memory-bank/` (AI development context and decisions)
- **Inline documentation**: All `*.rs` files (function docs, module docs, examples)
- **Code examples**: `/examples/` directory (working code samples)
- **Test documentation**: `tests/*.rs` (test descriptions and patterns)
- **Configuration help**: Built-in help text and error messages

### Automatic Documentation Updates
**Update documentation with code changes**:
- Search ALL documentation locations for references to changed functionality
- Verify accuracy by testing documented examples and configuration options
- Update inline documentation for any modified public APIs
- Ensure consistency across all documentation sources

### Memory Bank Maintenance
**Keep memory bank current**:
- Update `memory-bank/progress.md` when features are completed
- Refine `memory-bank/systemPatterns.md` with architectural changes
- Update `memory-bank/activeContext.md` with current development focus
- Document technical decisions in appropriate memory bank files

## Feature Development Guidelines

### New Feature Checklist
When implementing new features:
1. [ ] Create or reference GitHub issue
2. [ ] Document implementation plan
3. [ ] Follow existing code patterns
4. [ ] Add appropriate tests
5. [ ] Update documentation
6. [ ] Update CHANGELOG.md
7. [ ] Consider backward compatibility

### Testing Requirements
**Comprehensive test coverage**:
- Unit tests for new functionality
- Integration tests for feature interactions
- Document test patterns for complex features
- Ensure tests work with all feature flag combinations

## Project-Specific Patterns

### Report Generation
**Current reporting capabilities**:
- HTML reports with JavaScript charts (primary format)
- Markdown reports for text-based summaries
- JSON reports for programmatic processing
- PDF reports in development (Issue #628, using HTML-to-PDF via headless Chrome)

### Metrics Architecture
**Coordinated Omission Mitigation**:
- Recently implemented to correct for measurement artifacts
- Provides more accurate latency metrics
- Uses statistical corrections for dropped measurements
- Integration with all report formats

### Controller System
**Runtime control interfaces**:
- WebSocket controller for real-time control
- Telnet controller for command-line interaction
- Supports dynamic test adjustment
- Thread-safe communication patterns

### Gaggle (Distributed Testing)
**Currently being reimplemented**:
- Previous implementation disabled in v0.17.0
- Considering multiple approaches (Hydro, Zenoh, gRPC/Tonic)
- Will support distributed load generation
- Architecture decisions tracked in memory bank

## Configuration Management

### GooseConfiguration Pattern
**CLI and configuration file support**:
- Use `gumdrop` for CLI parsing
- Support both command-line and file-based configuration
- Validate options early with clear error messages
- Document all configuration options

### Default Values
**Use GooseDefault enum**:
- Centralized default value management
- Type-safe configuration defaults
- Easy to extend for new options

## Dependency Management

### Version Requirements
**Maintain compatibility**:
- Rust edition 2021
- Optional dependencies via feature flags
- Document minimum supported Rust version (MSRV)

### External Dependencies
**Be conservative with dependencies**:
- Prefer well-maintained crates with active communities
- Use feature flags for optional dependencies
- Document why each dependency is needed
- Consider security implications

## Context7 Configuration Maintenance

### Overview
The `context7.json` file provides configuration for the Context7 documentation service. This file must be kept up-to-date as features are added or changed in the Goose project.

### When to Update context7.json

Update the `context7.json` file when:
1. **New Features Are Merged**: Add to the `rules` array
2. **Report Formats Change**: Update the reporting formats rule
3. **Major Architecture Changes**: Reflect in the description or rules
4. **Build/Test Structure Changes**: Update `excludeFolders` or `excludeFiles`

### Pending Updates

Track these features and update `context7.json` when they're merged:

- [ ] **PDF Report Generation** (Issue #628)
  - When merged, update rule: "Integrates with various reporting formats: HTML, Markdown, JSON, PDF"
  - Remove the "coming soon" note about PDF support

- [ ] **Gaggle Reimplementation**
  - When complete, update rule about distributed testing
  - Remove "(currently being reimplemented)" note

### How to Update

1. **Rules Array**: Keep concise, one feature per rule
2. **Description**: Should remain high-level overview
3. **Exclusions**: Only exclude build artifacts and temporary files
4. **Version History**: Add tags when major versions are released

## Anti-Patterns to Avoid

### Over-Engineering
**Keep solutions simple and direct**:
- Do not add unnecessary abstraction layers
- Avoid premature optimization
- Prefer clarity over cleverness
- Follow YAGNI (You Aren't Gonna Need It) principle

### Breaking Changes
**Maintain backward compatibility**:
- Deprecate before removing
- Provide migration paths
- Document breaking changes clearly
- Consider impact on existing users

### Inconsistent Patterns
**Follow established conventions**:
- Use existing error handling patterns
- Follow project naming conventions
- Maintain consistent code structure
- Respect existing architectural decisions

## Debugging and Troubleshooting

### Leverage Goose's Built-in Logging
**Use appropriate log levels**:
- Debug logs for detailed troubleshooting
- Info logs for important events
- Warn logs for recoverable issues
- Error logs for failures requiring attention

### Performance Considerations
**Monitor impact of changes**:
- Consider memory usage for high-scale tests
- Optimize hot paths in metrics collection
- Use async patterns appropriately
- Profile before optimizing

## Pull Request Guidelines

### PR Description Template
**Include in every PR**:
- What the PR does
- Why the change is needed
- How to test the changes
- Related issues or context
- Breaking changes (if any)

### Review Readiness Checklist
Before marking PR ready for review:
- [ ] Tests pass locally
- [ ] Documentation is updated
- [ ] CHANGELOG.md entry added
- [ ] No unrelated changes included
- [ ] Follows project coding standards

## Success Criteria

### Code Quality
- Follows Rust idioms and best practices
- Maintains existing patterns
- Includes appropriate error handling
- Has comprehensive test coverage

### Documentation Quality
- API documentation is complete
- Examples work with current code
- Configuration options are documented
- Migration guides for breaking changes

### Maintainability
- Code is clear and self-documenting
- Complex logic includes comments
- Patterns are consistent throughout
- Future changes are considered

Remember: The goal is to maintain Goose as a reliable, performant, and user-friendly load testing framework. Focus on stability, clarity, and backward compatibility while continuously improving the codebase.