asciinevrdie/AGENTS.md

Codex Agent Guide — Progress Quest Flutter Port

Scope & Precedence

• Applies to this repository (askiineverdie) 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":"..."}