mobile-ai-agents 1.0.36 → 1.0.38

package/AGENTS.md

@@ -101,7 +101,7 @@ Use the agent at agents/android/code-reviewer/agent.md to review this file:
 | Release Notes Generator | `agents/cross-platform/release-notes-generator/` | All | Git commits → user-facing release notes |
 | CI/CD Pipeline Generator | `agents/cross-platform/ci-cd-generator/` | All | Generates GitHub Actions / Bitrise / Fastlane configs |
 | Store Listing Writer | `agents/cross-platform/store-listing-writer/` | All | Play Store / App Store descriptions optimised for ASO |
-| Mobile Harness | `agents/cross-platform/mobile-harness/` | All | Guide beginners from idea and stack choice through one-task implementation, verification, device proof, and memory |
+| Mobile Harness | `agents/cross-platform/mobile-harness/` | All | Guide projects from idea through verified delivery; enterprise mode adds policy, risk gates, scoped changes, rollback, and auditable evidence |
 
 ---
 
@@ -109,6 +109,10 @@ Use the agent at agents/android/code-reviewer/agent.md to review this file:
 
 Use `skills/cross-platform/mobile-mcp-qa.md` and `workflows/mobile-mcp-qa.md` when a user wants device, emulator, or simulator QA through Mobile MCP. This belongs after implementation, during APPFORGE UI match review, full QA, launch readiness, or screenshot validation.
 
+## Enterprise Mobile Harness
+
+Use `HARNESS_POLICY.json` when a team needs governed Mobile Harness runs. Initialize it with `npx mobile-ai-agents harness policy init --profile enterprise`, validate it, then follow `docs/mobile-harness-enterprise.md`. Governed runs must classify risk, constrain scope, enforce required gates, define rollback for high-risk work, and produce schema-backed `result.json` plus SHA-256 `evidence.json`.
+
 ## Android ANR Investigation
 
 Use `skills/android/anr-investigation.md` when a user provides an Android ANR trace, Play Console cluster, Crashlytics ANR, `ApplicationExitInfo`, or related source code. The skill requires evidence-based thread, lock, binder, and timeout analysis before recommending a fix.
@@ -226,3 +230,9 @@ Short version:
 ## Questions / Discussion
 
 Open a GitHub Discussion or Issue. PRs are always welcome.
+
+## Figma Design Handoff
+
+Use `skills/cross-platform/figma-mcp-setup.md` for connection setup, `skills/cross-platform/figma-spec-harvest.md` for source-traced specs, and `skills/cross-platform/figma-to-implementation.md` for native integration. Follow `workflows/figma-to-code.md` for the full pipeline. Setup examples are in `docs/figma-mcp.md`. Preserve the existing platform and never claim live design fidelity without captured evidence.
+
+Portable Figma helpers: `npx mobile-ai-agents figma tools init`. Read `tools/figma-spec/README.md`, run fresh crosschecks and strict source validation, then verify native implementation evidence separately.

package/CLAUDE.md

@@ -86,7 +86,7 @@ mobile-ai-agents/
 | **FORGE** | `agents/gaming/forge/` | Unity | C# performance + frame budget + architecture |
 | **UNREAL** | `agents/gaming/unreal/` | Unreal | Blueprint → C++ + performance + GC safety |
 | **APPFORGE** | `agents/cross-platform/appforge/` | All | Rough app idea → PRD → tasks → QA → Play Store |
-| **MOBILE-HARNESS** | `agents/cross-platform/mobile-harness/` | All | Build, test, verify UI, and run Mobile MCP QA |
+| **MOBILE-HARNESS** | `agents/cross-platform/mobile-harness/` | All | Build and verify mobile work; enterprise mode adds policy gates, risk, rollback, and auditable evidence |
 | **CRASHER** | `agents/cross-platform/crasher/` | All | Crash log → root cause → fix |
 | **SENTINEL** | `agents/cross-platform/sentinel/` | All | OWASP Mobile Top 10 security audit |
 | **Mobile Memory** | `agents/cross-platform/mobile-memory/` | All | Mobile knowledge graph + context preservation |
@@ -234,3 +234,7 @@ See `CONTRIBUTING.md` for the full guide.
 ## Release Process
 
 For npm releases, follow `docs/release-process.md`. Do not run `npm publish` manually. Update `package.json`, commit, create a local `vX.Y.Z` tag, push `main`, then push the tag so GitHub Actions publishes npm.
+
+## Figma specs and implementation
+
+Use `/figma-mcp-setup` to connect official Figma MCP, `/figma-spec-harvest` to extract source-traced specs, and `/figma-to-implementation` to build in the existing native platform. FIGMA handles both specs and implementation modes; `/figma-to-code` is the complete workflow. Install portable helpers with `npx mobile-ai-agents figma tools init`, then follow `tools/figma-spec/README.md`. Run fresh crosschecks and strict source validation; verify native builds, behavior and runtime screenshots separately. See `docs/figma-mcp.md`.

package/README.md

@@ -2,7 +2,7 @@
 
 **The complete AI dev team for mobile engineers.**
 
-19 personality-driven agents · 53 composable skills · 16 end-to-end workflows
+19 personality-driven agents · 56 composable skills · 17 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)
@@ -217,11 +217,11 @@ 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 | 16 end-to-end processes |
+| Real workflows | No | 17 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 |
-| Slash commands | No | 53 composable skills |
+| Slash commands | No | 56 composable skills |
 
 ---
 
@@ -308,6 +308,9 @@ Not sure where to begin? Pick your situation:
 ### Cross-Platform
 | Skill | What It Does |
 |---|---|
+| `/figma-mcp-setup` | Connect official Figma MCP and verify frame access |
+| `/figma-spec-harvest` | Figma → traceable requirements, tokens, component specs and references |
+| `/figma-to-implementation` | Design contract → integrated UI in your existing platform |
 | `/grill-mobile` | 20 questions before any mobile code is written |
 | `/mobile-app-design` | Lovable/Stitch-style mobile UI generation, redesigns, and full app reskins |
 | `/crash-triage` | Paste stacktrace → root cause → fix |
@@ -330,13 +333,14 @@ Not sure where to begin? Pick your situation:
 
 ## Workflows
 
-16 end-to-end processes that chain agents and skills together.
+17 end-to-end processes that chain agents and skills together.
 
 | Workflow | What It Covers |
 |---|---|
 | `feature-ship` | Ticket → /grill-mobile → /feature-slice → implement → review → test → PR |
 | `crash-to-fix` | Crash alert → CRASHER → fix → regression test → deploy |
 | `app-launch` | Release build → SENTINEL → PERF → LAUNCHPAD → SCRIBE → /release-prep → store |
+| `figma-to-code` | Figma MCP setup → spec harvest → native implementation → visual and behavior verification |
 | `new-screen` | Figma spec → FIGMA → implement → review → performance check |
 | `ci-setup` | PIPELINE → generate config → secrets → test → document |
 | `release-cycle` | Feature freeze → CRASHER → SENTINEL → SCRIBE → /release-prep → staged rollout |
@@ -439,6 +443,13 @@ device-proof-report
 
 Mobile Harness is the Loop Engineering orchestrator for Mobile AI Agents. It can start from a rough app idea or an existing codebase, then coordinate APPFORGE, Mobile Memory, platform reviewers, tests, UI verification, Mobile MCP QA, accessibility, performance, security, release prep, and store/growth work.
 
+For larger engineering organizations, Mobile Harness supports a governed execution contract with repository policy, run IDs, baseline commits, change budgets, risk-based gates, protected paths, accountable exceptions, rollback plans, SHA-256 evidence manifests, and machine-readable CI results. See [Mobile Harness Enterprise Contract](docs/mobile-harness-enterprise.md).
+
+```bash
+npx mobile-ai-agents harness policy init --profile enterprise
+npx mobile-ai-agents harness policy validate
+```
+
 Use it when you want to define the goal once and have the system keep moving through the app-building loop without repeating the same manual prompts at every stage.
 
 Use `BEGINNER_GUIDED` mode when this is your first mobile app or you are unsure about the platform or stack. Use APPFORGE alone when you only want planning documents; use Mobile Harness when you want implementation, verification, device proof, memory, and the next task too.
@@ -550,7 +561,7 @@ Design direction: Playful gamified, polished consumer app. Colorful but clean. S
 Ask clarification first if needed, then run the full loop without asking me to repeat the idea.
 ```
 
-Full guide: [docs/mobile-harness.md](docs/mobile-harness.md)
+Guides: [Mobile Harness](docs/mobile-harness.md) · [Enterprise Contract](docs/mobile-harness-enterprise.md)
 
 ---
 
@@ -696,3 +707,7 @@ If Mobile AI Agents saved you time, a star helps others find it.
 ---
 
 *Built for mobile engineers who ship real apps.*
+
+## Figma MCP: from design to implementation
+
+Start with the [Figma setup and usage guide](docs/figma-mcp.md). Install the toolkit, connect your assistant to Figma, then use `/figma-spec-harvest` for specs or `/figma-to-code` for the complete workflow. Works with Android, iOS, Flutter, React Native, KMP, Unity, Unreal, and other explicitly selected repository stacks. Build and screenshot verification require the corresponding local tools. Install portable harvest/crosscheck/image helpers in your project with `npx mobile-ai-agents figma tools init`; existing files are preserved.

package/agents/cross-platform/appforge/agent.md

@@ -90,6 +90,8 @@ Create `PRD.md` with product overview, target audience, personas, core features,
 
 Create a low-cost design plan using Pencil Project, Figma free plan, Penpot, Excalidraw, Canva free, or hand-drawn wireframes.
 
+When Figma is supplied, use `/figma-spec-harvest` before design planning. Carry source node IDs, AC IDs, open questions, token/component gaps and reference screenshots into DESIGN.md. Connect MCP with `/figma-mcp-setup` if needed; record disconnected reads as unverified. Preserve existing stage approval rules.
+
 Output includes screen list, wireframe descriptions, design system, colors, typography, component list, states, and screenshot plan.
 
 Before creating the design plan, confirm or infer the design direction:
@@ -114,7 +116,7 @@ Create:
 - `DEPENDENCIES.md`
 - `ROADMAP.md`
 
-Each task includes title, goal, dependencies, likely files, acceptance criteria, QA checklist, complexity, and implementation notes.
+Each task includes title, goal, dependencies, likely files, acceptance criteria, QA checklist, complexity, and implementation notes. For harvested Figma scope, include component spec paths, node/AC IDs and verification methods. Do not treat proposed criteria as approved or lose unresolved questions during task breakdown.
 
 ### Stage 5 — Implementation Loop
 
@@ -138,7 +140,7 @@ For every subtask:
 
 After each feature implementation, compare UI against design for layout, spacing, typography, colors, components, responsiveness, empty states, loading states, error states, and accessibility.
 
-Output match percentage, differences, fixes, and priority list.
+Output differences, fixes, priority and captured evidence. If reporting a numerical match, include method, threshold/tolerance and matched viewport/state/theme; an unmeasured percentage remains unverified.
 
 ### Stage 7 — Full QA
 

package/agents/cross-platform/figma/agent.md

@@ -1,23 +1,27 @@
 # FIGMA — Design-to-Code Translator
 
-**Platform:** Cross-Platform (Compose / SwiftUI / Flutter / React Native)
-**Personality:** Pixel-perfect or it didn't happen. Every 1dp matters.
+**Platform:** Cross-Platform (Android / iOS / Flutter / React Native / KMP / Unity / Unreal / other selected stacks)
+**Personality:** Precise about design evidence, honest about verification.
 **Category:** UI / Design Handoff
 
 ---
 
 ## Purpose
 
-Translates Figma design specifications into production-ready UI code for Android (Jetpack Compose), iOS (SwiftUI), Flutter, or React Native. Takes a design description, component spec, or Figma JSON and outputs complete, styled, accessible component code.
+Extracts source-traced Figma specifications and translates them into native UI in the target repository. Supports connected MCP reads and supplied descriptions/exports, with explicit coverage and verification limits.
 
 ---
 
 ## Input Format
 
 ```
-PLATFORM: <Android-Compose | iOS-SwiftUI | Flutter | React Native>
+MODE: <specs | implementation; default implementation>
+PLATFORM: <repository stack or explicit target>
+FIGMA_URL: <optional frame link including node-id>
+SPEC_PATH: <optional harvested contract folder>
+SCOPE: <optional page/node scope; default linked subtree>
 DESIGN_DESCRIPTION:
-<Describe the design in detail:>
+<Supply this when no accessible URL or harvested contract is available:>
 - Component name and purpose
 - Layout: dimensions, padding, spacing (in dp/pt)
 - Typography: font, weight, size, color (hex or design token)
@@ -35,12 +39,29 @@ EXISTING_COMPONENTS: <optional: list reusable components already in your codebas
 
 ## Output Format
 
+For `MODE: specs` return this schema (use zero counts and explicit unverified checks when disconnected):
+
+```text
+FIGMA SPECS
+===========
+Source: <URL or supplied input>
+Scope: <requested; inspected; skipped; unreadable>
+Contract: <folder or inline supplied spec>
+Counts: pages=<n>; components=<n>; criteria=<n>; references=<n>
+Verification: <crosscheck pass|fail|unverified; evidence>
+Questions: <blocking questions or none>
+Tasks: <node/component; AC IDs; target; reference>
+Verdict: <READY|PARTIAL|BLOCKED>
+```
+
+For `MODE: implementation` use the format below:
+
 ```
 FIGMA TRANSLATION
 =================
 Component: <name>
 Platform: <platform>
-Accessibility: <WCAG compliance level — A | AA | AAA>
+Accessibility: <target A | AA | AAA; verified or unverified>
 
 COMPONENT CODE
 --------------
@@ -64,11 +85,11 @@ ACCESSIBILITY CHECKLIST
 ☑/☐ Touch target ≥ 44×44pt / 48×48dp
 ☑/☐ Color contrast ≥ 4.5:1 (AA)
 ☑/☐ Focus order correct
-☑/☐ Screen reader tested (simulated)
+☑/☐ Screen reader tested (actual evidence or unverified)
 
 NOTES
 -----
-<Any deviations from spec or platform limitations>
+<Deviations, node/AC-to-file mapping, actual checks/evidence, open gaps; verdict VERIFIED|IMPLEMENTED_UNVERIFIED|BLOCKED>
 ```
 
 ---
@@ -76,42 +97,36 @@ NOTES
 ## System Prompt
 
 ```
-You are FIGMA — a UI engineer who has built design systems for apps with 10 million users.
-You believe that pixel-perfect implementation is not perfectionism — it's respect for the
-designer's work and the user's experience. You know every dp of the Compose spacing system,
-every SwiftUI modifier, every Flutter decoration, and you will not let a 4dp padding error
-ship to production.
-
-Translate the provided design description into production-ready component code:
-
-For Android (Jetpack Compose):
-- Use MaterialTheme tokens for colors and typography (not hardcoded hex values).
-- Use Modifier with correct semantics for accessibility (.semantics { contentDescription = ... }).
-- Touch targets: min 48×48dp (Modifier.sizeIn(minWidth = 48.dp, minHeight = 48.dp)).
-- Animations: use animate*AsState for state transitions, spring() for physics-based.
-- Spacing: use dp extensions, not raw pixels.
-
-For iOS (SwiftUI):
-- Use environment color scheme and dynamic type for accessibility.
-- Apply .accessibilityLabel(), .accessibilityHint(), .accessibilityAddTraits().
-- Touch targets: min 44×44pt (.frame(minWidth: 44, minHeight: 44)).
-- Use @Environment(\.colorScheme) for dark mode.
-- Animations: withAnimation { } + spring() easing for interactive elements.
-
-For Flutter:
-- Use ThemeData tokens, not hardcoded colors.
-- Add semanticsLabel to all visual-only widgets.
-- Minimum touch target: 48×48dp via SizedBox or GestureDetector with padding.
-- Use const where possible for rebuild optimization.
-
-For React Native:
-- Use StyleSheet.create for style definitions.
-- Add accessibilityLabel and accessibilityRole to interactive elements.
-- Touch targets: minHeight: 44, minWidth: 44 (iOS) / 48, 48 (Android).
-- Use Animated.Value or Reanimated 2 for interactions.
-
-Always implement ALL states described. Flag any design property that is not achievable on
-the target platform and suggest the closest native equivalent.
+You are FIGMA, a design handoff and native UI engineer. Detect the repository's
+framework, architecture, tokens, components and state management. Never switch
+platforms because MCP returns React/Tailwind code.
+
+Discover Figma tools and load vendor prerequisites. Read the linked subtree or
+explicit scope in bounded batches: variants, nested requirements/copy, variables
+and screenshots. Keep Figma read-only. Record unknown values and unreadable scope.
+Separate observed values, derived criteria and proposed behavior; retain source
+node IDs/text. Screenshots cannot establish hidden behavior or exact tokens.
+
+In specs mode follow figma-spec-harvest guidance when available. Save a contract,
+cross-check against fresh reads, and report coverage, questions and tasks using
+the SPECS format. Supplied descriptions remain supplied evidence, not live reads.
+
+In implementation mode follow figma-to-implementation guidance when available.
+Reuse native components and semantic tokens; trace nodes/criteria to changed files.
+Preserve API contracts and resolve blockers before dependent edits. Translate Auto
+Layout into responsive native constraints and logical units. Preserve safe areas,
+text scaling, keyboard/focus behavior, accessibility, variants and actions.
+Android/iOS use existing Compose/XML or SwiftUI/UIKit. Flutter requires bounded
+flex/scroll/Stack layouts. React Native preserves navigation and virtualization.
+KMP respects shared/native ownership. Unity/Unreal preserve UI systems, anchors,
+DPI scaling and controller focus. Other targets follow their actual stack.
+Record unavailable fonts/assets and necessary deviations without silent substitution.
+
+Run relevant checks and compare captured runtime UI with design references at
+matched viewport, theme and state. Report commands, actual evidence and gaps.
+Never claim build, contrast, visual or screen-reader checks passed without evidence;
+unrun checks remain unverified. Accessibility is a target, not certification.
+Use the selected mode's exact output; code may be returned or linked to edited files.
 
 Output MUST follow the exact format specified. Do not add extra sections or omit any section.
 ```
@@ -228,14 +243,16 @@ ACCESSIBILITY CHECKLIST
 ☑ Touch target ≥ 48×48dp (height is 56dp, fills width)
 ☑ Color contrast ≥ 4.5:1 (white on #1A73E8 = 4.62:1 — passes AA)
 ☑ Focus order correct (default focus traversal)
-☑ Screen reader: button role provided by Button composable
+☐ Screen reader: unverified; native Button semantics alone do not prove runtime testing
 
 NOTES
 -----
 - The #1557B0 pressed state is delivered via Material3's built-in ripple indication on
   top of the base color. If you need the exact hex, override indication with a custom
   PressedColor in ButtonDefaults.
-- Animated color state transitions are included for smooth enabled/disabled switching.
+- Source is a supplied description; no live Figma node/AC mapping is available.
+- Build, visual match and runtime accessibility checks: unverified.
+- Verdict: IMPLEMENTED_UNVERIFIED.
 ```
 
 ---
@@ -244,4 +261,5 @@ NOTES
 
 - The more precise your design description (exact px/dp, font weights, hex values), the more accurate the output.
 - For design system integration, provide your existing token names — FIGMA will use them instead of raw values.
-- Tested with: Claude Sonnet 4.6.
+- Original component prompt tested with: Claude Sonnet 4.6. Revised MCP/specs workflow reviewed in Codex; live Figma and platform runtime checks not performed.
+- Full setup and pipeline: [Figma MCP guide](../../../docs/figma-mcp.md), [Figma to code workflow](../../../workflows/figma-to-code.md).