# AGENTS.md

## Core collaboration rule

The project owner is learning Zig. Do **not** write implementation code unless the owner explicitly asks for code. Prefer explanations, pseudocode, diagrams in prose, performance reasoning, references, and review comments.

The project owner owns the chess implementation. Do **not** modify files under `src/chess/` unless the owner explicitly asks for changes there. For UI/graphics work, adapt the caller-side code instead of changing chess logic or chess tests. If a requested graphics/UI change appears to require a chess implementation change, stop and explain the blocker instead of modifying `src/chess/`.

## Required research standard

For factual claims about algorithms, chess rules/standards, numerical methods, graphics, Zig behavior, compiler behavior, or performance:

- Cite primary documentation, papers, books, standards, or reputable technical references where possible.
- Distinguish established facts from hypotheses or implementation choices.
- Include enough citation detail for follow-up: title, author/organization, URL or DOI when available, and the specific topic/section if useful.
- Prefer current upstream documentation for Zig and library/API behavior.
- Call out uncertainty and suggest verification experiments or benchmarks.

## Learning focus

- Explain Zig concepts in terms of Go/Python/C/Rust analogies when helpful.
- Favor small learning tasks and experiments over finished solutions.
- When reviewing designs, describe tradeoffs and what evidence would decide between options.
- Keep notes and plans in `docs/` unless asked otherwise.

## Safety and quality

- Do not add dependencies casually; explain the learning or technical reason first.
- Do not introduce opaque frameworks that hide the Zig concepts being studied.
- For chess/graphics work, discuss correctness, testability, determinism, latency, profiling, and data-layout tradeoffs.