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](https://coulomb.social/open/KeepaContributingfile).
The structure originates from best practices for setting up python repositories as documented for [PythonVibes](https://coulomb.social/open/PythonVibesGuide).
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:

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

**Consumers (pip install from registry):** see [docs/PACKAGE_RELEASE.md](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

```yaml
---
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](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](https://coulomb.social/open/KeepaContributingfile) with [PythonVibes](https://coulomb.social/open/PythonVibes) best practices integration.

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