Repository Guidelines

Project Structure & Module Organization

Current repo holds conceptual guides: notes1.md (Atomic Evaluation Engine architecture) and notes1a.md (Agno AoT alignment).
Place new docs in docs/ with concise ADR-style notes; keep root markdown for high-level manifestos and context packs.
When adding code, prefer src/ for runtime, examples/ for runnable snippets, tests/ for pytest suites, and scripts/ for one-off automation; keep data out of version control.

Python-first stack; target 3.11+. Use uv or poetry to isolate deps. Example bootstrap:
- uv sync (or poetry install) to install dependencies.
- uv run pytest to execute the suite.
- uv run python examples/demo.py for smoke demos; keep examples runnable without secrets.
Use docker compose up db if you introduce Postgres for audit trails; pin images and ports.

Favor typed Pydantic models for agent I/O; set show_full_reasoning=False and markdown=False in Agno agents to enforce zero-leakage outputs.
Keep functions/agents single-purpose and composable; prefer deterministic settings (temperature=0).
Name modules and files by intent: atoms/, workflows/, schemas.py; tests mirror paths (tests/atoms/test_decomposer.py).
Use snake_case for Python, lower-kebab for scripts; keep doc filenames descriptive (context-pack-*.md).

Use pytest; new features require unit coverage and at least one workflow-level test when orchestration changes.
Name tests test_<behavior>(); include fixtures for ground truth/claims pairs; keep hallucination regression cases.
Run uv run pytest -q before PRs; add regression tests when fixing bugs.

Commit messages in imperative present tense; scope prefix when obvious (e.g., agents: add verifier schema).
PRs should summarize changes, link issues, list test commands, and include before/after artifacts (JSON outputs or logs) for agent behavior changes.
Avoid committing secrets or large data; document any config/env vars in README.md or docs/config.md.