mobile-ai-agents 1.0.25 → 1.0.26

package/README.md

@@ -2,7 +2,7 @@
 
 **The complete AI dev team for mobile engineers.**
 
-19 personality-driven agents · 52 composable skills · 14 end-to-end workflows
+19 personality-driven agents · 52 composable skills · 15 end-to-end workflows
 Android · iOS · Flutter · React Native · Kotlin Multiplatform · Unity · Unreal
 
 [![npm](https://img.shields.io/npm/v/mobile-ai-agents?color=CB3837&label=npm)](https://www.npmjs.com/package/mobile-ai-agents)
@@ -143,7 +143,7 @@ Full guide: [docs/core-loops.md](docs/core-loops.md)
 
 `/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
+https://github.com/user-attachments/assets/c98d4468-d56d-41ce-b545-7d9fdc43e9d2
 
 `/flutter-review` on a real Flutter project — prioritized findings, zero setup:
 
@@ -213,7 +213,7 @@ Not sure where to begin? Pick your situation:
 |---|---|---|
 | Platform knowledge | Generic | Android · iOS · Flutter · React Native · Unity · Unreal |
 | Agent personalities | None | 19 named specialists with opinions |
-| Real workflows | No | 14 end-to-end processes |
+| Real workflows | No | 15 end-to-end processes |
 | Real examples | Toy pseudocode | Production code input/output pairs |
 | Installable | Copy-paste | `npx mobile-ai-agents install` |
 | Severity levels | None | CRITICAL · WARNING · INFO |
@@ -325,7 +325,7 @@ Not sure where to begin? Pick your situation:
 
 ## Workflows
 
-14 end-to-end processes that chain agents and skills together.
+15 end-to-end processes that chain agents and skills together.
 
 | Workflow | What It Covers |
 |---|---|
@@ -340,6 +340,7 @@ Not sure where to begin? Pick your situation:
 | `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 |
 | `issue-to-agent` | GitHub issue → classify → route to agents/skills → implementation and verification plan |
+| `device-proof-report` | Mobile MCP evidence → screenshots, assertions, bugs, and pass/fail proof |
 | `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 |
@@ -403,6 +404,21 @@ Mobile MCP gives Mobile AI Agents a device automation layer for iOS and Android
 
 Use it inside APPFORGE Stage 7 Full QA, UI match review, launch readiness checks, and screenshot validation. Full guide: [docs/mobile-mcp.md](docs/mobile-mcp.md)
 
+### Device Proof Reports
+
+Use `device-proof-report` after `/mobile-mcp-qa` when you need evidence that survives beyond the chat. It turns Mobile MCP actions, screenshots, element snapshots, crashes/logs, accessibility notes, and assertions into `DEVICE_QA_REPORT.md`.
+
+This helps teams prove that a build was installed, launched, tested on a named device, and checked against expected behavior. Use it for PR handoff, release gates, Mobile Harness reports, screenshot validation, and any bug fix where "works on my machine" is not enough.
+
+```text
+device-proof-report
+1. Read Mobile MCP screenshots and actions
+2. Record device, OS, app id, build, commit, and orientation
+3. Map each PASS/FAIL/BLOCKED result to evidence
+4. List crashes, accessibility notes, performance notes, and bugs
+5. Produce DEVICE_QA_REPORT.md with next fixes
+```
+
 ---
 
 ## Mobile Harness — Top-Level Orchestrator

package/cli/index.js

@@ -136,6 +136,7 @@ const WORKFLOWS = {
   'perf-sprint':       { file: 'workflows/perf-sprint.md'       },
   'mobile-memory-workflow':  { file: 'workflows/mobile-memory-workflow.md'  },
   'issue-to-agent':    { file: 'workflows/issue-to-agent.md'    },
+  'device-proof-report': { file: 'workflows/device-proof-report.md' },
   'appforge-workflow': { file: 'workflows/appforge-workflow.md' },
   'mobile-mcp-qa':     { file: 'workflows/mobile-mcp-qa.md'     },
   'mobile-harness':    { file: 'workflows/mobile-harness.md'    },

package/docs/index.html

@@ -337,7 +337,7 @@
   <div class="stats">
     <div class="stat"><div class="stat-num">19</div><div class="stat-label">Agents</div></div>
     <div class="stat"><div class="stat-num">35</div><div class="stat-label">Skills</div></div>
-    <div class="stat"><div class="stat-num">14</div><div class="stat-label">Workflows</div></div>
+    <div class="stat"><div class="stat-num">15</div><div class="stat-label">Workflows</div></div>
     <div class="stat"><div class="stat-num">7</div><div class="stat-label">Plugin Tracks</div></div>
   </div>
 </div>
@@ -549,7 +549,7 @@
 <section id="workflows">
   <div class="container">
     <div class="section-label">Workflows</div>
-    <h2>14 end-to-end processes.</h2>
+    <h2>15 end-to-end processes.</h2>
     <p class="section-sub">The differentiator. No other mobile AI toolkit has these — full sequences that chain agents and skills from ticket to store.</p>
 
     <div class="workflow-list">
@@ -593,6 +593,10 @@
         <div class="workflow-name">issue-to-agent</div>
         <div class="workflow-desc">GitHub issue → classify → route to agents/skills → implementation and verification plan</div>
       </div>
+      <div class="workflow-item">
+        <div class="workflow-name">device-proof-report</div>
+        <div class="workflow-desc">Mobile MCP evidence → screenshots, assertions, bugs, and pass/fail proof</div>
+      </div>
     </div>
   </div>
 </section>

package/docs/mobile-mcp.md

@@ -155,6 +155,8 @@ For every important flow, save:
 - Accessibility element list
 - Bugs with exact repro steps
 
+For auditable handoff, run the `device-proof-report` workflow after `/mobile-mcp-qa`. It produces `DEVICE_QA_REPORT.md` with build/install proof, screenshots, actions, assertions, crashes/logs, accessibility notes, pass/fail summary, and next fixes.
+
 ---
 
 ## Safety Rules

package/docs/wiki.md

@@ -14,10 +14,11 @@
 6. [Platform-by-Platform Agent Guide](#6-platform-by-platform-agent-guide)
 7. [How Skills Work](#7-how-skills-work)
 8. [How Prompts Work](#8-how-prompts-work)
-9. [Input Format Reference](#9-input-format-reference)
-10. [Output Format Reference](#10-output-format-reference)
-11. [Contributing a New Agent](#11-contributing-a-new-agent)
-12. [FAQ](#12-faq)
+9. [Device Proof Reports](#9-device-proof-reports)
+10. [Input Format Reference](#10-input-format-reference)
+11. [Output Format Reference](#11-output-format-reference)
+12. [Contributing a New Agent](#12-contributing-a-new-agent)
+13. [FAQ](#13-faq)
 
 ---
 
@@ -438,7 +439,61 @@ Prompts are one-shot — they don't require a system prompt, don't require a str
 
 ---
 
-## 9. Input Format Reference
+## 9. Device Proof Reports
+
+Device Proof Reports turn Mobile MCP QA evidence into a durable `DEVICE_QA_REPORT.md` file. Use them after `/mobile-mcp-qa` when you need to prove that a mobile build was installed, launched, tested, screenshotted, and verified on a named device, emulator, or simulator.
+
+### What it helps with
+
+- PR handoff: reviewers can see exact screenshots, actions, assertions, and failures.
+- Release gates: teams can verify launch, core flows, restart, rotation, and edge cases before store submission.
+- Bug fixes: every PASS or FAIL references evidence instead of relying on memory.
+- Mobile Harness: `DEVICE_QA_REPORT.md` can be attached to `MOBILE_HARNESS_REPORT.md`.
+- Future AI sessions: Mobile Memory can preserve device, build, screenshots, result, and next action.
+
+### When to run it
+
+Run `/mobile-mcp-qa` first to interact with the app and capture screenshots. Then run `device-proof-report` to package the evidence into a structured report.
+
+```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 invoice.
+3. Restart app.
+4. Confirm invoice persists.
+
+device-proof-report
+Use the Mobile MCP evidence from this QA pass and produce DEVICE_QA_REPORT.md.
+```
+
+### What the report proves
+
+`DEVICE_QA_REPORT.md` records:
+
+- Device, OS version, orientation, app id, build, and commit
+- Whether the build installed and launched
+- Every action performed and the target used
+- Assertions mapped to screenshot or UI evidence
+- Screenshots and what each screenshot proves
+- Crashes, logs, accessibility notes, and performance notes
+- Issues found with severity, repro steps, and suggested fixes
+- Pass/fail/blocked summary and next fixes
+
+### Best practices
+
+- Use stable screenshot filenames such as `01-home.png` and `04-after-restart.png`.
+- Do not mark a result PASS unless it references evidence.
+- For sensitive apps, use sandbox accounts and redact tokens, PII, payment data, and health data.
+- For failed flows, include the exact repro step and expected behavior.
+- After the report is created, save the result with `/mobile-memory-save`.
+
+---
+
+## 10. Input Format Reference
 
 Most agents use a consistent key-value input format:
 
@@ -463,7 +518,7 @@ MULTI_LINE_FIELD:
 
 ---
 
-## 10. Output Format Reference
+## 11. Output Format Reference
 
 ### Code Review Agents (Android, iOS)
 
@@ -537,7 +592,46 @@ OVERALL VERDICT: PASS / NEEDS WORK / INACCESSIBLE
 
 ---
 
-## 11. Contributing a New Agent
+### Device Proof Report
+
+```
+# Device QA Report
+
+## Summary
+Result: PASS | FAIL | BLOCKED
+Platform:
+Device:
+OS Version:
+Orientation:
+App ID:
+Build:
+Commit:
+Flow:
+
+## Build And Launch
+| Check | Evidence | Result |
+|---|---|---|
+
+## Actions Performed
+| Step | Action | Target | Evidence | Result |
+|---|---|---|---|---|
+
+## Assertions
+| ID | Expected Behavior | Evidence | Result |
+|---|---|---|---|
+
+## Screenshots
+| Screenshot | Screen | Proves |
+|---|---|---|
+
+## Issues Found
+| ID | Severity | Screen | Issue | Repro Step | Suggested Fix |
+|---|---|---|---|---|---|
+```
+
+---
+
+## 12. Contributing a New Agent
 
 ### Before you start
 
@@ -584,7 +678,7 @@ An agent is accepted if:
 
 ---
 
-## 12. FAQ
+## 13. FAQ
 
 **Q: Which LLM works best?**  
 A: Claude Sonnet 4.6 and GPT-4o both produce high-quality structured output for all agents. Smaller models (GPT-4o-mini, Claude Haiku) work for simpler agents (prompts, skills) but may produce less consistent structured output for complex agents (BLoC Feature Builder, CI/CD Generator).
@@ -612,4 +706,4 @@ A: Yes. The repo is MIT licensed — free to use, modify, and incorporate into c
 
 ---
 
-*Last updated: v1.0.0 — May 2026*
+*Last updated: v1.0.25 — August 2026*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-ai-agents",
-  "version": "1.0.25",
+  "version": "1.0.26",
   "description": "AI agents, skills, and Loop Engineering workflows for building, testing, auditing, and releasing mobile apps.",
   "bin": {
     "mobile-ai-agents": "cli/index.js",

package/workflows/device-proof-report.md

@@ -0,0 +1,223 @@
+# Workflow - Device Proof Report
+
+**Type:** Device evidence and QA reporting
+**Agents Used:** MOBILE-HARNESS, APPFORGE, AXIOM / SWIFT / DART / BRIDGE, CRASHER, PERF, Mobile Memory
+**Skills Used:** /mobile-mcp-qa, /prd-verification, /accessibility-audit, /perf-audit, /mobile-memory-save
+
+---
+
+## When to Use
+
+Use this workflow after a feature has been installed, launched, tested, screenshotted, and verified on an Android device/emulator or iOS device/simulator with Mobile MCP.
+
+The goal is not just to say the app works. The goal is to produce portable proof that a reviewer, teammate, or future AI session can inspect.
+
+---
+
+## Inputs
+
+- Platform: Android or iOS
+- Device name and OS version
+- App package name or bundle ID
+- Build path, build number, commit SHA, or release version
+- User flow under test
+- Expected behavior from PRD, design, task, or acceptance criteria
+- Mobile MCP screenshots
+- Mobile MCP UI element snapshots when available
+- Actions performed through Mobile MCP
+- Crash logs, console logs, or test output
+- Accessibility and performance notes
+
+---
+
+## Evidence Rules
+
+- Every PASS must reference evidence: screenshot, element snapshot, log, test output, or exact Mobile MCP action result.
+- Every FAIL must include a reproducible step and the expected behavior.
+- Every BLOCKED result must name the missing device, build, credential, app id, or artifact.
+- Do not use screenshots as decoration. Each screenshot must prove a state, transition, or failure.
+- Record package names, device names, OS versions, build identifiers, and orientation.
+- For sensitive apps, use sandbox accounts and redact credentials, tokens, PII, payment data, and health data.
+
+---
+
+## Steps
+
+```text
+1. PREPARE
+   -> Read PRD, design, task, and expected flow.
+   -> Confirm app id, build, target device, and Mobile MCP availability.
+
+2. INSTALL AND LAUNCH
+   -> Install the build when a build path is provided.
+   -> Launch the app by package name or bundle ID.
+   -> Capture initial screenshot and visible UI elements.
+
+3. EXECUTE FLOW
+   -> Run each user action through Mobile MCP.
+   -> Capture evidence after major state changes.
+   -> Record exact action, target, result, and screenshot id.
+
+4. VERIFY STATES
+   -> Compare visible UI, data, navigation, restart behavior, rotation, and edge cases against expected behavior.
+   -> Mark each assertion PASS, FAIL, or BLOCKED.
+
+5. REVIEW QUALITY
+   -> Note crashes, logs, accessibility issues, layout issues, and obvious performance symptoms.
+   -> Escalate to CRASHER, /accessibility-audit, or /perf-audit when evidence shows a deeper issue.
+
+6. WRITE REPORT
+   -> Produce DEVICE_QA_REPORT.md using the deterministic format below.
+   -> Attach or reference screenshots by stable filename.
+
+7. SAVE CONTEXT
+   -> Run /mobile-memory-save or update MOBILE_MEMORY.md with device, build, result, and next action.
+```
+
+---
+
+## Output
+
+Create:
+
+```text
+DEVICE_QA_REPORT.md
+```
+
+Format:
+
+```markdown
+# Device QA Report
+
+## Summary
+Result: PASS | FAIL | BLOCKED
+Platform:
+Device:
+OS Version:
+Orientation:
+App ID:
+Build:
+Commit:
+Flow:
+
+## Build And Launch
+| Check | Evidence | Result |
+|---|---|---|
+| Build installed | <path/version> | PASS/FAIL/BLOCKED |
+| App launched | <screenshot id> | PASS/FAIL/BLOCKED |
+| Initial screen visible | <screenshot id> | PASS/FAIL/BLOCKED |
+
+## Actions Performed
+| Step | Action | Target | Evidence | Result |
+|---|---|---|---|---|
+
+## Assertions
+| ID | Expected Behavior | Evidence | Result |
+|---|---|---|---|
+
+## Screenshots
+| Screenshot | Screen | Proves |
+|---|---|---|
+
+## Crashes And Logs
+- <crash/log finding or "None">
+
+## Accessibility Notes
+- <finding or "None">
+
+## Performance Notes
+- <finding or "None">
+
+## Issues Found
+| ID | Severity | Screen | Issue | Repro Step | Suggested Fix |
+|---|---|---|---|---|---|
+
+## Pass/Fail Summary
+- Passed:
+- Failed:
+- Blocked:
+
+## Next Fixes
+1. <highest priority fix or "None">
+2. <next fix or "None">
+3. <next fix or "None">
+```
+
+---
+
+## Example
+
+```markdown
+# Device QA Report
+
+## Summary
+Result: FAIL
+Platform: Android
+Device: Pixel_7_API_35
+OS Version: Android 15
+Orientation: Portrait
+App ID: com.example.invoice
+Build: app-debug.apk
+Commit: 7f31abc
+Flow: Create invoice and verify restart persistence
+
+## Build And Launch
+| Check | Evidence | Result |
+|---|---|---|
+| Build installed | app-debug.apk | PASS |
+| App launched | screenshots/01-home-empty.png | PASS |
+| Initial screen visible | Home dashboard | PASS |
+
+## Actions Performed
+| Step | Action | Target | Evidence | Result |
+|---|---|---|---|---|
+| 1 | Tap | Add Invoice | screenshots/02-add-invoice.png | PASS |
+| 2 | Type | Client field | screenshots/03-form-filled.png | PASS |
+| 3 | Tap | Save | screenshots/04-dashboard-saved.png | PASS |
+| 4 | Relaunch | App process | screenshots/05-dashboard-restart.png | FAIL |
+
+## Assertions
+| ID | Expected Behavior | Evidence | Result |
+|---|---|---|---|
+| QA-001 | Invoice appears after save | screenshots/04-dashboard-saved.png | PASS |
+| QA-002 | Invoice persists after restart | screenshots/05-dashboard-restart.png | FAIL |
+
+## Screenshots
+| Screenshot | Screen | Proves |
+|---|---|---|
+| screenshots/01-home-empty.png | Dashboard | App launches |
+| screenshots/04-dashboard-saved.png | Dashboard | Invoice saved |
+| screenshots/05-dashboard-restart.png | Dashboard | Persistence fails |
+
+## Crashes And Logs
+- None.
+
+## Accessibility Notes
+- Amount field should describe expected currency format.
+
+## Performance Notes
+- No visible launch delay during this pass.
+
+## Issues Found
+| ID | Severity | Screen | Issue | Repro Step | Suggested Fix |
+|---|---|---|---|---|---|
+| QA-BUG-001 | CRITICAL | Dashboard | Invoice disappears after restart | Save invoice, relaunch app | Await local database write before navigation |
+
+## Pass/Fail Summary
+- Passed: Install, launch, create invoice, save invoice.
+- Failed: Restart persistence.
+- Blocked: None.
+
+## Next Fixes
+1. Fix invoice persistence after app restart.
+2. Add a restart persistence regression test.
+3. Rerun this Device Proof Report.
+```
+
+---
+
+## Mobile Harness Integration
+
+Use this after `/mobile-mcp-qa` inside MOBILE-HARNESS when the user needs auditable evidence for a task, release gate, screenshot review, or handoff.
+
+For each completed task, attach `DEVICE_QA_REPORT.md` to `MOBILE_HARNESS_REPORT.md` and reference the exact screenshots used as proof.

package/workflows/mobile-harness.md

@@ -209,8 +209,9 @@ For each task:
 10. Verify behavior against `PRD.md`.
 11. Verify UI against design.
 12. Run `/mobile-mcp-qa` if device automation is available.
-13. Write `MOBILE_HARNESS_REPORT.md`.
-14. Update `MOBILE_MEMORY.md`.
+13. Produce `DEVICE_QA_REPORT.md` with the `device-proof-report` workflow when screenshots or device proof are required.
+14. Write `MOBILE_HARNESS_REPORT.md`.
+15. Update `MOBILE_MEMORY.md`.
 
 After a task passes, continue to the next safe task automatically when the user has approved autonomous execution for the project. Stop only at human gates defined in the Autonomy Contract.
 

package/workflows/mobile-mcp-qa.md

@@ -164,6 +164,8 @@ Create:
 MOBILE_MCP_QA_REPORT.md
 ```
 
+For release gates, PR handoff, or Mobile Harness evidence, follow this with the `device-proof-report` workflow to produce `DEVICE_QA_REPORT.md`.
+
 Format:
 
 ```markdown