mobile-browser-workflow-executor
Mobile Browser Workflow Executor
This skill executes mobile browser workflows defined in /workflows/mobile-browser-workflows.md using Playwright MCP as the primary engine, with Claude-in-Chrome as an optional alternative. It emulates a mobile viewport (393x852 - iPhone 14 Pro dimensions), validates workflows step-by-step, audits for iOS Human Interface Guidelines (HIG) anti-patterns, captures visual evidence with device frame mockups, and generates comprehensive reports.
Execution Modes
- Audit Mode (Default): Execute workflows, capture findings, generate reports. Does not modify code.
- Fix Mode: Execute audit, then automatically remediate identified issues with user approval.
Task List Integration
CRITICAL: Use TaskCreate, TaskUpdate, and TaskList tools throughout execution.
| Task | Purpose |
|---|---|
| Master task | mobile-browser-workflow-execution - tracks overall session |
| Per-workflow tasks | One task per workflow with step progress |
| Agent tasks | UX evaluation, fix agents, verification, report generation |
Session Recovery
At skill start, check for existing session file: .claude/tasks/mobile-browser-workflow-executor-session.json. If found, prompt user: "Resume previous session or start fresh?"
| Session State | Resume Action |
|---|---|
| No session exists | Create new, start Phase 1 |
| Workflow execution incomplete | Resume at incomplete workflow/step |
| UX evaluation not started | Start Phase 4 |
| Fix mode incomplete | Resume fix agents |
| Reports not generated | Start Phase 10-11 |
12-Phase Execution Flow
Phase 1: Read Workflows & Initialize
- Check for existing session state
- Read
/workflows/mobile-browser-workflows.md - Parse workflow structure (name, URL, steps, expected outcomes)
- Create master task hierarchy with per-workflow tasks
Phase 2: Initialize Mobile Browser
Prompt user for engine choice (Playwright MCP recommended, Claude-in-Chrome alternative). Configure viewport (393x852), user agent (iOS Safari 17.0), and touch events.
See references/playwright-mcp-tools.md for initialization code and tool reference. See references/viewport-config.md for device specifications.
Phase 3: Execute Workflow
Execute workflow steps sequentially with before/after screenshots at each step. Actions map to Playwright tools: Navigate, Tap, Type, Swipe, Wait, Verify, Screenshot.
See references/playwright-mcp-tools.md for the action mapping table, step execution template, and touch event simulation code.
For each workflow: navigate to starting URL, execute steps with retry logic (2 retries for timeouts/missing elements), capture screenshots, and scan for obvious iOS HIG issues.
Phase 4: UX Platform Evaluation [DELEGATE TO AGENT]
Delegate comprehensive iOS HIG validation to the Task tool. The agent evaluates: navigation patterns, touch target sizing (44pt minimum), native component usage, visual design (WCAG AA contrast), and platform conventions.
See references/agent-prompts.md for the full evaluation agent prompt, anti-pattern checklist, and measurement utilities (JavaScript).
Output: Findings documented in .claude/plans/mobile-browser-workflow-findings.md.
Phase 5: Record Findings
Consolidate all findings from execution and UX evaluation into structured markdown with severity (Critical/High/Medium/Low), category, location, current implementation, iOS HIG violation reference, impact, recommended solution, and implementation code.
Phase 6: Generate Audit Report
Present summary to user with workflow count, findings by severity, critical issues list, and generated artifacts. Prompt user for next steps:
- Fix issues automatically (Phase 8)
- Generate detailed reports (Phase 10-11)
- Deep dive on specific findings (return to Phase 4)
- Mark complete (Phase 12)
Phase 7: Screenshot Management
Organize screenshots into before/after/analysis/mockups directories per workflow. Optimize for web delivery and generate annotated versions highlighting issues.
See ../../references/screenshot-guide.md for directory structure, optimization code, annotation generation, and device frame wrapping.
Phase 8: Fix Mode Execution [DELEGATE TO AGENTS]
Present fix plan to user with proposed changes grouped by category. After user approval, spawn parallel fix agents (one per independent group: navigation, touch-targets, color-contrast, components). Each agent reads current files, applies iOS HIG-compliant fixes, and validates syntax.
See references/agent-prompts.md for fix agent prompts and implementation templates.
Phase 9: Local Verification [DELEGATE TO AGENT]
Re-run workflows to verify fixes resolved issues. Agent captures new screenshots, measures touch targets, verifies navigation changes, checks contrast ratios, and generates before/after metrics comparison.
See references/agent-prompts.md for the verification agent prompt.
Phase 10: Generate HTML Report [DELEGATE TO AGENT]
Create self-contained HTML report with embedded CSS, device frame mockups, dark/light mode, interactive expand/collapse findings, and print-friendly styles.
See examples/audit-report-template.html for the full HTML template.
Phase 11: Generate Markdown Report [DELEGATE TO AGENT]
Create GitHub-flavored Markdown report with table of contents, collapsible sections, relative image links, code blocks with syntax highlighting, and emoji status indicators.
Phase 12: Create PR and Monitor CI
Stage changes, create commit with detailed message listing all fixes by severity, create branch, push, create PR with metrics table and before/after screenshots, and monitor CI checks. Handle visual regression (expected), lint errors (fix immediately), and test failures (investigate).
Reference Materials
- references/playwright-mcp-tools.md - Tool reference for both engines, action mapping, initialization code, step execution templates
- ../../references/automation-limitations.md - Known limitations, error handling patterns, best practices
- ../../references/screenshot-guide.md - Directory structure, optimization, annotation, device frame wrapping
- references/agent-prompts.md - Full prompts for evaluation, fix, verification, and report agents with measurement utilities
- references/viewport-config.md - Device specifications, CSS device frame mockup, session state structure
- examples/audit-report-template.html - Complete HTML report template with CSS and JavaScript