chore: refactor agents.md

Author: mdjastrzebski

AGENTS.md

@@ -1,107 +1,20 @@
 # Code Assistant Context
 
-This document provides context for the any code assistant to understand the `@testing-library/react-native` project.
+`@testing-library/react-native` is a TypeScript/Jest library for testing React Native components with user-focused testing patterns.
 
-## Project Overview
-
-`@testing-library/react-native` (RNTL) provides a set of utilities for testing React Native components. It is designed to facilitate writing tests that resemble how users interact with the application, avoiding implementation details.
-
-- **Core Principle:** "The more your tests resemble the way your software is used, the more confidence they can give you."
-- **Tech Stack:** TypeScript, React Native, Jest.
-- **Architecture:** The library simulates the React Native runtime on top of `test-renderer`.
-
-## Project Guidelines
-
-- Small API surface
-- Expose all features of the underlying platform (react, react-reconciler) for Testing Libraries to use
-- Render host elements only, yet provide escape hatches to fibers when needed
-
-## Building and Running
-
-The project uses `yarn` for dependency management and script execution.
-
-- **Installation:** `yarn install`
-- **Run Tests:** `yarn test` (Runs Jest)
-- **Run Tests (CI):** `yarn test:ci` (Runs Jest with worker limits)
-- **Lint Code:** `yarn lint` (Runs ESLint on `src`)
-- **Type Check:** `yarn typecheck` (Runs TypeScript compiler)
-- **Format Check:** `yarn prettier`
-- **Validate All:** `yarn validate` (Runs Prettier, ESLint, Typecheck, and Tests in sequence)
-- **Build Project:** `yarn build` (Cleans, builds JS with Babel, and builds TS types)
-
-## Development Conventions
-
-- **Code Style:**
-  - **Linting:** ESLint is configured with `@callstack/eslint-config` and `typescript-eslint`. It enforces strict rules, including `no-console` and consistent type imports.
-  - **Formatting:** Prettier is used for code formatting (single quotes, trailing commas).
-  - **Imports:** Sorted using `eslint-plugin-simple-import-sort`.
-
-- **Testing:**
-  - **Framework:** Jest with `react-native` preset.
-  - **Location:** Tests are located within `src`, typically co-located in `__tests__` directories.
-  - **Setup:** `jest-setup.ts` configures the test environment. `src/index.ts` automatically configures cleanup after each test unless skipped.
-  - **Coverage:** Collected from `src`, excluding tests.
-  - **Organization:** Use `describe` to group test by theme. Avoid putting all tests in the same `describe` block. Avoid `describe` nesting. Avoid `describe` with only single test, make that test top-level. Prefere `test` over `it`.
-
-- **Commits & Releases:**
-  - **Commits:** Follow the **Conventional Commits** specification (e.g., `fix:`, `feat:`, `chore:`). This is enforced and used for changelog generation.
-  - **Releases:** Managed via `release-it`.
-
-- **File Structure:**
-  - `src/`: Source code.
-  - `src/pure.ts`: Core logic without side effects (no auto-cleanup).
-  - `src/index.ts`: Main entry point, re-exports `pure` and adds side effects (auto-cleanup).
-  - `examples/`: Example React Native applications using the library.
-  - `website/`: Documentation website.
-
-## Example App Regeneration
-
-- Prefer regenerating Expo example apps in a temporary directory and then copying the fresh scaffold into place, instead of mutating the existing app in place.
-- Before replacing an example app, move the current app directory to `/tmp` so repo-specific code, tests, assets, and configs can be restored selectively.
-- After copying a freshly generated app into `examples/`, remove the generated `.git` directory and generated `node_modules`, then reinstall from inside the repo workspace.
-
-- `examples/basic`:
-  - Generate from the Expo blank TypeScript scaffold:
-    - `yarn create expo-app /tmp/rntl-basic-fresh --template blank-typescript --yes`
-  - Restore the repo-specific sample app files on top of the new scaffold:
-    - `App.tsx`
-    - `components/`
-    - `__tests__/`
-    - `theme.ts`
-    - `jest.config.js`
-    - `jest-setup.ts`
-    - `babel.config.js`
-    - `eslint.config.mjs`
-    - `README.md`
-    - `.expo-shared/assets.json` if it existed before
-  - Keep the fresh Expo entrypoint (`index.ts`) and update `package.json` / `app.json` to match the repo naming and scripts.
-
-- `examples/cookbook`:
-  - Generate from a router-enabled Expo scaffold:
-    - `yarn create expo-app /tmp/rntl-cookbook-fresh --example with-router --yes`
-  - Restore the repo-specific cookbook files on top of the new scaffold:
-    - `app/`
-    - tutorial test directories such as `basics-tutorial/` and `basics-tutorial-react-strict-dom/`
-    - `theme.ts`
-    - `jest.config.js`
-    - `jest-setup.ts`
-    - `babel.config.js`
-    - `.eslintrc`, `.eslintignore`
-    - `README.md`
-    - custom assets not present in the scaffold, such as `assets/gradientRNBanner.png`
-    - `.expo-shared/assets.json` if it existed before
-  - Keep the fresh Expo Router entry setup, then reapply the cookbook-specific dependency set in `package.json` and `app.json`.
-
-- After regenerating either example app, validate from inside the app directory:
-  - `yarn expo install --check`
-  - `yarn lint`
+- Package manager: `yarn` (`yarn@4.11.0`)
+- Common commands:
+  - `yarn test`
+  - `yarn test:ci`
   - `yarn typecheck`
-  - `yarn test --watchman=false`
-
-- If the fresh scaffold introduces dependency-resolution churn, prefer restoring the previous `yarn.lock` first and then running `yarn install`, rather than re-resolving the whole dependency tree from scratch.
-
-## PR draft workflow:
-
-- Maintain `PR.txt` at the repository root using the structure from `.github/pull_request_template.md`.
-- Keep `PR.txt` aligned with the current branch diff relative to `origin/main`, including tests actually run and any known validation gaps.
-- Do not commit `PR.txt`.
+  - `yarn lint`
+  - `yarn prettier`
+  - `yarn build`
+  - `yarn validate`
+- Task-specific guidance:
+  - [Architecture and API design](docs/agents/architecture.md)
+  - [Build, validation, and repo layout](docs/agents/build-and-validation.md)
+  - [TypeScript and code style](docs/agents/code-style.md)
+  - [Testing conventions](docs/agents/testing.md)
+  - [Example app regeneration](docs/agents/example-apps.md)
+  - [Git, releases, and PR workflow](docs/agents/git-workflow.md)

docs/agents/architecture.md

@@ -0,0 +1,21 @@
+# Architecture And API Design
+
+## Project overview
+
+`@testing-library/react-native` provides utilities for testing React Native components in ways that resemble real usage and avoid implementation details.
+
+- Tech stack: TypeScript, React Native, Jest
+- Core principle: the closer tests are to real usage, the more confidence they provide
+- Runtime model: the library simulates the React Native runtime on top of `test-renderer`
+
+## API design principles
+
+- Prefer a small public API surface.
+- Expose underlying React and `react-reconciler` capabilities when Testing Libraries need them.
+- Render host elements only.
+- Provide escape hatches to fibers when needed.
+
+## Key entry points
+
+- `src/pure.ts`: side-effect-free core logic without auto-cleanup
+- `src/index.ts`: main entry point that re-exports `pure` and adds auto-cleanup side effects

docs/agents/build-and-validation.md

@@ -0,0 +1,27 @@
+# Build, Validation, And Repo Layout
+
+## Common commands
+
+- Install dependencies: `yarn install`
+- Run tests: `yarn test`
+- Run tests in CI mode: `yarn test:ci`
+- Type check: `yarn typecheck`
+- Lint source files: `yarn lint`
+- Check formatting: `yarn prettier`
+- Validate the main package: `yarn validate`
+- Build the package: `yarn build`
+
+## Command notes
+
+- `yarn lint` runs ESLint on `src`.
+- `yarn validate` runs typecheck, tests, lint, and Prettier checks for the main package.
+- `yarn build` cleans `build/`, transpiles source with Babel, and emits TypeScript declarations.
+
+## Repo layout
+
+- `src/`: source code
+- `src/pure.ts`: core logic without side effects
+- `src/index.ts`: main entry point with auto-cleanup side effects
+- `examples/`: example React Native apps
+- `website/`: documentation site
+- `codemods/`: codemod implementations and tests

docs/agents/code-style.md

@@ -0,0 +1,12 @@
+# TypeScript And Code Style
+
+## Linting and formatting
+
+- ESLint uses `@callstack/eslint-config` together with `typescript-eslint`.
+- Important enforced rules include `no-console` and consistent type imports.
+- Prettier is the formatter.
+- Formatting defaults include single quotes and trailing commas.
+
+## Imports
+
+- Keep imports sorted with `eslint-plugin-simple-import-sort`.

docs/agents/example-apps.md

@@ -0,0 +1,56 @@
+# Example App Regeneration
+
+## General workflow
+
+- Regenerate Expo example apps in a temporary directory, then copy the fresh scaffold into place.
+- Before replacing an example app, move the current app directory to `/tmp` so repo-specific files can be restored selectively.
+- After copying a generated app into `examples/`, remove the generated `.git` directory and `node_modules`, then reinstall from inside the repo workspace.
+
+## `examples/basic`
+
+- Generate from the Expo blank TypeScript template:
+  - `yarn create expo-app /tmp/rntl-basic-fresh --template blank-typescript --yes`
+- Restore these repo-specific files on top of the fresh scaffold:
+  - `App.tsx`
+  - `components/`
+  - `__tests__/`
+  - `theme.ts`
+  - `jest.config.js`
+  - `jest-setup.ts`
+  - `babel.config.js`
+  - `eslint.config.mjs`
+  - `README.md`
+  - `.expo-shared/assets.json` if it existed before
+- Keep the fresh Expo entrypoint `index.ts`.
+- Update `package.json` and `app.json` to match repo naming and scripts.
+
+## `examples/cookbook`
+
+- Generate from a router-enabled Expo scaffold:
+  - `yarn create expo-app /tmp/rntl-cookbook-fresh --example with-router --yes`
+- Restore these repo-specific files on top of the fresh scaffold:
+  - `app/`
+  - tutorial test directories such as `basics-tutorial/` and `basics-tutorial-react-strict-dom/`
+  - `theme.ts`
+  - `jest.config.js`
+  - `jest-setup.ts`
+  - `babel.config.js`
+  - `.eslintrc`
+  - `.eslintignore`
+  - `README.md`
+  - custom assets not present in the scaffold, such as `assets/gradientRNBanner.png`
+  - `.expo-shared/assets.json` if it existed before
+- Keep the fresh Expo Router entry setup.
+- Reapply the cookbook-specific dependency set in `package.json` and `app.json`.
+
+## Validation after regeneration
+
+- Run these commands from inside the regenerated app directory:
+  - `yarn expo install --check`
+  - `yarn lint`
+  - `yarn typecheck`
+  - `yarn test --watchman=false`
+
+## Lockfile guidance
+
+- If the fresh scaffold causes dependency-resolution churn, restore the previous `yarn.lock` first and then run `yarn install` instead of re-resolving the full tree.

docs/agents/git-workflow.md

@@ -0,0 +1,13 @@
+# Git, Releases, And PR Workflow
+
+## Commits and releases
+
+- Use Conventional Commits such as `fix:`, `feat:`, and `chore:`.
+- Releases are managed with `release-it`.
+
+## PR draft workflow
+
+- Maintain `PR.txt` at the repository root using the structure from `.github/pull_request_template.md`.
+- Keep `PR.txt` aligned with the current branch diff relative to `origin/main`.
+- Include tests actually run and any known validation gaps in `PR.txt`.
+- Do not commit `PR.txt`.

docs/agents/testing.md

@@ -0,0 +1,20 @@
+# Testing Conventions
+
+## Test stack
+
+- Test framework: Jest with the `react-native` preset
+- Test environment setup: `jest-setup.ts`
+- Auto-cleanup is configured from `src/index.ts` unless explicitly skipped
+
+## Test location and coverage
+
+- Library tests are typically colocated under `src/**/__tests__`
+- Coverage is collected from `src` and excludes test files
+
+## Test organization
+
+- Use `describe` blocks to group tests by theme.
+- Do not put all tests into a single `describe`.
+- Avoid nested `describe` blocks.
+- If a `describe` would contain only one test, make that test top-level instead.
+- Prefer `test` over `it`.