# Codex Agent Guide — Progress Quest Flutter Port

## Scope & Precedence
- Applies to this repository (`asciineverdie`) unless a more specific rule exists deeper in the tree.
- Order of authority: system/developer messages > this AGENTS.md > other inherited defaults.

## Goal
- Recreate the Progress Quest 6.4 single-player experience from `example/pq` in Flutter with identical gameplay, logic, and data.
- Run completely offline: no network calls, server selection, guild/brag uploads, or browser launches.
- Do not alter original algorithms or data (monsters, items, spells, modifiers, etc.). If a change is required, explain why and obtain user approval first.

## Guardrails
- Workspace-only edits; avoid destructive rewrites unless explicitly requested.
- Dependency or network changes (e.g., `pubspec.yaml`, new packages, online access) require prior user approval.
- Keep the app offline: remove/disable HTTP, web views, and external browser calls.
- Responses are in Korean by default; if uncertain, prefix with `Uncertain:` and list only the top two options.
- For multi-step work, use `update_plan` with exactly one `in_progress` step at a time.
- When following checklist documents, update checkboxes immediately as progress is made.

## Git / Commit / Review Comments
- Branch naming: `codex/<type>-<slug>` (e.g., `codex/feat-seed-loader`).
- Commit messages: Conventional Commit format `type(scope): summary`; summaries primarily in Korean (technical terms in English as needed).
- Review/report notes: present code/logs/commands first, followed by brief rationale. Use `Uncertain:` if unsure.
- After git push, share reports/descriptions in Korean.

## Coding Standards
- Language/Tools: Dart/Flutter; port original algorithms directly—no speculative optimizations or logic refactors.
- Data: keep extracted datasets (e.g., `Config.dfm`) 1:1 with the source; no ad-hoc edits.
- Style: two-space indentation; run `dart format .`; use meaningful names; avoid unnecessary comments.
- Structure: preserve standard Flutter structure; shared constants/data may live in `lib/data`, but logic must stay faithful to the original.
- Tests: add/update unit/widget tests when behavior changes, ensuring original logic is preserved.

## Validation
- Prefer to run before handoff:
  - `dart format --set-exit-if-changed .`
  - `flutter analyze`
  - `flutter test` (when tests exist)

## Sensitive Areas (require approval)
- Dependency graph changes (`pubspec.yaml`), platform build settings (Android/iOS/desktop), Gradle/Xcode configs, signing/provisioning.
- Introducing network access, modifying original data/algorithms, large file deletions, or repository restructuring.

## Communication
- Keep summaries concise; list code/logs/commands first, then short reasoning.
- For UI changes, briefly describe visual impact (layout/color/interaction).
- Offer numbered next-step options only when useful; otherwise, simply report completion.

## Architecture Discipline
- Preserve Single Responsibility Principle and Clean Architecture boundaries:
  - Presentation → Domain → Data dependency flow only; never depend upward.
  - Domain stays framework-agnostic; no Flutter/UI imports.
  - Data must not reference presentation; convert DTOs before exposing.
  - Split oversized files/functions; avoid “god” widgets or services.

## Notification
- Before final handoff, run the notification script when possible:
  - Requires macOS `terminal-notifier`.
  - Usage: `python3 /Users/maximilian.j.sul/.codex/notify.py '<json_payload>'`
  - Example payload: `{"type":"agent-turn-complete","input_messages":["..."],"last-assistant-message":"..."}`