tegwick
22ee93e125
Lazy-load agent registry (frontmatter index, parse on demand), copy agents by path during install, fix Makefile template tab lint issue, add registry performance tests, bump to 1.1.0, document CLI reinstall after pull.
190 lines
7.0 KiB
Markdown
190 lines
7.0 KiB
Markdown
# 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
|
|
```
|
|
|
|
## 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.
|