React Native Agent Kit

Project-owned instructions, Skills, specifications, and safe workflows for Codex and Claude in React Native repositories.

npm package: @monavi/react-native-agent-kit Release channel: Stable

React Native Agent Kit helps AI coding agents understand the project before they change it. The application repository remains the source of truth: active code, configuration, product specifications, and approved design references take priority over bundled examples.

What it adds

• Shared instructions for Codex and Claude
• Eleven focused Agent Skills
• Project specification and screen catalog
• Design reference and architecture documents
• Implementation plan, status, decisions, and verification notes
• Project-local ./agent and ./agent-kit commands
• Validation, audit, backup, update, and conflict-handling tools
• Optional minimal and scalable source scaffolds for new projects

Agent Kit does not force a navigation, state, networking, forms, storage, or UI library stack.

Installation

Install the package from the root of a React Native project:

npm install -D @monavi/react-native-agent-kit

Then choose the workflow that matches your project.

Existing React Native project

Preview adoption first:

npx rn-agent adopt . --dry-run

Apply it and validate the installation:

npx rn-agent adopt .
npx rn-agent check

Adoption preserves existing application source, Agent instructions, Skills, and project documentation. When an incoming Kit file conflicts with a project-owned file, the project copy is kept and the new candidate is written under:

.agent-kit-incoming/<version>/

Use adopt for projects that already contain application code. Do not use --force for routine adoption.

New or nearly empty project

Initialize only the Agent context:

npx rn-agent init . --yes

Initialize the Agent context and add a neutral scalable source foundation:

npx rn-agent init . --yes --scaffold scalable --apply-entry

Preview before changing files:

npx rn-agent init . --yes --scaffold scalable --apply-entry --dry-run

With --apply-entry, Agent Kit backs up the existing root App.* file and connects it to src/app/AppRoot.tsx.

Natural-language workflow

After installation, describe a task directly:

npx rn-agent "Create a login screen"
npx rn-agent "Connect the products API"
npx rn-agent "Redesign the product screen from Figma"
npx rn-agent "Fix the double submit bug"
npx rn-agent "Verify the current diff"

The CLI selects a matching Skill and creates a grounded prompt for Codex or Claude. Natural-language mode does not modify application source by itself.

For an ambiguous request, select the workflow explicitly:

npx rn-agent ask "Handle the reported save problem" --workflow bug

Supported workflows:

bootstrap, scaffold, inspect, feature, screen, design, api,
bug, refactor, verify, context

Natural-language routing and distributable package prompts are English-only.

Project-local commands

Initialization or adoption installs local helper commands:

./agent
./agent next
./agent check
./agent audit
./agent status
./agent help

On Windows:

agent.cmd
agent.cmd next
agent.cmd check

The npm binary aliases below run the same CLI:

rn-agent
rn-agent-kit
react-native-agent-kit

Source scaffolds

Scaffolding is optional and runs only when requested explicitly.

./agent scaffold . --profile minimal --dry-run
./agent scaffold . --profile scalable --apply-entry

minimal

Creates a small compiling foundation with:

• App root
• Representative screen
• UI primitive
• Theme tokens
• HTTP boundary
• Shared type
• Utility

scalable

Includes the minimal foundation plus neutral ownership boundaries for:

• Providers and startup
• Authentication
• App, feedback, form, and UI components
• Domain logic
• Errors and forms
• Hooks
• Native adapters
• Navigation
• State
• Storage

The scaffolds do not automatically install third-party packages or copy an ecommerce business domain.

See docs/agent/references/PROJECT_STRUCTURE_BLUEPRINTS.md.

Design and Figma workflow

Use the design workflow for approved Figma frames or screenshots:

npx rn-agent ask "Redesign the checkout screen from the approved Figma frame" --workflow design

Agent Kit separates:

• Visual truth: approved design references
• Behavioral truth: active code and PROJECT_SPEC.md

Navigation, validation, permissions, data flow, and side effects must remain grounded in the project rather than inferred from visuals.

Project-specific design sources are recorded in:

docs/agent/DESIGN_REFERENCE.md
docs/agent/SCREEN_CATALOG.md

Project audit

Run a structural audit when reviewing project readiness:

./agent audit
./agent audit --strict

The audit checks areas such as:

• Relative imports
• Declared dependencies
• Selected scaffold completeness
• App-entry integration
• Route and screen-catalog parity
• Documented component paths
• Design and architecture initialization
• Documented npm scripts
• Multiple lockfiles
• Floating dependency versions
• Common React Navigation companion packages
• Runtime packages placed only in development dependencies

Audit output still requires review. Static analysis does not prove runtime behavior.

Package selection guidance

Agent Kit provides package candidates and decision rules in:

docs/agent/references/DEPENDENCIES_AND_PACKAGES.md

It covers common React Native areas including:

• Navigation, including react-native-screens and react-native-safe-area-context
• Shared state
• Networking
• Forms and validation, including react-hook-form, zod, and @hookform/resolvers
• Persistence
• Testing
• Babel, Metro, TypeScript, ESLint, and CLI setup

Before proposing installation, the Agent must inspect the current project type, React Native version, package.json, lockfile, native configuration, existing architecture, peer dependencies, and verification commands.

The Kit does not install every candidate automatically and must not select floating latest versions without compatibility checks.

Updating Agent Kit

Install the latest package:

npm install -D @monavi/react-native-agent-kit

Preview the update:

npx rn-agent update . --dry-run

Apply and validate it:

npx rn-agent update .
npx rn-agent check

The updater preserves project-owned files such as:

• AGENTS.md and CLAUDE.md
• docs/agent/PROJECT_SPEC.md
• Screen catalog and design reference
• Project profile and architecture map
• Implementation plan and status
• Verification notes and decisions
• Customized Skills

Replaced Kit-managed files are backed up under .agent-kit-backups/. Conflicting upstream candidates are placed under .agent-kit-incoming/ for review.

See UPGRADE_NOTES.md for the complete update process.

Command reference

rn-agent init [target] [options]
rn-agent adopt [target] [options]
rn-agent update [target] [options]
rn-agent scaffold [target] [--profile minimal|scalable] [options]
rn-agent spec [target] [options]
rn-agent doctor [target]
rn-agent audit [target] [--strict]
rn-agent status [target]
rn-agent next [target] [--copy|--no-copy]
rn-agent ask <task> [--workflow <type>] [--no-copy]
rn-agent prompt <workflow> [--copy]
rn-agent sync [target]

Validation

For package development or before creating a release:

npm install
npm run check
npm pack --dry-run

Maintainer release

Stable releases are published through GitHub Actions Trusted Publishing using the latest dist-tag.

Do not run npm publish locally after Trusted Publishing has been configured.

The stable workflow publishes with:

npm publish --access public --tag latest

Prereleases, when intentionally prepared, must use the beta dist-tag. Do not publish a prerelease with the default latest tag.

Safety principles

• Treat PROJECT_SPEC.md as approved product truth.
• Do not invent APIs, credentials, dependencies, permissions, calculations, or business rules.
• Inspect the active project before changing architecture or adding libraries.
• Implement one controlled vertical slice at a time.
• Run real verification commands.
• Separate passed, failed, and unverified results.
• Treat bundled domain examples as references only.