CONTRIBUTING.md

Contributing

Contributions are welcome. Imago is designed to be extended — adding a new tool should be the easiest thing you do today.

Quick start for contributors

git clone https://github.com/your-org/imago
cd imago
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest tests/

Architecture checklist before opening a PR

1. Does your change add a new tool?

   • Create a class in image_agent/tools/ that extends runtime.tool.Tool
   • Give it name, description, parameters, and execute()
   • Call ToolRegistry.register(YourTool()) at module level
   • Add the import to image_agent/tools/__init__.py
   • No changes to cli.py

2. Does your change add a new core algorithm?

   • Place it in image_agent/core/
   • Keep it independent — no imports from tools or runtime
   • Use SUPPORTED_FORMATS from image_agent.core if needed

3. Does your change modify the CLI?

   • Add a dispatch handler in image_agent/cli.py
   • Register it in the COMMANDS dict
   • Keep argument parsing and formatting separate from tool logic

Code style

• Type hints on all function signatures
• Docstrings on public classes and methods
• No giant functions (split if >40 lines)
• No tool-to-tool imports (use core layer instead)

Tests

pytest tests/

PR title format

tool: short description
core: short description
runtime: short description