mobile-ai-agents 1.0.25 → 1.0.27

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)
@@ -126,7 +126,7 @@ Platform Plugins: Android · iOS · Flutter · React Native · Kotlin Multiplatf
 | 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` |
+| Performance | Startup, ANR, memory leaks, frame drops, battery, network, app size | `@PERF`, `@FREEZE`, `@RETAINER`, `/perf-audit`, [Performance Loop](docs/performance-loop.md) |
 | 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` |
@@ -137,13 +137,15 @@ Security and performance are built into the loop before release. They are not op
 
 Full guide: [docs/core-loops.md](docs/core-loops.md)
 
+Performance guide: [docs/performance-loop.md](docs/performance-loop.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
+https://github.com/user-attachments/assets/c98d4468-d56d-41ce-b545-7d9fdc43e9d2
 
 `/flutter-review` on a real Flutter project — prioritized findings, zero setup:
 
@@ -213,7 +215,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 +327,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 +342,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 +406,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/core-loops.md

@@ -69,7 +69,7 @@ The user should not have to manually prompt every stage. The system should stop
 | Planning | Turn rough ideas into PRDs, roadmaps, and task slices. | `@APPFORGE`, `/grill-mobile`, `/feature-slice` |
 | Architecture | Review system design, module boundaries, model separation, and clean code. | `@AXIOM`, `/clean-code-audit`, platform reviewers |
 | Development | Implement one feature slice at a time and keep code scoped. | `@MOBILE-HARNESS`, `@FIGMA`, screen builders, code reviewers |
-| Performance | Find and fix startup, ANR, memory, frame, battery, network, and size issues. | `@PERF`, `@FREEZE`, `@RETAINER`, `/perf-audit`, `/anr-investigation` |
+| Performance | Find and fix startup, ANR, memory, frame, battery, network, and size issues. | `@PERF`, `@FREEZE`, `@RETAINER`, `/perf-audit`, `/anr-investigation`, [Performance Loop](performance-loop.md) |
 | Security | Audit OWASP risks, secrets, auth, storage, deep links, WebViews, permissions, logs, and release hardening. | `@SENTINEL`, `security-scanner`, `/security-audit`, `/security-scan` |
 | Testing | Add unit/UI tests, run device QA, check accessibility, and verify PRD/design match. | TDD skills, `/prd-verification`, `/mobile-mcp-qa`, `/accessibility-audit` |
 | Release | Prepare CI/CD, signing, release notes, rollout, and store submission. | `@PIPELINE`, `@SCRIBE`, `/release-prep` |
@@ -117,6 +117,8 @@ Evidence: Play Console ANR trace, startup code, device reproduction
 Output: root cause, fix, verification plan, regression check
 ```
 
+Full Performance Loop guide: [performance-loop.md](performance-loop.md)
+
 ## Marketing Position
 
 Use this sentence when explaining the repo:
@@ -138,6 +140,5 @@ The model is intentionally ahead of the full implementation. The strongest next
 - `/prd-verification` rollout into Mobile Harness and APPFORGE evidence gates
 - Mobile Flight Recorder
 - Device Proof Reports
-- dedicated Performance Loop reports
 - dedicated Security Audit Loop reports
 - Kotlin Multiplatform plugin assets

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/performance-loop.md

@@ -0,0 +1,194 @@
+# Performance Loop
+
+Performance is a first-class Mobile AI Agents loop. Use it when a mobile app is slow, janky, freezing, leaking memory, draining battery, using too much network, or growing too large.
+
+The loop is evidence-first: measure the symptom, choose the right agent or skill, apply the smallest fix, re-measure, save the baseline, and monitor for regressions.
+
+---
+
+## What It Covers
+
+| Area | Symptoms | Best Starting Point |
+|---|---|---|
+| Startup | Cold start, hot start, slow splash, app open delay | `@PERF`, `/perf-audit` |
+| ANR | Frozen UI, input timeout, Play Console ANR | `@FREEZE`, `/anr-investigation` |
+| Memory leaks | Retained Fragment/View/Activity, growing heap, OOM | `@RETAINER`, `/memory-leak-investigation` |
+| Frame drops / jank | Slow scroll, dropped frames, animation stutter | `@PERF`, `/perf-audit`, platform reviewer |
+| Battery | High CPU wakeups, background work, location abuse | `@PERF`, `/perf-audit` |
+| Network | Chatty requests, large payloads, retry storms | `@PERF`, `/perf-audit` |
+| Bundle / app size | Large APK/AAB/IPA, slow download, bloated assets | `@PERF`, `/perf-audit` |
+| Slow screens | Heavy render, blocking IO, expensive lists | `@PERF`, `/perf-audit` |
+| Regression monitoring | Performance gets worse after a PR or release | `perf-sprint`, Mobile Harness |
+
+---
+
+## Agent And Skill Map
+
+| Need | Agent Or Skill | Use It For |
+|---|---|---|
+| Broad performance diagnosis | `@PERF` | Find bottlenecks, prioritize fixes, define measurements |
+| Android ANR investigation | `@FREEZE`, `/anr-investigation` | Thread, lock, binder, and timeout analysis |
+| Android memory leak analysis | `@RETAINER`, `/memory-leak-investigation` | LeakCanary reference path and lifecycle ownership |
+| Screen-level profiling | `/perf-audit` | Main thread, rendering, memory, list, and fix ranking |
+| Compose UI jank | `/compose-review`, `compose-ui-reviewer` | Recomposition, LazyColumn keys, effects, state stability |
+| Flutter rebuilds | `/flutter-review`, `@DART` | Widget rebuilds, state, layout, async handling |
+| React Native re-renders | `performance-optimizer`, `/rn-performance`, `@BRIDGE` | React memoization, FlatList, bridge hot paths |
+| Unity frame budget | `@FORGE`, `/game-perf` | Update loops, GC allocations, draw calls, physics |
+| Device validation | `/mobile-mcp-qa`, `device-proof-report` | Verify performance-sensitive flows on a target device |
+| Delivery orchestration | `@MOBILE-HARNESS`, `perf-sprint` | Run checks after implementation and save evidence |
+
+---
+
+## Loop Steps
+
+```text
+1. IDENTIFY SYMPTOM
+   -> Startup, ANR, memory leak, jank, battery, network, size, or slow screen.
+
+2. COLLECT EVIDENCE
+   -> Device model, OS, app version, commit, user flow, baseline numbers, traces, screenshots, logs.
+
+3. CHOOSE ROUTE
+   -> Select the smallest matching agent or skill from the map.
+
+4. ANALYZE ROOT CAUSE
+   -> Name the hot function, blocked thread, retained owner, expensive render path, or oversized asset.
+
+5. APPLY SMALLEST SAFE FIX
+   -> Change one bottleneck at a time so improvement can be attributed.
+
+6. VERIFY WITH MEASUREMENTS
+   -> Re-run the same flow on the same target and compare before/after numbers.
+
+7. SAVE PERFORMANCE BASELINE
+   -> Write `PERFORMANCE_AUDIT_REPORT.md` and store trace/screenshot links.
+
+8. MONITOR REGRESSIONS
+   -> Add a test, CI threshold, release gate, or follow-up task when possible.
+```
+
+---
+
+## Evidence To Collect
+
+| Platform | Evidence |
+|---|---|
+| Android | Play Console ANR cluster, `traces.txt`, Perfetto/Systrace, Android Studio Profiler, LeakCanary trace, APK Analyzer output, device model, API level |
+| iOS | Instruments Time Profiler, Core Animation, Allocations/Leaks, MetricKit, Xcode Organizer reports, device model, iOS version |
+| Flutter | Flutter DevTools Performance and Memory tabs, rebuild counts, timeline flame chart, package size output |
+| React Native | React DevTools Profiler, Flipper Perf Monitor, Hermes profile, Metro bundle size, native traces |
+| Unity | Unity Profiler, frame debugger, memory snapshot, draw call count, texture memory, target device |
+| Unreal | Unreal Insights, stat unit, stat game, stat RHI, render thread timing, packaged build size |
+
+If there is no baseline, the result is `BLOCKED` or `UNKNOWN`. Do not claim a performance fix without re-measuring.
+
+---
+
+## Android Examples
+
+### ANR During Startup
+
+```text
+Symptom: Play Console reports "Input dispatching timed out" during app launch.
+Evidence: ANR trace shows main thread blocked in RoomDatabase.query().
+Route: @FREEZE + /anr-investigation.
+Fix: Move startup database read to Dispatchers.IO and defer non-critical initialization.
+Verify: Compare cold start time and confirm no main-thread DB query appears in trace.
+Report: PERFORMANCE_AUDIT_REPORT.md with ANR cluster link, before/after startup time, and trace links.
+```
+
+### Fragment Memory Leak
+
+```text
+Symptom: Heap grows after opening and closing ProfileFragment.
+Evidence: LeakCanary shows RecyclerView retaining ProfileAdapter, which retains Fragment views.
+Route: @RETAINER + /memory-leak-investigation.
+Fix: Clear RecyclerView adapter in onDestroyView() and remove view references from adapter callbacks.
+Verify: Reopen/close ProfileFragment five times and confirm LeakCanary no longer reports retained Fragment.
+Report: PERFORMANCE_AUDIT_REPORT.md with retained size before/after and LeakCanary evidence.
+```
+
+---
+
+## Cross-Platform Examples
+
+| Platform | Symptom | Route | Verification |
+|---|---|---|---|
+| iOS | Slow SwiftUI list scroll | `@PERF`, `@SWIFT`, `/ios-performance` | Instruments Core Animation frame times improve |
+| Flutter | Product grid rebuilds every item | `@DART`, `/flutter-review`, `/perf-audit` | DevTools shows fewer rebuilds and frame times under 16ms |
+| React Native | Feed drops frames on like button | `performance-optimizer`, `/rn-performance` | React Profiler shows fewer row renders |
+| Unity | Mobile level spikes GC every few seconds | `@FORGE`, `/game-perf` | Unity Profiler shows no hot-path GC.Alloc spikes |
+| Unreal | Blueprint Tick runs expensive logic | `@UNREAL`, `/game-perf` | Unreal Insights shows reduced game thread time |
+
+---
+
+## Report Format
+
+Create:
+
+```text
+PERFORMANCE_AUDIT_REPORT.md
+```
+
+Use this deterministic format:
+
+```markdown
+# Performance Audit Report
+
+## Summary
+Result: PASS | FAIL | BLOCKED
+Platform:
+Device:
+OS Version:
+App Version:
+Commit:
+Flow:
+Performance Area: Startup | ANR | Memory | Frame | Battery | Network | Size | Slow Screen | Regression
+
+## Baseline
+| Metric | Before | Target | Evidence |
+|---|---:|---:|---|
+
+## Findings
+| ID | Severity | Area | Evidence | Root Cause | Fix Summary |
+|---|---|---|---|---|---|
+
+## Finding Details
+### PERF-001 - <short title>
+- Severity:
+- Area:
+- Evidence:
+- Root Cause:
+- Fix:
+- Verification:
+- Regression Guard:
+
+## Changes Made
+| File | Change | Reason |
+|---|---|---|
+
+## Verification
+| Metric | Before | After | Result | Evidence |
+|---|---:|---:|---|---|
+
+## Device Or Trace Evidence
+- <trace, screenshot, profiler export, issue, or report link>
+
+## Regression Monitoring
+- <test, CI threshold, dashboard, alert, or follow-up issue>
+
+## Next Actions
+1. <highest priority next fix or "None">
+2. <next fix or "None">
+3. <next fix or "None">
+```
+
+---
+
+## Pass/Fail Rules
+
+- `PASS`: The measured bottleneck improved or meets target, and evidence is attached.
+- `FAIL`: The bottleneck remains, got worse, or lacks a safe fix.
+- `BLOCKED`: Required evidence, device, build, credentials, or profiler access is missing.
+
+Performance work is complete only when the report includes before/after measurements and a regression monitoring decision.

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.27",
   "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

package/workflows/perf-sprint.md

@@ -44,6 +44,7 @@ When users are reporting slow performance, or before a major release as a perfor
    ↓ Document: before numbers, after numbers, what changed.
 
 6. DOCUMENT
+   ↓ Write PERFORMANCE_AUDIT_REPORT.md.
    ↓ Add before/after screenshots to PR description.
    ↓ Link to profiler traces in the PR.
    ↓ Add a performance test or threshold to CI so it doesn't regress.
@@ -75,4 +76,5 @@ When users are reporting slow performance, or before a major release as a perfor
 
 - Measured baseline vs. improved numbers
 - Code changes with documented performance rationale
+- `PERFORMANCE_AUDIT_REPORT.md`
 - Performance CI gate to prevent regression