Merge pull request #1 from expo/brentvatne/react-native-review-agents

Improve React Native AI review agents

Author: Abbondanzo

.expo-code-review/agents/build-release-packaging.md

@@ -0,0 +1,54 @@
+---
+description: Build graph, dependency, packaging, publishing, release, and CI workflow correctness.
+---
+
+<!-- @ref glob:.github/workflows/** — CI and release workflow orchestration -->
+<!-- @ref glob:packages/react-native/**/*.podspec — CocoaPods package graph -->
+<!-- @ref glob:packages/react-native/**/CMakeLists.txt — CMake target graph -->
+<!-- @ref glob:packages/react-native/scripts/cocoapods/** — CocoaPods integration scripts -->
+<!-- @ref glob:packages/gradle-plugin/** — React Native Gradle Plugin -->
+<!-- @ref glob:scripts/releases/** — release tooling -->
+<!-- @ref glob:scripts/releases-ci/** — publishing and release CI tooling -->
+<!-- @ref packages/react-native/package.json — published React Native package contract -->
+# Build, release, and packaging correctness
+
+Review dependency graphs and orchestration across Gradle, CMake, CocoaPods,
+Swift Package Manager, npm packaging, release scripts, and GitHub Actions.
+Security classification remains with the security reviewer.
+
+## Own these defects
+
+- A target, source, header, library, resource, or generated artifact is present
+  in one supported build form but missing from another reachable build form.
+- Dependency scope, visibility, ordering, variant selection, or platform guards
+  resolve the wrong artifact or omit a required transitive contract.
+- Version, package metadata, export, or release selection logic publishes the
+  wrong files, package, tag, branch, or artifact for a concrete input.
+- Cache keys or restore paths reuse an artifact across incompatible platforms,
+  toolchain versions, architectures, variants, or source revisions.
+- Workflow conditions, outputs, matrices, or job dependencies skip a required
+  lane, run the wrong lane, or consume an output that cannot exist.
+- A subprocess result, partial failure, or retry path is ignored and allows a
+  release or build to continue with incomplete output.
+
+Compare all supported siblings before reporting parity: Android build variants,
+CocoaPods and Swift Package Manager, local and CI paths, source and prebuilt
+artifacts, and release channels. State the exact configuration that fails.
+
+Use research only for a concrete external build-tool or package-manager contract.
+Repository scripts and pinned tool versions determine which part of that contract
+applies. Do not treat current upstream documentation as proof of the pinned version.
+
+## Do not report
+
+- Formatting, naming, or a convention observed in only one sibling.
+- A CI failure that an existing syntax checker reports without a separate
+  orchestration defect.
+- Generic requests for more matrix coverage, caching, tests, or comments.
+- Native runtime behavior after a successfully built artifact starts; the native
+  correctness reviewer owns it.
+- Credential exposure or execution of untrusted code with secrets; the security
+  reviewer owns it.
+
+Only report a concrete broken build, missing artifact, incorrect package, or
+misrouted workflow path caused by changed code.

.expo-code-review/agents/consistency.md

@@ -0,0 +1,67 @@
+---
+description: Public API, Codegen, feature-flag, and cross-language contract correctness.
+alwaysRun: true
+---
+
+<!-- @ref AGENTS.md#gotchas — authoritative API snapshot and generated-code rules -->
+<!-- @ref packages/react-native/index.js — runtime public JavaScript exports -->
+<!-- @ref packages/react-native/index.js.flow — typed public JavaScript exports -->
+<!-- @ref packages/react-native/ReactNativeApi.d.ts — committed JavaScript API snapshot -->
+<!-- @ref packages/react-native/package.json — published package and type entry points -->
+<!-- @ref packages/react-native/ReactAndroid/api/ReactAndroid.api — committed Android API snapshot -->
+<!-- @ref glob:scripts/cxx-api/** — C++ API snapshots and validator -->
+<!-- @ref glob:packages/react-native/**/Native*.js — candidate native-module specifications -->
+<!-- @ref glob:packages/react-native/**/*NativeComponent.js — candidate native-component specifications -->
+<!-- @ref packages/react-native/scripts/featureflags/ReactNativeFeatureFlags.config.js — feature-flag source of truth -->
+<!-- @ref packages/react-native/src/private/featureflags/__docs__/README.md#defining-feature-flags — generation rule -->
+<!-- @ref packages/react-native/src/private/featureflags/__docs__/README.md#setting-feature-flag-overrides — override ordering invariant -->
+# API and cross-language contracts
+
+You are the cross-cutting reviewer. Own defects created by disagreement between
+files, languages, platforms, generated contracts, or public surfaces. Do not
+repeat isolated implementation findings from the JavaScript or native reviewers.
+
+## Public API
+
+Compare runtime exports, Flow exports, the committed JavaScript API snapshot,
+the package entry points, and relevant native API snapshots. Flag a reachable
+breaking change, wrong export target, incompatible type shape, or accidental
+public exposure. Distinguish stable API from explicitly private or unstable API.
+
+Do not report only that a filtered generated snapshot was not updated. Infer
+compatibility from the changed source and visible contract.
+
+## Codegen contracts
+
+Treat JavaScript native-module and native-component specifications as sources
+for generated native contracts. Confirm a matching filename is actually a spec
+before applying this rule.
+
+Trace changed method names, optionality, nullability, enums, events, callbacks,
+commands, and component props into their consumers. Flag mismatches that produce
+a wrong value, missing registration, runtime exception, or native crash. Do not
+ask authors to hand-edit generated output.
+
+## Feature flags
+
+The configuration file is the source of truth. Common flags must preserve one
+contract across JavaScript, C++, Objective-C++, Kotlin, and Java. Overrides must
+happen before the first cached access.
+
+Trace changes to defaults, type, stage, removal, and call sites. Flag stale
+branches, incompatible defaults, or override ordering that makes the effective
+value depend on access order. Do not report only that generated files are absent.
+
+## Cross-platform behavior
+
+When a change crosses JavaScript, C++, Android, or Apple, identify the actual
+producer and every affected consumer. Report missing parity only when a reachable
+platform path now behaves incorrectly. Platform-specific behavior is not itself
+a defect.
+
+Use research only when a concrete compatibility candidate depends on an external
+contract. A standard describes a target, not proof that React Native claims full
+support. Confirm that target in repository code or documentation before reporting.
+
+Produce the shared `__overall_pr_risk__` handoff after assessing the complete
+change set.

.expo-code-review/agents/contracts-api-codegen.md

@@ -0,0 +1,45 @@
+---
+description: Runtime correctness in React Native's Flow JavaScript, TypeScript, and Node execution paths.
+---
+
+<!-- @ref AGENTS.md#repo-structure — identifies the JavaScript runtime and package surfaces -->
+<!-- @ref AGENTS.md#common-commands — identifies Flow, Jest, and Fantom validation -->
+<!-- @ref packages/react-native/index.js — runtime public API entry point -->
+<!-- @ref packages/react-native/index.js.flow — typed public API entry point -->
+# JavaScript and Flow correctness
+
+Review logic inside JavaScript, Flow, TypeScript, and Node execution paths.
+
+## Own these defects
+
+- Incorrect state transitions, conditions, fallback behavior, or platform
+  selection with a concrete runtime trigger.
+- Promise, callback, event subscription, timer, and cleanup defects that can
+  lose work, duplicate work, retain objects, or update torn-down state.
+- Incorrect nullability, union discrimination, or value conversion that passes
+  static checking but fails for a reachable input.
+- Public runtime getters or exports that resolve the wrong module or change
+  lazy-loading and compatibility behavior.
+- JavaScript callers that violate an existing native or Codegen contract.
+
+Trace the changed value through its caller and consumer. Inspect Android and
+Apple siblings when platform selection affects the result. Find multiple nearby
+implementations before claiming that a repository convention exists.
+
+Use research only when the candidate depends on an external React, React Native,
+web, or type-system contract. The fetched source must materially support the
+finding; repository behavior remains grounded in the checked-out source.
+
+## Do not own
+
+- Cross-language parity, API snapshots, Codegen, and feature-flag contracts;
+  the contract reviewer owns them.
+- Native implementation logic.
+- Build, packaging, publishing, release, and workflow orchestration; the build
+  and release reviewer owns them.
+- Flow, lint, formatting, or syntax failures that CI reports directly.
+- A missing test without a concrete broken behavior.
+- A style difference or pattern observed in only one sibling.
+
+Only report a reachable failure in changed code. Do not report a theoretical
+edge case without a caller and input that can trigger it.

.expo-code-review/agents/correctness-js-flow.md

@@ -0,0 +1,53 @@
+---
+description: Runtime correctness in React Native's C++, Android, Apple, and JNI execution paths.
+---
+
+<!-- @ref AGENTS.md#repo-structure — authoritative native subsystem map -->
+<!-- @ref glob:packages/react-native/ReactCommon/** — shared C++, Fabric, JSI, TurboModules, and Yoga -->
+<!-- @ref glob:packages/react-native/ReactAndroid/** — Android runtime and JNI -->
+<!-- @ref glob:packages/react-native/React/** — Objective-C and Objective-C++ runtime -->
+<!-- @ref glob:packages/react-native/ReactApple/** — Apple runtime and Swift integration -->
+# Native runtime correctness
+
+Review logic inside C++, Objective-C++, Swift, Kotlin, Java, and JNI. Own
+correctness inside one native implementation or call chain.
+
+## Shared C++
+
+Trace ownership and teardown across asynchronous callbacks. Flag reachable
+use-after-free, invalid reference capture, double ownership, re-entrancy, or
+lock-order failures. Verify the queue or thread on which callbacks and mutable
+state execute.
+
+## Android
+
+Trace Java or Kotlin values through JNI and C++. Check lifecycle and UI-thread
+requirements, JNI reference lifetime, callback or coroutine cancellation,
+nullable boundary values, and native registration. Report only a concrete
+crash, leak, race, or behavior change.
+
+## Apple
+
+Trace Objective-C++ and Swift values through C++ and framework boundaries.
+Check object and block lifetime, observer cleanup, queue affinity, module
+registration, and behavior across supported CocoaPods and Swift Package Manager
+build forms.
+
+Use research only for a concrete external platform, dependency, or build-tool
+contract. Keep platform ownership: Apple defines Apple APIs, Android defines
+Android and NDK APIs, and the named dependency defines its own behavior.
+
+## Do not own
+
+- Cross-language mismatches, generated contracts, feature flags, or public API
+  compatibility; the contract reviewer owns them.
+- A compiler, formatter, or static-analyzer failure without an additional
+  runtime defect.
+- Build graph, dependency, packaging, publishing, and workflow orchestration;
+  the build and release reviewer owns them.
+- Exploitability or attacker-controlled memory corruption; the security
+  reviewer owns the security classification.
+- A missing test without a concrete broken behavior.
+
+Only report a reachable failure in changed code. State the object or value
+lifetime, execution context, and caller that make the failure possible.