Mobile Engineering Agents

Appearance

📱 Mobile Engineering Agents ​

Turn your AI coding agent into a Senior mobile engineer ​

A drop-in knowledge system that gives Claude Code, Codex, Cursor, Windsurf, Gemini CLI, and Aider the judgment of an experienced mobile team — architecture, security, testing, and standards — so the code they generate is production-grade, not just plausible.

License: MITDocsPRs WelcomePlatformAI-ready

Docs Site · Quick Start · What's Inside · The Agent Team · How to Use · How It Works · Workflows

Why this exists ​

AI agents can write a lot of mobile code, fast. The bottleneck isn't typing — it's engineering judgment: picking the right architecture, getting concurrency and error handling right, securing data, and keeping the codebase maintainable as it grows.

Without this toolkit: "Build me a login screen" → a Massive View Controller with the token in UserDefaults and no tests.

With it: the agent acts as a Security Expert + SwiftUI Expert — OAuth2 + PKCE, Keychain storage, MVVM, typed errors, and unit tests — then self-reviews against a checklist.

This repo encodes that judgment as machine-loadable agents, skills, workflows, checklists, templates, prompts, standards, and architecture references. Primary focus: iOS / Swift / SwiftUI (with legacy UIKit + MVP codebases supported as a first-class paradigm); secondary: Android/Kotlin and Flutter.

It is not a tutorial or handbook. It's an operational toolkit you point your AI agent at.

Quick Start ​

Get running in three steps. The everyday workflow needs zero file paths.

1. Clone the toolkit into your project ​

bash
cd your-project
git clone https://github.com/sokpichdev/mobile-engineering-agents.git .mobile-agents
echo ".mobile-agents/" >> .gitignore   # optional: keep it out of your repo

The hidden .mobile-agents/ folder keeps the toolkit from cluttering your own files.

2. Wire up the entry file for your tool ​

bash
echo "@.mobile-agents/CLAUDE.md" > CLAUDE.md             # Claude Code
echo "@.mobile-agents/.cursorrules" > .cursorrules       # Cursor
echo "@.mobile-agents/.windsurfrules" > .windsurfrules   # Windsurf

The @ import pulls in the full toolkit. Codex (AGENTS.md) and Gemini CLI (GEMINI.md) auto-load their entry files straight from the cloned folder — no extra step.

3. Describe what you want ​

text
> Build a Profile screen that loads /me and stores the auth token securely.

On its first reply of every session, the agent confirms it loaded:

text
Mobile Engineering Agents — loaded ✓

See that line and you're wired in — the agent now routes every plain-language request to the right experts and scales its process to the task. Head to How to Use the Agents for the full usage model.

Confirm & keep updated ​

  • Quick check: start a session — the loaded ✓ line should head the reply.
  • Deterministic check: run ./verify.sh (or !verify in-session, which runs workflows/verify_setup.md) to validate every entry-point file and the agent/skill/workflow/checklist counts.
  • Update: cd .mobile-agents && git pull.

What's Inside ​

DirectoryWhat it gives your agentCount
agents/Loadable expert roles (architect, security, testing…)14
skills/Deep, single-topic know-how (auth, websockets, caching…)31
workflows/Step-by-step procedures (build a feature, integrate an API…)11
checklists/Objective, automatable review gates8
standards/Non-negotiable rules (coding, security, testing, git)7
architecture/Reference designs with Mermaid diagrams6
prompts/Copy-paste prompts for common tasks10
templates/Scaffolding with boilerplate Swift8
examples/Reference apps (banking, chat, CoffeeCraft, ecommerce, social)5

Plus AGENTS.md (orchestration), GLOSSARY.md (shared terms), and a README.md index inside every directory.

The Agent Team ​

Each agent is a self-contained role: purpose, responsibilities, hard rules, coding standards, review checklist, common mistakes, and example tasks. They're organized into four tiers that hand off to each other (see AGENTS.md).

Strategy ​

Implementation ​

Quality & Hardening ​

Gate & Delivery ​

How to Use the Agents ​

There are only two ways to drive the toolkit, and you'll use the first one 95% of the time.

Way 1 — Just describe the task (the default) ​

Talk to your agent in plain language. The entry file reads the request, routes it to the right experts, and self-reviews — you never name a file:

text
> Build an Account Summary screen that loads /accounts and stores the token securely.

Way 2 — Name a file to steer it (for precision or to override routing) ​

Point the agent at a specific role, workflow, or checklist when you want exact control:

text
> Read agents/security_expert.md and act as that agent, then audit Sources/Auth.

What to type for common goals ​

Your goalJust say…Or steer with…
Build a feature"Build a profile screen that loads /me"workflows/create_feature.md
Add / change an API"Add the /transactions endpoint"workflows/integrate_rest_api.md
Add auth / login"Add OAuth login with secure token storage"agents/security_expert.md
Review a diff"Review my changes"checklists/code_review.md
Fix something slow"The feed scroll is janky, fix it"agents/performance_expert.md
Write tests"Write tests for AuthRepository"agents/testing_expert.md

You don't need to know which agent owns a task — that's the toolkit's job. Naming a file (Way 2) is just how you override or sharpen the automatic routing.

Per-tool syntax ​

The mental model above is identical in every tool; only the way you reference a file changes. The examples below show the file-steer form (Way 2).

Claude Code

CLAUDE.md loads automatically. Pull in a specific role or workflow:

text
> Read agents/security_expert.md and act as that agent.
> Audit Sources/Auth for credential issues using checklists/security_review.md.
> Follow workflows/integrate_rest_api.md to add the /transactions endpoint.
OpenAI Codex

AGENTS.md is read automatically. Reference files in your prompt:

text
Using agents/swiftui_expert.md and standards/swiftui_standards.md, build the
account summary screen described below.
Cursor

.cursorrules applies automatically. Add a file to context and prompt:

text
@workflows/integrate_graphql.md implement the feed query with pagination.
Windsurf

.windsurfrules is applied by Cascade. Reference files in chat:

text
@checklists/code_review.md review the open diff.
Gemini CLI

GEMINI.md loads automatically. Use @path to include files:

text
@agents/testing_expert.md @standards/testing_standards.md write tests for AuthRepository.
Aider

Add files to the chat session:

bash
aider --read agents/ios_architect.md --read standards/architecture_standards.md

How It Works ​

You describe a task; the toolkit handles the assignment. Every request goes through the same four moves:

  1. Classify — the entry file reads your request and identifies its primary deliverable (architecture, UI, data, security, a test, a release).
  2. Route — it picks the one entry agent that owns that deliverable. You don't choose the agent; the request does.
  3. Chain — that agent hands off down the tiers (Strategy → Implementation → Hardening → Gate), scaling the chain to the task: a one-line fix gets the specialist plus a review, a new feature runs the full sequence.
  4. Self-review — the chain ends against the matching file in checklists/.

What loads when. Only the entry files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .windsurfrules) load at startup. Everything else — agents/, skills/, standards/, workflows/, checklists/ — is pulled in by the agent as the task needs it, so context stays lean. Naming a file yourself just overrides or sharpens this automatic routing.

Multi-platform by design. The agent detects your project's platform (iOS, Android, Flutter, React Native) and loads only that platform's subtree — skills/<topic>/<platform>/ and templates/<platform>/ — plus the shared, platform-neutral layers (standards/, architecture/, checklists/, workflows/). Within iOS, the agent also detects the UI paradigm (swiftui or uikit) and loads only that paradigm's files (omitting the ui: key means content applies to both). It never pulls another platform's code into context. iOS is the most complete today; see Contributing to help port the rest.

See AGENTS.md for the full routing table and the tier hierarchy, or the Example Workflows diagram below for a real multi-agent handoff.

Visualizing Agent Activity (Claude Code) ​

Watch the agents work in real time with agents-observe — a local, open-source (MIT) observability dashboard. It captures Claude Code hook events into a local SQLite database and streams them to a live web UI: tool calls, subagent hierarchy, session replay, and token/cost stats. Nothing leaves your machine.

Setup (requires Docker and Node):

bash
claude plugin marketplace add simple10/agents-observe
claude plugin install agents-observe

The plugin auto-starts its server on the next Claude Code session; the dashboard lives at http://localhost:4981. Manage it from inside Claude Code with /observe status, /observe restart, and /observe logs.

Each role in agents/ is mirrored as a native Claude Code subagent in .claude/agents/ (e.g. swiftui-expert, security-expert), so when work is delegated, every specialist appears as its own named agent in the dashboard instead of one anonymous session.

Example Workflows ​

Ready-made, end-to-end procedures — each with inputs, steps, validation, and acceptance criteria:

Behind the scenes, a non-trivial task flows through multiple agents:

Best Practices ​

  1. Load the smallest sufficient context — the specific agent/skill/workflow, not the whole repo.
  2. Chain agents for real work: architect → implementer → reviewer.
  3. Always end with a checklist — have the agent self-review against checklists/.
  4. Treat standards as non-negotiable — reference standards/ for consistent output.
  5. Prefer workflows over ad-hoc prompts for anything you'll do more than once.

Design Principles ​

Every agent defaults to the same engineering values, so output looks like one team wrote it:

  • Clean Architecture + MVVM and SOLID by default.
  • Security is a requirement, not an afterthought (OWASP MASVS).
  • Testable, modular, observable code with explicit, typed error handling.
  • Consistent standards across sessions, tools, and contributors.

Contributing — everyone is welcome ​

This is a community toolkit, and it gets sharper with every perspective. You do not need to be an iOS engineer to help. Here's where people of every background fit in:

If you're a…You can help by…
iOS / Swift devSharpening agents, skills, and standards; adding patterns you ship in production
Android / Kotlin devPorting iOS skills to Kotlin/Compose — Android parity is a top roadmap goal
Flutter / cross-platform devAdding Flutter, React Native, or KMP equivalents of existing skills and agents
Backend / API devImproving the networking, API-contract, and integration workflows
Tester / QAStrengthening the testing agent, the checklists, and test-strategy skills
Security reviewerAuditing the security standards and Keychain / crypto / pinning guidance
Critic / reviewerRunning the agents on real tasks and filing where the output falls short
Writer / typo hunterFixing typos, tightening wording, and improving clarity and examples
Web devBuilding a docs site or landing page for the toolkit (open an issue to claim it)
DesignerImproving the diagrams, the logo / banner, and visual explanations
AnyoneFiling ideas and bug reports, starring, and sharing the repo

Three ways in, smallest effort first — pick whichever fits:

  1. Spot something off? Open an issue — a typo, a wrong recommendation, a missing topic, or just an idea.
  2. Have feedback on agent output? Tell us what you asked, what you got, and what a senior engineer would have done instead — that's some of the most valuable input we receive.
  3. Want to write code or docs? See CONTRIBUTING.md for setup, section templates, and style, then send a PR.

Good First Issues ​

New to the project? These are scoped, beginner-friendly, and have clear acceptance criteria — the perfect place to start:

Browse good first issues

Your first contribution in four steps:

  1. Pick an issue from the list above and comment that you're taking it.
  2. Fork & branch — git checkout -b feat/<short-name>.
  3. Make the change following the section templates, then run npm install && npm run lint.
  4. Open a PR with a Conventional Commit title (e.g. feat(skills): add SwiftData storage skill).

That's it — a maintainer will review and help you land it.

Roadmap ​

  • [ ] Kotlin/Compose and Flutter parity for the iOS-first skills.
  • [ ] Machine-readable agent manifests (YAML front-matter) for automated routing.
  • [ ] Expanded example apps with full test suites.
  • [ ] Evaluations that score agent output against the checklists.
  • [ ] Optional MCP server exposing skills as callable tools.

License ​

MIT © Sok Pich — free to use, fork, and adapt.

If this makes your AI a better mobile engineer, give it a ⭐ and share it.