Repository Guidelines

Project Structure & Module Organization

lib/main.dart is the single entry point; group new features in subfolders under lib/ (e.g., timer/, settings/) with widgets/, services/, and models/ as needed.
Tests live in test/ (default widget_test.dart); mirror lib/ paths (lib/timer/controller.dart → test/timer/controller_test.dart).
Assets such as backgrounds reside in assets/ and are declared in pubspec.yaml; keep new images in the same folder and register them there.
Platform folders (android/, ios/, macos/, windows/, linux/, web/) hold generated build config—modify only when working on platform-specific code or permissions.

flutter pub get – install/update dependencies.
flutter analyze – static analysis using flutter_lints; run before commits.
dart format . – format codebase (uses 2-space indent).
flutter test – run all unit/widget tests; add --coverage to check coverage.
flutter run -d <device> – launch locally on a simulator/emulator or browser.
flutter build apk --release or flutter build web --release – produce release artifacts for mobile or web.

Follow analysis_options.yaml (flutter_lints); prefer clean imports and avoid unused code.
Use snake_case for files, PascalCase for types, camelCase for variables/methods, and ALL_CAPS for consts.
Keep widgets small and composable; separate stateful logic from rendering.
Document non-obvious logic with comments; avoid print debugging in committed code.

Use flutter_test for units and widgets; name files *_test.dart and describe behavior in test names ('starts countdown on tap').
Cover new logic paths and UI states (loading/error/success); add visuals only when needed.
Run flutter test locally before opening a PR; ensure assets or permissions used in tests are mocked (e.g., geolocator calls).

If using Git, follow Conventional Commits (feat: add timer presets, fix: handle geolocator errors).
Scope commits narrowly; keep diffs focused on one concern.
PRs should include: summary of changes, linked issues/tasks, screenshots or screen recordings for UI updates, and a checklist of commands run (flutter analyze, flutter test).
Flag platform-specific changes (Android/iOS/Web) and note any permission/config edits in pubspec.yaml or platform manifests.

Do not commit API keys or secrets; prefer runtime configuration or platform-specific secure stores.
Keep asset paths synced with pubspec.yaml to avoid runtime load failures.
When adding location-dependent features (geolocator), document permission prompts and testing steps per platform.