1 file changed
+37
AGENTS.md
new
+37
@@ -0,0 +1,37 @@
1
+# Repository Guidelines
2
+
3
+## Project Structure & Module Organization
4
+
5
+App setup lives in `lib/main.dart`, `lib/app.dart`, and `lib/bootstrap/`. Shared code belongs in `lib/core/`. Organize product code as vertical slices under `lib/features/<feature>/`, using `data/`, `providers/`, `views/`, and `utils/` as needed.
6
+
7
+Localization sources are `lib/l10n/app_*.arb`; resources live in `assets/`. Tests mirror production areas under `test/core/` and `test/features/`. Native projects are in `android/` and `ios/`; store media belongs in `docs/`.
8
+
9
+## Build, Test, and Development Commands
10
+
11
+Use FVM so development matches `.fvmrc` (Flutter 3.44.2):
12
+
13
+- `fvm flutter pub get` installs dependencies.
14
+- `fvm flutter run` launches the selected device.
15
+- `fvm flutter analyze` runs lints and analyzer checks.
16
+- `fvm dart format .` formats Dart sources.
17
+- `fvm flutter test [path]` runs all tests or a focused file.
18
+- `fvm flutter gen-l10n` regenerates localization output.
19
+- `fvm dart run build_runner build --delete-conflicting-outputs` refreshes ObjectBox output after entity changes.
20
+
21
+## Architecture, Style & UI Libraries
22
+
23
+Follow `.agents/skills/flutter-feature-based-architecture/SKILL.md` for every feature or refactor. A feature may import itself and `core/`, never a sibling feature. Keep views thin; place business rules, async work, persistence, and mutations in Riverpod notifiers or repositories. Extract UI sections into named `StatelessWidget` classes under `views/components/`, not private `_build...` helpers. Keep models and providers handwritten; ObjectBox is the existing generation exception.
24
+
25
+Use two-space indentation and `dart format`. Name files `snake_case.dart`, types `UpperCamelCase`, and members and providers `lowerCamelCase`. Render every icon with `HugeIcon` and a `HugeIcons.*` constant; do not use Flutter `Icon` or `Icons.*`. For animation, prefer Cue, provide an explicit motion, and use one `Cue` per coordinated scene with `Actor` delays for stagger. Follow `.agents/skills/hugeicons-usage/SKILL.md` and `.agents/skills/cue-animations/SKILL.md`. Do not hand-edit generated files.
26
+
27
+## Testing Guidelines
28
+
29
+Tests use `flutter_test` and end in `_test.dart`. Add regression tests beside the feature; use widget tests for navigation and provider-driven UI. Run tests and analysis before a PR. The MinIO test requires `LOCALMIND_MINIO_*` variables. No numeric coverage threshold is enforced, but changed behavior should be covered.
30
+
31
+## Commit & Pull Request Guidelines
32
+
33
+Use Conventional Commit-style prefixes: `feat:`, `fix:`, `refactor:`, and `chore:`, with optional scopes such as `fix(providers):`. Keep subjects imperative and reference issues when relevant. PRs should explain impact and verification, link issues, include before/after UI screenshots, and call out localization, permissions, schema, or generated-file updates.
34
+
35
+## Security & Configuration
36
+
37
+Never commit API keys, signing material, model data, or user conversations. `private/` and `playstore_keys/` are intentionally ignored. Treat server URLs and cloud-sync credentials as sensitive test data.