kaizen-agentic/CONTRIBUTING.md

Contributing

This document outlines how to get started, how we organize work, and how to help maintain the quality & clarity of our contributions.

Thank you for your interest in contributing!

Getting Started

Prerequisites

• Python 3.8+ for the core framework
• Git for version control
• Make for development commands (optional but recommended)
• Understanding of AI agent concepts (helpful but not required)

Initial Setup

1. Fork and clone the repository
2. Set up virtual environment: python -m venv .venv && source .venv/bin/activate
3. Install dependencies: make setup-complete or pip install -e .
4. Verify setup: make test-quick or pytest tests/
5. Familiarize yourself with agent system (see CLAUDE.md)

Development Workflow

Project Structure

This repository follows PythonVibes best practices:

• src/kaizen_agentic/ - Core framework source code
• agents/ - Specialized agent definitions (17+ agents)
• tests/ - Comprehensive test suite
• TODO.md - Current development tasks (Keep a Todofile format)
• CHANGELOG.md - Version history (Keep a Changelog format)

Making Changes

1. Create a feature branch: git checkout -b feature/your-feature-name
2. Make your changes following the code standards below
3. Write tests for new functionality
4. Run the test suite: make test or pytest
5. Check code quality: make lint or run black . and flake8 .
6. Update documentation as needed
7. Submit a pull request with clear description

Testing Requirements

• All new code must include tests
• Tests should pass locally before submitting PR
• Use pytest framework for all tests
• Aim for good test coverage of new functionality

Code Standards

Python Standards (PythonVibes)

• Follow PEP 8 style guide (100 character line length)
• Use type hints for all public APIs
• Write comprehensive docstrings
• Use src/ layout for source code
• Manage dependencies through pyproject.toml

Quality Tools

• Formatting: Black (black .)
• Linting: Flake8 (flake8 .)
• Type Checking: MyPy (mypy src/)
• Testing: Pytest (pytest)

Agent Development Standards

For contributing new agents or improving existing ones:

• Use consistent YAML frontmatter format
• Write clear, actionable instructions
• Define explicit scope and authority boundaries
• Follow existing agent patterns in agents/ directory

Types of Contributions

We welcome various types of contributions:

• Code: New features, bug fixes, improvements
• Agent Definitions: New specialized agents or agent improvements
• Documentation: README updates, code comments, guides
• Testing: New tests, test improvements, bug reports
• Performance: Optimization improvements and measurements

Issue Reporting

When reporting bugs, please include:

• Clear description of the problem
• Steps to reproduce the issue
• Expected vs actual behavior
• Environment details (Python version, OS)
• Relevant error messages or logs

Pull Request Process

1. Discuss significant changes in an issue first
2. Keep PRs focused on a single feature or fix
3. Write clear commit messages following conventional commit format
4. Update relevant documentation including TODO.md and CHANGELOG.md
5. Ensure all checks pass including tests and linting
6. Respond to review feedback promptly and constructively

Agent-Assisted Development

This repository includes 17+ specialized agents to assist with development:

• Use todo-keeper for TODO.md maintenance
• Use changelog-keeper for CHANGELOG.md updates
• Use contributing-keeper for this file maintenance
• See CLAUDE.md for complete agent catalog and usage

Community Guidelines

Kaizen Philosophy

We follow continuous improvement principles:

• Quality-first approach to all contributions
• Regular optimization and refinement
• Performance measurement and pattern analysis
• Collaborative problem-solving

Communication

• Be respectful and constructive in all interactions
• Use GitHub issues and discussions for project-related communication
• Share knowledge and help other contributors
• Follow the project's code of conduct

Recognition

Contributors are acknowledged in:

• Release notes and CHANGELOG.md
• Agent definition attribution
• Community recognition for significant contributions

---

Format: This file follows Keep a Contributing-File V0.0.1 with PythonVibes best practices integration.

Maintenance: Use agent-keepaContributingfile.md to help maintain this file.