hive/CONTRIBUTING.md

Contributing to Aden Agent Framework

Thank you for your interest in contributing to the Aden Agent Framework! This document provides guidelines and information for contributors.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct.

Contributor License Agreement

By submitting a Pull Request, you agree that your contributions will be licensed under the Aden Agent Framework license.

Issue Assignment Policy

To prevent duplicate work and respect contributors' time, we require issue assignment before submitting PRs.

How to Claim an Issue

1. Find an Issue: Browse existing issues or create a new one
2. Claim It: Leave a comment (e.g., "I'd like to work on this!")
3. Wait for Assignment: A maintainer will assign you within 24 hours
4. Submit Your PR: Once assigned, you're ready to contribute

Note: PRs for unassigned issues may be delayed or closed if someone else was already assigned.

The 5-Day Momentum Rule

To keep the project moving, issues with no activity for 5 days (no PR or status update) will be unassigned. If you need more time, just drop a quick comment!

Exceptions (No Assignment Needed)

You may submit PRs without prior assignment for:

• Documentation: Fixing typos or clarifying instructions — add the documentation label or include doc/docs in your PR title to bypass the linked issue requirement
• Micro-fixes: Add the micro-fix label or include micro-fix in your PR title to bypass the linked issue requirement. Micro-fixes must meet all qualification criteria:

  Qualifies	Disqualifies
  < 20 lines changed	Any functional bug fix
  Typos & Documentation & Linting	Refactoring for "clean code"
  No logic/API/DB changes	New features (even tiny ones)

If a high-quality PR is submitted for a "stale" assigned issue (no activity for 7+ days), we may proceed with the submitted code.

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/hive.git
3. Create a feature branch: git checkout -b feature/your-feature-name
4. Make your changes
5. Run checks and tests:

   make check                              # Lint and format checks
   cd core && python -m pytest tests/ -v   # Core tests
   

6. Commit your changes following our commit conventions
7. Push to your fork and submit a Pull Request

Development Setup

# Install Python packages and verify setup
./quickstart.sh

# Verify installation manually (optional)
python -c "import framework; import aden_tools; print('✓ Setup complete')"

Windows Users:
If you are on native Windows, it is recommended to use WSL (Windows Subsystem for Linux).
Alternatively, make sure to run PowerShell or Git Bash with Python 3.11+ installed, and disable "App Execution Aliases" in Windows settings.

Tip: Installing Claude Code skills is optional for running existing agents, but required if you plan to build new agents.

Commit Convention

We follow Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(auth): add OAuth2 login support
fix(api): handle null response from external service
docs(readme): update installation instructions

Pull Request Process

1. Get assigned to the issue first (see Issue Assignment Policy)
2. Update documentation if needed
3. Add tests for new functionality
4. Ensure make check and core tests pass (cd core && python -m pytest tests/ -v)
5. Update the CHANGELOG.md if applicable
6. Request review from maintainers

PR Title Format

Follow the same convention as commits:

feat(component): add new feature description

Project Structure

• core/ - Core framework (agent runtime, graph executor, protocols)
• tools/ - MCP Tools Package (tools for agent capabilities)
• exports/ - Agent packages and examples
• docs/ - Documentation
• scripts/ - Build and utility scripts
• .claude/ - Claude Code skills for building/testing agents

Code Style

• Use Python 3.11+ for all new code
• Follow PEP 8 style guide
• Add type hints to function signatures
• Write docstrings for classes and public functions
• Use meaningful variable and function names
• Keep functions focused and small

Testing

Note: When testing agents in exports/, always set PYTHONPATH:

PYTHONPATH=core:exports python -m agent_name test

# Run all tests for the framework
cd core && python -m pytest

# Run all tests for tools
cd tools && python -m pytest

# Run tests for a specific agent
PYTHONPATH=core:exports python -m agent_name test

Questions?

Feel free to open an issue for questions or join our Discord community.

Thank you for contributing!