Bernd Worsch
260b9b27e9
- CONTRIBUTING.md: add Session Start/Close protocol reference with YAML frontmatter schema (including new memory: enabled|disabled field) - agents: add ## Session Start / ## Session Close blocks to project-management, tdd-workflow, requirements-engineering, scope-analyst - registry.py: add AgentCategory.META; add memory field to AgentDefinition (parsed from frontmatter, default None = enabled); add coach/meta keyword detection and sys-medic/medic to infrastructure detection WP-0002 T09, T10, T11 done. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
169 lines
6.2 KiB
Markdown
169 lines
6.2 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)
|
|
|
|
## 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
|
|
|
|
#### 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
|
|
|
|
## 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.
|