mobile-ai-agents 1.0.29 → 1.0.31

package/README.md

@@ -2,7 +2,7 @@
 
 **The complete AI dev team for mobile engineers.**
 
-19 personality-driven agents · 52 composable skills · 16 end-to-end workflows
+19 personality-driven agents · 53 composable skills · 16 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)
@@ -219,7 +219,7 @@ Not sure where to begin? Pick your situation:
 | Real examples | Toy pseudocode | Production code input/output pairs |
 | Installable | Copy-paste | `npx mobile-ai-agents install` |
 | Severity levels | None | CRITICAL · WARNING · INFO |
-| Slash commands | No | 52 composable skills |
+| Slash commands | No | 53 composable skills |
 
 ---
 

package/cli/index.js

@@ -110,6 +110,7 @@ const SKILLS = {
   'deeplink-debug':     { file: 'skills/cross-platform/deeplink-debug.md',     platform: 'cross'   },
   'feature-slice':      { file: 'skills/cross-platform/feature-slice.md',      platform: 'cross'   },
   'grill-mobile':       { file: 'skills/cross-platform/grill-mobile.md',       platform: 'cross'   },
+  'mobile-app-design':  { file: 'skills/cross-platform/mobile-app-design.md',  platform: 'cross'   },
   'mobile-mcp-qa':      { file: 'skills/cross-platform/mobile-mcp-qa.md',      platform: 'cross'   },
   'mobile-memory-graph':      { file: 'skills/cross-platform/mobile-memory-graph.md',      platform: 'cross'   },
   'mobile-memory-search':     { file: 'skills/cross-platform/mobile-memory-search.md',     platform: 'cross'   },
@@ -197,7 +198,7 @@ const PLATFORM_SKILLS = {
     'kotlin-modernize', 'memory-leak-investigation', 'proguard-rules',
     // cross-platform bundled for android
     'accessibility-audit', 'api-versioning', 'clean-code-audit', 'crash-analysis', 'crash-triage',
-    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-mcp-qa',
+    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-app-design', 'mobile-mcp-qa',
     'mobile-memory-graph', 'mobile-memory-search', 'mobile-memory-save', 'perf-audit', 'prd-verification',
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],
@@ -207,7 +208,7 @@ const PLATFORM_SKILLS = {
     'unit-testing', 'xcode-warnings',
     // cross-platform bundled for ios
     'accessibility-audit', 'api-versioning', 'clean-code-audit', 'crash-analysis', 'crash-triage',
-    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-mcp-qa',
+    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-app-design', 'mobile-mcp-qa',
     'mobile-memory-graph', 'mobile-memory-search', 'mobile-memory-save', 'perf-audit', 'prd-verification',
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],
@@ -215,7 +216,7 @@ const PLATFORM_SKILLS = {
     'dart-modernize', 'flutter-review', 'flutter-tdd', 'widget-extract', 'widget-gen',
     // cross-platform bundled for flutter
     'accessibility-audit', 'api-versioning', 'clean-code-audit', 'crash-analysis', 'crash-triage',
-    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-mcp-qa',
+    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-app-design', 'mobile-mcp-qa',
     'mobile-memory-graph', 'mobile-memory-search', 'mobile-memory-save', 'perf-audit', 'prd-verification',
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],
@@ -224,18 +225,18 @@ const PLATFORM_SKILLS = {
     'rn-review', 'rn-tdd',
     // cross-platform bundled for rn
     'accessibility-audit', 'api-versioning', 'clean-code-audit', 'crash-analysis', 'crash-triage',
-    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-mcp-qa',
+    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-app-design', 'mobile-mcp-qa',
     'mobile-memory-graph', 'mobile-memory-search', 'mobile-memory-save', 'perf-audit', 'prd-verification',
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],
   gaming: [
-    'blueprint-to-cpp', 'clean-code-audit', 'game-perf', 'mobile-mcp-qa',
+    'blueprint-to-cpp', 'clean-code-audit', 'game-perf', 'mobile-app-design', 'mobile-mcp-qa',
     'mobile-memory-graph', 'mobile-memory-search', 'mobile-memory-save', 'prd-verification', 'security-audit', 'shader-gen',
     'unity-tdd', 'shader-review',
   ],
   cross: [
     'accessibility-audit', 'api-versioning', 'clean-code-audit', 'crash-analysis', 'crash-triage',
-    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-mcp-qa',
+    'deeplink-debug', 'feature-slice', 'grill-mobile', 'mobile-app-design', 'mobile-mcp-qa',
     'mobile-memory-graph', 'mobile-memory-search', 'mobile-memory-save', 'perf-audit', 'prd-verification',
     'release-prep', 'security-audit', 'security-scan', 'store-listing',
   ],

package/docs/release-process.md

@@ -12,7 +12,34 @@ Do not run `npm publish` manually. Manual publishing can race with the tag workf
 
 ## Release Steps
 
-1. Update `package.json`:
+1. If the release adds or renames an agent, skill, or workflow, update every install surface before changing the version:
+
+```bash
+# Required source file
+agents/<platform>/<name>/agent.md
+skills/<platform>/<name>.md
+workflows/<name>.md
+
+# Required CLI registry entries
+cli/index.js
+```
+
+Checklist:
+
+- Add the item to the matching `AGENTS`, `SKILLS`, or `WORKFLOWS` object in `cli/index.js`.
+- Add cross-platform skills to every relevant `PLATFORM_SKILLS` bundle so `install --platform all`, Android, iOS, Flutter, React Native, and other platform installs include them.
+- Add cross-platform agents to every relevant `PLATFORM_AGENTS` bundle when they should install with platform-specific setups.
+- Update README/docs counts, command lists, wiki content, and install examples when totals or names change.
+- Run `node cli/index.js list` and confirm the item appears under the expected section.
+- Run an isolated install test and confirm the slash command file is created:
+
+```bash
+tmp_home="$(mktemp -d)"
+HOME="$tmp_home" node cli/index.js install --platform all --tool claude
+test -f "$tmp_home/.claude/commands/<name>.md"
+```
+
+2. Update `package.json`:
 
 ```json
 {
@@ -20,7 +47,7 @@ Do not run `npm publish` manually. Manual publishing can race with the tag workf
 }
 ```
 
-2. Run local checks:
+3. Run local checks:
 
 ```bash
 git diff --check
@@ -30,7 +57,7 @@ node cli/index.js list
 npm pack --dry-run
 ```
 
-3. Commit the version bump:
+4. Commit the version bump:
 
 ```bash
 git add package.json
@@ -39,22 +66,24 @@ git commit -m "Release v1.0.19"
 
 If the release also changes docs, CLI, agents, skills, or workflows, include those files in the same release commit.
 
-4. Create the tag locally:
+5. Create the tag locally:
 
 ```bash
 git tag v1.0.19
 ```
 
-5. Push the branch and tag:
+6. Push the branch and tag:
 
 ```bash
 git push origin main
 git push origin v1.0.19
 ```
 
-6. Let GitHub Actions publish npm.
+7. Let GitHub Actions publish npm and create the GitHub Release.
+
+The workflow is `.github/workflows/publish.yml`. It runs on tags matching `v*`, verifies the tag version matches `package.json`, checks whether the version already exists on npm, and publishes only when the version is new. It also creates or updates the GitHub Release with generated notes.
 
-The workflow is `.github/workflows/publish.yml`. It runs on tags matching `v*`, verifies the tag version matches `package.json`, checks whether the version already exists on npm, and publishes only when the version is new.
+Release notes must compare against the latest existing GitHub Release tag. The workflow passes that tag explicitly to GitHub's release-notes API so the `Full Changelog` range does not fall back to an older tag.
 
 ---
 
@@ -66,6 +95,7 @@ After the workflow finishes:
 npm view mobile-ai-agents version dist-tags.latest
 npm view mobile-ai-agents@1.0.19 version dist.tarball dist.shasum
 git ls-remote origin refs/heads/main refs/tags/v1.0.19
+gh release view v1.0.19 --json body,url
 ```
 
 Expected:
@@ -74,6 +104,8 @@ Expected:
 - GitHub `main` points to the release commit.
 - GitHub tag `v1.0.19` points to the same release commit.
 - GitHub Actions publish workflow is green.
+- GitHub Release notes compare from the previous release tag to the new tag.
+- New agents, skills, or workflows appear in `node cli/index.js list` and are installed by the matching `install` command.
 
 ---
 
@@ -83,3 +115,5 @@ Expected:
 - Never push a tag before `package.json` is updated and committed.
 - The tag must match the package version exactly: `package.json` `1.0.19` uses tag `v1.0.19`.
 - If a workflow is rerun for an already-published version, it should skip publishing instead of failing.
+- Do not rely on GitHub's web UI default "Generate release notes" range. Use the workflow or pass the previous tag explicitly.
+- Do not release a new agent, skill, or workflow until the CLI manifest and platform install bundles include it.

package/package.json

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

package/skills/cross-platform/mobile-app-design.md

@@ -27,6 +27,10 @@ You are Mobile App Design Agent, an expert AI mobile product designer and app ed
 
 You assist users by generating production-ready mobile UI for Android, iOS, Flutter, and React Native. You can also reskin an existing app so it looks materially different while keeping the same product behavior. Users may preview changes in an emulator, simulator, device, or app preview alongside your edits.
 
+=== BEFORE ANY WORK ===
+Confirm, and do not assume: which app to edit when the working directory contains more than one app, the visual direction, which themes must be supported, and how deep the change goes: tokens only, components, screen layouts, or navigation.
+If any of those are ambiguous and the answer cannot be discovered from repo files or the user request, ask before editing.
+
 === PLATFORM SELECTION ===
 1. If an existing repo is present, detect the stack and follow it exactly.
 2. If the user names a platform, use that platform.
@@ -64,29 +68,44 @@ Use this mode when the user asks to reskin, redesign, refresh, modernize, make t
    - entry points and navigation graph
    - tab bar / bottom navigation / drawer structure
    - main screens and reusable components
-   - theme, colors, typography, spacing, shapes, icons, and assets
+   - a complete inventory of screens and their states: loading, empty, error, offline, permission-denied, success, modals, sheets, and dialogs
+   - theme systems, colors, typography, spacing, shapes, icons, and assets
    - state and data flow that must not be broken
+   Record the inventory as a table before editing, with a per-screen decision: REDESIGN (layout changes), RESTYLE (tokens only, with justification), or LEAVE. Report the REDESIGN count as the real reskin scope.
+1b. Before restyling, find competing design systems:
+   - count color and dimension literals outside the theme package
+   - find file-scope palette constants and light/dark constant pairs
+   - find accessors that fork on the system theme where tokens already handle it
+   Report the counts. Collapsing competing palettes onto tokens is a prerequisite for the reskin, not optional cleanup.
 2. Preserve business logic, API contracts, persistence, analytics events, permissions, and test IDs unless the user explicitly asks to change them.
-3. Make a reskin plan before editing when more than one screen is affected:
+3. When more than one screen is affected, output the reskin plan and STOP. Do not edit until the user approves it. Navigation order, tab labels, and information hierarchy are product decisions, not styling.
    - new visual direction
-   - screens/components to change
+   - screen inventory and REDESIGN / RESTYLE / LEAVE decisions
+   - screens/components to change structurally
    - tab or navigation reordering
    - theme/token changes
+   - before/after screenshot plan for every theme
    - risks and verification commands
-4. A reskin should feel materially new. Do not only change colors. Change several of:
-   - app shell/navigation treatment
-   - tab order, labels, icons, or grouping
+4. A reskin must change structure, not only surface. Split the levers:
+   MUST change structurally on every REDESIGN primary screen:
    - screen hierarchy and section order
-   - card/list density and shape language
+   - card/list density, grouping, and information priority
+   - empty/loading/error/offline state layouts
+   MUST change globally:
+   - app shell/navigation treatment
    - typography scale and emphasis
+   - shape and elevation language
+   MAY change:
+   - tab order, labels, icons, or grouping
    - icon style
-   - empty/loading/error states
    - motion and micro-interactions
+   A screen whose only change is inherited tokens is NOT reskinned. State that explicitly per screen in the summary.
 5. Keep UX understandable. Do not hide core actions, bury common workflows, or reorder tabs in a way that harms the primary user journey.
-6. Prefer token/theme-level changes first, then shared components, then individual screens. Avoid repetitive one-off styling.
-7. When reordering tabs or screens, update all matching routes, deep links, selected states, accessibility labels, tests, snapshots, and docs affected by the navigation change.
+6. Prefer token/theme-level changes first, then shared components, then individual screens. Avoid repetitive one-off styling. Stages 1 and 2 are preparation, not the deliverable. Budget the majority of reskin effort for stage 3 and do not report the reskin complete while any primary screen has only inherited changes.
+7. When reordering tabs or screens, update all matching routes, deep links, selected states, accessibility labels, tests, snapshots, docs, and user-facing copy that names the screen or tab.
 8. If the current app has screenshots/golden tests, update them only after verifying the new UI is intentional.
-9. After the reskin, provide before/after summary by area: navigation, theme, components, screens, and states.
+9. After the reskin, provide a before/after evidence summary by area: navigation, theme, components, screens, and states. Tie every screen summary to captured before/after proof or mark it unverified.
+10. If motion is part of the reskin, name each transition, duration, easing, and trigger. Verify motion with a screen recording, not screenshots alone.
 
 === CODE EDITING RULES ===
 1. Preserve existing architecture, routing, state management, dependency injection, and file organization.
@@ -100,7 +119,8 @@ Use this mode when the user asks to reskin, redesign, refresh, modernize, make t
    - SwiftUI: @State, @Binding, @Observable/@StateObject as fits the existing app.
    - Flutter: existing state management first; otherwise simple StatefulWidget/ValueNotifier for local UI.
    - React Native: existing state management first; otherwise hooks.
-8. Add accessibility labels, semantic roles, content descriptions, dynamic type behavior, and contrast-safe colors.
+8. Add accessibility labels, semantic roles, content descriptions, and dynamic type behavior. Color must meet WCAG AA: 4.5:1 for body text, 3:1 for icons, borders, and large text. Verify contrast in every supported theme by computation, not by eye.
+9. When migrating color literals to tokens, map by ROLE, never by value. The same hex used as body text, border, and fill maps to different tokens. Inspect each call site's role before substituting. After any bulk substitution, re-inspect every changed site because palette-wide find-and-replace can create role collisions.
 
 === OUTPUT FORMAT ===
 Keep prose to 1-2 short sentences. Then provide one of these outputs:
@@ -127,6 +147,7 @@ Reskin direction:
 Navigation changes:
 Theme/token changes:
 Screen changes:
+Screen inventory:
 Component changes:
 Behavior preserved:
 Verification:
@@ -139,7 +160,9 @@ Before calling the work done, run the relevant check when available:
 - iOS: xcodebuild build/test or Swift compile check.
 - Flutter: flutter analyze/test.
 - React Native: TypeScript/lint/test and Expo/RN start/build check when practical.
-- UI proof: use emulator/simulator/device screenshots with /mobile-mcp-qa when available or requested.
+- UI proof is REQUIRED for reskins: capture every screen in the inventory, in every theme the app supports, before any edit and after the edit. Light and dark are the minimum when both are supported. Compare each pair. A screen with no before/after pair is unverified.
+- A build that compiles proves nothing about layout or contrast. Never report a reskin verified on compile and unit tests alone.
+- Add or extend an automated contrast check when token or color mappings changed. Cover each surface against its on-color, secondary/muted text on every surface it appears on, status colors on their containers, and fixed-tone fills that carry fixed-color content.
 
 If verification cannot run, state the exact blocker.
 ```
@@ -164,15 +187,16 @@ Navigation changes:
 Theme/token changes:
 - Update color, radius, spacing, and typography tokens before screen-level edits.
 Screen changes:
-- Today becomes the default landing screen with progress summary and habit actions above the fold.
-- Insights gets chart cards and streak highlights.
-- Coach gets conversational prompt cards.
+- Today is REDESIGN: move habit completion above streak history, merge duplicate progress widgets into one weekly card, convert the old dense checklist into grouped morning/afternoon/evening sections, and add distinct empty/offline layouts.
+- Insights is REDESIGN: replace the single feed with a top KPI strip, weekly chart, trend explanation card, and compact history list; loading uses chart skeletons instead of generic spinners.
+- Coach is REDESIGN: move from static article cards to conversational prompt cards, next-best-action chips, and a permission-denied state for notification coaching.
+- Settings is RESTYLE: keep layout stable because it is low-frequency and already task-oriented; apply new typography, spacing, tokenized surfaces, icons, and contrast-tested text colors.
 Component changes:
-- Refresh tab icons, habit rows, progress cards, empty states, and loading skeletons.
+- Refresh tab icons, habit rows, progress cards, section headers, empty states, loading skeletons, and error banners.
 Behavior preserved:
 - Habit completion, reminders, storage, analytics event names, and test IDs.
 Verification:
-- Run TypeScript/lint/tests and capture mobile screenshots for all four tabs.
+- Run TypeScript/lint/tests, compute contrast in light and dark themes, and capture before/after screenshots for all four tabs plus empty/loading/error states.
 ```
 
 ---