mobile-ai-agents 1.0.23

package/docs/installation.md

@@ -0,0 +1,271 @@
+# Installation Guide
+
+This guide is for first-time users who want Mobile AI Agents installed in their AI coding tool without needing to understand the repo structure first.
+
+---
+
+## Quick Start
+
+If you are not sure what to choose, use the default install:
+
+```bash
+npx mobile-ai-agents install
+```
+
+This installs Mobile AI Agents for Claude Code. It adds agents, skills, and workflows as slash commands in:
+
+```text
+~/.claude/commands/
+~/.claude/agents/
+```
+
+After install, open Claude Code in your app project and try:
+
+```text
+/flutter-review
+/android-tdd
+/crasher
+```
+
+---
+
+## Before You Install
+
+You need:
+
+1. Node.js 18 or newer
+2. An AI coding tool such as Claude Code, Cursor, Windsurf, GitHub Copilot, or Codex
+3. A terminal opened in the project where you want the rules installed
+
+Check Node.js:
+
+```bash
+node --version
+```
+
+If this prints a version like `v18.x`, `v20.x`, or newer, you are ready.
+
+---
+
+## Step 1: Pick Your AI Tool
+
+Choose the tool you use most often:
+
+| I use... | Run this |
+|---|---|
+| Claude Code | `npx mobile-ai-agents install` |
+| Cursor | `npx mobile-ai-agents install --tool cursor` |
+| Windsurf | `npx mobile-ai-agents install --tool windsurf` |
+| GitHub Copilot | `npx mobile-ai-agents install --tool copilot` |
+| Codex / OpenAI | `npx mobile-ai-agents install --tool codex` |
+| More than one tool | `npx mobile-ai-agents install --tool all` |
+
+If you do not know which one to pick, start with the command for your editor. For example, Cursor users should use `--tool cursor`.
+
+---
+
+## Step 2: Run the Command From Your App Project
+
+Open a terminal inside your mobile app project, not inside Mobile AI Agents.
+
+Example:
+
+```bash
+cd ~/Code/my-flutter-app
+npx mobile-ai-agents install --tool cursor
+```
+
+Why this matters:
+
+- Cursor installs files into your current project under `.cursor/rules/`
+- Windsurf installs `.windsurfrules` into your current project
+- Copilot installs `.github/copilot-instructions.md` into your current project
+- Codex installs `AGENTS.md` into your current project
+- Claude Code installs globally into `~/.claude/`
+
+---
+
+## Step 3: Optionally Limit by Platform
+
+By default, Mobile AI Agents installs all platforms:
+
+- Android
+- iOS
+- Flutter
+- React Native
+- Unity / Unreal
+- Cross-platform workflows
+
+For a smaller install, choose one platform:
+
+```bash
+npx mobile-ai-agents install --platform android
+npx mobile-ai-agents install --platform ios
+npx mobile-ai-agents install --platform flutter
+npx mobile-ai-agents install --platform rn
+npx mobile-ai-agents install --platform gaming
+```
+
+You can combine platform and tool:
+
+```bash
+npx mobile-ai-agents install --platform flutter --tool cursor
+npx mobile-ai-agents install --platform android --tool codex
+npx mobile-ai-agents install --platform rn --tool all
+```
+
+---
+
+## What Gets Installed
+
+| Tool | Files created |
+|---|---|
+| Claude Code | `~/.claude/agents/*.md` and `~/.claude/commands/*.md` |
+| Cursor | `.cursor/rules/*.mdc` |
+| Windsurf | `.windsurfrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Codex / OpenAI | `AGENTS.md` |
+
+The install command does not change your application source code. It only adds instruction files for your AI coding tool.
+
+---
+
+## Examples by Tool
+
+### Claude Code
+
+```bash
+npx mobile-ai-agents install
+```
+
+Then open Claude Code and run a slash command:
+
+```text
+/crasher
+```
+
+Paste a crash log and ask for the root cause.
+
+### Cursor
+
+```bash
+npx mobile-ai-agents install --tool cursor
+```
+
+Then use Cursor Chat:
+
+```text
+@axiom review this ViewModel
+@flutter-review review this widget
+```
+
+### Windsurf
+
+```bash
+npx mobile-ai-agents install --tool windsurf
+```
+
+Windsurf reads `.windsurfrules` from your project. After install, ask Windsurf to use the relevant Mobile AI Agents agent or skill.
+
+### GitHub Copilot
+
+```bash
+npx mobile-ai-agents install --tool copilot
+```
+
+Then use Copilot Chat with workspace context:
+
+```text
+@workspace Review this file using the Android code reviewer rules.
+```
+
+### Codex / OpenAI
+
+```bash
+npx mobile-ai-agents install --tool codex
+```
+
+This creates `AGENTS.md` in your project. Codex reads that file as project instructions when working in the repo.
+
+---
+
+## Local Clone Install
+
+Use this if you cloned the Mobile AI Agents repo and want to install from local files instead of npm:
+
+```bash
+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
+```
+
+For most users, `npx mobile-ai-agents install` is simpler.
+
+---
+
+## Troubleshooting
+
+### `npx: command not found`
+
+Install Node.js from [nodejs.org](https://nodejs.org/) and reopen your terminal.
+
+### `mobile-ai-agents: command not found`
+
+Use the full `npx` command:
+
+```bash
+npx mobile-ai-agents install
+```
+
+### Cursor does not see the rules
+
+Make sure the command created files under:
+
+```text
+.cursor/rules/
+```
+
+Then restart Cursor or reload the window.
+
+### Codex does not follow the instructions
+
+Make sure `AGENTS.md` exists at the root of the project you opened in Codex.
+
+### I installed the wrong platform
+
+Run the install command again with the platform you want:
+
+```bash
+npx mobile-ai-agents install --platform flutter --tool cursor
+```
+
+---
+
+## Recommended First Commands
+
+| Project type | Try first |
+|---|---|
+| Android | `/axiom` or `/compose-review` |
+| iOS | `/swift-review` |
+| Flutter | `/flutter-review` |
+| React Native | `/rn-review` or `/perf-audit` |
+| Unity / Unreal | `/game-perf` or `/blueprint-to-cpp` |
+| Any app | `/crasher`, `/release-prep`, `/store-listing` |
+
+---
+
+## Wiki Version
+
+If you maintain the GitHub Wiki, copy this page into a wiki page named:
+
+```text
+Installation
+```
+
+Suggested wiki URL:
+
+```text
+https://github.com/salmanashraf/mobile-agency/wiki/Installation
+```

package/docs/mobile-harness.md

@@ -0,0 +1,160 @@
+# Mobile Harness
+
+Mobile Harness is the top-level orchestrator for Mobile AI Agents. It can start from a rough idea or an existing codebase, then coordinate planning, implementation, tests, UI verification, device QA, memory, and launch preparation.
+
+Use it when you want one AI system to manage the full mobile delivery loop with as little human effort as safely possible, while still using specialized agents and skills underneath.
+
+---
+
+## Mental Model
+
+```text
+MOBILE-HARNESS
+├── APPFORGE      → idea, PRD, design, tasks, roadmap
+├── Mobile Memory → long-term memory across days/weeks
+├── AXIOM/SWIFT/DART/BRIDGE → platform code review
+├── /mobile-mcp-qa → emulator/device UI verification
+├── /accessibility-audit → accessibility verification
+├── /perf-audit or PERF → performance verification
+├── CRASHER       → crash/debug investigation
+├── LAUNCHPAD     → Play Store listing
+├── SCRIBE        → release notes
+└── PIPELINE      → CI/CD and build/release automation
+```
+
+APPFORGE plans. Mobile Memory remembers. Mobile Harness orchestrates execution and evidence.
+
+---
+
+## Autonomy Contract
+
+Mobile Harness should do the work, not assign work back to the user.
+
+It should autonomously:
+
+- Create missing `PRD.md`, `DESIGN.md`, `TASKS.md`, `DEPENDENCIES.md`, `ROADMAP.md`, `MOBILE_MEMORY.md`, QA reports, and launch docs.
+- Pick practical MVP defaults when the user gives a rough idea.
+- Implement one approved task at a time.
+- Run tests, builds, platform review, PRD checks, UI checks, and Mobile MCP QA when available.
+- Fix failures inside the current task scope.
+- Preserve context so the project can continue across days or weeks.
+
+It should ask the user only for decisions or access it cannot safely infer:
+
+- Business decisions, monetization choices, launch date changes, and MVP scope changes.
+- API keys, certificates, app store access, billing, and credentials.
+- Paid actions, destructive actions, public releases, and legal/privacy policy ownership.
+- Approval before code implementation starts, unless the user has already approved autonomous execution.
+
+---
+
+## Source of Truth
+
+Mobile Harness verifies against docs, not memory:
+
+| Artifact | Required | Used For |
+|---|---|---|
+| `MOBILE_MEMORY.md` | Required for multi-session work | Current context, decisions, next action |
+| `PRD.md` | Required before implementation | Behavior and requirements |
+| `DESIGN.md` or design plan | Required before UI work | Layout, states, visual target |
+| `TASKS.md` | Required before implementation | Task scope and acceptance criteria |
+| `DEPENDENCIES.md` | Required before implementation | Libraries, APIs, env vars |
+| `MOBILE_HARNESS_REPORT.md` | Required after each cycle | Evidence and pass/fail state |
+
+If these docs are missing, Mobile Harness routes to APPFORGE first.
+
+---
+
+## Basic Prompts
+
+Start a new app:
+
+```text
+Use MOBILE-HARNESS.
+Start from a new app idea and orchestrate APPFORGE, Mobile Memory, implementation, QA, and launch prep.
+```
+
+Resume a long-running project:
+
+```text
+Use MOBILE-HARNESS.
+Read MOBILE_MEMORY.md, PRD.md, DESIGN.md, TASKS.md, and DEPENDENCIES.md.
+Continue from NEXT ACTION.
+```
+
+Run one approved task:
+
+```text
+@MOBILE-HARNESS
+MODE: FEATURE_EXECUTION
+PLATFORM: Android
+STACK: Kotlin, Compose, Hilt, Room
+TASK: Implement TASKS.md Task 4, invoice creation form.
+TEST_COMMAND: ./gradlew testDebugUnitTest
+APP_ID: com.example.invoice
+DONE_CRITERIA:
+- User can enter client, amount, due date, notes.
+- Save button disabled until required fields are valid.
+- Saved invoice appears on dashboard after app restart.
+- UI matches design within 90%.
+```
+
+---
+
+## Report Format
+
+Every run produces:
+
+```text
+MOBILE HARNESS REPORT
+=====================
+Platform:
+Task:
+Status: PASS | FAIL | BLOCKED
+Mode:
+Artifacts Read:
+Orchestration State:
+Implementation Summary:
+Code Review:
+Tests:
+PRD Verification:
+UI Match:
+Mobile MCP QA:
+Acceptance Criteria:
+Memory Update:
+Remaining Issues:
+NEXT ACTION:
+```
+
+---
+
+## Pass Criteria
+
+A task is done only when:
+
+- Acceptance criteria pass
+- Tests pass, or skipped tests are explicitly justified
+- PRD verification passes with source references
+- `/prd-verification` proves implementation, UI evidence, tests, and reports match `PRD.md`, `DESIGN.md`, and `TASKS.md`
+- UI match reaches the agreed threshold, default 90%
+- Mobile MCP QA passes, or device QA is explicitly unavailable
+- No CRITICAL platform-review findings remain
+- `MOBILE_MEMORY.md` is updated
+- The report contains one concrete `NEXT ACTION`
+
+---
+
+## Video Demo Script
+
+1. Show `MOBILE-HARNESS` in the README.
+2. Start with: `Use MOBILE-HARNESS. Build this app idea end to end with autonomous execution.`
+3. Show the harness creating or loading `MOBILE_MEMORY.md`.
+4. Show it creating `PRD.md`, `DESIGN.md`, `TASKS.md`, and `DEPENDENCIES.md` instead of asking the user to write them.
+5. Approve the plan once.
+6. Show the harness selecting one task.
+7. Show the harness reading artifacts before editing.
+8. Show one small code change.
+9. Show tests running.
+10. Show PRD verification and UI match review.
+11. Show `/mobile-mcp-qa` device flow.
+12. End on `MOBILE HARNESS REPORT` and updated `MOBILE_MEMORY.md`.

package/docs/mobile-mcp.md

@@ -0,0 +1,172 @@
+# Mobile MCP Integration
+
+Mobile MCP is an MCP server for mobile automation across iOS and Android simulators, emulators, and real devices. It gives AI agents a platform-agnostic way to inspect screens, interact with apps, and run scripted QA flows.
+
+Use it in Mobile AI Agents as the device automation layer for APPFORGE, QA, accessibility checks, and launch readiness.
+
+---
+
+## What Mobile MCP Provides
+
+Mobile MCP supports:
+
+- iOS real devices
+- iOS simulators
+- Android real devices
+- Android emulators
+
+It exposes tools for:
+
+- Listing available devices
+- Reading screen size and orientation
+- Setting orientation
+- Listing installed apps
+- Installing, launching, terminating, and uninstalling apps
+- Taking and saving screenshots
+- Listing UI elements on screen
+- Tapping, double tapping, long pressing, and swiping
+- Typing text
+- Pressing device buttons
+- Opening URLs
+
+---
+
+## Install
+
+Standard MCP config:
+
+```json
+{
+  "mcpServers": {
+    "mobile-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mobilenext/mobile-mcp@latest"]
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest
+```
+
+Codex:
+
+```bash
+codex mcp add mobile-mcp npx "@mobilenext/mobile-mcp@latest"
+```
+
+Cursor:
+
+Go to Cursor Settings -> MCP -> Add new MCP Server. Use command type:
+
+```bash
+npx -y @mobilenext/mobile-mcp@latest
+```
+
+Windsurf:
+
+Add a new MCP server using command type:
+
+```bash
+npx @mobilenext/mobile-mcp@latest
+```
+
+---
+
+## Mobile AI Agents Usage
+
+### APPFORGE
+
+Use Mobile MCP in APPFORGE Stage 7 Full QA:
+
+```text
+/mobile-mcp-qa
+```
+
+Then provide:
+
+- Platform
+- App package name or bundle ID
+- Build path if needed
+- Flow to test
+- Expected result
+- Edge cases
+
+### UI Match Review
+
+Use screenshots and element lists to compare implementation against the approved design:
+
+- Layout
+- Spacing
+- Text
+- Empty states
+- Loading states
+- Error states
+- Accessibility labels
+
+### Launch QA
+
+Before store submission, use Mobile MCP to verify:
+
+- First launch
+- Main flow
+- Offline behavior
+- App restart
+- Rotation
+- Permission denial
+- Crash-prone paths
+- Store screenshot screens
+
+---
+
+## Example Prompt
+
+```text
+/mobile-mcp-qa
+PLATFORM: Android
+APP_ID: com.example.invoice
+BUILD_PATH: app/build/outputs/apk/debug/app-debug.apk
+FLOW:
+1. Launch app.
+2. Create a new invoice.
+3. Save it.
+4. Restart app.
+5. Confirm invoice persists.
+EXPECTED:
+Invoice remains visible after restart with correct client, amount, due date, and status.
+EDGE_CASES:
+Rotate dashboard, enter invalid amount, deny notification permission.
+```
+
+---
+
+## Recommended QA Evidence
+
+For every important flow, save:
+
+- Initial screen screenshot
+- Form filled screenshot
+- Success state screenshot
+- Error state screenshot
+- Restart or rotation screenshot
+- Accessibility element list
+- Bugs with exact repro steps
+
+---
+
+## Safety Rules
+
+- Do not automate actions in third-party apps unless the user explicitly asks and owns the account/session.
+- Do not submit real payments, ratings, reviews, or irreversible actions during QA.
+- Prefer test accounts and sandbox builds.
+- Record package names, device names, and build versions in every report.
+
+---
+
+## References
+
+- Mobile MCP GitHub: https://github.com/mobile-next/mobile-mcp
+- Mobile MCP package: https://www.npmjs.com/package/@mobilenext/mobile-mcp