Mobile Agency

The complete AI dev team for mobile engineers.

19 personality-driven agents · 52 composable skills · 13 end-to-end workflows Android · iOS · Flutter · React Native · Kotlin Multiplatform · Unity · Unreal

Installation Guide · Core Loops · mobile-karpathy · Wiki · Getting Started · Contributing

AI agents, skills, and Loop Engineering workflows for building, testing, reviewing, and shipping Android, iOS, Flutter, React Native, Unity, and Unreal apps.

What is Mobile Agency?

Mobile Agency is a ready-to-use AI engineering system for mobile apps, hybrid apps, and games. Instead of learning every platform from scratch or writing the same prompts again and again, you install the agents, skills, and workflows, then use them to plan, build, review, test, and ship real Android, iOS, Flutter, React Native, Kotlin Multiplatform, Unity, and Unreal projects.

Bring the idea. Mobile Agency brings the mobile team: product planning, architecture review, feature development, clean-code audits, security checks, performance analysis, UI verification, device QA, release prep, and store growth.

Mobile Agency is built around Loop Engineering and a mobile-karpathy mindset: define the goal once, then let the system keep moving through planning, implementation, code audit, security review, UI verification, device QA, reporting, and context saving. The aim is to reduce manual work and repeated manual prompting so developers can focus on product decisions, architecture tradeoffs, credentials, and final approval.

Install

New to AI coding tools? Start with the step-by-step Installation Guide.

Fast path:

npx mobile-agency install

This installs Mobile Agency for Claude Code. For Cursor, Windsurf, GitHub Copilot, Codex, platform-only installs, and troubleshooting, see docs/installation.md.

Common installs:

| I use... | Run this | |---|---| | Claude Code | npx mobile-agency install | | Cursor | npx mobile-agency install --tool cursor | | Windsurf | npx mobile-agency install --tool windsurf | | GitHub Copilot | npx mobile-agency install --tool copilot | | Codex / OpenAI | npx mobile-agency install --tool codex | | All supported tools | npx mobile-agency install --tool all |

Local clone install:

git clone https://github.com/salmanashraf/mobile-agency
cd mobile-agency
./install.sh --platform android
./install.sh --platform flutter --tool cursor
./install.sh --tool all

How It Works

Mobile Agency turns AI coding from one-off prompts into a repeatable mobile engineering loop.

| Step | What Happens | Command | |---|---|---| | 1. Install | Add the agents, skills, and workflows to your AI coding tool. | npx mobile-agency install | | 2. Open your app | Use it inside an Android, iOS, Flutter, React Native, KMP, Unity, or Unreal project. | Claude Code · Cursor · Windsurf · Copilot · Codex | | 3. Start the loop | Tell Mobile Harness the app or feature goal once. It asks clarification questions before building. | /mobile-harness | | 4. Build with gates | The loop plans, implements, reviews architecture, checks security, audits performance, verifies UI, and runs QA. | @MOBILE-HARNESS | | 5. Continue later | Project context, decisions, reports, and next tasks are saved so work can continue across sessions. | Mobile Memory |

For focused work, use a specialist directly:

//mobile-harness Create Habit Tracker App
@AXIOM review HomeViewModel.kt
@CRASHER analyze crash.log
/flutter-review lib/home_screen.dart
/perf-audit startup
/security-audit release

Who It Helps

| Role | How Mobile Agency Helps | |---|---| | Senior developers | Delegates repeatable review, debugging, release, and QA work while keeping output tied to platform-specific standards and evidence. | | Architects and tech leads | Turns product goals into PRDs, tasks, architecture checks, security gates, UI verification, and release readiness reports that teams can review. | | Fresh joiners and new AI users | Provides a guided path from idea to implementation, with clear questions, examples, checklists, and safe defaults instead of a blank AI chat. |

The goal is a practical mobile engineering loop: plan the feature, build one task at a time, audit the code, run tests, verify the UI, test on a simulator or device, save context, and continue later without losing project memory.

Core Loops and Platform Plugins

Mobile Agency is organized around core engineering loops, then extended with platform-specific plugins. Start with the loop that matches your current problem, then apply the Android, iOS, Flutter, React Native, Kotlin Multiplatform, Unity, or Unreal expertise needed for your app.

Core Loops: Planning -> Architecture -> Development -> Performance -> Security -> Testing -> Release -> Growth -> Maintenance
Platform Plugins: Android · iOS · Flutter · React Native · Kotlin Multiplatform · Unity · Unreal

| Core Loop | What It Handles | Best Starting Point | |---|---|---| | Planning | Idea discovery, PRD, roadmap, task breakdown | @APPFORGE, /grill-mobile, /feature-slice | | Architecture | System design, clean code, module boundaries, model separation | @AXIOM, /clean-code-audit, platform reviewers | | Development | Feature implementation, UI build, refactor, code review | @MOBILE-HARNESS, @FIGMA, platform builders | | Performance | Startup, ANR, memory leaks, frame drops, battery, network, app size | @PERF, @FREEZE, @RETAINER, /perf-audit | | Security | OWASP, secrets, auth, storage, deep links, WebView, permissions | @SENTINEL, /security-audit, /security-scan | | Testing | Unit tests, UI tests, accessibility, PRD checks, device QA | /mobile-mcp-qa, TDD skills, accessibility audit | | Release | CI/CD, signing, release notes, rollout, store checklist | @PIPELINE, @SCRIBE, /release-prep | | Growth | ASO, store listing, screenshots, monetization | @LAUNCHPAD, /store-listing | | Maintenance | Crash triage, context memory, issue planning, regression checks | @CRASHER, Mobile Memory, issue-to-agent workflow |

Security and performance are built into the loop before release. They are not optional cleanup steps.

Full guide: docs/core-loops.md

See It In Action

/mobile-harness running Loop Engineering — one flow for planning, building, testing, UI verification, and release checks:

https://github.com/user-attachments/assets/848a0427-8b0d-414a-a48e-79df38238674

/flutter-review on a real Flutter project — prioritized findings, zero setup:

https://github.com/user-attachments/assets/427422db-b6b1-4e93-96d0-ad5dd2843f53

@AXIOM reviewing Android Kotlin/Compose code — Clean Architecture, lifecycle leaks, coroutine misuse, and Compose anti-patterns:

https://github.com/user-attachments/assets/ee8bbd61-9c64-47bf-a9b3-7812cc12412c

More context: AXIOM discussion

Start Here

Not sure where to begin? Pick your situation:

| I want to… | Use this | |---|---| | Debug a crash | @CRASHER + paste your stacktrace | | Review Android code | @AXIOM + paste your Kotlin file | | Design Compose navigation | @NAVIGATOR + list screens and flows | | Review Flutter code | /flutter-review + paste your Dart file | | Optimize a slow screen | /perf-audit + describe the screen | | Test on a device or emulator | /mobile-mcp-qa + provide app id and flow | | Build, test, and verify a feature | @MOBILE-HARNESS + approved PRD/design/tasks | | Prepare a release | /release-prep | | Generate release notes | @SCRIBE + paste your git log | | Build an app from idea to store | @APPFORGE + answer the discovery questions |

Before vs After

Android — Memory Leak

| | | |---|---| | Input | HomeViewModel holding a Context reference | | Agent | @AXIOM | | Output | CRITICAL: Context leak via ViewModel — replace with ApplicationContext or use WeakReference | | Result | Leak eliminated before PR merge |

Android — ANR

| | | |---|---| | Input | Network call on main thread in onCreate() | | Agent | @AXIOM | | Output | CRITICAL: Blocking IO on main thread — move to viewModelScope.launch(Dispatchers.IO) | | Result | ANR fixed with coroutine scope and dispatcher |

Flutter — Widget Review

| | | |---|---| | Input | HomeScreen with setState on a 400-line widget | | Agent | /flutter-review | | Output | 9 ranked findings: draft hydration in build(), ScrollController leak, missing semanticLabels, touch targets below 48dp | | Result | Findings fixed before merge, accessibility score improved |

Why Mobile Agency?

| | Generic AI prompt repos | Mobile Agency | |---|---|---| | Platform knowledge | Generic | Android · iOS · Flutter · React Native · Unity · Unreal | | Agent personalities | None | 19 named specialists with opinions | | Real workflows | No | 13 end-to-end processes | | Real examples | Toy pseudocode | Production code input/output pairs | | Installable | Copy-paste | npx mobile-agency install | | Severity levels | None | CRITICAL · WARNING · INFO | | Slash commands | No | 52 composable skills |

Agent Roster

Platform Agents

| Agent | Platform | Personality | Mission | |---|---|---|---| | AXIOM | Android | Battle-scarred architect. Zero tolerance for GlobalScope. Has survived 3 Jetpack migrations. | Reviews Kotlin/Compose for Clean Architecture, leaks, and anti-patterns | | NAVIGATOR | Android | Back-stack cartographer. Every destination has a type and every pop has a reason. | Generates and reviews type-safe Compose navigation, nested graphs, deep links, and bottom navigation | | RETAINER | Android | Heap detective. Follows every strong reference until the guilty owner confesses. | LeakCanary and heap-retention reports to exact owner, fix, and verification plan | | FREEZE | Android | Main-thread forensic analyst. Every freeze has a blocking chain. | ANR traces, Play Console clusters, and thread dumps to root cause, fix, and verification | | SWIFT | iOS | Elegant, memory-safety obsessed. Will shame your retain cycles. | Reviews Swift/SwiftUI for memory safety, concurrency, and idiomatic patterns | | DART | Flutter | Pixel-perfect widget obsessive. Counts rebuilds like a miser counts coins. | Reviews Flutter for rebuild efficiency, state management, and performance | | BRIDGE | React Native | JSI evangelist. Tracks every bridge crossing like a border guard. | Finds bridge bottlenecks, re-renders, and New Architecture migration paths | | FORGE | Unity | Game systems architect. Frame budget is sacred. | Reviews C# for GC pressure, Update() abuse, and draw call inefficiency | | UNREAL | Unreal Engine | Blueprint-to-C++ enforcer. Every Tick() must earn its place. | Blueprint optimization, C++ migration, and Tick() abuse |

Cross-Platform Agents

| Agent | Personality | Mission | |---|---|---| | CRASHER | Forensic investigator. Nothing escapes. | Crash log → root cause → concrete fix, all platforms | | SENTINEL | Paranoid by design. Every input is malicious until proven otherwise. | OWASP Mobile Top 10 security audit | | APPFORGE | End-to-end product lead. Practical, launch-focused, allergic to vague MVPs. | Rough app idea → PRD → tasks → QA → Play Store launch prep | | MOBILE-HARNESS | Principal delivery lead. Trusts evidence, not vibes. | Autonomous top-level orchestrator for planning, build, memory, tests, UI verification, Mobile MCP QA, and launch | | MOBILE MEMORY | Project memory that survives sessions. | Mobile knowledge graph + context preservation across any AI tool | | LAUNCHPAD | ASO-obsessed conversion scientist. | Play Store + App Store copy, keywords, screenshot brief | | PIPELINE | Automation purist. If it's done manually twice, it's a pipeline waiting to exist. | GitHub Actions / Bitrise / Fastlane configuration | | PERF | Frame-rate zealot. Carries a stopwatch everywhere. | Profile slow screens → concrete optimization plan | | SCRIBE | User-first writer. Translates git commits into things humans understand. | Git log → polished release notes | | FIGMA | Pixel-perfect or it didn't happen. | Figma spec → Compose / SwiftUI / Flutter / RN code |

Skills Library

35 focused prompt modules — use inline or compose with agents.

Android

| Skill | What It Does | |---|---| | /anr-investigation | Evidence-first Android ANR classification, root cause, fix, and verification | | /android-tdd | Red-green-refactor loop for JUnit5 + Compose UI tests | | /compose-review | Recomposition audit before PR | | /compose-migration | XML layouts → Jetpack Compose | | /kotlin-modernize | Old Kotlin → modern idioms | | /memory-leak-investigation | LeakCanary reference-path and lifecycle ownership analysis | | /proguard-rules | R8/ProGuard rules from your dependency list |

iOS

| Skill | What It Does | |---|---| | /ios-tdd | XCTest TDD loop for Swift/SwiftUI | | /swiftui-review | View lifecycle + memory audit + unnecessary redraws | | /swift-concurrency | Completion handlers → async/await safely | | /xcode-warnings | Explains and fixes Xcode warnings in plain English |

Flutter

| Skill | What It Does | |---|---| | /flutter-tdd | Widget test + unit test + Bloc test loop | | /flutter-review | Widget tree audit, const constructors, state management | | /widget-extract | Extracts oversized build() into reusable components | | /dart-modernize | Pre-null-safety Dart → Dart 3.x patterns |

React Native

| Skill | What It Does | |---|---| | /rn-tdd | Jest + React Native Testing Library loop | | /rn-review | Bridge calls audit + re-render profiling | | /new-arch-migrate | Step-by-step New Architecture migration | | /expo-optimize | Expo config + OTA + bundle size audit |

Gaming

| Skill | What It Does | |---|---| | /unity-tdd | NUnit + Unity Test Runner (EditMode + PlayMode) | | /shader-gen | Plain English → HLSL/ShaderLab shader | | /game-perf | Frame budget audit + draw call optimizer | | /blueprint-to-cpp | Unreal Blueprint → C++ with explanation |

Cross-Platform

| Skill | What It Does | |---|---| | /grill-mobile | 20 questions before any mobile code is written | | /crash-triage | Paste stacktrace → root cause → fix | | /perf-audit | Slow screen → systematic profiling guide | | /clean-code-audit | App-wide clean code, model separation, and architecture boundary audit | | /security-audit | Complete mobile app security audit for release readiness | | /prd-verification | Check implementation, UI evidence, tests, and reports against PRD/design/tasks | | /store-listing | Conversation → ASO-optimized listing copy | | /feature-slice | Epic → independently shippable tickets | | /release-prep | Full release checklist from freeze to store | | /accessibility-audit | WCAG 2.1 AA + platform accessibility review | | /api-versioning | API deprecation strategy for mobile clients | | /deeplink-debug | Diagnoses broken deep links across Android and iOS | | /mobile-mcp-qa | Run AI-assisted QA on iOS/Android devices, simulators, and emulators | | /mobile-memory-save | Checkpoint your session — resume on any AI tool instantly | | /mobile-memory-graph | Build a mobile knowledge graph from your codebase files | | /mobile-memory-search | Search local Mobile Agency memory and inject relevant context |

Workflows

13 end-to-end processes that chain agents and skills together.

| Workflow | What It Covers | |---|---| | feature-ship | Ticket → /grill-mobile → /feature-slice → implement → review → test → PR | | crash-to-fix | Crash alert → CRASHER → fix → regression test → deploy | | app-launch | Release build → SENTINEL → PERF → LAUNCHPAD → SCRIBE → /release-prep → store | | new-screen | Figma spec → FIGMA → implement → review → performance check | | ci-setup | PIPELINE → generate config → secrets → test → document | | release-cycle | Feature freeze → CRASHER → SENTINEL → SCRIBE → /release-prep → staged rollout | | perf-sprint | Baseline → /perf-audit → fix → re-measure → document | | game-level | Design doc → FORGE/UNREAL → /shader-gen → /game-perf → /unity-tdd → playtest | | new-project-setup | /grill-mobile → architecture → CI → security baseline → test infrastructure | | mobile-memory-workflow | Mobile Memory: restore context → capture decisions → generate MOBILE_MEMORY.md → hand off across AI tools | | appforge-workflow | App idea → PRD → design plan → tasks → implementation gates → QA → Play Store | | mobile-mcp-qa | Install/launch app → inspect UI → run flows → capture screenshots → QA report | | mobile-harness | Approved task → implementation → tests → UI match → Mobile MCP QA → report |

Release Process

npm publishing is handled by GitHub Actions from git tags. Do not run npm publish manually.

# 1. bump package.json version, for example 1.0.19
git add package.json
git commit -m "Release v1.0.19"

# 2. create and push the release tag
git tag v1.0.19
git push origin main
git push origin v1.0.19

GitHub Actions publishes npm after the tag push. Full guide: docs/release-process.md

APPFORGE — Idea to Store

APPFORGE turns a rough mobile app idea into a small, shippable MVP plan and Play Store launch package.

@APPFORGE
1. Discovery        → refined ideas + best MVP recommendation
2. PRD              → PRD.md
3. Free design plan → screens, wireframes, design system, states
4. Task breakdown   → TASKS.md + DEPENDENCIES.md + ROADMAP.md
5. Implementation   → one approved subtask at a time
6. UI match review  → layout, spacing, colors, accessibility
7. Full QA          → QA_REPORT.md + launch readiness score
8. Store prep       → PLAYSTORE_LISTING.md + SCREENSHOT_PLAN.md + RELEASE_CHECKLIST.md

APPFORGE does not write code until the PRD, design plan, and task breakdown are approved. It pairs with AXIOM, SWIFT, DART, and BRIDGE for platform review, then LAUNCHPAD and /release-prep for store launch.

Mobile MCP fits the QA stage next: use it for emulator, simulator, or real-device automation once the app is ready for flow testing.

Mobile MCP — Device QA Automation

Mobile MCP gives Mobile Agency a device automation layer for iOS and Android simulators, emulators, and real devices.

/mobile-mcp-qa
1. List devices
2. Install or launch app
3. Capture screenshot + UI elements
4. Tap, type, swipe, rotate, restart
5. Verify happy path and edge cases
6. Produce MOBILE_MCP_QA_REPORT.md

Use it inside APPFORGE Stage 7 Full QA, UI match review, launch readiness checks, and screenshot validation. Full guide: docs/mobile-mcp.md

Mobile Harness — Top-Level Orchestrator

Mobile Harness is the Loop Engineering orchestrator for Mobile Agency. It can start from a rough app idea or an existing codebase, then coordinate APPFORGE, Mobile Memory, platform reviewers, tests, UI verification, Mobile MCP QA, accessibility, performance, security, release prep, and store/growth work.

Use it when you want to define the goal once and have the system keep moving through the app-building loop without repeating the same manual prompts at every stage.

What It Runs

Goal
-> clarify delivery profile and design direction
-> create or read PRD.md, DESIGN.md, TASKS.md, DEPENDENCIES.md, ROADMAP.md
-> implement one scoped task
-> run platform review
-> run tests
-> verify PRD and UI match
-> run device QA when available
-> run performance/security/accessibility checks when relevant
-> update MOBILE_MEMORY.md
-> produce MOBILE_HARNESS_REPORT.md

First Questions It Should Ask

Mobile Harness now asks the questions that prevent thin or wrong output:

1. New app idea or existing codebase?
2. Platform and stack?
3. Delivery profile?
   A. Smallest MVP
   B. Demo-grade MVP
   C. Production-ready MVP
4. Design direction?
   Clean utility, polished consumer, playful gamified, premium wellness,
   dense dashboard, enterprise/admin, kids/education, game-like, or custom reference.
5. Existing PRD/design/tasks/dependencies/memory?
6. Build/test command?
7. Device/emulator/simulator available?
8. Done criteria?

For video, marketing, or social demos, choose:

Delivery Profile: Demo-grade MVP
Design direction: Playful gamified, polished consumer, or another clear visual style.

Demo-grade mode requires seeded data, multiple visible screens/states, a screenshot plan, and a UI polish pass. It should not stop at a technically correct but boring two-screen app.

Run It

In Claude Code, install Mobile Agency, open your app project, then run:

/mobile-harness

For a full explicit prompt, use:

@MOBILE-HARNESS

Use Mobile Agency Loop Engineering to build this app from idea to verified MVP.

App idea: <your app idea>
Platform: <Android | iOS | Flutter | React Native>
Tech stack: <your stack>

Delivery Profile: Demo-grade MVP
Design direction: <clean utility | polished consumer | playful gamified | premium wellness | dense dashboard | enterprise/admin | custom reference>

Before building, ask only the clarification questions needed to avoid wrong assumptions.
After clarification, run the full loop:
1. Planning
2. Architecture
3. Development
4. Performance review
5. Security audit
6. Testing plan
7. UI/device verification
8. Release checklist
9. Growth/store listing draft
10. Save project context

Do not ask me to repeat the idea at each stage.
Do not skip stages.
Keep changes scoped.
Create or update project files as needed.
At the end, produce MOBILE_HARNESS_REPORT.md with build, tests, PRD verification, UI match, device QA, and next action.

Example Demo Prompt

@MOBILE-HARNESS

Use Mobile Agency Loop Engineering to build a demo-grade Android app.

App idea: Habit Pulse — an offline habit tracker where users add habits, mark today complete, see streaks, and review progress.
Platform: Android
Tech stack: Kotlin + Jetpack Compose + Room
Delivery Profile: Demo-grade MVP
Design direction: Playful gamified, polished consumer app. Colorful but clean. Streaks, progress, rewards, cards, dashboard, and screenshot-ready seeded data.

Ask clarification first if needed, then run the full loop without asking me to repeat the idea.

Full guide: docs/mobile-harness.md

Mobile Memory — Never Lose Context

When tokens run out or you switch AI tools, your entire session context — architectural decisions, agent findings, code in progress — vanishes. Mobile Memory captures durable project context locally and can generate a portable MOBILE_MEMORY.md handoff file.

mobile-agency memory init        → creates local project memory
mobile-agency memory capture     → saves decisions, findings, progress, and next actions
mobile-agency memory search      → searches project memory
mobile-agency memory checkpoint  → generates MOBILE_MEMORY.md for handoff

For local persistent memory in a project:

npx mobile-agency memory init
npx mobile-agency memory capture --type decision --text "Use Room for offline persistence"
npx mobile-agency memory search persistence
npx mobile-agency memory inject
npx mobile-agency memory checkpoint

This stores raw local memory in .mobile-agency/memory/, keeps sensitive event history out of git by default, and generates MOBILE_MEMORY.md when you want a portable handoff.

Works across Claude Code, Cursor, Windsurf, ChatGPT, and Gemini. Integrates with every Mobile Agency agent — AXIOM findings, CRASHER analysis, and LAUNCHPAD copy are all preserved in the same file.

Inspired by Graphify's token reduction approach, built for mobile architecture. Up to 80× token reduction on large mobile projects vs reading raw files.

Claude slash commands are now named /mobile-memory, /mobile-memory-save, /mobile-memory-graph, and /mobile-memory-search.

Full guide: docs/mobile-memory.md

The Viral File

mobile-karpathy.md — 4 rules that stop AI coding agents shipping broken mobile apps.

Add it to your project's CLAUDE.md. Share it independently. It's designed to travel.

Rule 1 — Ask the API level before assuming
Rule 2 — Check for existing platform components first
Rule 3 — Never touch what wasn't asked
Rule 4 — Performance is a feature, not an afterthought

Real Examples

Every agent ships with a real worked example — production code in, structured findings out.

| Example | Input | Output | |---|---|---| | Android review | examples/android-code-review/input.kt | output.md | | Crash triage | examples/crash-triage/input.txt | output.md | | Flutter review | examples/flutter-review/input.dart | output.md | | Store listing | examples/store-listing/input.md | output.md | | New screen workflow | examples/new-screen-workflow/figma-spec.md | output.kt | | App idea to store | agents/cross-platform/appforge/agent.md | Stage-gated discovery, PRD, design, tasks, QA, and store prep |

Multi-Tool Support

| Tool | How to Use | |---|---| | Claude Code | npx mobile-agency install | | Cursor | npx mobile-agency install --tool cursor | | Windsurf | npx mobile-agency install --tool windsurf | | GitHub Copilot | Paste agent system prompt into Copilot instructions | | Codex / OpenAI | Use agents as system prompts via API or CLI | | Local repo | git clone + ./install.sh |

Contributing

See CONTRIBUTING.md for the full guide.

• Every agent needs a personality, not just a function
• Every agent needs a real worked example using production code
• Run your agent against at least 2 real files before submitting
• Skills must have a slash command name
• Workflows must list every agent and skill used, step by step

Community

• GitHub Discussions — share your output, ask questions, show and tell
• Issues — bug reports, new agent requests

If Mobile Agency saved you time, a star helps others find it.

Built for mobile engineers who ship real apps.