mobile-ai-agents 1.0.30 → 1.0.32

package/cli/index.js

@@ -245,6 +245,10 @@ const PLATFORM_SKILLS = {
 // Workflows are always installed regardless of platform selection
 const ALL_WORKFLOWS = Object.keys(WORKFLOWS);
 
+function workflowCommandName(name) {
+  return (AGENTS[name] || SKILLS[name]) ? `${name}-workflow` : name;
+}
+
 const PRIMARY_MEMORY_DIR = '.mobile-ai-agents';
 const LEGACY_MEMORY_DIR = '.mobile-agency';
 const MEMORY_DIR = fs.existsSync(path.join(process.cwd(), LEGACY_MEMORY_DIR)) &&
@@ -881,9 +885,10 @@ async function installForClaude(platforms) {
   await Promise.all(ALL_WORKFLOWS.map(async (name) => {
     const meta = WORKFLOWS[name];
     if (!meta) return;
-    const dest = path.join(CLAUDE_COMMANDS_DIR, `${name}.md`);
+    const commandName = workflowCommandName(name);
+    const dest = path.join(CLAUDE_COMMANDS_DIR, `${commandName}.md`);
     await downloadFile(meta.file, [dest]);
-    ok(name);
+    ok(commandName === name ? name : `${name} → ${commandName}`);
   }));
 
   console.log('');
@@ -923,9 +928,10 @@ async function installForCursor(platforms) {
   await Promise.all(ALL_WORKFLOWS.map(async (name) => {
     const meta = WORKFLOWS[name];
     if (!meta) return;
-    const dest = path.join(rulesDir, `${name}.mdc`);
+    const commandName = workflowCommandName(name);
+    const dest = path.join(rulesDir, `${commandName}.mdc`);
     await downloadFile(meta.file, [dest]);
-    ok(name);
+    ok(commandName === name ? name : `${name} → ${commandName}`);
   }));
 
   console.log('');
@@ -1181,10 +1187,11 @@ async function cmdAdd(args) {
       process.exit(1);
     }
     ensureDir(CLAUDE_COMMANDS_DIR);
-    const dest = path.join(CLAUDE_COMMANDS_DIR, `${name}.md`);
+    const commandName = workflowCommandName(name);
+    const dest = path.join(CLAUDE_COMMANDS_DIR, `${commandName}.md`);
     log(`Fetching ${bold(name)} workflow...`);
     await downloadFile(meta.file, [dest]);
-    ok(`${name} → ${dim(dest)}`);
+    ok(`${commandName} → ${dim(dest)}`);
   } else {
     err(`Unknown type: ${type}. Use 'agent', 'skill', or 'workflow'.`);
     process.exit(1);

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,20 +66,20 @@ 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 and create the GitHub Release.
+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.
 
@@ -78,6 +105,7 @@ Expected:
 - 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.
 
 ---
 
@@ -88,3 +116,4 @@ Expected:
 - 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.30",
+  "version": "1.0.32",
   "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.
 ```
 
 ---

package/skills/cross-platform/mobile-mcp-qa.md

@@ -10,7 +10,7 @@
 
 Use Mobile MCP to run AI-assisted QA on a real device, emulator, or simulator. This skill turns a feature flow into a repeatable device test plan using screenshots, accessibility snapshots, element inspection, taps, typing, swipes, app install, app launch, and device orientation checks.
 
-Mobile MCP is best used after implementation, during APPFORGE Stage 7 Full QA, or before store submission.
+Mobile MCP is best used after implementation, during APPFORGE Stage 7 Full QA, after `/mobile-app-design` reskins, or before store submission.
 
 ---
 
@@ -61,6 +61,30 @@ EDGE_CASES:
 <offline, invalid input, rotation, restart, permissions, api errors>
 ```
 
+### Reskin QA Input
+
+Use this format when verifying a `/mobile-app-design` redesign or reskin:
+
+```text
+COMMAND: /mobile-mcp-qa
+MODE: RESKIN_QA
+PLATFORM: <Android | iOS | Flutter | React Native>
+APP_ID: <Android package name or iOS bundle id>
+BUILD_PATH: <optional apk/ipa/app path>
+DEVICE: <optional target device name>
+SUPPORTED_THEMES: <light | dark | light,dark | custom themes>
+SCREEN_INVENTORY:
+| Screen/State | Decision | Expected Change | Route/Tab |
+|---|---|---|---|
+| <screen + state> | REDESIGN | <layout/hierarchy/state change> | <route/tab> |
+BASELINE_EVIDENCE:
+<before screenshots, screenshot paths, or "capture before from current build">
+EXPECTED_REDESIGN:
+<approved reskin plan, navigation changes, theme changes, and state coverage>
+REGRESSION_RISKS:
+<tab reorder, renamed copy, deep links, dark mode, keyboard, safe area, analytics, etc.>
+```
+
 ---
 
 ## Skill Prompt
@@ -68,6 +92,8 @@ EDGE_CASES:
 ```text
 Run a Mobile MCP QA pass for the provided mobile app flow.
 
+If MODE is RESKIN_QA, run the Reskin QA flow instead of ordinary flow QA.
+
 STEP 1 — VERIFY SETUP
 - List available devices.
 - Select the requested device, or choose the first available emulator/simulator.
@@ -101,7 +127,79 @@ Check:
 - App restart preserves required state
 - Offline/API error behavior is user-safe
 
-STEP 5 — REPORT
+RESKIN QA FLOW
+Use this flow when MODE is RESKIN_QA or when the user provides a `/mobile-app-design` screen inventory.
+
+STEP R1 — VERIFY RESKIN INPUTS
+- Read SCREEN_INVENTORY and EXPECTED_REDESIGN.
+- Preserve each inventory decision exactly: REDESIGN, RESTYLE, or LEAVE.
+- Confirm SUPPORTED_THEMES. If the app supports light and dark, both are required.
+- If baseline screenshots are missing and the current build is already the after build, mark before evidence as missing instead of inventing it.
+
+STEP R2 — CAPTURE OR REGISTER BASELINE
+- For each inventory row, attach the provided before screenshot or capture a before screenshot if the baseline build is available.
+- Name evidence predictably: before-<theme>-<screen>-<state>.
+- A screen/state without before evidence is still testable after the edit, but its before/after comparison status is UNVERIFIED.
+
+STEP R3 — CAPTURE AFTER STATE
+- Launch the after build.
+- Visit every screen/state in SCREEN_INVENTORY.
+- Capture after screenshots for every supported theme.
+- For loading, empty, error, offline, permission-denied, and success states, use controlled test data, network toggles, permissions, or documented setup steps when available.
+- Name evidence predictably: after-<theme>-<screen>-<state>.
+
+STEP R4 — VERIFY STRUCTURAL CHANGE
+For each inventory row:
+- REDESIGN must show layout, hierarchy, grouping, density, information-priority, or state-layout changes. Token-only changes are FAIL.
+- RESTYLE may show token/component updates only, but must have a justification.
+- LEAVE should remain intentionally unchanged except for unavoidable global shell or token updates.
+- Mark missing before or after screenshots as UNVERIFIED.
+
+STEP R5 — VERIFY REGRESSIONS
+Check:
+- clipped or overlapping text
+- safe areas, status bar, navigation bar, and notches
+- keyboard avoidance
+- minimum 44pt/48dp touch targets
+- light/dark contrast and invisible text risk
+- tab order, selected state, route names, deep links, and back behavior
+- renamed screen/tab copy across labels, empty states, prompts, and accessibility text
+- loading, empty, error, offline, disabled, permission-denied, and success states
+- orientation when the app supports it
+
+STEP R6 — REPORT RESKIN QA
+Return:
+MOBILE MCP RESKIN QA REPORT
+===========================
+Platform:
+Device:
+App:
+Themes:
+Result: PASS | FAIL | PARTIAL | BLOCKED
+
+Screen Evidence:
+| Screen/State | Decision | Theme | Before | After | Result |
+|---|---|---|---|---|---|
+
+Structural Verification:
+| Screen/State | Decision | Expected Change | Observed Change | Result |
+|---|---|---|---|---|
+
+Regression Checks:
+| Check | Screen/State | Result | Evidence |
+|---|---|---|---|
+
+Issues:
+| Severity | Screen/State | Issue | Evidence | Fix |
+|---|---|---|---|---|
+
+Evidence For PRD Verification:
+- <compact screenshot list and report summary that can be pasted into /prd-verification>
+
+Recommended Next Action:
+<single concrete fix or next test>
+
+STEP 5 — REPORT ORDINARY FLOW QA
 Return:
 MOBILE MCP QA REPORT
 ====================
@@ -129,6 +227,81 @@ Recommended Next Action:
 <single concrete fix or next test>
 ```
 
+### Reskin QA Example
+
+#### Input
+
+```text
+COMMAND: /mobile-mcp-qa
+MODE: RESKIN_QA
+PLATFORM: React Native
+APP_ID: com.example.habits
+SUPPORTED_THEMES: light,dark
+SCREEN_INVENTORY:
+| Screen/State | Decision | Expected Change | Route/Tab |
+|---|---|---|---|
+| Today/populated | REDESIGN | grouped morning/afternoon/evening sections | Today |
+| Today/empty | REDESIGN | coaching empty state with primary action | Today |
+| Insights/populated | REDESIGN | KPI strip + weekly chart + compact history | Insights |
+| Settings/default | RESTYLE | tokenized surfaces and clearer typography | Settings |
+BASELINE_EVIDENCE:
+before-light-today-populated.png, before-dark-today-populated.png,
+before-light-insights-populated.png, before-dark-insights-populated.png
+EXPECTED_REDESIGN:
+Tabs reordered to Today, Insights, Coach, Settings. Today and Insights require structural layout changes. Settings is restyle only.
+REGRESSION_RISKS:
+dark mode contrast, renamed Strategy copy, tab selected state, safe areas
+```
+
+#### Output
+
+```text
+MOBILE MCP RESKIN QA REPORT
+===========================
+Platform: React Native
+Device: iPhone 15 Simulator
+App: com.example.habits
+Themes: light, dark
+Result: FAIL
+
+Screen Evidence:
+| Screen/State | Decision | Theme | Before | After | Result |
+|---|---|---|---|---|---|
+| Today/populated | REDESIGN | light | before-light-today | after-light-today | PASS |
+| Today/populated | REDESIGN | dark | before-dark-today | after-dark-today | PASS |
+| Insights/populated | REDESIGN | light | before-light-insights | after-light-insights | PASS |
+| Insights/populated | REDESIGN | dark | before-dark-insights | after-dark-insights | FAIL |
+| Settings/default | RESTYLE | dark | missing | after-dark-settings | UNVERIFIED |
+
+Structural Verification:
+| Screen/State | Decision | Expected Change | Observed Change | Result |
+|---|---|---|---|---|
+| Today/populated | REDESIGN | grouped sections | sections visible | PASS |
+| Insights/populated | REDESIGN | KPI + chart + history | chart clipped in dark | FAIL |
+| Settings/default | RESTYLE | token updates | no before evidence | UNVERIFIED |
+
+Regression Checks:
+| Check | Screen/State | Result | Evidence |
+|---|---|---|---|
+| Dark contrast | Insights | FAIL | chart label unreadable |
+| Tab selected state | All tabs | PASS | selected indicator moves |
+| Renamed copy | Today | PASS | no stale Strategy copy |
+
+Issues:
+| Severity | Screen/State | Issue | Evidence | Fix |
+|---|---|---|---|---|
+| WARNING | Insights/dark | Chart label has low contrast | after-dark-insights | Use onSurface token |
+| INFO | Settings/default | Missing baseline | after-dark-settings | Capture before image next run |
+
+Evidence For PRD Verification:
+- Today populated: light/dark before-after PASS.
+- Insights dark: FAIL due chart contrast.
+- Settings: UNVERIFIED because baseline missing.
+
+Recommended Next Action:
+Fix Insights dark chart label contrast and rerun Reskin QA for Insights and Settings.
+```
+
 ---
 
 ## Example

package/workflows/mobile-mcp-qa.md

@@ -1,6 +1,7 @@
 # Workflow — Mobile MCP QA
 
 **Type:** Device automation QA  
+**Slash Command:** `/mobile-mcp-qa-workflow` when installed alongside the `/mobile-mcp-qa` skill
 **Agents Used:** APPFORGE, AXIOM / SWIFT / DART / BRIDGE, CRASHER, PERF, Mobile Memory
 **Skills Used:** /mobile-mcp-qa, /accessibility-audit, /perf-audit, /mobile-memory-save