# AGENTS Guide

## Purpose
This file is mandatory reading at the start of every session in this repository.
It defines how agents should navigate the codebase, implement work, validate changes, and create checkpoints.

## Precedence and Scope
- Scope: applies to the entire repository.
- Override rule: if a deeper-path `AGENTS.md` is added later, it overrides this file for its subtree only.

## Codebase Map
- `lib/core`: engine, opponents, content loading, storage, domain models.
- `lib/features`: feature modules (`home`, `lessons`, `puzzles`, `play`) with screen/bloc/widget code.
- `lib/shared`: reusable UI, board wrapper, theme primitives.
- `assets/content`: content manifest and lesson/puzzle JSON assets.
- `docs`: ADRs and per-service/per-bloc markdown documentation.
- `test`: core tests, feature tests, widget tests, golden smoke tests.

## Task Execution Workflow
1. Explore first: inspect relevant files and current behavior before editing.
2. Implement in small slices.
3. Validate each slice immediately (do not batch all validation at the end).
4. Keep progress steady; avoid large unverified change sets.

## Branch Policy (New Features)
- Do not implement new features directly on `main`.
- Use a feature branch; naming is intentionally flexible.
- Recommended examples:
  - `feature/drag-input`
  - `fix/lesson-flow`
  - `chore/ci-cleanup`
  - `docs/agent-guide`

## Checkpoint Commit Policy
- Create a checkpoint commit after each logical unit is implemented and validated.
- Keep each checkpoint focused and reversible.
- Commit message format:
  - `<type>: <short intent>`
- Add a brief commit body when context is needed (`what changed` and `why`).

## Validation Gate Before Checkpoint Commits
Run all of the following before creating a checkpoint commit:
- `dart format .`
- `flutter analyze`
- `flutter test`

If UI/golden behavior changes:
- update/verify goldens explicitly (for example with `--update-goldens` when intended), and note it in the summary.

## Docs Maintenance Rules
- If core service or bloc behavior changes, update the matching markdown in:
  - `docs/core`
  - `docs/features`
- If architecture or directional decisions change, add/update an ADR in `docs/adr`.
- Example: if `GameBloc` behavior changes, update `docs/features/game_bloc.md` in the same work unit.

## Git Hygiene
- Keep `.gitignore` current for generated and machine-local artifacts.
- Never commit build outputs or local environment files.
- Keep commits small, reviewable, and rollback-friendly.

## Definition of Done (per task)
- Code compiles and runs for the changed area.
- `flutter analyze` passes.
- `flutter test` passes.
- Related docs are updated where behavior changed.
- Final handoff summarizes changed files and next verification steps.