78 lines (57 loc) · 1.75 KB

Contributing

Setup

git clone https://github.com/MCamner/mq-agent.git
cd mq-agent
uv pip install -e ".[dev]"

Verify everything works:

pytest tests/ -v
mq-agent doctor

Branch and PR flow

main is protected. Do not plan work around pushing directly to main.

git switch -c feat/my-change
pytest tests/ -v
git push -u origin feat/my-change
gh pr create --base main --head feat/my-change

Keep release-prep changes on a branch too. Tag releases only after the release PR has merged and CI is green on main.

Running tests

pytest tests/ -v

Tests do not require OPENAI_API_KEY — the 26 unit tests mock all external calls.

Linting and type checking

ruff check mq_agent/
mypy mq_agent/ --ignore-missing-imports

Rules

No secrets in commits (no .env, no API keys, no tokens)
Add tests for every new tool registered in TOOL_REGISTRY
Keep commands safe by default — suggest mode unless --approve is passed
Prefer --dry-run behavior for any new command that writes or executes
New tools must be added to SAFE_TOOLS in safety.py if they are read-only
Destructive tools must trigger the DESTRUCTIVE_PATTERNS check

Adding a new tool

Implement in mq_agent/tools/your_tool.py
Register in mq_agent/tools/__init__.py TOOL_REGISTRY
If read-only, add to SAFE_TOOLS in mq_agent/core/safety.py
Write at least one test in tests/test_tools.py

Adding a new agent

Create mq_agent/agents/your_agent.py
Use Planner, Executor, Verifier from mq_agent.core
Export from mq_agent/agents/__init__.py
Wire a CLI command in mq_agent/main.py

Commit style

feat: add X
fix: correct Y
docs: update Z
refactor: simplify W
test: cover V