Mobile Documentation

Everything you need to set up and use Archie Mobile for React Native development.

Overview

Archie Mobile is a structured workflow framework designed specifically for React Native development teams. It provides your AI coding agent with persistent memory adapted to mobile development, role-based skills that understand platform-specific concerns, and approval gates that keep you in control of architectural decisions.

While Archie works for any codebase, Archie Mobile specializes in React Native projects. It understands screen hierarchies, native modules, platform-specific files (.ios.tsx, .android.tsx), Expo workflows, and mobile-specific challenges like performance, offline support, and deep linking.

Compatibility: Works with Claude Code and React Native projects (Expo recommended). Supports bare workflow and custom native code. VCS: GitHub, GitLab, Bitbucket.

Setup

Option A — Automated (recommended)

Copy Archie Mobile into your project root, open Claude Code, and run:

/setup

The setup skill guides you through mobile project bootstrapping. It asks about your workflow (Expo vs bare), navigation library, state management, target platforms (iOS/Android), and app store configurations. Then it populates archie.config.json and all memory files with mobile-aware defaults.

Setup Questions

Expo or bare workflow?

Expo (recommended) or bare React Native with custom native code.

Navigation library

React Navigation (standard) or other routing solution.

State management

Zustand, Redux, Context API, or none.

Target platforms

iOS only, Android only, or both.

Option B — Manual

1. Copy the files

cp -r archie-mobile/. your-rn-project/

2. Edit archie.config.json

Fill in your app name, services, platforms (ios, android, shared), and VCS platform.

3. Fill in memory files

Read files in memory/project-context/ and replace prompts with your mobile project details.

4. Verify

Run /status to confirm everything is connected.

Memory System

Archie Mobile maintains a mobile-focused memory system. All persistent context lives in memory/ and is pre-populated with React Native patterns.

memory/MEMORY.md

Project index — read first every session. Mobile-aware entry point.

memory/project-context/architecture.md

Screen hierarchy, navigation flow, native module boundaries, platform-specific decisions.

memory/project-context/tech-stack.md

React Native version, Expo SDK, React Navigation, state library, testing framework.

memory/project-context/development-setup.md

How to run locally (Expo dev server, simulators), build for iOS/Android, EAS Build setup.

memory/patterns/code-patterns.md

Component patterns, hook patterns, styling (StyleSheet, NativeWind, etc), navigation typing, API layer.

memory/decisions/ADRs.md

Architecture decisions — why Expo vs bare, navigation choices, state management, offline strategy.

memory/features/epic-backlog.md

Feature pipeline — ideas, active epics, completed features. Mobile-specific scope.

memory/backlog/tasks.md

Task queue tagged by platform (ios, android, shared). Dev agents work per-platform or cross-platform.

memory/debugging-insights/known-issues.md

Known bugs, platform gotchas (iOS vs Android differences), simulator issues, build errors.

memory/mobile-app/MEMORY.md

Main app service context — entry points, screen files, key dependencies.

Size limit: Each memory file must stay under 300 lines. Split into sub-files if approaching the limit.

Skills Reference

/setup— Bootstrap a mobile project

When to use: First time using Archie Mobile. Asks about Expo, navigation, state management, platforms, and app store details.

Output: archie.config.json + all memory files with mobile defaults.

/status— Quick project overview

When to use: Any time — to see build status, active features, task queue, platform coverage, and suggested next action.

Output: Read-only summary including iOS/Android build health. Doesn't modify files.

/standup— Generate a standup report

When to use: Start of day or before a sync. Shows done, in-progress, blocked, and up next — including build/deploy status.

Output: Formatted standup report with task statuses, MR links, blockers, crash rates, and build health.

/architect— Design a feature

When to use: You have a feature idea (especially L/XL) and want to design it before coding. Considers deep linking, push notifications, offline support.

Output: Epic entry in epic-backlog.md with component flow, data model, platform-specific concerns, and risk analysis.

/tech-lead— Break an epic into tasks

When to use: An approved epic exists and you want implementable task breakdown tagged by platform.

Output: Story + task breakdown. Tasks tagged ios/android/shared. Auto-injected into backlog on approval.

/quick— Fast-track for S/M features

When to use: Small or medium feature that doesn't need full architecture review. Touches one or two screens.

Output: Epic + task breakdown + backlog injection — all in one pass with one approval gate.

/dev-agent— Implement one task (in isolated worktree)

When to use: Tasks are in the backlog. Handles both shared code and platform-specific files (.ios.tsx, .android.tsx).

Output: Isolated worktree, implementation, tests, commit, and MR. Lock released. Backlog updated.

Pro

Quality & Review Skills

/security-review— Mobile security audit

When to use: Before app store submission or after major changes. Audits secure storage, biometric auth, deep link injection, certificate pinning, exported components, debug flags in production.

Output: Security findings by severity (Critical → Low) specific to mobile threats. Injects findings into backlog as prioritized tasks.

/code-review— Mobile code quality review

When to use: After a PR or sprint. Reviews for unnecessary re-renders, bridge overhead, large list performance, image optimization, memory leaks, and platform-specific code quality.

Output: Review categorized as Must Fix / Should Fix / Consider. Optionally injects items into backlog.

/test-plan— Mobile test planning

When to use: Before implementing tests. Plans unit tests (Jest), component tests (RNTL), E2E tests (Detox/Maestro), and platform-specific test matrix.

Output: Prioritized test matrix (P0/P1/P2) covering unit, component, integration, E2E, and platform-specific scenarios. Injects [test] tasks into backlog.

/retro— Sprint retrospective

When to use: End of sprint or milestone. Analyzes git history, task completion, build times, crash rates, app store metrics, and agent performance.

Output: Evidence-based retrospective with velocity, quality metrics, platform differences, and action items. Injects improvement tasks into backlog.

Workflows

Full Workflow (L/XL features)

/architect  →  approve  →  /tech-lead  →  approve  →  /dev-agent
  design         ✓          break down      ✓          implement

Fast-Track (S/M features)

/quick  →  approve  →  /dev-agent
  design + tasks   ✓     implement

When to use which

Full workflow — feature spans multiple screens, requires native modules, API changes, or significant state management refactor.

Fast-track — single screen feature, no native code, isolated state changes. If /quick detects complexity, it redirects to /architect.

Skip to backlog — for bug fixes and small improvements, add tasks directly to memory/backlog/tasks.md and run /dev-agent.

Platform tagging: Tasks can be tagged ios, android, or shared. Dev agents respect these tags and only pick up tasks for their assigned platform.

Mobile-Specific Patterns

Archie Mobile's memory/patterns/code-patterns.md covers React Native best practices specific to your project.

Screen Component Structure

How to organize screen files, hook patterns, navigation params, and performance considerations.

Custom Hooks

Shared hook patterns for data fetching, state management, device info, permissions, and offline support.

Navigation Typing

Type-safe navigation with React Navigation, route params, deep linking conventions.

API Layer & Offline

HTTP client setup, request/response interceptors, retry logic, offline queue, data sync patterns.

Platform-Specific Code

Using Platform.select(), .ios.tsx/.android.tsx files, native modules, conditional logic.

Styling

StyleSheet vs styled-components vs NativeWind. Responsive design, dark mode, spacing scale.

Build & Deploy

Archie Mobile integrates with your build and deployment pipeline.

Local Development

Expo projects: npx expo start for development server, connects to iOS Simulator and Android Emulator.

Bare workflow: npm run ios / npm run android for simulators, Xcode/Android Studio for native development.

Testing locally: npm test (unit/component tests), simulator testing before builds.

EAS Build (Expo projects)

Configuration: eas.json defines build profiles (development, preview, production) for iOS and Android.

Building: eas build --platform ios --profile production for app store builds.

Signing: EAS handles provisioning profiles, signing certificates, and app store credentials.

App Store Submission

iOS (App Store): eas submit --platform ios or manual submission via App Store Connect.

Android (Google Play): eas submit --platform android or manual upload to Google Play Console.

Pre-submission: Run /security-review before submitting to catch mobile security issues.

Platform Differences

iOS and Android have different UI conventions, capabilities, and constraints. Archie Mobile helps manage these differences.

Design & Navigation

iOS uses tab bars and back buttons. Android prefers hamburger menus. Use platform-specific navigation in React Navigation configs.

Safe Area & Insets

iOS has notches. Android has navigation bars. Use useSafeAreaInsets() to adapt layouts.

Permissions

iOS requires user prompts. Android has runtime permissions. Handle both with react-native-permissions.

Back Button Behavior

iOS has swipe-back gestures. Android has hardware back button. Use React Navigation's useIsFocused() and useFocusEffect().

Deep Linking

Universal Links (iOS) vs App Links (Android). Configure both in Archie Mobile setup and linking config.

Testing

Test on real devices when possible. Simulator behavior differs from production. Use Detox for cross-platform E2E tests.

VCS Integration

Set vcs.platform and vcs.cli in archie.config.json:

Platform	CLI	Term	Create
GitHub	`gh`	pull request	`gh pr create`
GitLab	`glab`	merge request	`glab mr create`
Bitbucket	`bb`	pull request	`bb pr create`
None	`—`	—	`git push (manual)`

Commit Convention

All commits follow Conventional Commits. Platform tags help organize mobile-specific work.

feat(T-001, ios): add biometric authentication
feat(T-002, shared): improve API error handling
fix(T-005, android): handle back button in modal
test(T-010, shared): add E2E test for login flow

Tips

Test on real devices. Simulators don't catch everything — network issues, permissions, gesture handling. Test iOS on iPhone and Android on real devices before release.

Keep bundle size small. Mobile users care about app size and startup time. Monitor bundle size in each build. Use code splitting and lazy loading for screens.

Platform-specific code is okay. Don't force shared code where iOS and Android genuinely differ. Use .ios.tsx/.android.tsx files without guilt.

Offline-first by default. Mobile networks are unreliable. Design with offline support in mind from the start. Cache data, queue requests, handle sync gracefully.

Use /status often. It shows build health, platform coverage, and blockers — especially useful when shipping to app stores.

Run /security-review before release. Mobile apps have unique security challenges (biometric spoofing, deep link injection, exported components). Review before every app store submission.

Ready to get started? Run /setup in Claude Code or read the mobile walkthrough.