metal-kompanion/AGENTS.md

Repository Guidelines

This guide supports new agents contributing to metal-kompanion, the MCP backend for Kompanion. Follow these practices to keep the service buildable, testable, and easy to review.

MCP Usage

• This project uses agentic-control-framework Use this for task planning

Project Structure & Module Organization

• src/ holds C++ code: mcp/ for server facade and tool routing, memory/ for embeddings contracts, dal/ for persistence, and policy/ for capability rules.
• docs/ hosts design notes; runtime/kom_runner.py is the Python orchestrator for agent execution against Ollama; db/ and sql/ capture Postgres schemas.
• docs/third_party is a symlink to reference code and apidocs.
• Place sample payloads or fixtures under tests/ (currently tests/schemas/ for JSON samples). Generated artifacts live in build/.
• src/cli is a command line prompt interface that tests the memory integration and pattern substiton.
• tools

Build, Test, and Development Commands

cmake -S . -B build          # configure with CMake 3.22+, targets C++20
cmake --build build -j       # compile the kom_mcp executable
ctest --test-dir build       # run CTest suites once they are defined
python3 runtime/kom_runner.py # exercise the runtime loop (requires OLLAMA_BASE)

Run the Python runtime from a virtualenv seeded with pip install -r runtime/requirements.txt.

Coding Style & Naming Conventions

• C++20, clang/gcc friendly, 4-space indentation, braces on the same line (class KomMcpServer {).
• Classes use PascalCase; methods camelCase; private members keep the trailing underscore (tools_). Prefer std:: types and RAII helpers over raw pointers.
• Keep headers lean: forward declare where possible and document non-obvious behavior with concise comments.

Testing Guidelines

• Add unit or schema validation tests under tests/, mirroring the source tree (e.g., tests/mcp/ for dispatcher tests).
• Register new tests with CTest via add_test in CMakeLists.txt; verify they pass with ctest --output-on-failure.
• Provide realistic JSON samples for new tools alongside schema updates to guard against regressions.

Commit & Pull Request Guidelines

• Follow the existing scope: message pattern from git history (docker: fix host ollama port); keep messages imperative and present tense.
• Each PR should state intent, link relevant issues, and include before/after notes or screenshots when UI-adjacent runtime behavior changes.
• Mention how to reproduce test runs (cmake --build, ctest) and flag configuration or migration steps (e.g., sql/ changes).

Security & Configuration Tips

• Do not commit secrets; runtime state lives beneath XDG paths (~/.local/state/kompanion). Document any new env vars in docs/.
• When integrating new tools, ensure access control aligns with policy/ capabilities and record expected journal entries in runtime docs.