CONTRIBUTING.md

# Contributing to Felix Framework

Welcome to the Felix Framework! We're excited you're interested in contributing to our helix-based multi-agent cognitive architecture research project. 🌪️

## 🎯 Project Philosophy

Felix Framework is **research-grade software** built with scientific rigor. We prioritize:
- **Evidence-based development** with measurable outcomes
- **Test-driven development** (tests before code, always)
- **Hypothesis-driven research** with statistical validation
- **Complete documentation** of decisions and failures
- **Reproducible experiments** with version-controlled data

Before contributing, please read our [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md) for detailed standards.

## 🚀 Quick Start for Contributors

### Prerequisites
- **Python 3.12+** 
- **Git** with basic familiarity
- **Research mindset** - we document everything!

### Setup Development Environment

```bash
# 1. Fork and clone the repository
git clone https://github.com/CalebisGross/thefelix.git
cd thefelix

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Verify setup
python validate_felix_framework.py
python -m pytest tests/unit/ -v

# 5. Run benchmark to ensure everything works
python benchmark_enhanced_systems.py
```

If all tests pass and benchmarks show 100% success rate, you're ready to contribute!

## 🤝 How to Contribute

We welcome several types of contributions:

### 🔬 Research Contributions
- **New hypotheses** for testing helix-based coordination
- **Experimental implementations** of cognitive architectures
- **Performance analysis** and optimization studies
- **Comparative studies** with other multi-agent frameworks

### 💻 Code Contributions
- **Core framework improvements** (helix geometry, agent systems)
- **New agent specializations** (research, analysis, synthesis types)
- **LLM integrations** and multi-model orchestration
- **Performance optimizations** with measurable impact

### 📊 Testing & Validation
- **Test coverage improvements** (we aim for >95%)
- **Integration test scenarios** across system boundaries
- **Performance benchmarks** and regression tests
- **Property-based tests** using hypothesis library

### 📚 Documentation
- **Research documentation** in markdown format
- **Code examples** and usage patterns
- **Architecture Decision Records** (ADRs)
- **Tutorial content** for complex features

## 🔍 Finding Your First Contribution

### Good First Issues
Look for issues labeled with:
- `good-first-issue` - Well-scoped for newcomers
- `research` - Research-oriented contributions
- `testing` - Test improvement opportunities
- `documentation` - Documentation enhancements

### Areas Needing Help
1. **Test Coverage**: Expand test coverage for edge cases
2. **Performance Benchmarks**: Add benchmarks for scalability analysis
3. **Documentation**: Improve code examples and tutorials
4. **Research Experiments**: Implement new hypothesis tests
5. **LLM Integration**: Enhance multi-model orchestration

## 🧪 Development Process

### Our Test-First Approach

**CRITICAL**: All code contributions must follow test-driven development:

```bash
# 1. Write tests FIRST (this is mandatory)
# Create test file: tests/unit/test_your_feature.py

# 2. Run tests to ensure they fail
python -m pytest tests/unit/test_your_feature.py -v

# 3. Implement code to make tests pass
# Create/modify: src/your_module/your_feature.py

# 4. Verify tests pass
python -m pytest tests/unit/test_your_feature.py -v

# 5. Run full test suite
python -m pytest tests/unit/ -v
```

### Hypothesis-Driven Development

Every significant change should:
1. **State a clear hypothesis** in your PR description
2. **Predict expected outcomes** with measurable criteria
3. **Document alternatives considered** and why rejected
4. **Provide validation evidence** through tests/benchmarks

### Documentation Requirements

Before submitting any PR:
- [ ] Update relevant documentation
- [ ] Add docstrings to new functions/classes
- [ ] Create/update tests with good coverage
- [ ] Update RESEARCH_LOG.md if research-related
- [ ] Add ADR if architectural decision made

## 📝 Pull Request Guidelines

### Branch Naming
- `feature/description` - New functionality
- `experiment/hypothesis-name` - Research experiments
- `fix/issue-description` - Bug fixes
- `docs/section-name` - Documentation updates

### PR Checklist

Before submitting your pull request:

#### Code Quality
- [ ] All new code has corresponding tests
- [ ] Tests pass locally: `python -m pytest tests/unit/ -v`
- [ ] Code follows project style guidelines
- [ ] No unused imports or dead code
- [ ] Docstrings added for public functions/classes

#### Research Standards
- [ ] Hypothesis clearly stated in PR description
- [ ] Expected outcomes documented
- [ ] Validation methodology described
- [ ] Performance impact measured (if applicable)

#### Documentation
- [ ] README.md updated if user-facing changes
- [ ] RESEARCH_LOG.md updated if research contribution
- [ ] ADR created if architectural decision
- [ ] Code comments explain "why", not "what"

#### Testing
- [ ] Unit tests cover new functionality
- [ ] Integration tests updated if cross-system changes
- [ ] Performance benchmarks run: `python benchmark_enhanced_systems.py`
- [ ] No regression in existing test coverage

### Commit Message Format

Use our structured commit format from DEVELOPMENT_RULES.md:

```
[TYPE]: Brief description (max 50 chars)

WHY: Detailed explanation of the problem/need
WHAT: Specific changes made
EXPECTED: Predicted outcome/behavior
ALTERNATIVES: Other approaches considered and why rejected
TESTS: How this change will be validated

[Optional: BREAKING CHANGES, NOTES, etc.]
```

**Types**: `feat`, `fix`, `test`, `docs`, `refactor`, `experiment`, `perf`

### PR Template

When you create a PR, please include:

```markdown
## Hypothesis
[State your hypothesis clearly]

## Changes Made
- [List specific changes]
- [Include rationale for each]

## Expected Outcomes
- [Measurable predictions]
- [Performance expectations]

## Validation
- [ ] Tests added/updated
- [ ] Benchmarks run
- [ ] Documentation updated

## Alternatives Considered
[Other approaches and why rejected]

## Breaking Changes
[If any, describe impact]
```

## 🧪 Testing Requirements

### Test Organization
```
tests/
├── unit/           # Individual component tests
├── integration/    # Cross-component tests
└── performance/    # Benchmark and performance tests
```

### Coverage Standards
- **Unit tests**: >95% line coverage for new code
- **Integration tests**: All public APIs tested
- **Performance tests**: Benchmarks for performance-critical code

### Running Tests

```bash
# All unit tests with coverage
python -m pytest tests/unit/ -v --cov=src --cov-report=html

# Specific test module
python -m pytest tests/unit/test_helix_geometry.py -v

# Integration tests
python -m pytest tests/integration/ -v

# Performance tests (marked as slow)
python -m pytest tests/performance/ -m slow -v

# Run with specific markers
python -m pytest -m "unit and not slow" -v
```

### Test Markers
Use pytest markers to categorize tests:
- `@pytest.mark.unit` - Unit tests for individual components
- `@pytest.mark.integration` - Integration tests
- `@pytest.mark.performance` - Performance and benchmark tests
- `@pytest.mark.slow` - Tests taking >1 second
- `@pytest.mark.hypothesis` - Property-based tests

## 📊 Code Style & Standards

### Python Style
- **PEP 8** compliance with 88-character line limit
- **Type hints** for all public functions
- **Docstrings** in Google format for all public APIs
- **Descriptive variable names** (no abbreviations)

### Example Code Style
```python
from typing import List, Optional
import numpy as np

def generate_helix_points(
    num_turns: int = 33,
    nodes: int = 133,
    top_radius: float = 33.0,
    bottom_radius: float = 0.001
) -> List[HelixPoint]:
    """Generate helix points with mathematical precision.
    
    Args:
        num_turns: Number of complete helix rotations
        nodes: Total number of agent positions
        top_radius: Starting radius at helix top
        bottom_radius: Ending radius at helix bottom
        
    Returns:
        List of HelixPoint objects with x, y, z coordinates
        
    Raises:
        ValueError: If parameters result in invalid geometry
    """
    # Implementation with clear variable names
    angle_increment = 2 * np.pi / (nodes / num_turns)
    # ... rest of implementation
```

### Architecture Decisions
Document significant decisions in `decisions/ADR-XXX-title.md`:

```markdown
# ADR-XXX: Title of Decision

## Status
Accepted | Superseded | Deprecated

## Context
[Situation and problem]

## Decision
[What we decided]

## Consequences
[Positive and negative impacts]

## Alternatives Considered
[Other options and why rejected]
```

## 🔬 Research Contributions

### Proposing New Hypotheses
1. **Research existing literature** and document findings
2. **State hypothesis clearly** with measurable predictions
3. **Design validation methodology** before implementation
4. **Consider statistical power** and sample sizes needed

### Experimental Process
1. **Document hypothesis** in `research/hypothesis-name.md`
2. **Implement tests first** to validate hypothesis
3. **Build minimal implementation** to test hypothesis
4. **Collect and analyze data** with statistical rigor
5. **Document results** regardless of success/failure

### Failed Experiments
We preserve ALL experiments, including failures:
- Code preserved in `experiments/failed/`
- Documentation of why it failed
- Lessons learned and insights gained
- Analysis prevents repeating mistakes

### Research Log Entries
Update `RESEARCH_LOG.md` for research contributions:

```markdown
## 2025-XX-XX: [Your Contribution]
**Hypothesis**: [What you're testing]
**Progress**: [What was accomplished]
**Obstacles**: [What challenges encountered]
**Insights**: [What was learned]
**Next Steps**: [What comes next]
```

## 🐛 Bug Reports

### Before Reporting a Bug
1. **Search existing issues** for duplicates
2. **Test on latest main branch** to confirm bug exists
3. **Gather reproduction steps** with minimal example
4. **Check if it's a configuration issue** vs actual bug

### Bug Report Template
```markdown
**Bug Description**
Clear description of the issue

**Reproduction Steps**
1. Step one
2. Step two
3. Step three

**Expected Behavior**
What should happen

**Actual Behavior**
What actually happens

**Environment**
- OS: [e.g., Ubuntu 22.04]
- Python: [e.g., 3.12.0]
- Felix Version: [e.g., commit hash]
- Dependencies: [relevant package versions]

**Additional Context**
- Log outputs
- Screenshots if relevant
- Related issues
```

## 💡 Feature Requests

### Before Requesting Features
1. **Check if it aligns** with core research objectives
2. **Search existing issues** for similar requests
3. **Consider the complexity** and maintenance burden
4. **Think about testing strategy** for the feature

### Feature Request Template
```markdown
**Problem Statement**
What problem does this solve?

**Proposed Solution**
Detailed description of proposed feature

**Research Justification**
How does this advance our research goals?

**Validation Methodology**
How would we test/validate this feature?

**Alternatives Considered**
Other ways to solve this problem

**Implementation Notes**
Technical considerations or challenges
```

## 🌟 Recognition

We value all contributions! Contributors are recognized in:
- **README.md** contributors section
- **Release notes** for significant contributions
- **Research papers** when contributions advance research
- **Project documentation** for major improvements

## 📞 Getting Help

### Communication Channels
- **GitHub Issues**: Technical questions and bug reports
- **GitHub Discussions**: Research discussions and brainstorming
- **Pull Request Comments**: Code review discussions

### Documentation Resources
- **[README.md](./README.md)**: Project overview and quick start
- **[DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md)**: Detailed development standards
- **[PROJECT_INDEX.md](./PROJECT_INDEX.md)**: Complete project structure
- **[RESEARCH_LOG.md](./RESEARCH_LOG.md)**: Research progress and findings

### Research Resources
- **[research/](./research/)**: Research hypotheses and methodologies
- **[docs/](./docs/)**: Technical documentation and specifications
- **[decisions/](./decisions/)**: Architecture decision records

## 📋 Code of Conduct

### Our Standards
- **Research integrity** above all else
- **Respectful communication** in all interactions
- **Constructive feedback** focused on improving the work
- **Collaborative problem-solving** approach
- **Evidence-based discussions** rather than opinions

### Unacceptable Behavior
- Making claims without evidence
- Ignoring test-first development requirements
- Submitting code without documentation
- Personal attacks or unprofessional conduct
- Plagiarism or research misconduct

### Enforcement
Issues will be addressed through:
1. **Direct communication** for minor issues
2. **Documented warnings** for repeated violations
3. **Temporary restrictions** for serious violations
4. **Permanent exclusion** for research misconduct

## 🏁 Getting Started Checklist

Ready to contribute? Here's your checklist:

- [ ] Read [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md) thoroughly
- [ ] Set up development environment successfully
- [ ] Run tests and benchmarks to verify setup
- [ ] Choose a contribution area that interests you
- [ ] Look for good first issues or create a proposal
- [ ] Fork the repository and create a feature branch
- [ ] Write tests first, then implement your contribution
- [ ] Document your changes thoroughly
- [ ] Submit a pull request following our guidelines

## 🎉 Thank You!

Your contributions help advance multi-agent cognitive architecture research. Every test, every line of code, every documentation improvement, and every research insight makes Felix Framework better.

**Welcome to the helix revolution!** 🌪️

---

*For detailed development standards and research methodology, see [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md)*

*For project structure and component details, see [PROJECT_INDEX.md](./PROJECT_INDEX.md)*