60 lines
3.6 KiB
Markdown
60 lines
3.6 KiB
Markdown
# 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":"..."}`
|