kaizen-agentic/CONTRIBUTING.md

Contributing

This is a Contributing file, used to specify how the repository is and should stay organized. The format is based on Keep a Contributing-File V0.0.1. The structure originates from best practices for setting up python repositories as documented for PythonVibes. Use agent-keepa-contributing-file.md to help maintaining this file.

This document outlines how to get started, how we organise 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)

After pulling updates: reinstall the CLI so new commands are available:

pip install -e .              # project venv
# or
pipx install -e . --force     # global pipx install

Consumers (pip install from registry): see docs/PACKAGE_RELEASE.md for Gitea PyPI credentials and --extra-index-url install paths.

Maintainers (release): make agents-sync-package before tagging when agents/ changes; make package-check and the pre-tag checklist in docs/PACKAGE_RELEASE.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)
• Pre-commit: pip install pre-commit && pre-commit install (see .pre-commit-config.yaml)
• CI: Gitea Actions workflow .gitea/workflows/ci.yml runs on push/PR to main

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

YAML frontmatter schema

---
name: <agent-name>
description: <one-line description>
category: testing | quality | process | infrastructure | release | docs | support | meta
memory: enabled  # optional; default enabled. Set to disabled for stateless utility agents
---

Session-start protocol (for session-bound agents)

Agents that do ongoing work across sessions should include a session-start block:

1. Check for .kaizen/agents/<name>/memory.md in the project root
2. If present, read it and acknowledge relevant context in the opening brief
3. Optionally invoke kaizen-agentic memory brief <name> for cross-agent orientation

Include this block in the agent prompt under a ## Session Start heading.

Session-close protocol (for session-bound agents)

At the end of each session the agent should:

1. Update ## Accumulated Findings, ## What Worked, ## Watch Points as needed
2. Append one line to ## Session Log (format: YYYY-MM-DD · <summary> · <outcome>)
3. Bump last_updated and session_count in the frontmatter

Include this block in the agent prompt under a ## Session Close heading.

Agents for which session state is irrelevant (e.g. keepaTodofile, keepaChangelog) should set memory: disabled in their frontmatter and omit these sections.

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

Feedback

We welcome bugs, feature ideas, and adoption experience reports.

• CLI: kaizen-agentic feedback — lists channels and issue templates
• Guide: docs/FEEDBACK.md
• Templates: .gitea/ISSUE_TEMPLATE/ (bug, feature, general feedback)

For cross-repo coordination between custodian agents, use State Hub messages (POST /messages/) — see session protocol in .claude/rules/session-protocol.md.

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.