# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

The project uses Python 3.11 with a local virtualenv.

```bash
# Activate virtualenv
source venv/bin/activate

# Install dependencies (once pyproject.toml or requirements.txt exists)
pip install -e ".[dev]"

# Run all tests
pytest

# Run a single test file
pytest tests/path/to/test_file.py

# Run a single test by name
pytest tests/path/to/test_file.py::test_function_name -v

# Lint and type-check
ruff check .
mypy .
```

> Update this section as `pyproject.toml` and `requirements.txt` are added.

## Architecture

This project is in early initialization. Architecture notes will be added here as the codebase grows. Follow `PLAN.md` or `SPEC.md` for current requirements before writing any code.

## Core Workflow
- **TDD Strictly:** ALWAYS write or ask for a failing test case before implementing logic.
- **Spec-First:** Follow `PLAN.md` or `SPEC.md`. Do not guess requirements.
- **Plain English:** Explain logic in simple Subject-Verb-Object sentences.

## Python Standards
- **Type Hints:** MANDATORY for all function arguments and returns.
- **Data Validation:** Use `Pydantic` models, not raw dictionaries.
- **Docstrings:** Google-style, concise.
- **No `os.path`:** Use `pathlib` for file handling.

## Interaction Rules
- **No Hallucinations:** If unsure about a library, ask to check docs.
- **Context:** Do NOT read `venv/`, `node_modules/`, or large data files.

## Human-in-the-Loop Protocol (MANDATORY)

After generating any significant code (more than 20 lines or modifying core logic), you MUST automatically perform the following steps BEFORE asking me to proceed:

1. **Self-Explanation:** Briefly explain *what* you changed and *why*, in Plain English.
2. **Structural Check:** Did you introduce any new dependencies? Did you change any function signatures?
3. **Risk Assessment:** What is the most likely thing to break with this change?
4. **Verification Plan:** Tell me exactly which test command to run to verify this specific change.