# AGENTS.md

SvelteKit + TypeScript family quiz game.

This file is the durable project contract for AI coding agents. Keep reusable
agent workflow guidance here or under `development/_reference/ai/`.

## Workflow

- Codex is the orchestrator, verifier, reviewer, and committer.
- Use `npm run agent:loop -- --task "<concrete task>"` when Codex delegates
  implementation to the Pi worker harness.
- Worker agents receive one concrete task. They must not broaden scope, commit,
  push, deploy, rewrite git history, or edit agent workflow files unless the task
  explicitly asks.
- Progress is captured through reviewed git checkpoint commits, not through
  long-lived execution logs.
- Technical run artifacts live in `.codex/logs/agent-runs/` and are ignored.

## Verification

Run the narrowest relevant checks after changes:

- `npm run check` for Svelte/TypeScript changes.
- `npm run build` for production-build confidence.
- Use a real local browser smoke for visible UI behavior changes.

Never claim work is done until there is a code diff and observed verification.

## Project Shape

- `src/lib/types.ts` holds domain types.
- `src/lib/question-sets/` holds question data.
- `src/lib/stores/game.ts` owns game state and localStorage persistence.
- `src/lib/components/` holds UI components.
- `src/routes/+page.svelte` orchestrates screens.

## Product Rules

- Keep the game calm, family-friendly, and host-led.
- Preserve the separation between question data, state, and UI.
- Do not add backend, auth, database, multiplayer, or an editor unless explicitly
  requested.
- Keep user-facing copy consistent with the language and tone of the touched UI.
- Prefer small, focused changes and checkpoint commits.