Committing AI guidelines and gitignore for local config stuff. (#280)

* Committing AI guidelines and gitignore for local config stuff.

* Update uses of example setup

* Committing AI guidelines and gitignore for local config stuff.

* PR guidance

* Additional tweaks to commands and AGENTS file

---------

Co-authored-by: Evan Masseau <>

Author: evan-masseau

.cursor/BUGBOT.md

@@ -0,0 +1 @@
+For context on this project, review `/AGENTS.md`.

.github/CONTRIBUTING.md

@@ -42,7 +42,7 @@ This project is a monorepo managed using [Yarn workspaces](https://yarnpkg.com/f
 To get started with the project, run the following in the root directory to install the required dependencies for each package:
 
 ```sh
-yarn example-setup
+yarn example setup
 ```
 
 And configure the pre-commit hooks with:
@@ -138,7 +138,7 @@ Our pre-commit hooks verify that the linter and tests pass when committing.
 The `package.json` file contains various scripts for common tasks:
 
 - `yarn`: setup project by installing dependencies.
-- `yarn example-setup`: install dependencies for the example app
+- `yarn example setup`: install dependencies for the example app
 - `yarn typecheck`: type-check files with TypeScript.
 - `yarn lint`: lint files with ESLint.
 - `yarn test`: run unit tests with Jest.

.github/pull_request_template.md

@@ -1,17 +1,21 @@
 # Description
-<!-- Briefly describe the feature or bug that your pull request addresses, 1-2 sentences. -->
 
+<!-- Briefly describe the feature or bug that your pull request addresses, 1-2 sentences. -->
 
 ## Due Diligence
+
 <!-- Best practices before submitting, add additional notes below -->
+
 - [ ] I have tested this on a simulator/emulator or a physical device, on iOS and Android (if applicable).
 - [ ] I have added sufficient unit/integration tests of my changes.
 - [ ] I have adjusted or added new test cases to team test docs, if applicable.
 - [ ] I am confident these changes are implemented with feature parity across iOS and Android (if applicable).
 
 ## Release/Versioning Considerations
+
 <!-- Help determine how this should be categorized for release, add additional notes below. -->
 <!-- Please add the planned version as a `milestone` label on this PR -->
+
 - [ ] `Patch` Contains internal changes or backwards-compatible bug fixes.
 - [ ] `Minor` Contains changes to the public API.
 - [ ] `Major` Contains **breaking** changes.
@@ -20,15 +24,14 @@
 - [ ] This is planned work for an upcoming release.
   - If no, author or reviewer should account for this in a release plan, or describe why not below.
 
-
 ## Changelog / Code Overview
-<!-- What was changed / added / removed and why. Attach screenshots or other supporting materials -->
 
+<!-- What was changed / added / removed and why. Attach screenshots or other supporting materials -->
 
 ## Test Plan
-<!-- Provide reproducible testing steps. Link any artifacts, recordings, spreadsheets, etc. -->
 
+<!-- Provide reproducible testing steps. Link any artifacts, recordings, spreadsheets, etc. -->
 
 ## Related Issues/Tickets
-<!-- Link to relevant Jira issues, Slack discussions, Google Docs -->
 
+<!-- Link to relevant Jira issues, Slack discussions, Google Docs -->

.github/workflows/ios-build.yml

@@ -59,7 +59,7 @@ jobs:
         if: env.turbo_cache_hit != 1 && steps.cocoapods-cache.outputs.cache-hit != 'true'
         run: |
           export RCT_NEW_ARCH_ENABLED=${{ inputs.new-architecture }}
-          yarn example-setup
+          yarn example setup
           rm -f example/ios/.xcode.env.local
 
       - name: Build example for iOS

.gitignore

@@ -78,3 +78,6 @@ android/keystores/debug.keystore
 
 # generated by bob
 lib/
+
+# Local AI settings files
+.claude

AGENTS.md

@@ -0,0 +1,90 @@
+# AI Agent Guidelines
+
+This file provides guidance to AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) when
+working with code in this repository.
+
+You should assume the role of a senior React Native developer with substantial hybrid app development experience
+in addition to a deep background in native development on Android and iOS.
+
+You will be asked to help with code reviews, feature implementations, and debugging issues in this SDK.
+You prioritize code quality, maintainability, and adherence to the project's architecture and coding styles and standards.
+You create reusable code, searching for existing implementations first, and if you see conflicting
+or duplicative methods of doing the similar tasks, refactor common functionality into shared helpers/utilities.
+The experience of 3rd party developers integrating the SDK should be smooth, intuitive and as simple as possible.
+You prefer solutions using the most modern, practical and efficient approaches available in the React Native ecosystem.
+Always use up-to-date resources considering that React Native is an ever-changing landscape, old answers are often
+out of date or misleading. You avoid mistakes, and would rather answer that you don't know, or take more time
+researching than make something up. Cite your sources especially for anything with a modicum of uncertainty.
+
+## Project Overview
+
+This repository contains the Klaviyo React Native SDK, which provides a bridge between React Native applications
+and the native Klaviyo SDKs for iOS (Swift) and Android (Kotlin). The SDK enables key Klaviyo functionality including
+analytics tracking, push notifications, and in-app forms in React Native applications.
+
+## Repository Structure
+
+- `/src/`: TypeScript implementation of the React Native SDK
+  - `index.tsx`: Main entry point exporting the Klaviyo interface
+  - `*.ts`: API-specific implementations (Profile, Event, Push, Forms)
+- `/ios/`: Native iOS/Swift bridge implementation
+- `/android/`: Native Android/Kotlin bridge implementation
+- `/example/`: Example React Native app demonstrating SDK usage
+
+## Development Guidelines
+
+### Core Principles
+
+1. **Type Safety**: All code should be fully typed with TypeScript. Any bridged data should be thoroughly validated.
+2. **Platform Consistency**: Keep API surface consistent across platforms
+3. **Error Handling**: Ensure proper error handling and propagation
+4. **Documentation**: Keep inline documentation current
+5. **Testing**: Update tests when changing functionality
+
+### Native Bridge Development
+
+- **iOS**: Objective-C and Swift bridge layer communicating to Swift SDK
+- **Android**: Kotlin module bridge communicating to Kotlin SDK
+
+### Common Development Tasks
+
+#### Building and Testing
+
+```bash
+# Install dependencies
+yarn install
+
+# Build TypeScript code
+yarn build
+
+# Run TypeScript type-checking
+yarn typecheck
+
+# Run linter
+yarn lint
+
+# Run tests
+yarn test
+
+# Install dependencies for running the example app
+yarn example setup
+```
+
+#### Running Example App
+
+```bash
+# Start Metro bundler
+yarn example start
+
+# Run iOS example
+yarn example ios
+
+# Run Android example
+yarn example android
+```
+
+## Pull Requests
+
+If prompted to create a pull request, favor starting it in draft unless asked otherwise.
+You **MUST** follow the pull request template used by this repository, including important details
+in the relevant subsections of the template.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -106,7 +106,7 @@ code to call out key setup steps, search for `iOS Installation Step` and `Androi
 To run the example app:
 
 - Clone this repository
-- From the root directory, run `yarn example-setup`. This is an alias that will do the following:
+- From the root directory, run `yarn example setup`. This is an alias that will do the following:
   - Run `yarn install --immutable` from the root directory
   - Navigate to the `example` directory and run `bundle install`
   - Navigate to the `example/ios` directory and run `bundle exec pod install`
@@ -407,7 +407,6 @@ native code. Note that either of these approaches is sufficient to inform the Kl
 
 2. **Native Notification Permission**:
    Follow instructions from our native SDK documentation to request permission from native code:
-
    - [Android](https://github.com/klaviyo/klaviyo-android-sdk#collecting-push-tokens)
    - [iOS](https://github.com/klaviyo/klaviyo-swift-sdk?tab=readme-ov-file#request-push-notification-permission)
 

Troubleshooting.md

@@ -3,6 +3,7 @@
 ## Android Troubleshooting
 
 ### `minSdkVersion` Issues
+
 We have seen projects, particularly on react-native versions `0.72.x` and `0.71.x`, that required a `minSdkVersion`
 of `24`, despite the Klaviyo Android SDK supporting API 23+. If you encounter this, please file an issue in our
 repository and provide version numbers of your react-native dependencies.
@@ -13,7 +14,6 @@ repository and provide version numbers of your react-native dependencies.
 
 1. If you are seeing issues related to `minimum deployment target` when installing pods, you may need to update your
    minimum iOS version to 13.0 in your Podfile with one of the following strategies:
-
    - Specify iOS version directly in the `Podfile`:
      ```ruby
      MIN_IOS_OVERRIDE = '13.0'
@@ -24,6 +24,7 @@ repository and provide version numbers of your react-native dependencies.
      platform :ios, min_ios_version_supported
      ```
    - Set the deployment target to 13.0 in XCode, and then pull `IPHONEOS_DEPLOYMENT_TARGET` from the XCode project:
+
      ```ruby
      #######
      # Read min iOS version from Xcode project and set as min iOS version for Podfile
@@ -64,10 +65,8 @@ There are many workarounds suggested in this issue's thread and a few other simi
 However, the workaround that worked for us involves intercepting the launch arguments in the app delegate and adding
 a key `UIApplicationLaunchOptionsURLKey`, which React Native expects to be present when calling the `Linking.getInitialURL()` listener.
 
-
 Here's a method to implement this workaround:
 
-
 ```swift
 - (NSMutableDictionary *)getLaunchOptionsWithURL:(NSDictionary * _Nullable)launchOptions {
   NSMutableDictionary *launchOptionsWithURL = [NSMutableDictionary dictionaryWithDictionary:launchOptions];
@@ -88,7 +87,6 @@ Here's a method to implement this workaround:
 Ensure that this method is called from `application:didFinishLaunchingWithOptions:` before calling the superclass method with the
 modified launch arguments, like so:
 
-
 ```swift
 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
 {
@@ -108,7 +106,7 @@ This implementation is included in the example app in this repo and can be used
 Make sure to use the URL scheme (rntest://) of the example app when testing.
 
 ### iOS APNS Token Troubleshooting
+
 There is an open issue with [`@react-native-firebase/messaging`](https://github.com/invertase/react-native-firebase/issues/8022) where the SDK will uppercase any APNS token returned using `messaging().getAPNSToken()`.
 You can verify this by adding a log the `AppDelegate.m` file that prints the deviceToken (you will need to convert to a hex string).
 This might have no impact on your use case, but is something to consider when designing.
-

example/package.json

@@ -3,6 +3,7 @@
   "version": "0.3.1",
   "private": true,
   "scripts": {
+    "setup": "(yarn install --immutable && bundle install && cd ios && bundle exec pod install)",
     "android": "react-native run-android",
     "ios": "react-native run-ios",
     "start": "react-native start",