Skip to content

jcuervo/rn-builder

BranchesTags

Repository files navigation

RN Builder — React Native Agent + Skills

A menu-driven Claude Code agent for building, testing, and shipping production React Native apps for iOS and Android. Expo-first. For each unsettled stack concern, the agent presents 2–5 vetted alternatives via AskUserQuestion and implements whichever the user picks. Delegates performance work to Callstack's react-native-best-practices skill.

What's in the box

rn-builder/
├── agent/
│   └── rn-builder.md                           # Agent definition
└── skills/
    ├── rn-scaffold-expo/                       # Menu orchestrator + per-concern menus
    │   ├── SKILL.md
    │   └── references/
    │       ├── new-project-setup.md              # Orchestrates all menus end-to-end
    │       ├── typescript-config.md              # Fixed: TS strict (no menu)
    │       ├── folder-architecture.md            # Fixed: src/ layout (no menu)
    │       ├── stack-navigation.md               # Menu: Expo Router, React Navigation
    │       ├── stack-state.md                    # Menu: Zustand, Jotai, RTK, Legend State
    │       ├── stack-data.md                     # Menu: TanStack Query, SWR, Apollo, RTK Query
    │       ├── stack-styling.md                  # Menu: NativeWind, Unistyles 3, Tamagui, StyleSheet, Restyle
    │       ├── stack-storage.md                  # Menu: MMKV, expo-sqlite+Drizzle, WatermelonDB, Op-SQLite, AsyncStorage (+ fixed expo-secure-store for secrets)
    │       ├── stack-forms.md                    # Menu: RHF+Zod, Formik+Yup, TanStack Form
    │       ├── stack-lists.md                    # Menu: FlashList, FlatList, LegendList
    │       ├── stack-animations.md               # Menu: Reanimated 4+Gesture Handler, LayoutAnimation, Lottie
    │       ├── stack-auth.md                     # Menu: Clerk, Supabase, Auth0, Better Auth, Firebase
    │       └── stack-observability.md            # Menu: Sentry+PostHog, Crashlytics+FB Analytics, Bugsnag+Mixpanel, LogRocket
    ├── rn-testing/                             # Jest + RNTL + Maestro + CI (fixed picks)
    │   ├── SKILL.md
    │   └── references/
    │       ├── jest-rntl-setup.md
    │       ├── component-test-patterns.md
    │       ├── maestro-e2e-setup.md
    │       ├── mocking-native-modules.md
    │       └── ci-test-matrix.md
    ├── rn-release-eas/                         # EAS Build + Submit + Update + signing (fixed picks)
    │   ├── SKILL.md
    │   └── references/
    │       ├── eas-build-profiles.md
    │       ├── eas-submit-stores.md
    │       ├── eas-update-ota.md
    │       ├── ios-signing-credentials.md
    │       ├── android-signing-credentials.md
    │       └── store-metadata-checklist.md
    ├── rn-native-modules/                      # Bridging native code
    │   ├── SKILL.md
    │   └── references/
    │       ├── expo-modules-api-first.md
    │       ├── turbo-module-ios.md
    │       ├── turbo-module-android.md
    │       └── prebuild-config-plugins.md
    ├── rn-security-audit/                      # Mobile-specific security audit (opt-in)
    │   ├── SKILL.md
    │   └── references/
    │       ├── bundle-secrets.md                 # JS bundle secret scan (trufflehog + grep)
    │       ├── secure-storage.md                 # Tokens / PII in the right storage tier
    │       ├── deep-links.md                     # Deep link & universal link hijack audit
    │       ├── webview-hardening.md              # react-native-webview safe defaults
    │       ├── native-permissions.md             # app.json plugin & permission scope audit
    │       ├── masvs-checklist.md                # OWASP MASVS L1 pre-submission pass
    │       └── security-md-template.md           # SECURITY.md template + accepted-risks/CVE-suppression registry
    └── rn-dependency-audit/                    # Supply chain & dep CVE audit (opt-in)
        ├── SKILL.md
        └── references/
            ├── cve-triage.md                     # npm audit + osv-scanner triage
            ├── license-compliance.md             # GPL/AGPL/SSPL scan + attribution screen
            ├── lockfile-integrity.md             # Lockfile drift, typosquats, registry tampering
            ├── native-module-vetting.md          # Pre-install vetting for native modules
            └── ci-integration.md                 # Wiring all audits into CI + EAS hooks

How the menu mode works

User: "Set up a new Expo app for X"
        │
        ▼
Agent reads rn-scaffold-expo/references/new-project-setup.md
        │
        ▼
Step 1: Create project shell           (no menu — npx create-expo-app)
Step 2: TypeScript strict              (no menu — typescript-config.md)
Step 3: Folder architecture            (no menu — folder-architecture.md)
Step 4: Present menus in batches via AskUserQuestion:
        │
        ├── Batch 1 (≤4 questions): Navigation, State, Server data, Styling
        ├── Batch 2 (≤4 questions): Storage, Forms, Lists, Animations
        └── Batch 3 (≤4 questions): Auth, Observability
        │
        ▼
Step 5: Install picked packages via npx expo install (composed from picks)
Step 6: Wire each pick using its reference file's Quick Pattern
Step 7: Smoke test (tsc, lint, expo start, iOS/Android boot)
Step 8: Write picks to STACK.md so future runs read instead of re-asking

For ongoing feature work (not scaffolding), the agent reads package.json first and short-circuits any menu where a vetted package is already installed.

Per-concern menus (recommended option in bold)

Concern Options
Navigation Expo Router, React Navigation
State (client) Zustand, Jotai, Redux Toolkit, Legend State
Server data TanStack Query v5, SWR, Apollo Client, RTK Query
Styling NativeWind v4, Unistyles 3, Tamagui, StyleSheet, Restyle
Storage (general) MMKV, expo-sqlite + Drizzle, WatermelonDB, Op-SQLite, AsyncStorage
Storage (secrets) expo-secure-store (fixed, no menu)
Forms React Hook Form + Zod, Formik + Yup, TanStack Form
Lists FlashList v2, FlatList, LegendList
Animations Reanimated 4 + Gesture Handler, LayoutAnimation, Lottie
Auth Clerk Expo, Supabase Auth, Auth0, Better Auth, Firebase Auth
Observability Sentry + PostHog, Crashlytics + Firebase Analytics, Bugsnag + Mixpanel, LogRocket

"Recommended" means: when the user has no preference, this is the agent's suggested pick — labeled "(Recommended)" in the menu. The agent still presents the full menu; it does not silently default.

Fixed picks (no menu)

Concern Pick Why no menu
Language TypeScript (strict) Plain JS is never right in 2026
Framework Expo SDK + EAS Bare RN is a fallback, not a peer
Secrets storage expo-secure-store Tokens go nowhere else
Testing (unit) Jest + RNTL See rn-testing/SKILL.md
Testing (E2E) Maestro See rn-testing/SKILL.md
CI / build / ship EAS Build/Submit/Update See rn-release-eas/SKILL.md

Installation

Prerequisites

  • Claude Code installed (CLI, desktop, or IDE extension — any will work)
  • Git available on your $PATH
  • A ~/.claude/ directory (Claude Code creates this on first run)

Install scope — pick one

Scope Install location When to use
Global (recommended) ~/.claude/agents/ and ~/.claude/skills/ The agent is available in every project on your machine. Best for personal use.
Project-local <your-project>/.claude/agents/ and <your-project>/.claude/skills/ The agent ships with one specific project, version-controlled alongside it. Best for teams who want every contributor to use the same agent without each installing it.

The install steps below are identical aside from the destination path.

Option 1 — Global install (one-liner)

For macOS / Linux:

# Clone to a temp location, copy into ~/.claude/, clean up
TMP=$(mktemp -d) && \
  git clone --depth 1 https://github.com/jcuervo/rn-builder.git "$TMP" && \
  mkdir -p ~/.claude/agents/engineering ~/.claude/skills && \
  cp "$TMP/agent/rn-builder.md" ~/.claude/agents/engineering/ && \
  cp -R "$TMP/skills/"* ~/.claude/skills/ && \
  rm -rf "$TMP" && \
  echo "RN Builder installed. Restart Claude Code to pick it up."

For Windows (PowerShell):

$tmp = New-Item -ItemType Directory -Path (Join-Path $env:TEMP ([guid]::NewGuid()))
git clone --depth 1 https://github.com/jcuervo/rn-builder.git $tmp.FullName
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\agents\engineering" | Out-Null
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item "$($tmp.FullName)\agent\rn-builder.md" "$env:USERPROFILE\.claude\agents\engineering\"
Copy-Item "$($tmp.FullName)\skills\*" "$env:USERPROFILE\.claude\skills\" -Recurse
Remove-Item $tmp.FullName -Recurse -Force
Write-Host "RN Builder installed. Restart Claude Code to pick it up."

Option 1 — Global install (step by step)

If you'd rather not run a one-liner:

# 1. Clone the repo somewhere convenient
git clone https://github.com/jcuervo/rn-builder.git
cd rn-builder

# 2. Install the agent
mkdir -p ~/.claude/agents/engineering
cp agent/rn-builder.md ~/.claude/agents/engineering/

# 3. Install the core skills (always recommended)
mkdir -p ~/.claude/skills
cp -R skills/rn-scaffold-expo ~/.claude/skills/
cp -R skills/rn-testing ~/.claude/skills/
cp -R skills/rn-release-eas ~/.claude/skills/
cp -R skills/rn-native-modules ~/.claude/skills/

# 4. Install the optional audit skills (recommended — they're opt-in, see below)
cp -R skills/rn-security-audit ~/.claude/skills/
cp -R skills/rn-dependency-audit ~/.claude/skills/

Option 2 — Project-local install

Run from inside your existing React Native project root:

# 1. Clone into a temp dir
TMP=$(mktemp -d) && \
  git clone --depth 1 https://github.com/jcuervo/rn-builder.git "$TMP"

# 2. Copy into the project's .claude/ directory
mkdir -p .claude/agents/engineering .claude/skills
cp "$TMP/agent/rn-builder.md" .claude/agents/engineering/
cp -R "$TMP/skills/"* .claude/skills/

# 3. Clean up
rm -rf "$TMP"

# 4. Commit so the rest of your team gets it for free
git add .claude/agents .claude/skills
git commit -m "Add RN Builder agent + skills"

Project-local installs override global installs of the same name. If a contributor has a global rn-builder and the project ships a different version, the project's wins.

Option 3 — Git submodule (advanced)

If you want updates to flow automatically when you git pull:

cd your-rn-project
git submodule add https://github.com/jcuervo/rn-builder.git .claude/rn-builder
git submodule update --init --recursive

# Then symlink agent + skills into the locations Claude Code expects
ln -s ../rn-builder/agent/rn-builder.md .claude/agents/rn-builder.md
for skill in .claude/rn-builder/skills/*/; do
  ln -s "../rn-builder/skills/$(basename $skill)" ".claude/skills/$(basename $skill)"
done

To update: git submodule update --remote .claude/rn-builder.

Verify the install

After installing, start a Claude Code session and check that the agent loaded:

# From any directory:
claude --list-agents | grep -i "RN Builder"

# Confirm the skills are visible:
ls ~/.claude/skills/ | grep -E "rn-(scaffold|testing|release|native|security|dependency)"

You should see RN Builder in the agents list and six rn-* skills in the skills directory.

Quick functional smoke test — open Claude Code in any directory and prompt:

Using the RN Builder agent, what menu options exist for client state?

If the agent answers with the curated menu from stack-state.md (Zustand, Jotai, Redux Toolkit, Legend State), the install is good.

Updating

# Pull the latest and re-copy
cd <where-you-cloned-rn-builder>
git pull
cp agent/rn-builder.md ~/.claude/agents/engineering/
cp -R skills/* ~/.claude/skills/

Project-local installs: re-run the project-local install commands. Submodule installs: git submodule update --remote.

This repo follows semver in spirit — breaking changes to the agent's menu structure or skill triggers will be called out in release notes. Reference files (the procedural content) are updated freely.

Uninstall

rm ~/.claude/agents/engineering/rn-builder.md
rm -rf ~/.claude/skills/rn-{scaffold-expo,testing,release-eas,native-modules,security-audit,dependency-audit}

Optional skills note

rn-security-audit and rn-dependency-audit are opt-in audit skills with tight triggers — they only activate when the user explicitly asks for a security audit, dependency triage, store-submission check, or responds to a vulnerability disclosure. They do not fire during routine feature work, so installing them has near-zero context cost.

For broader application security (backend, IAM, network), pair this agent with the Security Engineer agent.

Using the agent

Once installed, you can invoke it three ways:

  1. Automatic — Claude Code routes React Native / Expo questions to RN Builder by reading its description. Just describe what you want ("set up a new Expo app for a fitness tracker").
  2. Explicit by name — "Use the RN Builder agent to set up a new Expo project."
  3. In a multi-agent workflow — from another agent, via the Agent tool with subagent_type: "RN Builder".

The agent will detect existing stack picks from package.json before presenting menus, so you can run it against an existing project without it re-asking what you already use.

Verification baseline

Every task this agent owns has the same verification floor:

  1. npx tsc --noEmit passes.
  2. npx expo lint passes.
  3. Relevant tests pass.
  4. App boots and the change is observable on at least one platform (preferably both).
  5. For new scaffolds: picks recorded in STACK.md at project root.

If you can't run the app, the agent says so explicitly — it does not claim success.

Related skills (delegated, not duplicated)

Skill Owns
react-native-best-practices (Callstack) Performance — FPS, TTI, bundle size, memory, native profiling
react-native-best-practices/agents/brownfield-migration Embedding RN into existing native iOS/Android apps
upgrading-react-native RN/Expo version bumps via rn-diff-purge
github-actions iOS simulator + Android emulator cloud builds
Security Engineer agent Backend / API / IAM / network security beyond the mobile client
Compliance Auditor agent HIPAA / PCI / SOC 2 / ISO 27001 controls and evidence

This agent never re-implements what another skill owns.

License

MIT. Reference content draws on public Expo, React Native, Sentry, and other vendor documentation.

Status

Build complete in menu mode. Each per-concern reference file documents its options in depth — install commands, Quick Patterns, When to Pick / Not to Pick, Deep Dives, and Common Pitfalls.

To add a new alternative to any menu: add the option to the matching stack-*.md reference file (full per-option section) and add the row to the menu table. The agent reads the file fresh on every triage, so updates take effect immediately.

About

Expo-first React Native specialist for shipping production iOS + Android apps

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors