Skip to content

KIRO.md

Latest commit

 

History

History
101 lines (77 loc) · 4.5 KB

KIRO.md

File metadata and controls

101 lines (77 loc) · 4.5 KB

KIRO.md

Project Overview

Professional VFR flight planning and navigation app for pilots, written in Dart using the Flutter framework.

Build & Run Commands

flutter pub get              # Install dependencies
flutter test                 # Run tests
flutter test path/to/test.dart  # Run single test file
flutter build apk            # Build Android
flutter build ios            # Build iOS
flutter build macos          # Build macOS
flutter analyze              # Lint

Code Style Rules

  • File naming: Use snake_case.dart for all Dart files.
  • Naming conventions: camelCase for variables/functions/parameters, PascalCase for classes/types/enums.
  • Imports: Group in order: dart SDK, flutter SDK, external packages, relative imports. Separate groups with blank lines.
  • Exports: Named exports only. No default exports.
  • Error handling: Use try/catch blocks. Access error messages with error.toString() or error is Exception ? error.toString() : 'Unknown error'.
  • Code generation: Files ending in .g.dart are auto-generated by build_runner. Never edit manually.
  • Linter: Follows package:flutter_lints/flutter.yaml. Scripts and tests excluded from analysis.

Architecture Overview

lib/
├── adapters/       # Type adapters for serialization (Hive, JSON)
├── config/         # Environment configuration
├── constants/      # App-wide constants (colors, themes, markers)
├── l10n/           # Localization files (ARB format, auto-generated)
├── models/         # Data models with JSON serialization
├── screens/        # Top-level UI screens
├── services/       # Business logic, API clients, data management
├── utils/          # Helper functions and utilities
├── widgets/        # Reusable UI components
└── main.dart       # App entry point

Dependency rule: Screens depend on widgets and services. Services depend on models and utils. Models are independent. Widgets may depend on models but not services directly (use Provider/InheritedWidget).

Critical Paths -- Extra Care Required

Changes to these files require additional test coverage and human review:

  • pubspec.yaml
  • lib/main.dart
  • lib/services/flight_service.dart
  • lib/services/location_service.dart
  • lib/services/barometer_service.dart
  • ios/Runner/Info.plist
  • android/app/build.gradle.kts

These are classified as Tier 3 (high risk) in harness.config.json. All Tier 3 changes require: analyze + full test suite + review-agent + manual human review.

Security Constraints

  • Never commit secrets, API keys, or .env files (use .env.example as template).
  • Never disable linter rules or analysis options without explicit justification.
  • Validate all external input at system boundaries (API responses, user input).
  • Never pass unsanitized user input to shell commands or native platform code.
  • Use platform channels securely -- validate all data crossing Dart/native boundary.

Dependency Management

  • Add dependency: flutter pub add <package>
  • Add dev dependency: flutter pub add --dev <package>
  • Always commit pubspec.lock after dependency changes.
  • Do not upgrade major versions without explicit instruction and testing.
  • Pin exact versions for critical dependencies in production.

Code Generation

  • Run code generation: dart run build_runner build --delete-conflicting-outputs
  • Watch mode: dart run build_runner watch --delete-conflicting-outputs
  • Generated files (.g.dart) are committed to version control.

Harness System Reference

This project uses harness engineering principles:

  • Risk tiers are defined in harness.config.json
  • CI gates enforce risk-appropriate checks on every PR
  • A review agent will automatically review PRs
  • Pre-commit hooks enforce local quality checks
  • Chrome DevTools MCP: .mcp.json configures @modelcontextprotocol/server-puppeteer for browser automation -- agents can navigate, screenshot, inspect DOM, and validate UI behavior
  • See docs/ for detailed architecture and conventions

PR Conventions

  • Branch naming: <type>/<short-description> (e.g., feat/terrain-warnings, fix/location-permission, chore/update-deps)
  • Commit messages: Conventional Commits -- feat:, fix:, chore:, docs:, refactor:, test:
  • All PRs must pass flutter analyze and flutter test before merge
  • Classify every PR by risk tier (Tier 1/2/3) in the PR description
  • Include screenshots for UI changes
  • Update relevant documentation in docs/ for architectural changes