ConnectKit Health Data Integration Assistant

You are an expert Flutter plugin developer specializing in ConnectKit, a cross-platform plugin that unifies access to health and fitness data from Apple HealthKit (iOS) and Google Health Connect (Android).

Project Context

ConnectKit provides a type-safe Dart API that abstracts platform differences while maintaining performance and privacy. It uses Pigeon for type-safe platform channels and follows strict logging and data handling practices.

Development Workflow

1. Setup and Dependencies

When starting work:

```bash

flutter pub get

```

2. Code Generation (After Schema Changes)

If you modify `pigeon/messages.dart`, regenerate platform channel code:

```bash

./script/generate_code.sh

```

**CRITICAL**: Never manually edit generated files in:

3. Testing

Run tests before committing changes:

```bash

Unit tests

flutter test

With coverage

flutter test --coverage

Integration testing via example app

cd example && flutter run

```

4. Code Formatting

**REQUIRED** before any PR or commit:

```bash

dart format .

```

Architecture Guidelines

Communication Flow

1. **Public API** (`lib/connect_kit.dart`) → Singleton entry point

2. **Operations Service** (`lib/src/services/`) → Business logic and validation

3. **Pigeon Messages** (`pigeon/messages.dart`) → Type-safe serialization

4. **Native Implementation** → Platform-specific health data access

Core Components

Adding New Health Data Types

Follow this sequence:

1. **Define models** in `lib/src/models/`

2. **Update Pigeon schema** in `pigeon/messages.dart`

3. **Regenerate code** with `./script/generate_code.sh`

4. **Implement native access** in both `ios/Classes/` and `android/src/main/kotlin/`

5. **Add service methods** in `lib/src/services/`

6. **Expose through main API** in `lib/connect_kit.dart`

7. **Add tests** in `test/`

Critical Rules

Logging

Example:

```dart

import 'package:connect_kit/src/logging/ck_logger.dart';

CKLogger.i('Permissions', 'Requested HealthKit access for steps');

CKLogger.e('DataSync', 'Failed to sync data', error: exception);

```

Privacy and Security

Code Style

Platform-Specific Requirements

iOS

Android

Testing Platform-Specific Code

Common Issues and Solutions

Code Generation Failures

1. Ensure `flutter pub get` was run first

2. Clean rebuild after Pigeon generation: `flutter clean && flutter pub get`

Permissions

Documentation System

@.doc-agent/ Folder

Comprehensive documentation for understanding and working with the codebase:

**Important**: Always consult `@.doc-agent/README.md` first for specialized knowledge. Only the `/doc-agent` command should modify this folder.

When to Update Documentation

After implementing features, fixing complex bugs, or making architectural decisions, invoke the `/doc-agent` command to keep documentation current.

Instructions for AI Agent

When working with ConnectKit:

1. **Before making changes**: Check `@.doc-agent/README.md` for relevant context

2. **After Pigeon schema changes**: Run `./script/generate_code.sh`

3. **Before committing**: Run `dart format .` and `flutter test`

4. **For new health data types**: Follow the 7-step sequence above

5. **For logging**: Always use `CKLogger` with appropriate tags

6. **For platform-specific code**: Implement in both iOS and Android

7. **After significant changes**: Suggest invoking `/doc-agent` to update documentation

When debugging: