Repository navigation
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.
Choose BEGINNER_GUIDED mode if you have only an app idea, do not know the right mobile stack, or want each checkpoint explained in plain language. It uses the same rigorous build and QA gates as the standard harness.
Use APPFORGE alone when you only want planning documents. Use Mobile Harness when you want the plan implemented, verified, tested on a device, saved to memory, and continued task by task.
For organization-wide use, add HARNESS_POLICY.json and follow the Enterprise Contract. Governed runs add risk classification, scoped change budgets, owners, policy gates, rollback, expiring exceptions, hashed evidence, and machine-readable CI results.
npx mobile-ai-agents harness policy init --profile enterprise
npx mobile-ai-agents harness policy validateMOBILE-HARNESS
├── APPFORGE → idea, PRD, design, tasks, roadmap
├── Mobile Memory → long-term memory across days/weeks
├── AXIOM/SWIFT/DART/BRIDGE → platform code review
├── /mobile-app-design → screens, navigation, redesigns, and reskins
├── /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. Mobile Flight Recorder records the end-of-session handoff so another session can resume from the exact next action.
The fixed loop is:
PLAN -> DESIGN -> TASK -> IMPLEMENT -> VERIFY -> DEVICE PROOF -> MEMORY -> NEXT ACTION
Mobile Harness asks four simple questions: what the app does and who it serves, whether it targets Android/iPhone/both, which languages you know, and whether you want a learning prototype, polished demo, or production app. It inspects an existing project before recommending a stack.
For a new project, its defaults are native Compose for Android, native SwiftUI for Apple platforms, React Native with Expo for cross-platform TypeScript developers, and Flutter for teams that accept Dart and prioritize consistent custom UI. The recommendation includes reasons and tradeoffs; it is not treated as universally correct.
Before coding it creates:
-
PRD.mdfor the user problem and requirements. -
DESIGN.mdfor screens, states, navigation, accessibility, and screenshot proof. -
TASKS.mdfor small independently verifiable work items. -
DEPENDENCIES.mdfor tools, services, keys, and setup. -
ROADMAP.mdfor milestones and deferred scope. -
MOBILE_MEMORY.mdfor decisions, progress, blockers, and the next action.
It stops for approval before the first code change and before credentials, destructive actions, paid services, irreversible migrations, public deployment, or store release.
Use MOBILE-HARNESS in BEGINNER_GUIDED mode.
App idea: A simple meal planner for busy parents.
Target platform: Not sure.
Experience: I know basic TypeScript and this is my first mobile app.
Goal: A polished demo.
Recommend the stack, explain why, create the planning documents, and stop for approval before coding.
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.
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 |
ROADMAP.md |
Required for idea-to-app work | Milestones, sequence, deferred scope, release checkpoints |
HARNESS_POLICY.json |
Required for enterprise/regulated runs | Risk rules, gates, owners, commands, protected paths, evidence, exceptions |
MOBILE_HARNESS_REPORT.md |
Required after each cycle | Evidence and pass/fail state |
.mobile-ai-agents/harness/runs/<runId>/result.json |
Required for governed runs | CI and audit result |
If these docs are missing, Mobile Harness routes to APPFORGE first.
Start a new app:
Use MOBILE-HARNESS.
Start from a new app idea and orchestrate APPFORGE, Mobile Memory, implementation, QA, and launch prep.
Resume a long-running project:
Use MOBILE-HARNESS.
Read MOBILE_MEMORY.md, PRD.md, DESIGN.md, TASKS.md, and DEPENDENCIES.md.
Continue from NEXT ACTION.
Run one approved task:
@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%.
Every run produces:
MOBILE HARNESS REPORT
=====================
Platform:
Task:
Status: PASS | FAIL | BLOCKED
Mode:
Current Loop Stage:
Run ID:
Policy:
Risk:
Repository State:
Scope:
Beginner Checkpoint:
Artifacts Read:
Orchestration State:
Gate Decisions:
Exceptions:
Implementation Summary:
Code Review:
Tests:
PRD Verification:
UI Match:
Mobile MCP QA:
Acceptance Criteria:
Memory Update:
Evidence Manifest:
Rollback:
Remaining Issues:
NEXT ACTION:
A task is done only when:
- Acceptance criteria pass
- Tests pass, or skipped tests are explicitly justified
- PRD verification passes with source references
-
/prd-verificationproves implementation, UI evidence, tests, and reports matchPRD.md,DESIGN.md, andTASKS.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.mdis updated - The report contains one concrete
NEXT ACTION
- Show
MOBILE-HARNESSin the README. - Start with:
Use MOBILE-HARNESS. Build this app idea end to end with autonomous execution. - Show the harness creating or loading
MOBILE_MEMORY.md. - Show it creating
PRD.md,DESIGN.md,TASKS.md, andDEPENDENCIES.mdinstead of asking the user to write them. - Approve the plan once.
- Show the harness selecting one task.
- Show the harness reading artifacts before editing.
- Show one small code change.
- Show tests running.
- Show PRD verification and UI match review.
- Show
/mobile-mcp-qadevice flow. - End on
MOBILE HARNESS REPORTand updatedMOBILE_MEMORY.md.
Getting Started
Documentation
- All Documentation
- Installation
- Figma MCP and Design Handoff
- Figma Spec Tools
- Core Loops
- Mobile Engineering Loop
- Mobile Memory
- Performance Loop
Reference
- Agents
- Platform Guide
- Skills and Prompts
- Android Device QA Setup
- Mobile App Design Skill
- Mobile Harness
- Enterprise Mobile Harness
- Workflows
- Reference
Community
Repository github.com/salmanashraf/mobile-ai-agents
Version: v1.0.38 · MIT License