# Repository Guidelines

## Project Structure & Module Organization
FullMooncGPT hosts the orchestration code for conversational agents. Place runtime modules in `src/fullmooncgpt/`, grouped by feature folders such as `agents/`, `pipelines/`, and `integrations/`. Shared helpers belong in `src/fullmooncgpt/common/` so they can be reused without circular dependencies. Prompt templates, YAML configs, and sample payloads live in `assets/`, with a short `README.md` per subsection describing expected inputs and outputs. Tests sit in `tests/`, mirroring the module layout, and notebooks or exploratory scripts go under `research/` so they never ship with the package.

## Build, Test, and Development Commands
1. `python -m pip install -r requirements.txt` installs the runtime stack; add dev-only tooling to `requirements-dev.txt`.
2. `python -m pip install -e .[dev]` enables editable development once `pyproject.toml` is in place.
3. `python -m fullmooncgpt.cli --help` exercises the primary entry point; add new subcommands under `src/fullmooncgpt/cli/`.
4. `python -m pytest` runs the entire suite; pass `-k` to focus on a subset during iteration.
5. `ruff format && ruff check` enforce formatting and linting; run before every commit to match CI.

## Coding Style & Naming Conventions
Target Python 3.11+, annotate public functions, and rely on dataclasses or pydantic models for structured payloads. Follow snake_case for modules and functions, PascalCase for classes, and keep module names short but descriptive. Stick to 4-space indentation and keep functions focused on a single responsibility. Store configuration in `.env` files loaded through `pydantic-settings` rather than hard-coding credentials.

## Testing Guidelines
Use pytest and hypothesis for property-based coverage. Name files `test_<module>.py` and isolate test data under `tests/fixtures/`. Aim for ≥85% statement coverage; capture notable gaps in the PR description. Mark slow or external-integration tests with `@pytest.mark.slow` so CI can opt in.

## Commit & Pull Request Guidelines
Adopt Conventional Commits (for example, `feat: planner adds multi-hop support`) to keep changelog generation simple. Keep PRs scoped; include a checklist covering tests run, documentation updates, and backward compatibility notes. Link related issues with `Closes #ID` and attach logs or screenshots for UI-facing adjustments. Request at least one maintainer review and avoid force pushes after review without coordination.