Contributing

Thank you for your interest in contributing to Compounding Engineering! This project thrives on community contributions.

Ways to Contribute

• 🐛 Report bugs - Help us identify issues
• 💡 Suggest features - Share ideas for improvements
• 📝 Improve documentation - Help others understand the project
• 🔧 Submit code - Fix bugs or add features
• ⭐ Share knowledge - Contribute review agents or workflow improvements

Looking for something to do? Check out our Issues page for open tasks!

Getting Started

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/dspy-compounding-engineering.git
cd dspy-compounding-engineering

2. Set Up Development Environment

# Install dependencies including dev tools
uv sync --group dev

# Install pre-commit hooks
uv run pre-commit install

3. Create a Branch

All pull requests must come from branches using one of the following prefixes:

• feature/: New functionality
• fix/: Bug fixes
• testing/: Test expansion or verification
• chore/: Maintenance and infrastructure

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Development Workflow

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=agents --cov=workflows --cov=utils

# Run specific tests
uv run pytest tests/test_knowledge_base.py -v

Linting and Formatting

# Check code style
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

# Format code
uv run ruff format .

Running the CLI Locally

# Use uv run for development
uv run python cli.py review --help

# Or activate the venv
source .venv/bin/activate
python cli.py review

Project Structure

dspy-compounding-engineering/
├── agents/              # DSPy agent signatures and modules
│   ├── review/          # Code review agents
│   ├── workflow/        # Work execution agents
│   └── research/        # Repository research agents
├── workflows/           # High-level workflow orchestration
│   ├── review.py
│   ├── triage.py
│   ├── work_unified.py
│   └── plan.py
├── utils/               # Shared utilities
│   ├── knowledge_base.py
│   ├── git_service.py
│   └── todo_service.py
├── docs/                # MkDocs documentation
├── tests/               # Test suite
└── cli.py               # CLI entry point

Adding a New Review Agent

Review agents are specialized code reviewers. Here's how to add one:

1. Create the Agent File

Create agents/review/your_agent_name.py:

import dspy

class YourAgentReviewer(dspy.Signature):
    \"\"\"Specialized review agent for [specific concern]\"\"\"
    
    file_path: str = dspy.InputField(desc="Path to the file being reviewed")
    file_content: str = dspy.InputField(desc="Content of the file")
    context: str = dspy.InputField(desc="Additional context from knowledge base")
    
    finding: str = dspy.OutputField(
        desc="Detailed finding with severity, issue, and recommendation"
    )

2. Register in agents/review/__init__.py

from .your_agent_name import YourAgentReviewer

REVIEW_AGENTS = [
    # ... existing agents ...
    ("Your Agent Name", YourAgentReviewer),
]

3. Add Tests

Create tests/test_your_agent.py:

import dspy
from agents.review.your_agent_name import YourAgentReviewer

def test_your_agent_reviewer():
    # Test your agent logic
    pass

4. Update Documentation

Add your agent to docs/usage/review.md.

Pull Request Process

1. Write Good Commit Messages

We strictly follow the Conventional Commits standard. Every commit must be prefixed with a type:

• feat: A new feature
• fix: A bug fix
• docs: Documentation changes
• style: Formatting/Linting (no logic change)
• refactor: Code reorganization
• test: Adding or fixing tests
• chore: Maintenance tasks (dependencies, CI, metadata)

Example: feat(security): implement path traversal protection

2. Interactive Rebase Before Merging

Before merging your branch into dev, please use an interactive rebase to clean up your history into clean, logical blocks.

# Clean up your history relative to dev
git rebase -i dev

Use squash or fixup to remove "noisy" commits (fix typos, work-in-progress).

2. Create a Pull Request

• Write a clear title and description
• Reference any related issues (#123)
• Explain what changed and why
• Include screenshots for UI changes
• Ensure all tests pass

3. Code Review

• Respond to feedback constructively
• Make requested changes
• Update your PR branch if needed

4. Merge

We use a Squash and Merge workflow for all Pull Requests targeting the master branch. This ensures our release history remains clean and readable for public users.

Testing Guidelines

Unit Tests

Test individual functions and classes:

def test_knowledge_base_save():
    kb = KnowledgeBase()
    learning = {
        "category": "test",
        "summary": "Test learning",
        "content": "Test content"
    }
    kb.save(learning)
    assert kb.retrieve("test") is not None

Integration Tests

Test workflows end-to-end:

def test_review_workflow(tmp_path):
    # Create a test repository
    # Run review workflow
    # Assert findings are generated
    pass

Documentation

Documentation is built with MkDocs. To preview locally:

uv run mkdocs serve
# Open http://127.0.0.1:8000

Update documentation in docs/ when adding features.

Code Style

• Follow PEP 8
• Use type hints where appropriate
• Write docstrings for public functions
• Keep functions focused and small
• Prefer readability over cleverness

Questions?

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to Compounding Engineering! 🎉