lunchpick/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

lib/ follows Clean Architecture: core/ for shared constants, errors, network utilities, and base widgets; data/ for API clients, datasources, and repository implementations; domain/ for entities and use cases; presentation/ for Riverpod providers, pages, and widgets. Tests mirror features in test/, Hive migration specs live in test_hive/. Platform scaffolding sits under android/, ios/, macos/, linux/, windows/, web/, and docs under doc/.

Build, Test, and Development Commands

• flutter pub get – run after cloning or switching branches.
• flutter pub run build_runner build --delete-conflicting-outputs – regenerates adapters, JSON code, and merges doc/restaurant_data/store.db changes into assets/data/store_seed.json and store_seed.meta.json.
• flutter pub run build_runner watch --delete-conflicting-outputs – keep this on during development to auto-regenerate seeds when store.db changes.
• flutter run -d ios|android|chrome – launch on the target device/simulator (prefer simulators with location APIs).
• flutter build apk|appbundle|ios --release – production bundles after QA is green.

Coding Style & Naming Conventions

See doc/03_architecture/code_convention.md: two-space indent, 80-char soft wrap (120 hard), imports grouped Dart → packages → project, one public class per file. Use PascalCase for classes/providers, camelCase for methods/variables, UPPER_SNAKE_CASE for constants, snake_case for files/folders. Business logic identifiers and UI strings stay in English; comments/docs may be in Korean with the first English term in parentheses. Keep widgets small and compose within the relevant presentation/* module to preserve MVVM boundaries.

Testing Guidelines

Use the Flutter test runner: flutter test for all, flutter test test/..._test.dart for targeted runs, flutter test --coverage && genhtml coverage/lcov.info -o coverage/html for coverage. Name tests with _test.dart alongside sources. Prefer group/testWidgets to describe behaviors (e.g., “should recommend restaurants under rainy limits”). Run flutter test test_hive when Hive persistence changes.

Commit & Pull Request Guidelines

Commit format type(scope): summary (e.g., feat(recommendation): enforce rainy radius), optional body and Resolves: #123. Types: feat, fix, docs, style, refactor, test, chore. Create feature branches from develop, include API/UI screenshots when visuals change, describe validation steps, and link issues before review. Keep PRs focused on a single feature/bugfix.

Security & Configuration Tips

Never commit API secrets. Create lib/core/constants/api_keys.dart locally with placeholders and use secure storage/CI wiring. Verify location permissions and weather API keys before captures or uploads.

Scope, Goals, and Guardrails

• Applies repo-wide unless more specific instructions exist; system/developer directives still win.
• Keep changes minimal and localized; avoid destructive rewrites, config changes, or dependency bumps unless requested.
• For multi-step tasks, maintain an update_plan with exactly one step in_progress.
• Responses stay concise and list code/logs before rationale. If uncertain, prefix with “Uncertain:” and surface at most the top two options.
• Work is workspace-scoped; ask before adding dependencies or new network calls. Avoid unrequested deletes/rewrites/config changes.

Collaboration & Language

• Default responses must be in Korean; keep code/logs/commands in their original form.
• Business logic, identifiers, and UI strings remain in English; comments/docs in Korean with the first English term in parentheses.
• Git push reports and work completion reports are in Korean.
• Write code comments and commit/PR/work summary comments in Korean; include English terms in parentheses when helpful.

Validation & Quality Checks

• Run dart format --set-exit-if-changed . before finishing.
• Always run flutter analyze and relevant flutter test suites (including flutter test test_hive when Hive code changes) before hand-off. Add/update tests when behavior changes or bugs are fixed.
• Document executed commands in your PR or hand-off notes.

Sensitive Areas & Approvals

• Editing Android/iOS/macOS build settings, signing artifacts, Gradle/Xcode configs needs explicit approval.
• Do not touch pubspec.yaml dependency graphs, secrets, or add network activity/tools without requester confirmation.

Branch & Reporting Conventions

• Branch naming: codex/<type>-<slug> (e.g., codex/fix-search-null).
• Commit messages use type(scope): summary; keep explanations short and focused on observable behavior.
• When offering alternatives, show only the top two concise options.
• When closing a work report, propose concrete next tasks; if none, state that work is complete.

Notification & Wrap-up

• Before final report or end of conversation, run /Users/maximilian.j.sul/.codex/notify.py.
• Update any needed working docs before reporting results.

SRP & Layering Checklist

• Each file/class should have a single reason to change; split widgets ~400 lines and methods ~60 lines into helpers.
• Preserve presentation → domain → data dependency flow. Domain stays framework-agnostic; data must not reference presentation.
• Extract validation/transform/sort/filter logic into services/utilities instead of burying it inside widgets.