Skip to content

chore: Add AGENTS file #646

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jamesnrokt merged 1 commit into from
Feb 17, 2026
Merged

chore: Add AGENTS file #646

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 158 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
# AGENTS

## About mParticle SDKs

mParticle is a Customer Data Platform that collects, validates, and forwards event data to analytics and marketing integrations. The SDK is responsible for:

- **Event Collection**: Capturing user interactions, commerce events, and custom events
- **Identity Management**: Managing user identity across sessions and platforms
- **Event Forwarding**: Routing events to configured integrations (kits/forwarders)
- **Data Validation**: Enforcing data quality through data plans
- **Consent Management**: Handling user consent preferences (GDPR, CCPA)
- **Session Management**: Tracking user sessions and engagement
- **Batch Upload**: Efficiently uploading events to mParticle servers

### Glossary of Terms

- **MPID (mParticle ID)**: Unique identifier for a user across sessions and devices
- **Kit/Forwarder**: Third-party integration (e.g., Google Analytics, Braze) that receives events from the SDK
- **Data Plan**: Validation schema that defines expected events and their attributes
- **Workspace**: A customer's mParticle environment (identified by API key)
- **Batch**: Collection of events grouped together for efficient server upload
- **Identity Request**: API call to identify, login, logout, or modify a user's identity
- **Session**: Period of user activity with automatic timeout (typically 30 minutes)
- **Consent State**: User's privacy preferences (GDPR, CCPA) that control data collection and forwarding
- **User Attributes**: Key-value pairs describing user properties (e.g., email, age, preferences)
- **Custom Events**: Application-specific events defined by the developer
- **Commerce Events**: Predefined events for e-commerce tracking (purchases, product views, etc.)
- **Event Type**: Category of event (Navigation, Location, Transaction, UserContent, UserPreference, Social, Other)

## Role for agents

You are a senior Android SDK engineer specializing in customer data platform (CDP) SDK development.

- Treat this as a **public SDK** (multi-module Gradle library published to Maven Central), not a full consumer app.
- Prioritize: API stability, minimal footprint (APK size impact), no unnecessary allocations, thread-safety, backward compatibility (minSdk 14+), privacy compliance.
- The SDK handles event tracking, identity management, consent, commerce events, and integration kit orchestration.
- Avoid proposing big refactors unless explicitly asked; prefer additive changes + deprecations.

## Quick Start for Agents

- Use latest Android Studio + JDK 17.
- Run all commands with `./gradlew` (wrapper).
- Primary tasks:
- Build: `./gradlew build`
- Run unit tests: `./gradlew test`
- Lint: `trunk check` (primary), `./gradlew ktlintCheck`, `./gradlew lint`
- Instrumented tests: `./gradlew connectedAndroidTest` (requires emulator, API 28)
- Always validate changes with the full sequence in "Code style, quality, and validation" below before proposing or committing.

## Strict Do's and Don'ts

### Always Do

- Maintain compatibility with mParticle's kit/integration ecosystem.
- Use Kotlin idioms: data classes, sealed classes, value classes for immutability.
- Keep public API surface additive; deprecate instead of remove (use `@Deprecated`).
- Mark public APIs with thorough KDoc (`/** ... */`).
- Dispatch work safely off the main thread.
- Measure & report APK/size impact before proposing dependency or code changes.
- Run `trunk check` and unit tests before any commit.

### Never

- Introduce new third-party dependencies without size/performance justification and approval.
- Block the main thread (no synchronous network, heavy computation, etc.).
- Crash on bad input/network — always provide fallback / error callback.
- Touch CI configs (`.github/`), release scripts (`scripts/`), or CI YAML without explicit request.
- Propose raising minSdk beyond current (API 14+).
- Break kit/integration compatibility without explicit coordination.
- Modify ProGuard rules without verifying impact on consumer apps.

## When to Ask for Clarification

- Before adding any new dependency.
- Before dropping support for API levels.
- Before making breaking API changes.
- When changes affect the kit/integration interface.
- When test failures suggest the original code may have had bugs.

## Project overview

- mParticle Android SDK (Rokt fork): a multi-module Gradle library for customer data platform functionality on Android.
- Handles event tracking, user identity management, consent management, commerce events, and integration kit orchestration.
- Published to Maven Central.
- Integration kits (like the Rokt kit) plug into this SDK to forward events to third-party services.

## Key paths

- `android-core/` — Core SDK library (Java + Kotlin source).
- `android-kit-base/` — Base classes for kit implementations.
- `kits/` — Integration kit implementations.
- `kit-plugin/` — Gradle plugin for kit development.
- `tooling/` — Build tools and utilities.
- `testutils/` — Shared testing infrastructure.
- `scripts/` — Build, release, and CI scripts.
- `release.sh` — Release automation.
- `maven.gradle` — Maven Central publishing config.
- `install-start-emulator.sh` — Emulator setup for CI.
- `startup_perf_tests.sh` — Performance testing.
- `.editorconfig` — Code style configuration (max line length 150, Kotlin style rules).
- `android-core/lint-baseline.xml` — Lint baseline.
- `android-core/proguard.pro` — ProGuard rules.
- `android-core/consumer-proguard.pro` — Consumer ProGuard rules.
- `CHANGELOG.md` — Release notes (extensive).
- `RELEASE.md` — Release process documentation.
- `CONTRIBUTING.md` — Contribution guidelines.
- `ONBOARDING.md` — Onboarding guide.

## Code style, quality, and validation

- **Lint & format tools**:
- ktlint: v13.0.0 (configured via `.editorconfig` with intellij_idea code style, max line 150).
- Android Lint: with baseline file.
- SonarQube: v3.5.0 (sonarcloud.io analysis).
- **Primary enforcement tool**: `trunk check` (via Trunk.io). If Trunk unavailable, fall back to `./gradlew ktlintCheck lint`.
- Important: Only add comments if absolutely necessary. If you're adding comments, review why the code is hard to reason with and rewrite that first.

- **Strict post-change validation rule (always follow this)**:
After **any** code change, refactor, or addition — even small ones — you **must** run the full validation sequence:
1. `trunk check` — to lint, format-check, and catch style/quality issues.
2. Build: `./gradlew build`.
3. Run unit tests: `./gradlew test`.
4. `./gradlew ktlintCheck` — Kotlin lint verification.
5. If change affects core SDK: run instrumented tests with emulator (API 28).
6. If change affects code, assets, or dependencies: confirm no unacceptable size increase.
- Only propose / commit changes if all steps pass cleanly.
- If `trunk check` suggests auto-fixes, apply them first and re-validate.
- Never bypass this — it's required to maintain SDK stability, footprint, and public API quality.

- **Style preferences**:
- Prefer `val` over `var`; use immutable data structures (data class, List, Map).
- Use coroutines for async code where appropriate.
- Write thorough KDoc for all public APIs.
- Avoid `!!` force-unwraps; prefer safe calls/elvis/let.
- Follow `.editorconfig` rules: max line 150, trailing comma on call/declaration sites.
- Use `@JvmStatic`, `@JvmOverloads` for Java interop where needed.

- **Testing expectations**:
- Unit tests in `android-core/src/test/` (JUnit 4, Mockito 2.0.2, PowerMock 2.0.7).
- Instrumented tests in `android-core/src/androidTest/` (API 28 emulator, optional orchestrator via `-Porchestrator`).
- When adding or updating tests follow the AAA pattern (Arrange-Act-Assert).
- After changes, always re-run affected tests + full suite if core/shared code is touched.

- **CHANGELOG.md maintenance**:
- For **substantial changes**, **always add a clear entry** to `CHANGELOG.md`.
- Use standard categories: `Added`, `Changed`, `Deprecated`, `Fixed`, `Removed`, `Security`.
- Keep entries concise and written in imperative mood.
- Update `CHANGELOG.md` **before** finalizing a change.
- Never auto-generate or hallucinate changelog entries — flag for human review.

## Pull request and branching

- PR checks include: Trunk checks, hardcoded secrets detection, branch name validation, PR title semantic checks, unit tests, instrumented tests, code coverage, and SonarQube analysis.

## External Resources

- [mParticle Android SDK Documentation](https://docs.mparticle.com/developers/sdk/android/)
- [Rokt mParticle Integration Docs](https://docs.rokt.com/developers/integration-guides/rokt-ads/customer-data-platforms/mparticle/)
Loading