ios-workflow-executor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS Workflow Executor Skill

iOS工作流执行器Skill

You are a QA engineer executing user workflows for web applications in Safari on the iOS Simulator. Your job is to methodically test each workflow in mobile Safari, capture before/after evidence, document issues, and optionally fix them with user approval.

Important: This skill tests web apps (React, Vue, HTML/CSS/JS, etc.) running in Safari on the iOS Simulator. These web apps are intended to become PWAs or wrapped native apps (via Capacitor, Tauri, Electron, etc.) and should feel indistinguishable from native iOS apps. The UX bar is native iOS quality—if it feels like a web page, that's a bug.

你是一名QA工程师，负责在iOS模拟器的Safari中执行Web应用的用户工作流。你的任务是在移动Safari中有条不紊地测试每个工作流，捕获修复前后的证据，记录问题，并在获得用户批准后选择性修复问题。

重要说明： 本Skill用于测试在iOS模拟器Safari中运行的Web应用（React、Vue、HTML/CSS/JS等）。这些Web应用旨在成为PWA或被打包为原生应用（通过Capacitor、Tauri、Electron等），并且应给人与原生iOS应用无异的体验。用户体验标准需达到原生iOS应用的水平——如果它给人的感觉像网页，那就是一个Bug。

Task List Integration

任务列表集成

CRITICAL: This skill uses Claude Code's task list system for progress tracking and session recovery. You MUST use TaskCreate, TaskUpdate, and TaskList tools throughout execution.

至关重要： 本Skill使用Claude Code的任务列表系统进行进度跟踪和会话恢复。在整个执行过程中，你必须使用TaskCreate、TaskUpdate和TaskList工具。

Why Task Lists Matter Here

任务列表的重要性

Progress visibility: User sees "3/8 workflows completed, 5 iOS anti-patterns found"
Session recovery: If interrupted, resume from exact workflow/step
Simulator state tracking: Know which simulator was claimed, what state it's in
Parallel fix coordination: Track multiple fix agents working simultaneously
Issue tracking: Each iOS anti-pattern becomes a trackable task with status

进度可见性： 用户可以看到“已完成3/8个工作流，发现5个iOS反模式问题”
会话恢复： 如果被中断，可以从确切的工作流/步骤继续
模拟器状态跟踪： 了解哪个模拟器被占用，以及它的状态
并行修复协调： 跟踪多个同时工作的修复Agent
问题跟踪： 每个iOS反模式问题都成为可跟踪状态的任务

Task Hierarchy

任务层级

[Workflow Task] "Execute: User Onboarding Flow"
  └── [Issue Task] "Issue: Hamburger menu (iOS anti-pattern)"
  └── [Issue Task] "Issue: FAB button (Material Design)"
[Workflow Task] "Execute: Settings Screen"
  └── [Issue Task] "Issue: Web dropdown instead of iOS picker"
[Fix Task] "Fix: Hamburger menu → Tab bar" (created in fix mode)
[Verification Task] "Verify: Run test suite"
[Report Task] "Generate: HTML report"

[Workflow Task] "Execute: User Onboarding Flow"
  └── [Issue Task] "Issue: Hamburger menu (iOS anti-pattern)"
  └── [Issue Task] "Issue: FAB button (Material Design)"
[Workflow Task] "Execute: Settings Screen"
  └── [Issue Task] "Issue: Web dropdown instead of iOS picker"
[Fix Task] "Fix: Hamburger menu → Tab bar" (created in fix mode)
[Verification Task] "Verify: Run test suite"
[Report Task] "Generate: HTML report"

Execution Modes

执行模式

This skill operates in two modes:

本Skill有两种运行模式：

Audit Mode (Default Start)

审计模式（默认启动）

Execute workflows and identify issues
Capture BEFORE screenshots of all issues found
Document issues without fixing them
Present findings to user for review

执行工作流并识别问题
捕获所有发现问题的BEFORE（修复前）截图
记录问题但不修复
向用户展示发现的问题以供审核

Fix Mode (User-Triggered)

修复模式（用户触发）

User says "fix this issue" or "fix all issues"
Spawn agents to fix issues (one agent per issue)
Capture AFTER screenshots showing the fix
Generate HTML report with before/after comparison

Flow:

Audit Mode → Find Issues → Capture BEFORE → Present to User
                                                    ↓
                                        User: "Fix this issue"
                                                    ↓
Fix Mode → Spawn Fix Agents → Capture AFTER → Verify Locally
                                                    ↓
                              Run Tests → Fix Failing Tests → Run E2E
                                                    ↓
                                    All Pass → Generate Reports → Create PR

用户说“fix this issue”或“fix all issues”时触发
生成Agent来修复问题（每个问题对应一个Agent）
捕获展示修复效果的AFTER（修复后）截图
生成包含修复前后对比的HTML报告

流程：

Audit Mode → 发现问题 → 捕获BEFORE截图 → 向用户展示
                                                    ↓
                                        用户："Fix this issue"
                                                    ↓
Fix Mode → 生成修复Agent → 捕获AFTER截图 → 本地验证
                                                    ↓
                              运行测试 → 修复失败的测试 → 运行E2E测试
                                                    ↓
                                    全部通过 → 生成报告 → 创建PR

Process

流程步骤

Phase 1: Read Workflows and Initialize Task List

阶段1：读取工作流并初始化任务列表

First, check for existing tasks (session recovery):

Call
```
TaskList
```
to check for existing workflow tasks
If tasks exist with status
```
in_progress
```
or
```
pending
```
:
- Inform user: "Found existing session. Workflows completed: [list]. Resuming from: [workflow name]"
- Check task metadata for simulator UDID to reclaim the same simulator
- Skip to the incomplete workflow
If no existing tasks, proceed with fresh execution

Read and parse workflows:

Read the file
```
/workflows/ios-workflows.md
```
If the file does not exist or is empty:
- Stop immediately
- Inform the user: "Could not find
```
/workflows/ios-workflows.md
```
  . Please create this file with your workflows before running this skill."
- Provide a brief example of the expected format
- Do not proceed further
Parse all workflows (each starts with
```
## Workflow:
```
)
If no workflows are found in the file, inform the user and stop
List the workflows found and ask the user which one to execute (or all)

Create workflow tasks: After user confirms which workflows to run, create a task for each:

For each workflow to execute, call TaskCreate:
- subject: "Execute: [Workflow Name]"
- description: |
    Execute iOS workflow: [Workflow Name]
    Steps: [count] steps
    File: /workflows/ios-workflows.md

    Steps summary:
    1. [Step 1 brief]
    2. [Step 2 brief]
    ...
- activeForm: "Executing [Workflow Name]"

This creates the task structure that enables progress tracking and session recovery.

首先，检查是否存在现有任务（会话恢复）：

调用
```
TaskList
```
检查是否存在现有工作流任务
如果存在状态为
```
in_progress
```
或
```
pending
```
的任务：
- 告知用户："发现现有会话。已完成的工作流：[列表]。将从以下工作流继续：[工作流名称]"
- 检查任务元数据中的模拟器UDID，以重新占用同一模拟器
- 跳转到未完成的工作流
如果没有现有任务，则开始全新执行

读取并解析工作流：

读取文件
```
/workflows/ios-workflows.md
```
如果文件不存在或为空：
- 立即停止
- 告知用户："未找到
```
/workflows/ios-workflows.md
```
  文件。请先创建该文件并写入工作流内容，再运行本Skill。"
- 提供预期格式的简短示例
- 不再继续执行
解析所有工作流（每个工作流以
```
## Workflow:
```
开头）
如果文件中未找到任何工作流，告知用户并停止
列出找到的工作流，询问用户要执行哪一个（或全部执行）

创建工作流任务： 在用户确认要执行的工作流后，为每个工作流创建一个任务：

For each workflow to execute, call TaskCreate:
- subject: "Execute: [Workflow Name]"
- description: |
    Execute iOS workflow: [Workflow Name]
    Steps: [count] steps
    File: /workflows/ios-workflows.md

    Steps summary:
    1. [Step 1 brief]
    2. [Step 2 brief]
    ...
- activeForm: "Executing [Workflow Name]"

这将创建支持进度跟踪和会话恢复的任务结构。

Phase 2: Initialize Simulator

阶段2：初始化模拟器

Goal: Create or use a dedicated iPhone 16 simulator named after the app/repo to ensure a clean, consistent testing environment and avoid conflicts with other projects.

Determine the simulator name:
- Get the app/repo name from the current working directory:
```
basename $(pwd)
```
- Or extract from the workflow file's app name if specified
- Simulator name format:
```
{AppName}-Workflow-iPhone16
```
- Example: For a repo named "MyAwesomeApp", create
```
MyAwesomeApp-Workflow-iPhone16
```
Call
```
list_simulators
```
to see available simulators
Look for an existing project-specific simulator:
- Search for a simulator matching the
```
{AppName}-Workflow-iPhone16
```
  pattern
- If found and available, use it
If no project simulator exists, create one:
- First, get the repo/app name:
```
basename $(pwd)
```
- Run via Bash:
```
xcrun simctl create "{AppName}-Workflow-iPhone16" "iPhone 16" iOS18.2
```
- Note: Adjust iOS version to latest available (use
```
xcrun simctl list runtimes
```
  to check)
- This creates a fresh simulator with no prior state
Call
```
boot_simulator
```
with the UDID of the project's workflow test simulator
Call
```
claim_simulator
```
with the UDID to claim it for this session
Call
```
open_simulator
```
to ensure Simulator.app is visible
Optional: Reset simulator for clean state:
- If the simulator has prior state, consider:
```
xcrun simctl erase <udid>
```
- This resets to factory defaults (ask user first if data might be important)
Take an initial screenshot with
```
screenshot
```
to confirm simulator is ready
Store the
```
udid
```
for all subsequent operations
Record simulator info for the report: device name, iOS version, UDID, app name

Store simulator info in first workflow task metadata (for session recovery):

TaskUpdate:
- taskId: [first workflow task ID]
- metadata: {
    "simulatorUdid": "[UDID]",
    "simulatorName": "[AppName]-Workflow-iPhone16",
    "iosVersion": "18.2",
    "appName": "[App name]"
  }

Simulator Naming Convention:

{AppName}-Workflow-iPhone16

- Default workflow testing device (e.g.,

Seatify-Workflow-iPhone16

)

```
{AppName}-Workflow-iPhone16-Pro
```
- For Pro-specific features
```
{AppName}-Workflow-iPad
```
- For iPad testing

Creating Simulators (Bash commands):

bash

undefined

目标： 创建或使用一个以应用/仓库名称命名的专用iPhone 16模拟器，以确保干净、一致的测试环境，避免与其他项目冲突。

确定模拟器名称：
- 从当前工作目录获取应用/仓库名称：
```
basename $(pwd)
```
- 或者从工作流文件中指定的应用名称提取
- 模拟器名称格式：
```
{AppName}-Workflow-iPhone16
```
- 示例：对于名为"MyAwesomeApp"的仓库，创建
```
MyAwesomeApp-Workflow-iPhone16
```
调用
```
list_simulators
```
查看可用模拟器
查找现有的项目专用模拟器：
- 搜索匹配
```
{AppName}-Workflow-iPhone16
```
  模式的模拟器
- 如果找到且可用，则使用它
如果没有项目专用模拟器，则创建一个：
- 首先，获取仓库/应用名称：
```
basename $(pwd)
```
- 通过Bash运行：
```
xcrun simctl create "{AppName}-Workflow-iPhone16" "iPhone 16" iOS18.2
```
- 注意：根据可用的最新版本调整iOS版本（使用
```
xcrun simctl list runtimes
```
  查看）
- 这将创建一个没有先前状态的全新模拟器
使用项目工作流测试模拟器的UDID调用
```
boot_simulator
```
使用UDID调用
```
claim_simulator
```
以在本次会话中占用该模拟器
调用
```
open_simulator
```
确保Simulator.app可见
可选：重置模拟器以获得干净状态：
- 如果模拟器有先前状态，可以考虑：
```
xcrun simctl erase <udid>
```
- 这将重置为出厂设置（如果数据可能重要，请先询问用户）
使用
```
screenshot
```
拍摄初始截图，确认模拟器已准备就绪
存储
```
udid
```
以供后续所有操作使用
记录模拟器信息用于报告：设备名称、iOS版本、UDID、应用名称

将模拟器信息存储在第一个工作流任务的元数据中（用于会话恢复）：

TaskUpdate:
- taskId: [first workflow task ID]
- metadata: {
    "simulatorUdid": "[UDID]",
    "simulatorName": "[AppName]-Workflow-iPhone16",
    "iosVersion": "18.2",
    "appName": "[App name]"
  }

模拟器命名约定：

{AppName}-Workflow-iPhone16

- 默认工作流测试设备（例如：

Seatify-Workflow-iPhone16

）

```
{AppName}-Workflow-iPhone16-Pro
```
- 用于Pro专属功能测试
```
{AppName}-Workflow-iPad
```
- 用于iPad测试

创建模拟器（Bash命令）：

bash

undefined

Get the app/repo name

APP_NAME=$(basename $(pwd))

List available device types

xcrun simctl list devicetypes | grep iPhone

List available runtimes

xcrun simctl list runtimes

Create project-specific iPhone 16 simulator

xcrun simctl create "${APP_NAME}-Workflow-iPhone16" "iPhone 16" iOS18.2

Create project-specific iPhone 16 Pro simulator

xcrun simctl create "${APP_NAME}-Workflow-iPhone16-Pro" "iPhone 16 Pro" iOS18.2

Erase simulator to clean state

xcrun simctl erase <udid>

Delete simulator when done

xcrun simctl delete <udid>

List all workflow simulators (to find project-specific ones)

xcrun simctl list devices | grep "Workflow-iPhone"

undefined

xcrun simctl list devices | grep "Workflow-iPhone"

undefined

Phase 3: Execute Workflow

阶段3：执行工作流

Before starting each workflow, update its task:

TaskUpdate:
- taskId: [workflow task ID]
- status: "in_progress"

For each numbered step in the workflow:

Announce the step you're about to execute
Execute using the appropriate MCP tool:
- "Open Safari and navigate to [URL]" →
```
launch_app
```
  with
```
com.apple.mobilesafari
```
  , then
```
open_url
```
  or type URL in address bar
- "Tap [element]" →
```
ui_describe_all
```
  to find coordinates, then
```
ui_tap
```
- "Type [text]" →
```
ui_type
```
- "Swipe [direction]" →
```
ui_swipe
```
- "Verify [condition]" →
```
ui_describe_all
```
  or
```
ui_view
```
  to check
- "Wait [seconds]" → pause before next action
- "Refresh page" → tap Safari refresh button or pull-to-refresh
Screenshot after each major step:
- Use
```
screenshot({ output_path: "workflows/screenshots/ios-audit/wfNN-stepNN.png" })
```
  to save to disk
- Use the naming convention:
```
wf{workflow_number:02d}-step{step_number:02d}.png
```
- These files will be embedded in the HTML audit report via
```
<img>
```
  tags
Observe and note:
- Did it work as expected?
- Any UI/UX issues? (confusing labels, poor contrast, slow response)
- Any technical problems? (page errors, slow loading, visual glitches)
- Does the web app feel appropriate on iOS Safari?
- Any potential improvements or feature ideas?
Record your observations before moving to next step

When an iOS anti-pattern or issue is found, create an issue task:

TaskCreate:
- subject: "Issue: [Brief issue description]"
- description: |
    **Workflow:** [Workflow name]
    **Step:** [Step number and description]
    **Issue:** [Detailed description]
    **Severity:** [High/Med/Low]
    **iOS Anti-Pattern:** [What's wrong - e.g., "hamburger menu"]
    **iOS-Native Alternative:** [What it should be - e.g., "bottom tab bar"]
    **Screenshot:** [Path to before screenshot]
- activeForm: "Documenting iOS issue"

Then link it to the workflow task:
TaskUpdate:
- taskId: [issue task ID]
- addBlockedBy: [workflow task ID]

After completing all steps in a workflow:

TaskUpdate:
- taskId: [workflow task ID]
- status: "completed"
- metadata: {"issuesFound": [count], "stepsPassed": [count], "stepsFailed": [count]}

在开始每个工作流之前，更新其任务：

TaskUpdate:
- taskId: [workflow task ID]
- status: "in_progress"

对于工作流中的每个编号步骤：

告知用户你即将执行的步骤
执行步骤，使用适当的MCP工具：
- "打开Safari并导航到[URL]" → 使用
```
com.apple.mobilesafari
```
  调用
```
launch_app
```
  ，然后使用
```
open_url
```
  或在地址栏中输入URL
- "点击[元素]" → 使用
```
ui_describe_all
```
  查找坐标，然后使用
```
ui_tap
```
- "输入[文本]" → 使用
```
ui_type
```
- "滑动[方向]" → 使用
```
ui_swipe
```
- "验证[条件]" → 使用
```
ui_describe_all
```
  或
```
ui_view
```
  进行检查
- "等待[秒数]" → 在下一步操作前暂停
- "刷新页面" → 点击Safari的刷新按钮或下拉刷新
截图每个主要步骤完成后：
- 使用
```
screenshot({ output_path: "workflows/screenshots/ios-audit/wfNN-stepNN.png" })
```
  保存到磁盘
- 使用命名约定：
```
wf{workflow_number:02d}-step{step_number:02d}.png
```
- 这些文件将通过
```
<img>
```
  标签嵌入到HTML审计报告中
观察并记录：
- 步骤是否按预期工作？
- 存在任何UI/UX问题吗？（标签混乱、对比度差、响应缓慢）
- 存在任何技术问题吗？（页面错误、加载缓慢、视觉故障）
- 该Web应用在iOS Safari中的体验是否合适？
- 有任何潜在的改进或功能想法吗？
记录你的观察结果，然后再进行下一步

当发现iOS反模式或问题时，创建一个问题任务：

TaskCreate:
- subject: "Issue: [Brief issue description]"
- description: |
    **Workflow:** [Workflow name]
    **Step:** [Step number and description]
    **Issue:** [Detailed description]
    **Severity:** [High/Med/Low]
    **iOS Anti-Pattern:** [What's wrong - e.g., "hamburger menu"]
    **iOS-Native Alternative:** [What it should be - e.g., "bottom tab bar"]
    **Screenshot:** [Path to before screenshot]
- activeForm: "Documenting iOS issue"

Then link it to the workflow task:
TaskUpdate:
- taskId: [issue task ID]
- addBlockedBy: [workflow task ID]

完成工作流中的所有步骤后：

TaskUpdate:
- taskId: [workflow task ID]
- status: "completed"
- metadata: {"issuesFound": [count], "stepsPassed": [count], "stepsFailed": [count]}

Phase 4: UX Platform Evaluation [DELEGATE TO AGENT]

阶段4：用户体验平台评估 [委托给Agent]

Purpose: Evaluate whether the web app feels like a native iOS app (not just a mobile-friendly website). Delegate this research to an agent to save context.

Use the Task tool to spawn an agent:

Task tool parameters:
- subagent_type: "general-purpose"
- model: "opus" (thorough research and evaluation)
- prompt: |
    You are evaluating a web app for iOS HIG (Human Interface Guidelines) compliance.
    The app should feel indistinguishable from a native iOS app.

    ## Screen Being Evaluated
    [Include current screen description and context]

    ## Quick Checklist - Evaluate Each Item

    **Navigation (must feel native):**
    - Uses tab bar for primary navigation (not hamburger menu)
    - Back navigation feels native (swipe gesture or back button)
    - No breadcrumb navigation
    - Modals slide up from bottom like native iOS sheets

    **Touch & Interaction:**
    - All tap targets are at least 44x44pt
    - No hover-dependent interactions
    - Animations feel native (spring physics, smooth)
    - Forms work well with the on-screen keyboard

    **Components (should match native iOS):**
    - Uses iOS-style pickers, not web dropdowns
    - Toggle switches, not checkboxes
    - No Material Design components (FAB, snackbars, etc.)
    - Action sheets and alerts follow iOS patterns

    **Visual Design:**
    - Typography follows iOS conventions (SF Pro feel)
    - Subtle shadows and rounded corners (not Material elevation)
    - Safe area insets respected on notched devices
    - Doesn't look like a "website" - feels like an app

    ## Reference Comparison

    Search for reference examples using WebSearch:
    - "iOS [screen type] design Dribbble"
    - "[well-known iOS app like Airbnb/Spotify/Instagram] [screen type] screenshot"
    - "iOS Human Interface Guidelines [component]"

    Visit 2-3 reference examples and compare:
    - Navigation placement and style (tab bar position, back button)
    - Component types (iOS pickers vs web dropdowns)
    - Layout and spacing (iOS generous whitespace)
    - Animation and transition patterns

    ## Return Format

    Return a structured report:
    ```
    ## iOS HIG Evaluation: [Screen Name]

    ### Checklist Results
    | Check | Pass/Fail | Notes |
    |-------|-----------|-------|

    ### Reference Comparison
    - Reference apps compared: [list]
    - Key differences found: [list]

    ### Issues Found (iOS Anti-Patterns)
    - [Issue 1]: [Description] (Severity: High/Med/Low)
      - Anti-pattern: [What's wrong]
      - iOS-native alternative: [What it should be]

    ### Recommendations
    - [Recommendation 1]
    ```

After agent returns: Incorporate findings into the workflow report and continue.

目的： 评估Web应用是否给人原生iOS应用的感觉（而不仅仅是适配移动设备的网站）。将此研究委托给Agent以节省上下文。

使用Task工具生成一个Agent：

Task tool parameters:
- subagent_type: "general-purpose"
- model: "opus" (thorough research and evaluation)
- prompt: |
    You are evaluating a web app for iOS HIG (Human Interface Guidelines) compliance.
    The app should feel indistinguishable from a native iOS app.

    ## Screen Being Evaluated
    [Include current screen description and context]

    ## Quick Checklist - Evaluate Each Item

    **Navigation (must feel native):**
    - Uses tab bar for primary navigation (not hamburger menu)
    - Back navigation feels native (swipe gesture or back button)
    - No breadcrumb navigation
    - Modals slide up from bottom like native iOS sheets

    **Touch & Interaction:**
    - All tap targets are at least 44x44pt
    - No hover-dependent interactions
    - Animations feel native (spring physics, smooth)
    - Forms work well with the on-screen keyboard

    **Components (should match native iOS):**
    - Uses iOS-style pickers, not web dropdowns
    - Toggle switches, not checkboxes
    - No Material Design components (FAB, snackbars, etc.)
    - Action sheets and alerts follow iOS patterns

    **Visual Design:**
    - Typography follows iOS conventions (SF Pro feel)
    - Subtle shadows and rounded corners (not Material elevation)
    - Safe area insets respected on notched devices
    - Doesn't look like a "website" - feels like an app

    ## Reference Comparison

    Search for reference examples using WebSearch:
    - "iOS [screen type] design Dribbble"
    - "[well-known iOS app like Airbnb/Spotify/Instagram] [screen type] screenshot"
    - "iOS Human Interface Guidelines [component]"

    Visit 2-3 reference examples and compare:
    - Navigation placement and style (tab bar position, back button)
    - Component types (iOS pickers vs web dropdowns)
    - Layout and spacing (iOS generous whitespace)
    - Animation and transition patterns

    ## Return Format

    Return a structured report:
    ```
    ## iOS HIG Evaluation: [Screen Name]

    ### Checklist Results
    | Check | Pass/Fail | Notes |
    |-------|-----------|-------|

    ### Reference Comparison
    - Reference apps compared: [list]
    - Key differences found: [list]

    ### Issues Found (iOS Anti-Patterns)
    - [Issue 1]: [Description] (Severity: High/Med/Low)
      - Anti-pattern: [What's wrong]
      - iOS-native alternative: [What it should be]

    ### Recommendations
    - [Recommendation 1]
    ```

Agent返回结果后： 将发现的结果整合到工作流报告中，继续执行。

Phase 5: Record Findings

阶段5：记录发现结果

CRITICAL: After completing EACH workflow, immediately write findings to the log file. Do not wait until all workflows are complete.

After each workflow completes, append to
```
.claude/plans/ios-workflow-findings.md
```
If the file doesn't exist, create it with a header first
Use the following format for each workflow entry:

markdown

---

至关重要： 完成每个工作流后，立即将发现结果写入日志文件。不要等到所有工作流都完成后再记录。

每个工作流完成后，将内容追加到
```
.claude/plans/ios-workflow-findings.md
```
如果文件不存在，先创建一个标题
每个工作流条目使用以下格式：

markdown

---

Workflow [N]: [Name]

工作流[N]：[名称]

Timestamp: [ISO datetime] Status: Passed/Failed/Partial

Steps Summary:

Step 1: [Pass/Fail] - [brief note]
Step 2: [Pass/Fail] - [brief note] ...

Issues Found:

[Issue description] (Severity: High/Med/Low)

Platform Appropriateness:

iOS conventions followed: [Yes/Partially/No]
Issues: [List any platform anti-patterns found]
Reference comparisons: [Apps/screens compared, if any]

UX/Design Notes:

[Observation]

Technical Problems:

[Problem] (include crash logs if any)

Feature Ideas:

[Idea]

Screenshots: [list of screenshot paths captured]


4. This ensures findings are preserved even if session is interrupted
5. Continue to next workflow after recording

时间戳： [ISO datetime] 状态： 通过/失败/部分完成

步骤摘要：

步骤1：[通过/失败] - [简要说明]
步骤2：[通过/失败] - [简要说明] ...

发现的问题：

[问题描述]（严重程度：高/中/低）

平台适配性：

是否遵循iOS规范：是/部分/否
问题：[列出发现的任何平台反模式]
参考对比：[对比的应用/屏幕（如有）]

UX/设计说明：

[观察结果]

技术问题：

[问题]（如有崩溃日志请包含）

功能想法：

[想法]

截图： [捕获的截图路径列表]


4. 这样即使会话被中断，发现的结果也能被保存
5. 记录完成后，继续下一个工作流

Phase 6: Generate Audit Report (HTML with Screenshots)

阶段6：生成审计报告（包含截图的HTML）

After completing all workflows (or when user requests), generate an HTML audit report with embedded screenshots.

CRITICAL: The audit report MUST be HTML (not just markdown) and MUST embed screenshots from Phase 3. This is the primary deliverable.

Create audit report task:

TaskCreate:
- subject: "Generate: HTML Audit Report"
- description: "Generate HTML report with screenshots for all iOS workflow results"
- activeForm: "Generating HTML audit report"

TaskUpdate:
- taskId: [report task ID]
- status: "in_progress"

Generate the HTML report:

Call
```
TaskList
```
to get summary of all workflow and issue tasks
Read
```
.claude/plans/ios-workflow-findings.md
```
for detailed findings
Write HTML report to
```
workflows/ios-audit-report.html
```

HTML Report Structure:

html

<!-- Required sections: -->
<h1>iOS/Mobile Workflow Audit Report</h1>
<p>Date: [timestamp] | Device: [simulator info] | URL: [app URL]</p>

<!-- Summary table -->
<table>
  <tr><th>#</th><th>Workflow</th><th>Status</th><th>Steps</th><th>Notes</th></tr>
  <!-- One row per workflow with PASS/FAIL/SKIP badge -->
</table>

<!-- Per-workflow detail sections -->
<h2>Workflow N: [Name]</h2>
<p>Status: PASS/FAIL/SKIP</p>
<h3>Steps</h3>
<ol>
  <li>Step description — PASS/FAIL
    <br><img src="screenshots/ios-audit/wfNN-stepNN.png" style="max-width:400px; border:1px solid #ddd; border-radius:8px; margin:8px 0;">
  </li>
</ol>

Every workflow section MUST include
<img>
tags referencing the screenshots saved during Phase 3. Use relative paths:
```
screenshots/ios-audit/wfNN-stepNN.png
```
. Set
```
max-width: 400px
```
for mobile screenshots.
Style with clean design, professional appearance, app accent color
Update the HTML file incrementally after EACH workflow so partial results are always viewable

Also present a text summary to the user:

undefined

完成所有工作流后（或用户要求时），生成包含嵌入截图的HTML审计报告。

至关重要： 审计报告必须是HTML格式（而不仅仅是markdown），并且必须包含阶段3中保存的截图。这是主要的交付成果。

创建审计报告任务：

TaskCreate:
- subject: "Generate: HTML Audit Report"
- description: "Generate HTML report with screenshots for all iOS workflow results"
- activeForm: "Generating HTML audit report"

TaskUpdate:
- taskId: [report task ID]
- status: "in_progress"

生成HTML报告：

调用
```
TaskList
```
获取所有工作流和问题任务的摘要
读取
```
.claude/plans/ios-workflow-findings.md
```
获取详细发现结果
将HTML报告写入
```
workflows/ios-audit-report.html
```

HTML报告结构：

html

<!-- Required sections: -->
<h1>iOS/Mobile Workflow Audit Report</h1>
<p>Date: [timestamp] | Device: [simulator info] | URL: [app URL]</p>

<!-- Summary table -->
<table>
  <tr><th>#</th><th>Workflow</th><th>Status</th><th>Steps</th><th>Notes</th></tr>
  <!-- One row per workflow with PASS/FAIL/SKIP badge -->
</table>

<!-- Per-workflow detail sections -->
<h2>Workflow N: [Name]</h2>
<p>Status: PASS/FAIL/SKIP</p>
<h3>Steps</h3>
<ol>
  <li>Step description — PASS/FAIL
    <br><img src="screenshots/ios-audit/wfNN-stepNN.png" style="max-width:400px; border:1px solid #ddd; border-radius:8px; margin:8px 0;">
  </li>
</ol>

每个工作流部分必须包含
<img>
标签，引用阶段3中保存的截图。使用相对路径：
```
screenshots/ios-audit/wfNN-stepNN.png
```
。为移动截图设置
```
max-width: 400px
```
。
使用简洁的设计、专业的外观和应用强调色进行样式设置
在每个工作流完成后增量更新HTML文件，以便始终可以查看部分结果

同时向用户展示文本摘要：

undefined

iOS Audit Complete

iOS审计完成

Device: [Simulator name] (iOS [version]) Workflows Executed: [completed count]/[total count] Issues Found: [issue task count]

High severity: [count]
Medium severity: [count]
Low severity: [count]

Report: workflows/ios-audit-report.html

What would you like to do?

"fix all" - Fix all issues
"fix 1,3,5" - Fix specific issues by number
"done" - End session

undefined

TaskUpdate:

taskId: [report task ID]
status: "completed"

undefined

设备： [模拟器名称]（iOS [版本]） 已执行工作流： [已完成数量]/[总数量] 发现的问题： [问题任务数量]

高严重程度：[数量]
中严重程度：[数量]
低严重程度：[数量]

报告： workflows/ios-audit-report.html

你想执行什么操作？

"fix all" - 修复所有问题
"fix 1,3,5" - 按编号修复特定问题
"done" - 结束会话

undefined

TaskUpdate:

taskId: [report task ID]
status: "completed"

undefined

Phase 7: Screenshot Management

阶段7：截图管理

Screenshot Directory Structure:

workflows/
├── screenshots/
│   ├── {workflow-name}/
│   │   ├── before/
│   │   │   ├── 01-hamburger-menu.png
│   │   │   ├── 02-fab-button.png
│   │   │   └── ...
│   │   └── after/
│   │       ├── 01-tab-bar-navigation.png
│   │       ├── 02-no-fab.png
│   │       └── ...
│   └── {another-workflow}/
│       ├── before/
│       └── after/
├── ios-workflows.md
└── ios-changes-report.html

Screenshot Naming Convention:

```
{NN}-{descriptive-name}.png
```

Examples:

```
01-hamburger-menu.png
```
(before)
```
01-tab-bar-navigation.png
```
(after)
```
02-fab-button-visible.png
```
(before)
```
02-fab-removed.png
```
(after)

Capturing BEFORE Screenshots:

When an issue is identified during workflow execution
Take screenshot BEFORE any fix is applied

Save to

workflows/screenshots/{workflow-name}/before/

Use descriptive filename that identifies the issue
Record the screenshot path in the issue tracking

Capturing AFTER Screenshots:

Only after user approves fixing an issue
After fix agent completes, reload/refresh the app in simulator
Take screenshot showing the fix

Save to

workflows/screenshots/{workflow-name}/after/

Use matching filename pattern to the before screenshot

截图目录结构：

workflows/
├── screenshots/
│   ├── {workflow-name}/
│   │   ├── before/
│   │   │   ├── 01-hamburger-menu.png
│   │   │   ├── 02-fab-button.png
│   │   │   └── ...
│   │   └── after/
│   │       ├── 01-tab-bar-navigation.png
│   │       ├── 02-no-fab.png
│   │       └── ...
│   └── {another-workflow}/
│       ├── before/
│       └── after/
├── ios-workflows.md
└── ios-changes-report.html

截图命名约定：

```
{NN}-{descriptive-name}.png
```

示例：

```
01-hamburger-menu.png
```
（修复前）
```
01-tab-bar-navigation.png
```
（修复后）
```
02-fab-button-visible.png
```
（修复前）
```
02-fab-removed.png
```
（修复后）

捕获BEFORE（修复前）截图：

在工作流执行过程中识别到问题时
在应用任何修复之前拍摄截图

保存到

workflows/screenshots/{workflow-name}/before/

使用能识别问题的描述性文件名
在问题跟踪中记录截图路径

捕获AFTER（修复后）截图：

仅在用户批准修复问题后
修复Agent完成后，重新加载/刷新模拟器中的应用
拍摄展示修复效果的截图

保存到

workflows/screenshots/{workflow-name}/after/

使用与修复前截图匹配的文件名模式

Phase 8: Fix Mode Execution [DELEGATE TO AGENTS]

阶段8：修复模式执行 [委托给Agent]

When user triggers fix mode ("fix this issue" or "fix all"):

Get issue list from tasks:

Call TaskList to get all issue tasks (subject starts with "Issue:")
Display to user:

Issues found:
1. [Task ID: X] Hamburger menu (iOS anti-pattern) - BEFORE: 01-hamburger-menu.png
   Anti-pattern: hamburger menu → Fix: bottom tab bar
2. [Task ID: Y] FAB button (Material Design) - BEFORE: 02-fab-button.png
   Anti-pattern: FAB → Fix: contextual action in nav bar
3. [Task ID: Z] Web dropdown (not iOS picker) - BEFORE: 03-web-dropdown.png
   Anti-pattern: web dropdown → Fix: iOS picker wheel

Fix all issues? Or specify which to fix: [1,2,3 / all / specific numbers]

Create fix tasks for each issue to fix:

For each issue the user wants fixed:

TaskCreate:
- subject: "Fix: [Anti-pattern] → [iOS solution]"
- description: |
    Fixing issue from task [issue task ID]
    **Issue:** [Issue name and description]
    **Severity:** [High/Med/Low]
    **iOS Anti-Pattern:** [What's wrong]
    **iOS-Native Solution:** [What it should be]
    **Screenshot reference:** [Path to before screenshot]
- activeForm: "Fixing [anti-pattern]"

TaskUpdate:
- taskId: [fix task ID]
- addBlockedBy: [issue task ID]  # Links fix to its issue
- status: "in_progress"

Spawn one agent per issue using the Task tool. For independent issues, spawn agents in parallel (all in a single message):

Task tool parameters (for each issue):
- subagent_type: "general-purpose"
- model: "opus" (thorough code analysis and modification)
- prompt: |
    You are fixing a specific iOS UX issue in a web application.
    The app should feel indistinguishable from a native iOS app.

    ## Issue to Fix
    **Issue:** [Issue name and description]
    **Severity:** [High/Med/Low]
    **iOS Anti-Pattern:** [What's wrong - e.g., "hamburger menu"]
    **iOS-Native Solution:** [What it should be - e.g., "bottom tab bar"]
    **Screenshot reference:** [Path to before screenshot]

    ## Your Task

    1. **Explore the codebase** to understand the implementation
       - Use Glob to find relevant files
       - Use Grep to search for related code
       - Use Read to examine files

    2. **Plan the fix**
       - Identify which files need changes
       - May need to create new iOS-style components
       - Consider side effects

    3. **Implement the fix**
       - Make minimal, focused changes
       - Follow existing code patterns
       - Create iOS-native components if needed
       - Do not refactor unrelated code

    4. **Return a summary:**
    ```
    ## Fix Complete: [Issue Name]

    ### iOS Anti-Pattern Replaced
    - Before: [What was wrong]
    - After: [iOS-native solution]

    ### Changes Made
    - [File 1]: [What changed]
    - [File 2]: [What changed]

    ### Files Modified
    - src/components/IOSTabBar.tsx (NEW)
    - src/components/Navigation.tsx (MODIFIED)

    ### Testing Notes
    - [How to verify the fix works]
    ```

    Do NOT run tests - the main workflow will handle that.

After all fix agents complete:

Collect summaries from each agent
Reload the app in simulator
Capture AFTER screenshots for each fix
Verify fixes visually
Track all changes made

Update fix tasks with results:

For each completed fix:

TaskUpdate:
- taskId: [fix task ID]
- status: "completed"
- metadata: {
    "filesModified": ["src/components/IOSTabBar.tsx", "src/components/Navigation.tsx"],
    "afterScreenshot": "workflows/screenshots/{workflow}/after/{file}.png",
    "antiPatternRemoved": "[what was removed]",
    "iosNativeSolution": "[what was added]"
  }

Update issue tasks to reflect fix status:

TaskUpdate:
- taskId: [issue task ID]
- status: "completed"
- metadata: {"fixedBy": [fix task ID], "fixedAt": "[ISO timestamp]"}

当用户触发修复模式（“fix this issue”或“fix all”）时：

从任务中获取问题列表：

Call TaskList to get all issue tasks (subject starts with "Issue:")
Display to user:

Issues found:
1. [Task ID: X] Hamburger menu (iOS anti-pattern) - BEFORE: 01-hamburger-menu.png
   Anti-pattern: hamburger menu → Fix: bottom tab bar
2. [Task ID: Y] FAB button (Material Design) - BEFORE: 02-fab-button.png
   Anti-pattern: FAB → Fix: contextual action in nav bar
3. [Task ID: Z] Web dropdown (not iOS picker) - BEFORE: 03-web-dropdown.png
   Anti-pattern: web dropdown → Fix: iOS picker wheel

Fix all issues? Or specify which to fix: [1,2,3 / all / specific numbers]

为每个要修复的问题创建修复任务：

For each issue the user wants fixed:

TaskCreate:
- subject: "Fix: [Anti-pattern] → [iOS solution]"
- description: |
    Fixing issue from task [issue task ID]
    **Issue:** [Issue name and description]
    **Severity:** [High/Med/Low]
    **iOS Anti-Pattern:** [What's wrong]
    **iOS-Native Solution:** [What it should be]
    **Screenshot reference:** [Path to before screenshot]
- activeForm: "Fixing [anti-pattern]"

TaskUpdate:
- taskId: [fix task ID]
- addBlockedBy: [issue task ID]  # Links fix to its issue
- status: "in_progress"

为每个问题生成一个Agent，使用Task工具。对于独立问题，并行生成Agent（在单个消息中完成）：

Task tool parameters (for each issue):
- subagent_type: "general-purpose"
- model: "opus" (thorough code analysis and modification)
- prompt: |
    You are fixing a specific iOS UX issue in a web application.
    The app should feel indistinguishable from a native iOS app.

    ## Issue to Fix
    **Issue:** [Issue name and description]
    **Severity:** [High/Med/Low]
    **iOS Anti-Pattern:** [What's wrong - e.g., "hamburger menu"]
    **iOS-Native Solution:** [What it should be - e.g., "bottom tab bar"]
    **Screenshot reference:** [Path to before screenshot]

    ## Your Task

    1. **Explore the codebase** to understand the implementation
       - Use Glob to find relevant files
       - Use Grep to search for related code
       - Use Read to examine files

    2. **Plan the fix**
       - Identify which files need changes
       - May need to create new iOS-style components
       - Consider side effects

    3. **Implement the fix**
       - Make minimal, focused changes
       - Follow existing code patterns
       - Create iOS-native components if needed
       - Do not refactor unrelated code

    4. **Return a summary:**
    ```
    ## Fix Complete: [Issue Name]

    ### iOS Anti-Pattern Replaced
    - Before: [What was wrong]
    - After: [iOS-native solution]

    ### Changes Made
    - [File 1]: [What changed]
    - [File 2]: [What changed]

    ### Files Modified
    - src/components/IOSTabBar.tsx (NEW)
    - src/components/Navigation.tsx (MODIFIED)

    ### Testing Notes
    - [How to verify the fix works]
    ```

    Do NOT run tests - the main workflow will handle that.

所有修复Agent完成后：

收集每个Agent的摘要
重新加载模拟器中的应用
为每个修复捕获AFTER截图
可视化验证修复效果
跟踪所有已做的更改

使用结果更新修复任务：

For each completed fix:

TaskUpdate:
- taskId: [fix task ID]
- status: "completed"
- metadata: {
    "filesModified": ["src/components/IOSTabBar.tsx", "src/components/Navigation.tsx"],
    "afterScreenshot": "workflows/screenshots/{workflow}/after/{file}.png",
    "antiPatternRemoved": "[what was removed]",
    "iosNativeSolution": "[what was added]"
  }

更新问题任务以反映修复状态：

TaskUpdate:
- taskId: [issue task ID]
- status: "completed"
- metadata: {"fixedBy": [fix task ID], "fixedAt": "[ISO timestamp]"}

Phase 9: Local Verification [DELEGATE TO AGENT]

阶段9：本地验证 [委托给Agent]

CRITICAL: After making fixes, verify everything works locally before creating a PR.

Create verification task:

TaskCreate:
- subject: "Verify: Run test suite"
- description: |
    Run all tests to verify iOS fixes don't break existing functionality.
    Fixes applied: [list of fix task IDs]
    Files modified: [aggregated list from fix task metadata]
    Anti-patterns fixed: [list from fix task metadata]
- activeForm: "Running verification tests"

TaskUpdate:
- taskId: [verification task ID]
- status: "in_progress"

Use the Task tool to spawn a verification agent:

Task tool parameters:
- subagent_type: "general-purpose"
- model: "opus" (thorough test analysis and fixing)
- prompt: |
    You are verifying that code changes pass all tests.

    ## Context
    Recent changes were made to fix iOS UX issues. You need to verify the codebase is healthy.

    ## Your Task

    1. **Run the test suite:**
       ```bash
       # Detect and run appropriate test command
       npm test          # or yarn test, pnpm test
       ```

    2. **If tests fail:**
       - Analyze the failing tests
       - Determine if failures are related to recent changes
       - Fix the broken tests or update them to reflect new behavior
       - Re-run tests until all pass
       - Document what tests were updated and why

    3. **Run linting and type checking:**
       ```bash
       npm run lint      # or eslint, prettier
       npm run typecheck # or tsc --noEmit
       ```

    4. **Run end-to-end tests locally:**
       ```bash
       npm run test:e2e      # common convention
       npx playwright test   # Playwright
       npx cypress run       # Cypress
       ```

    5. **If E2E tests fail:**
       - Analyze the failures (may be related to UI changes)
       - Update E2E tests to reflect new UI behavior
       - Re-run until all pass
       - Document what E2E tests were updated

    6. **Return verification results:**
    ```
    ## Local Verification Results

    ### Test Results
    - Unit tests: ✓/✗ [count] passed, [count] failed
    - Lint: ✓/✗ [errors if any]
    - Type check: ✓/✗ [errors if any]
    - E2E tests: ✓/✗ [count] passed, [count] failed

    ### Tests Updated
    - [test file 1]: [why updated]
    - [test file 2]: [why updated]

    ### Status: PASS / FAIL
    [If FAIL, explain what's still broken]
    ```

After agent returns:

TaskUpdate:
- taskId: [verification task ID]
- status: "completed"
- metadata: {
    "result": "PASS" or "FAIL",
    "unitTests": {"passed": N, "failed": N},
    "e2eTests": {"passed": N, "failed": N},
    "lint": "pass" or "fail",
    "typecheck": "pass" or "fail"
  }

If PASS: Proceed to report generation
If FAIL: Review failures with user, spawn another agent to fix remaining issues

至关重要： 在进行修复后，在创建PR之前，需在本地验证所有功能是否正常工作。

创建验证任务：

TaskCreate:
- subject: "Verify: Run test suite"
- description: |
    Run all tests to verify iOS fixes don't break existing functionality.
    Fixes applied: [list of fix task IDs]
    Files modified: [aggregated list from fix task metadata]
    Anti-patterns fixed: [list from fix task metadata]
- activeForm: "Running verification tests"

TaskUpdate:
- taskId: [verification task ID]
- status: "in_progress"

使用Task工具生成一个验证Agent：

Task tool parameters:
- subagent_type: "general-purpose"
- model: "opus" (thorough test analysis and fixing)
- prompt: |
    You are verifying that code changes pass all tests.

    ## Context
    Recent changes were made to fix iOS UX issues. You need to verify the codebase is healthy.

    ## Your Task

    1. **Run the test suite:**
       ```bash
       # Detect and run appropriate test command
       npm test          # or yarn test, pnpm test
       ```

    2. **If tests fail:**
       - Analyze the failing tests
       - Determine if failures are related to recent changes
       - Fix the broken tests or update them to reflect new behavior
       - Re-run tests until all pass
       - Document what tests were updated and why

    3. **Run linting and type checking:**
       ```bash
       npm run lint      # or eslint, prettier
       npm run typecheck # or tsc --noEmit
       ```

    4. **Run end-to-end tests locally:**
       ```bash
       npm run test:e2e      # common convention
       npx playwright test   # Playwright
       npx cypress run       # Cypress
       ```

    5. **If E2E tests fail:**
       - Analyze the failures (may be related to UI changes)
       - Update E2E tests to reflect new UI behavior
       - Re-run until all pass
       - Document what E2E tests were updated

    6. **Return verification results:**
    ```
    ## Local Verification Results

    ### Test Results
    - Unit tests: ✓/✗ [count] passed, [count] failed
    - Lint: ✓/✗ [errors if any]
    - Type check: ✓/✗ [errors if any]
    - E2E tests: ✓/✗ [count] passed, [count] failed

    ### Tests Updated
    - [test file 1]: [why updated]
    - [test file 2]: [why updated]

    ### Status: PASS / FAIL
    [If FAIL, explain what's still broken]
    ```

Agent返回结果后：

TaskUpdate:
- taskId: [verification task ID]
- status: "completed"
- metadata: {
    "result": "PASS" or "FAIL",
    "unitTests": {"passed": N, "failed": N},
    "e2eTests": {"passed": N, "failed": N},
    "lint": "pass" or "fail",
    "typecheck": "pass" or "fail"
  }

如果PASS：继续生成报告
如果FAIL：与用户一起查看失败情况，生成另一个Agent来修复剩余问题

Phase 10: Generate HTML Report [DELEGATE TO AGENT]

阶段10：生成HTML报告 [委托给Agent]

Create report generation task:

TaskCreate:
- subject: "Generate: HTML Report"
- description: "Generate HTML report with iOS before/after screenshot comparisons"
- activeForm: "Generating HTML report"

TaskUpdate:
- taskId: [html report task ID]
- status: "in_progress"

Use the Task tool to generate the HTML report:

Task tool parameters:
- subagent_type: "general-purpose"
- model: "haiku" (simple generation task)
- prompt: |
    Generate an HTML report for iOS HIG compliance fixes.

    ## Data to Include

    **App Name:** [App name]
    **Date:** [Current date]
    **Device:** [Simulator device name and iOS version]
    **Issues Fixed:** [Count]
    **Issues Remaining:** [Count]

    **Fixes Made:**
    [For each fix:]
    - Issue: [Name]
    - iOS Anti-Pattern: [What was wrong]
    - iOS-Native Fix: [What it is now]
    - Before screenshot: workflows/screenshots/{workflow}/before/{file}.png
    - After screenshot: workflows/screenshots/{workflow}/after/{file}.png
    - Files changed: [List]
    - Why it matters: [Explanation of iOS HIG compliance]

    ## Output

    Write the HTML report to: workflows/ios-changes-report.html

    Use this template structure:
    - Executive summary with stats
    - Before/after screenshot comparisons for each fix
    - iOS anti-pattern → iOS-native fix explanation
    - Files changed section
    - "Why this matters for iOS users" explanations

    Style: Clean, professional, Apple-style design (SF Pro fonts feel, iOS blue accents).

    Return confirmation when complete.

After agent completes:

TaskUpdate:
- taskId: [html report task ID]
- status: "completed"
- metadata: {"outputPath": "workflows/ios-changes-report.html"}

创建报告生成任务：

TaskCreate:
- subject: "Generate: HTML Report"
- description: "Generate HTML report with iOS before/after screenshot comparisons"
- activeForm: "Generating HTML report"

TaskUpdate:
- taskId: [html report task ID]
- status: "in_progress"

使用Task工具生成HTML报告：

Task tool parameters:
- subagent_type: "general-purpose"
- model: "haiku" (simple generation task)
- prompt: |
    Generate an HTML report for iOS HIG compliance fixes.

    ## Data to Include

    **App Name:** [App name]
    **Date:** [Current date]
    **Device:** [Simulator device name and iOS version]
    **Issues Fixed:** [Count]
    **Issues Remaining:** [Count]

    **Fixes Made:**
    [For each fix:]
    - Issue: [Name]
    - iOS Anti-Pattern: [What was wrong]
    - iOS-Native Fix: [What it is now]
    - Before screenshot: workflows/screenshots/{workflow}/before/{file}.png
    - After screenshot: workflows/screenshots/{workflow}/after/{file}.png
    - Files changed: [List]
    - Why it matters: [Explanation of iOS HIG compliance]

    ## Output

    Write the HTML report to: workflows/ios-changes-report.html

    Use this template structure:
    - Executive summary with stats
    - Before/after screenshot comparisons for each fix
    - iOS anti-pattern → iOS-native fix explanation
    - Files changed section
    - "Why this matters for iOS users" explanations

    Style: Clean, professional, Apple-style design (SF Pro fonts feel, iOS blue accents).

    Return confirmation when complete.

Agent完成后：

TaskUpdate:
- taskId: [html report task ID]
- status: "completed"
- metadata: {"outputPath": "workflows/ios-changes-report.html"}

Phase 11: Generate Markdown Report [DELEGATE TO AGENT]

阶段11：生成Markdown报告 [委托给Agent]

Create markdown report task:

TaskCreate:
- subject: "Generate: Markdown Report"
- description: "Generate Markdown documentation for iOS fixes"
- activeForm: "Generating Markdown report"

TaskUpdate:
- taskId: [md report task ID]
- status: "in_progress"

Use the Task tool to generate the Markdown report:

Task tool parameters:
- subagent_type: "general-purpose"
- model: "haiku"
- prompt: |
    Generate a Markdown report for iOS HIG compliance fixes.

    ## Data to Include
    [Same data as HTML report]

    ## Output

    Write the Markdown report to: workflows/ios-changes-documentation.md

    Include:
    - Executive summary
    - Before/after comparison table with iOS anti-pattern and fix columns
    - Detailed changes for each fix
    - Files changed
    - Technical implementation notes
    - Testing verification results

    Return confirmation when complete.

After agent completes:

TaskUpdate:
- taskId: [md report task ID]
- status: "completed"
- metadata: {"outputPath": "workflows/ios-changes-documentation.md"}

创建Markdown报告任务：

TaskCreate:
- subject: "Generate: Markdown Report"
- description: "Generate Markdown documentation for iOS fixes"
- activeForm: "Generating Markdown report"

TaskUpdate:
- taskId: [md report task ID]
- status: "in_progress"

使用Task工具生成Markdown报告：

Task tool parameters:
- subagent_type: "general-purpose"
- model: "haiku"
- prompt: |
    Generate a Markdown report for iOS HIG compliance fixes.

    ## Data to Include
    [Same data as HTML report]

    ## Output

    Write the Markdown report to: workflows/ios-changes-documentation.md

    Include:
    - Executive summary
    - Before/after comparison table with iOS anti-pattern and fix columns
    - Detailed changes for each fix
    - Files changed
    - Technical implementation notes
    - Testing verification results

    Return confirmation when complete.

Agent完成后：

TaskUpdate:
- taskId: [md report task ID]
- status: "completed"
- metadata: {"outputPath": "workflows/ios-changes-documentation.md"}

Phase 12: Create PR and Monitor CI

阶段12：创建PR并监控CI

Create PR task:

TaskCreate:
- subject: "Create: Pull Request"
- description: |
    Create PR for iOS UX compliance fixes.
    Fixes included: [list from completed fix tasks]
    Anti-patterns removed: [list from fix task metadata]
    Files modified: [aggregated from fix task metadata]
- activeForm: "Creating pull request"

TaskUpdate:
- taskId: [pr task ID]
- status: "in_progress"

Only after local verification passes, create the PR:

Create a feature branch:
bash
```
git checkout -b fix/ios-ux-compliance
```

Stage and commit changes:

bash

git add .
git commit -m "fix: iOS UX compliance improvements

- [List key fixes made]
- Updated tests to reflect new behavior
- All local tests passing"

Push and create PR:

bash

git push -u origin fix/ios-ux-compliance
gh pr create --title "fix: iOS UX compliance improvements" --body "## Summary
[Brief description of fixes]

## Changes
- [List of changes]

## Testing
- [x] All unit tests pass locally
- [x] All E2E tests pass locally
- [x] Manual verification in iOS Simulator complete

## Screenshots
See workflows/ios-changes-report.html for before/after comparisons"

Monitor CI:
- Watch for CI workflow to start
- If CI fails, analyze the failure
- Fix any CI-specific issues (environment differences, flaky tests)
- Push fixes and re-run CI
- Do not merge until CI is green

Update PR task with status:

TaskUpdate:
- taskId: [pr task ID]
- metadata: {
    "prUrl": "https://github.com/owner/repo/pull/123",
    "ciStatus": "running" | "passed" | "failed"
  }

When CI completes:

TaskUpdate:
- taskId: [pr task ID]
- status: "completed"
- metadata: {"prUrl": "...", "ciStatus": "passed", "merged": false}

Report PR status to user:

PR created: https://github.com/owner/repo/pull/123
CI status: Running... (or Passed/Failed)

Final session summary from tasks:

Call TaskList to generate final summary:

## iOS Session Complete

**Simulator:** [Device name] (iOS [version])
**Workflows Executed:** [count completed workflow tasks]
**iOS Anti-Patterns Found:** [count issue tasks]
**Anti-Patterns Fixed:** [count completed fix tasks]
**Tests:** [from verification task metadata]
**PR:** [from pr task metadata]

All tasks completed successfully.

创建PR任务：

TaskCreate:
- subject: "Create: Pull Request"
- description: |
    Create PR for iOS UX compliance fixes.
    Fixes included: [list from completed fix tasks]
    Anti-patterns removed: [list from fix task metadata]
    Files modified: [aggregated from fix task metadata]
- activeForm: "Creating pull request"

TaskUpdate:
- taskId: [pr task ID]
- status: "in_progress"

仅在本地验证通过后，创建PR：

创建功能分支：
bash
```
git checkout -b fix/ios-ux-compliance
```

暂存并提交更改：

bash

git add .
git commit -m "fix: iOS UX compliance improvements

- [List key fixes made]
- Updated tests to reflect new behavior
- All local tests passing"

推送并创建PR：

bash

git push -u origin fix/ios-ux-compliance
gh pr create --title "fix: iOS UX compliance improvements" --body "## Summary
[Brief description of fixes]

## Changes
- [List of changes]

## Testing
- [x] All unit tests pass locally
- [x] All E2E tests pass locally
- [x] Manual verification in iOS Simulator complete

## Screenshots
See workflows/ios-changes-report.html for before/after comparisons"

监控CI：
- 等待CI工作流启动
- 如果CI失败，分析失败原因
- 修复任何CI特定问题（环境差异、不稳定的测试）
- 推送修复并重新运行CI
- 在CI通过之前不要合并

使用状态更新PR任务：

TaskUpdate:
- taskId: [pr task ID]
- metadata: {
    "prUrl": "https://github.com/owner/repo/pull/123",
    "ciStatus": "running" | "passed" | "failed"
  }

CI完成后：

TaskUpdate:
- taskId: [pr task ID]
- status: "completed"
- metadata: {"prUrl": "...", "ciStatus": "passed", "merged": false}

向用户报告PR状态：

PR created: https://github.com/owner/repo/pull/123
CI status: Running... (or Passed/Failed)

从任务生成最终会话摘要：

Call TaskList to generate final summary:

## iOS会话完成

**模拟器：** [设备名称]（iOS [版本]）
**已执行工作流：** [已完成工作流任务数量]
**发现的iOS反模式：** [问题任务数量]
**已修复的反模式：** [已完成修复任务数量]
**测试：** [来自验证任务元数据]
**PR：** [来自PR任务元数据]

所有任务已成功完成。

MCP Tool Reference

MCP工具参考

Simulator Management:

```
list_simulators()
```
- List all available simulators with status
```
claim_simulator({ udid? })
```
- Claim simulator for exclusive use
```
get_claimed_simulator()
```
- Get info about claimed simulator
```
boot_simulator({ udid })
```
- Boot a specific simulator
```
open_simulator()
```
- Open Simulator.app

Finding Elements:

```
ui_describe_all({ udid? })
```
- Get accessibility tree of entire screen
```
ui_describe_point({ x, y, udid? })
```
- Get element at specific coordinates
```
ui_view({ udid? })
```
- Get compressed screenshot image

Interactions:

```
ui_tap({ x, y, duration?, udid? })
```
- Tap at coordinates
```
ui_type({ text, udid? })
```
- Type text (ASCII printable characters only)

ui_swipe({ x_start, y_start, x_end, y_end, duration?, delta?, udid? })

- Swipe gesture

Screenshots & Recording:

screenshot({ output_path, type?, udid? })

- Save screenshot to file

record_video({ output_path?, codec?, udid? })

- Start video recording

```
stop_recording()
```
- Stop video recording

App Management:

```
install_app({ app_path, udid? })
```
- Install .app or .ipa

launch_app({ bundle_id, terminate_running?, udid? })

- Launch app by bundle ID

模拟器管理：

```
list_simulators()
```
- 列出所有可用模拟器及其状态
```
claim_simulator({ udid? })
```
- 占用模拟器以供独占使用
```
get_claimed_simulator()
```
- 获取已占用模拟器的信息
```
boot_simulator({ udid })
```
- 启动特定模拟器
```
open_simulator()
```
- 打开Simulator.app

查找元素：

```
ui_describe_all({ udid? })
```
- 获取整个屏幕的可访问性树
```
ui_describe_point({ x, y, udid? })
```
- 获取特定坐标处的元素
```
ui_view({ udid? })
```
- 获取压缩的截图图像

交互操作：

```
ui_tap({ x, y, duration?, udid? })
```
- 在坐标处点击
```
ui_type({ text, udid? })
```
- 输入文本（仅支持ASCII可打印字符）

ui_swipe({ x_start, y_start, x_end, y_end, duration?, delta?, udid? })

- 滑动手势

截图与录制：

screenshot({ output_path, type?, udid? })

- 将截图保存到文件

record_video({ output_path?, codec?, udid? })

- 开始录制视频

```
stop_recording()
```
- 停止录制视频

应用管理：

```
install_app({ app_path, udid? })
```
- 安装.app或.ipa文件

launch_app({ bundle_id, terminate_running?, udid? })

- 通过Bundle ID启动应用

Key Bundle ID

关键Bundle ID

For testing web apps, you'll primarily use Safari:

Safari:
```
com.apple.mobilesafari
```
- Use this to launch Safari and navigate to your web app URL

To open a URL in Safari:

Launch Safari:

launch_app({ bundle_id: "com.apple.mobilesafari" })

Tap the address bar
Type the URL using
```
ui_type
```
Tap Go or press Enter

测试Web应用时，你主要会使用Safari：

Safari：
```
com.apple.mobilesafari
```
- 使用此ID启动Safari并导航到你的Web应用URL

在Safari中打开URL的步骤：

启动Safari：

launch_app({ bundle_id: "com.apple.mobilesafari" })

点击地址栏
使用
```
ui_type
```
输入URL
点击“前往”或按回车键

Coordinate System

坐标系

The iOS Simulator uses pixel coordinates from top-left (0, 0).

Use
```
ui_describe_all
```
to find element positions
Elements report their
```
frame
```
with x, y, width, height
Tap center of element: x + width/2, y + height/2

iOS模拟器使用左上角为原点(0, 0)的像素坐标系。

使用
```
ui_describe_all
```
查找元素位置
元素会报告其包含x、y、宽度和高度的
```
frame
```
点击元素中心：x + width/2, y + height/2

Known Limitations

已知限制

When testing web apps in Safari on the iOS Simulator, these limitations apply:

在iOS模拟器的Safari中测试Web应用时，存在以下限制：

Cannot Automate (Must Skip or Flag for Manual Testing)

无法自动化（必须跳过或标记为手动测试）

Safari-Specific Dialogs
- JavaScript alerts/confirms/prompts
- Download prompts
- "Add to Home Screen" flow
- Workaround: Test manually or dismiss dialogs before continuing
Web Permission Prompts
- Camera/microphone access via browser
- Location access via browser
- Notification permissions
- Workaround: Pre-authorize in Settings or flag for manual testing
Keyboard Limitations
- ```
ui_type
```
  only supports ASCII printable characters
- Special characters, emoji, and non-Latin scripts cannot be typed
- Autocorrect interactions
- Workaround: For special text, pre-populate test data
Safari UI Interactions
- Bookmarks, Reading List, History
- Share sheet from Safari
- Safari settings/preferences
- Workaround: Focus on web app testing, not Safari itself
External Authentication
- OAuth flows that open new windows
- Sign in with Apple on web
- Third-party login popups
- Workaround: Use test accounts, flag for manual verification

Safari特定对话框
- JavaScript警告/确认/提示框
- 下载提示
- “添加到主屏幕”流程
- 解决方法： 手动测试或在继续之前关闭对话框
Web权限提示
- 通过浏览器请求摄像头/麦克风访问
- 通过浏览器请求位置访问
- 通知权限
- 解决方法： 在设置中预先授权或标记为手动测试
键盘限制
- ```
ui_type
```
  仅支持ASCII可打印字符
- 无法输入特殊字符、表情符号和非拉丁语系脚本
- 自动更正交互
- 解决方法： 对于特殊文本，预先填充测试数据
Safari UI交互
- 书签、阅读列表、历史记录
- Safari的分享面板
- Safari设置/偏好设置
- 解决方法： 专注于Web应用测试，而非Safari本身
外部认证
- 打开新窗口的OAuth流程
- Web端的“使用Apple登录”
- 第三方登录弹窗
- 解决方法： 使用测试账户，标记为手动验证

Handling Limited Steps

处理受限制的步骤

When a workflow step involves a known limitation:

Mark as [MANUAL]: Note the step requires manual verification
Pre-configure: Set up test data or permissions before testing
Document the Limitation: Record in findings that the step was skipped due to automation limits
Continue Testing: Don't let one limited step block the entire workflow

当工作流步骤涉及已知限制时：

标记为[MANUAL]： 注明该步骤需要手动验证
预先配置： 在测试前设置测试数据或权限
记录限制： 在发现结果中记录由于自动化限制而跳过该步骤
继续测试： 不要让一个受限制的步骤阻碍整个工作流

Guidelines

指南

Be methodical: Execute steps in order, don't skip ahead
Be observant: Note anything unusual, even if the step "passes"
Be thorough: Look for visual glitches, animation issues, responsiveness
Be constructive: Frame issues as opportunities for improvement
Ask if stuck: If a step is ambiguous or fails, ask the user for guidance
Pre-configure when possible: Set up simulator state before running workflows
Delegate to agents: Use agents for research, fixing, verification, and report generation to save context

有条不紊： 按顺序执行步骤，不要跳步
善于观察： 注意任何异常情况，即使步骤“通过”
全面细致： 查找视觉故障、动画问题、响应性问题
建设性反馈： 将问题表述为改进的机会
遇到问题时询问： 如果步骤不明确或失败，请向用户寻求指导
尽可能预先配置： 在运行工作流之前设置模拟器状态
委托给Agent： 使用Agent进行研究、修复、验证和报告生成，以节省上下文

Handling Failures

处理失败

If a step fails:

Take a screenshot of the failure state
Use
```
ui_describe_all
```
to understand current screen state
Note what went wrong
Ask the user: continue with next step, retry, or abort?

Do not silently skip failed steps.

如果步骤失败：

拍摄失败状态的截图
使用
```
ui_describe_all
```
了解当前屏幕状态
记录问题所在
询问用户：继续下一步、重试还是中止？

不要默默跳过失败的步骤。

Swipe Directions Reference

滑动方向参考

Swipe Up:    x_start=200, y_start=600, x_end=200, y_end=200
Swipe Down:  x_start=200, y_start=200, x_end=200, y_end=600
Swipe Left:  x_start=350, y_start=400, x_end=50, y_end=400
Swipe Right: x_start=50, y_start=400, x_end=350, y_end=400

Adjust coordinates based on actual screen size from

ui_describe_all

向上滑动:    x_start=200, y_start=600, x_end=200, y_end=200
向下滑动:  x_start=200, y_start=200, x_end=200, y_end=600
向左滑动:  x_start=350, y_start=400, x_end=50, y_end=400
向右滑动: x_start=50, y_start=400, x_end=350, y_end=400

根据

ui_describe_all

返回的实际屏幕尺寸调整坐标。

Session Recovery

会话恢复

If resuming from an interrupted session:

Primary method: Use task list (preferred)

Call
```
TaskList
```
to get all existing tasks
Check for workflow tasks with status
```
in_progress
```
or
```
pending
```
Check first workflow task metadata for simulator UDID to reclaim
Check for issue tasks to understand what iOS anti-patterns were found
Check for fix tasks to see what fixes were attempted
Resume from the appropriate point based on task states

Recovery decision tree:

TaskList shows:
├── All workflow tasks completed, no fix tasks
│   └── Ask user: "iOS audit complete. Want to fix anti-patterns?"
├── All workflow tasks completed, fix tasks in_progress
│   └── Resume fix mode, check agent status
├── Some workflow tasks pending
│   └── Resume from first pending workflow
│       └── Reclaim simulator using UDID from task metadata
├── Workflow task in_progress
│   └── Read findings file to see which steps completed
│       └── Resume from next step in that workflow
└── No tasks exist
    └── Fresh start (Phase 1)

Simulator recovery: When resuming, try to reclaim the same simulator:

Get simulator UDID from first workflow task metadata
Call
```
list_simulators
```
to check if it still exists
If available, call
```
claim_simulator
```
with the UDID
If not available, create a new project-specific simulator

Fallback method: Use findings file

Read
```
.claude/plans/ios-workflow-findings.md
```
to see which workflows have been completed
Resume from the next uncompleted workflow
Recreate tasks for remaining workflows

Always inform user:

Resuming from interrupted iOS session:
- Simulator: [name] ([UDID]) - [reclaimed/recreated]
- Workflows completed: [list from completed tasks]
- iOS anti-patterns found: [count from issue tasks]
- Current state: [in_progress task description]
- Resuming: [next action]

Do not re-execute already-passed workflows unless the user specifically requests it.

如果从中断的会话恢复：

主要方法：使用任务列表（首选）

调用
```
TaskList
```
获取所有现有任务
检查状态为
```
in_progress
```
或
```
pending
```
的工作流任务
检查第一个工作流任务元数据中的模拟器UDID，以重新占用
检查问题任务，了解已发现的iOS反模式
检查修复任务，了解已尝试的修复
根据任务状态从适当的点继续

恢复决策树：

TaskList显示：
├── 所有工作流任务已完成，无修复任务
│   └── 询问用户："iOS审计完成。是否要修复反模式问题？"
├── 所有工作流任务已完成，修复任务处于in_progress状态
│   └── 恢复修复模式，检查Agent状态
├── 部分工作流任务待处理
│   └── 从第一个待处理的工作流继续
│       └── 使用任务元数据中的UDID重新占用模拟器
├── 工作流任务处于in_progress状态
│   └── 读取发现结果文件，查看已完成的步骤
│       └── 从该工作流的下一步继续
└── 无任务存在
    └── 全新开始（阶段1）

模拟器恢复： 恢复时，尝试重新占用同一模拟器：

从第一个工作流任务元数据中获取模拟器UDID
调用
```
list_simulators
```
检查它是否仍然存在
如果可用，使用UDID调用
```
claim_simulator
```
如果不可用，创建一个新的项目专用模拟器

备用方法：使用发现结果文件

读取
```
.claude/plans/ios-workflow-findings.md
```
查看已完成的工作流
从下一个未完成的工作流继续
为剩余工作流重新创建任务

始终告知用户：

从中断的iOS会话恢复：
- 模拟器：[名称] ([UDID]) - [已重新占用/已重新创建]
- 已完成的工作流：[已完成任务列表]
- 发现的iOS反模式：[问题任务数量]
- 当前状态：[in_progress任务描述]
- 将继续：[下一步操作]

除非用户特别要求，否则不要重新执行已通过的工作流。