@shaykec/app-agent 1.0.9 → 1.0.11

package/.cursor/skills/web-analyzer/SKILL.md

@@ -0,0 +1,310 @@
+# Web Analyzer Skill
+
+Analyze the web crawl report and website screenshots to produce a structured app specification (web-to-app manifest) that drives the rest of the build pipeline.
+
+## Inputs
+
+- **Web crawl report**: `output/{app-name}/reports/02-web-crawl-report.md`
+- **Website screenshots**: `output/{app-name}/web-crawl/screenshots/*.png` (passed as image attachments)
+- **Focus directive** (optional): User's description of what to prioritize
+- **Platform**: ios, android, or react-native
+
+## Process
+
+### 1. Read the Crawl Report
+
+Read `reports/02-web-crawl-report.md` to understand:
+- Site map (all pages discovered)
+- Navigation structure
+- Brand palette (colors, typography, layout patterns)
+- Content model (entities, fields, categories)
+- Functionality inventory (search, forms, filters, auth, CRUD)
+
+### 2. View the Screenshots
+
+Examine all saved screenshots to visually verify and refine:
+- Color accuracy (screenshots show the actual rendered colors)
+- Layout patterns (card grids, list styles, hero sections, spacing)
+- Visual hierarchy (what's prominent, what's secondary)
+- Overall brand "feel" (modern, classic, playful, corporate, etc.)
+- Typography style (even if exact fonts can't be extracted)
+
+### 3. Map Pages to Mobile Screens
+
+Apply these mapping rules:
+
+| Web Pattern | Mobile Pattern |
+|-------------|---------------|
+| Home/landing page | Home tab (main tab) |
+| List/catalog page (products, articles) | List screen (scrollable, searchable) |
+| Detail page (product detail, article) | Detail screen (push navigation) |
+| Search page / search results | Search/Explore tab or search overlay |
+| Category/filter page | Filter sheet or Explore tab |
+| User profile / account | Profile tab |
+| Favorites / wishlist / saved | Favorites tab |
+| Contact / about / info | Info section in Profile or separate screen |
+| Form (create, submit) | Create/Compose screen (modal or push) |
+| Cart / checkout | Cart tab or sheet (if e-commerce) |
+| Settings / preferences | Settings screen (in Profile tab) |
+
+**Tab Bar Strategy** (max 4-5 tabs):
+1. **Home** — always the first tab (mirrors home page)
+2. **Explore/Search** — if the site has search, catalog, or browse functionality
+3. **Favorites** — if the site has save/wishlist/bookmark functionality
+4. **Profile** — if the site has user accounts, settings, or contact info
+5. **Extra tab** — only if the site has a major section that doesn't fit above (e.g., Cart for e-commerce)
+
+### 4. Map Navigation
+
+| Web Navigation | Mobile Navigation |
+|----------------|-------------------|
+| Top nav bar links | Tab bar items |
+| Sub-menu / dropdown | Navigation stack (push screens) |
+| Breadcrumbs | Back button (automatic in nav stack) |
+| Pagination | Infinite scroll or load-more |
+| Modal / popup | Sheet or modal presentation |
+| Sidebar / drawer | Not recommended — flatten into tabs |
+
+### 5. Extract Brand Tokens
+
+From the crawl report and screenshots, produce exact brand tokens:
+
+```
+Primary Color:      #XXXXXX  (main CTA / button color)
+Secondary Color:    #XXXXXX  (accent / highlight color)
+Background:         #XXXXXX  (page background)
+Surface:            #XXXXXX  (card / section background)
+Text Primary:       #XXXXXX  (headings, main text)
+Text Secondary:     #XXXXXX  (captions, secondary text)
+Error:              #FF3B30  (default if not visible on site)
+Success:            #34C759  (default if not visible on site)
+
+Corner Radius:      {small/medium/large} → {4/8/12}pt
+Shadow Style:       {none/subtle/prominent}
+Spacing Scale:      {tight/medium/generous}
+
+Typography Style:   {sans-serif/serif/rounded} → map to system fonts
+```
+
+### 6. Define Data Model
+
+From the content model in the crawl report:
+- Map each entity to a Swift struct / Kotlin data class / TypeScript interface
+- Define fields with types (String, Int, Double, URL, Date, Bool)
+- Identify primary entity (the main "item" the app displays)
+- Identify relationships (entity A has many entity B)
+
+### 7. Generate Content Brief
+
+Adapt website copy for mobile:
+- App display name (from website name/logo)
+- Tab labels (short, 1-2 words)
+- Screen titles
+- Empty state messages
+- Search placeholder text
+- CTA button labels
+- Onboarding text (if the site has a value proposition)
+- Category names
+
+### 8. Decide: Template or Scratch
+
+Compare the web-to-app mapping against available templates in CATALOG.md:
+- If a template matches 70%+ of the required screens/features → use template mode
+- If no template is a good fit → recommend scratch mode
+- Always prefer template mode for reliability
+
+### 9. Generate Parallel Batches
+
+Divide screens into 2-3 batches for parallel customization and testing:
+- **Batch 1**: Home + Explore/Search screens
+- **Batch 2**: Detail + Create/Form screens
+- **Batch 3**: Profile + Settings + Favorites screens
+
+## Output
+
+Write `output/{app-name}/reports/03-web-to-app-manifest.md` with this structure:
+
+```markdown
+# Web-to-App Manifest
+
+## Source
+- **URL**: {url}
+- **App Name**: {derived from website name}
+- **Bundle ID**: com.appship.{appname}
+- **Platform**: {platform}
+- **Build Mode**: {template/scratch}
+- **Selected Template**: {template name or "N/A for scratch mode"}
+
+## Screen Mapping
+
+| # | Web Page | Mobile Screen | Tab | Navigation |
+|---|----------|--------------|-----|------------|
+| 1 | Home | HomeView | Home | Root |
+| 2 | Products | ProductListView | Explore | Root |
+| 3 | Product Detail | ProductDetailView | — | Push from ProductList |
+| 4 | Search Results | SearchView | Explore | Overlay |
+| 5 | Cart | CartView | Cart | Root |
+| 6 | Profile | ProfileView | Profile | Root |
+
+## Tab Bar
+
+| # | Tab | Label | Icon (SF Symbol / Material) | Root Screen |
+|---|-----|-------|---------------------------|-------------|
+| 1 | Home | Home | house.fill / home | HomeView |
+| 2 | Explore | Explore | magnifyingglass / search | ProductListView |
+| 3 | Favorites | Saved | heart.fill / favorite | FavoritesView |
+| 4 | Profile | Profile | person.fill / person | ProfileView |
+
+## Brand Tokens
+
+### Colors (Light Mode)
+- primary: #{hex}
+- secondary: #{hex}
+- background: #{hex}
+- surface: #{hex}
+- textPrimary: #{hex}
+- textSecondary: #{hex}
+- error: #{hex}
+- success: #{hex}
+
+### Colors (Dark Mode)
+- primary: #{hex} (lightened for dark bg)
+- secondary: #{hex}
+- background: #1C1C1E
+- surface: #2C2C2E
+- textPrimary: #FFFFFF
+- textSecondary: #8E8E93
+
+### Layout
+- cornerRadius: {value}
+- shadowStyle: {none/subtle/prominent}
+- spacingScale: {tight/medium/generous}
+
+### Typography
+- fontStyle: {sans-serif/serif/rounded}
+- iOS: {system font recommendation}
+- Android: {font recommendation}
+
+## Data Model
+
+### {PrimaryEntity} (e.g., Product)
+```
+id: String (UUID)
+name: String
+description: String
+imageUrl: URL
+price: Double (optional)
+category: String
+rating: Double (optional)
+isFavorite: Bool
+createdAt: Date
+```
+
+### Categories
+- {Category 1}
+- {Category 2}
+- ...
+
+## Content Brief
+
+### App Name & Branding
+- **Display Name**: {name}
+- **Tagline**: {from website}
+
+### Tab Labels
+- Home, Explore, Saved, Profile
+
+### Screen Titles
+- Home: "{title}"
+- Explore: "{title}"
+- ...
+
+### Empty States
+- No items: "{message}"
+- No favorites: "{message}"
+- No search results: "{message}"
+
+### CTAs
+- Primary CTA: "{label}"
+- Secondary CTA: "{label}"
+
+## Mock Data Spec
+
+### {PrimaryEntity} (generate 12-15 items)
+Use realistic content observed on the website:
+- Item 1: {name}, {category}, {description snippet}
+- Item 2: ...
+(list 5-6 examples, agent generates the rest)
+
+### Categories (4-6)
+- {name}: {description}
+
+## AppConfig Values
+
+Map to CUSTOMIZE markers in the template:
+- `appName`: "{value}"
+- `primaryColor`: "#{hex}"
+- `accentColor`: "#{hex}"
+- `tabTitles`: ["{tab1}", "{tab2}", "{tab3}", "{tab4}"]
+- `categories`: ["{cat1}", "{cat2}", ...]
+- `entityName`: "{name}"
+- `entityNamePlural`: "{names}"
+(continue for all CUSTOMIZE markers)
+
+## Screen Changes
+
+### HomeView
+- Replace hero section with: {description from website}
+- Cards should display: {entity fields}
+- Style: {layout pattern from website}
+- Reference screenshot: page-home.png
+
+### {ScreenName}
+- Changes: {description}
+- Reference screenshot: page-{slug}.png
+
+(repeat for each screen)
+
+## Parallel Batches
+
+### Screen Customization Batches
+- **Batch 1** (Simulator 1): HomeView, ExploreView, SearchView
+- **Batch 2** (Simulator 2): DetailView, CreateView, FavoritesView
+- **Batch 3** (Simulator 3): ProfileView, SettingsView
+
+### UI Testing Batches
+- **Batch 1** (Simulator 1): Home tab, Explore tab
+- **Batch 2** (Simulator 2): Detail screen, Create flow, Favorites tab
+- **Batch 3** (Simulator 3): Profile tab, Settings
+
+### Maestro Test Batches
+- **Batch 1**: launch.yaml, home-tab.yaml, explore-tab.yaml
+- **Batch 2**: detail-screen.yaml, create-flow.yaml, search-flow.yaml
+- **Batch 3**: profile-tab.yaml, favorites-tab.yaml, e2e-navigation.yaml
+```
+
+## Template Selection Heuristics
+
+When deciding which template to use, consider:
+
+| Website Type | Best Template Match |
+|-------------|-------------------|
+| E-commerce / Shop | ShopTemplate |
+| Blog / News / Content | SocialTemplate |
+| Booking / Appointments | BookTemplate |
+| Fitness / Health tracking | TrackTemplate |
+| Finance / Banking | FinanceTemplate |
+| Social / Community | SocialTemplate |
+| Chat / Messaging | ChatTemplate |
+| General / Mixed | Skeleton (or scratch) |
+
+If the web-to-app manifest matches a template at 70%+ screen overlap, use it. Otherwise, recommend scratch mode or the Skeleton template.
+
+## Key Principles
+
+1. **Mobile-first thinking**: websites have infinite scroll space; mobile apps need concise, focused screens
+2. **Tab bar is the backbone**: map the site's main sections to 4-5 tabs maximum
+3. **Progressive disclosure**: detail pages are push-navigated from list pages, not shown inline
+4. **Brand fidelity**: match the website's colors, typography feel, and card/layout patterns as closely as the native platform allows
+5. **Content fidelity**: use actual content from the website (entity names, categories, descriptions) not generic placeholders
+6. **Platform conventions**: respect iOS HIG and Material Design guidelines even while matching the web brand

package/.cursor/skills/web-crawler/SKILL.md

@@ -0,0 +1,252 @@
+# Web Crawler Skill
+
+Systematically crawl a website using ai-tester MCP tools to capture its structure, brand, content, and functionality. Produce a structured crawl report that feeds into the web-analyzer skill.
+
+## Inputs
+
+- **URL**: The website URL to crawl
+- **Focus directive** (optional): Which sections to prioritize
+
+## Tools
+
+Use ONLY ai-tester MCP tools for all web interaction:
+- `inspect({ platform: "web", url: "...", saveBaseline: "...", label: "..." })` — load page, get screenshot + element tree
+- `navigate({ url: "..." })` — navigate to a page
+- `act({ action: "tap", selector: "..." })` — click elements (menus, dropdowns, modals)
+- `act({ action: "swipe", direction: "down" })` — scroll the page
+- `wait({ for: "duration", duration: 2000 })` — wait for content to load
+
+## Crawl Strategy
+
+### Phase 1: Home Page Analysis
+
+1. Load the home page:
+   ```
+   inspect({ platform: "web", url: "{url}", saveBaseline: "page-home", label: "Home" })
+   ```
+2. Save the screenshot path: `output/{app-name}/web-crawl/screenshots/page-home.png`
+3. Analyze the element tree for:
+   - **Navigation elements**: `<nav>`, header links, hamburger menus, footer links
+   - **Hero/banner sections**: main call-to-action areas
+   - **Content sections**: cards, lists, grids
+   - **Brand signals**: logo, primary colors in buttons/headers, font styles
+
+### Phase 2: Navigation Discovery
+
+From the home page element tree, identify all major navigation links:
+- Primary navigation (top nav bar, main menu)
+- Secondary navigation (sidebar, sub-menus)
+- Footer navigation (about, contact, legal)
+- Call-to-action links (sign up, get started, shop now)
+
+Build a **page queue** of URLs to visit. Prioritize:
+1. Primary nav links (always visit)
+2. Pages mentioned in the focus directive (if provided)
+3. Secondary nav links (visit if under 10 pages total)
+4. Skip: external links, auth/login pages, legal/privacy pages
+
+### Phase 3: Page-by-Page Crawl
+
+For each page in the queue (max 10 pages, depth 2 from home):
+
+1. Navigate to the page:
+   ```
+   navigate({ url: "{pageUrl}" })
+   ```
+2. Wait for content to load:
+   ```
+   wait({ for: "duration", duration: 2000 })
+   ```
+3. Capture screenshot + element tree:
+   ```
+   inspect({ saveBaseline: "page-{slug}", label: "{Page Title}" })
+   ```
+4. Scroll down to capture below-fold content:
+   ```
+   act({ action: "swipe", direction: "down" })
+   wait({ for: "duration", duration: 1000 })
+   inspect({ saveBaseline: "page-{slug}-scroll", label: "{Page Title} (scrolled)" })
+   ```
+5. Check for interactive elements:
+   - **Forms**: identify input fields, textareas, submit buttons
+   - **Dropdowns/modals**: tap to open, capture expanded state
+   - **Tabs/accordions**: click to reveal hidden content
+   - **Search**: identify search inputs and their behavior
+
+Record for each page:
+- URL
+- Page title
+- Screenshot file paths (above-fold + scrolled)
+- Element tree summary (interactive elements count, content sections)
+- Content type (list page, detail page, form page, informational page)
+- Key entities displayed (products, articles, users, events, etc.)
+
+### Phase 4: Brand Extraction
+
+From the collected screenshots and element trees, extract:
+
+**Colors**:
+- Primary color: dominant color in buttons, headers, and CTAs
+- Secondary color: accent color used for highlights, links, hover states
+- Background: main page background color
+- Surface: card/section background color
+- Text colors: heading color, body text color
+- Error/success colors if visible in any forms
+
+**Typography**:
+- Heading font style (serif, sans-serif, monospace)
+- Body text font style
+- Relative sizes (large headings, medium subheads, regular body)
+
+**Layout Patterns**:
+- Card style (rounded corners, shadows, borders)
+- Grid layout (2-column, 3-column, masonry)
+- List layout (compact, spacious, with thumbnails)
+- Spacing rhythm (tight, medium, generous)
+
+**Logo & Imagery**:
+- Logo description (text-based, icon, combination mark)
+- Image style (photos, illustrations, icons)
+- Hero section pattern (full-width image, gradient, video)
+
+### Phase 5: Functionality Inventory
+
+Catalog all interactive functionality discovered:
+
+- **Search**: search bar location, search behavior (instant, page-based)
+- **Forms**: sign up, contact, create/edit forms — list all fields
+- **Filters**: category filters, sort options, tag filters
+- **Navigation patterns**: pagination, infinite scroll, back/forward
+- **Authentication**: login/signup forms (note: do NOT attempt to log in)
+- **CRUD indicators**: create buttons, edit icons, delete actions
+- **E-commerce**: cart, checkout, product selection
+- **Social**: comments, likes, sharing, user profiles
+
+## Output
+
+Write `output/{app-name}/reports/02-web-crawl-report.md` with this structure:
+
+```markdown
+# Web Crawl Report
+
+## Source
+- **URL**: {url}
+- **Crawl date**: {date}
+- **Pages crawled**: {count}
+- **Focus directive**: {description or "none"}
+
+## Site Map
+
+| # | Page | URL | Type | Screenshot |
+|---|------|-----|------|------------|
+| 1 | Home | {url} | Landing | page-home.png |
+| 2 | Products | {url}/products | List | page-products.png |
+| ... | | | | |
+
+## Navigation Structure
+
+### Primary Navigation
+- Home
+- Products → /products
+- About → /about
+- Contact → /contact
+
+### Secondary Navigation
+(sub-menus, sidebar links)
+
+### Footer Navigation
+(footer links)
+
+## Brand Palette
+
+### Colors
+- **Primary**: #{hex} (from: buttons, headers)
+- **Secondary**: #{hex} (from: links, accents)
+- **Background**: #{hex}
+- **Surface**: #{hex} (cards, sections)
+- **Text Primary**: #{hex}
+- **Text Secondary**: #{hex}
+
+### Typography
+- **Headings**: {font style description}
+- **Body**: {font style description}
+- **Size scale**: {relative sizes}
+
+### Layout Patterns
+- **Cards**: {description — rounded corners, shadow, border}
+- **Grid**: {column count, gap}
+- **Spacing**: {tight/medium/generous}
+
+### Logo & Imagery
+- **Logo**: {description}
+- **Image style**: {photos/illustrations/icons}
+
+## Content Model
+
+### Entities
+1. **{Entity Name}** (e.g., Product)
+   - Fields: name, price, image, description, category, rating
+   - Seen on: /products, /products/{id}
+   - Count: ~{n} items visible
+
+2. **{Entity Name}** (e.g., Blog Post)
+   - Fields: title, author, date, excerpt, image
+   - Seen on: /blog, /blog/{slug}
+
+### Categories
+- {Category 1}: {description}
+- {Category 2}: {description}
+
+## Functionality Inventory
+
+### Search
+- Location: {header/page}
+- Type: {instant/page-based}
+
+### Forms
+1. **{Form Name}** (e.g., Contact Form)
+   - Fields: name, email, message
+   - Location: /contact
+
+### Filters & Sorting
+- {description of filter/sort options}
+
+### Authentication
+- Login: {yes/no, location}
+- Sign up: {yes/no, location}
+
+### Other Features
+- {feature}: {description}
+
+## Page Details
+
+### Page: {Page Name}
+- **URL**: {url}
+- **Type**: {list/detail/form/landing}
+- **Screenshot**: page-{slug}.png
+- **Key elements**: {description}
+- **Interactive elements**: {count} buttons, {count} links, {count} inputs
+- **Content**: {summary of what's displayed}
+
+(repeat for each page)
+```
+
+## Limits & Safety
+
+- **Max pages**: 10 (prioritize primary nav and focus directive pages)
+- **Max depth**: 2 levels from home page
+- **Timeout**: 5 seconds per page load — skip pages that don't load
+- **No authentication**: do NOT attempt to log in or create accounts
+- **No form submission**: inspect forms but do NOT submit them
+- **No payments**: do NOT interact with payment flows
+- **External links**: skip links to other domains
+- **Rate limiting**: wait 1-2 seconds between page navigations
+
+## Focus Directive Handling
+
+If a focus directive is provided:
+1. Still crawl the home page first (for brand extraction)
+2. Prioritize pages related to the directive
+3. Explore those sections more deeply (depth 2)
+4. Other sections: capture at depth 1 only (screenshot + basic element tree)
+5. In the crawl report, mark which pages are "primary" (from directive) vs "secondary"

package/AGENTS.md

@@ -29,8 +29,8 @@ flowchart TD
     S6 -->|Build fails| S6fix["Fix errors"]
     S6fix --> S6
 
-    S6 -->|Build succeeds| S7["Step 7: PARALLEL — Security Audit + Validation"]
-    S7 --> S8["Step 8: Boot Simulators"]
+    S6 -->|Build succeeds| S7["Step 7: PARALLEL — Audits + Boot Sims"]
+    S7 --> S8["Step 8: Install App"]
     S8 --> S9["Step 9: PARALLEL — Interactive UI Testing (2-3 simulators)"]
 
     S9 -->|Bug found| S9fix["Fix + rebuild"]
@@ -45,18 +45,18 @@ flowchart TD
 
 | Step | Name | Parallelism | What Happens |
 |------|------|-------------|-------------|
-| 0 | Analysis Phase | **4 parallel tasks** | Validate prompt + select template + select design brand + select shared modules concurrently. Abort if validation fails. |
+| 0 | Analysis Phase | **3 parallel tasks** | Validate prompt + catalog analysis (template + modules) + design brand concurrently. Abort if validation fails. |
 | 1 | Clone Template | — | Copy the template into `output/{app-name}/`. |
 | 2 | Rename App | — | Update display name, bundle ID, package name, all code references. Uses script if available. |
 | 3 | Customization Planning | — | Produce a manifest with design brief, content brief, AppConfig values, mock data spec, module integration plan, per-screen changes, and parallel batches. |
 | 4 | Update Shared Files + Integrate Modules | — | Apply manifest to AppConfig, MockDataProvider, Theme/Colors. Integrate selected modules by reading references from `templates/shared/` and writing adapted code into the app. |
 | 5 | Screen Customization | **2-3 parallel subagents** | Each subagent runs the platform customizer skill (ios-customizer, android-customizer, or react-native-customizer) on its assigned batch of screen files from the manifest. |
 | 6 | Build | — | Compile the app. Fix errors and rebuild until it succeeds. Save the artifact path. |
-| 7 | Post-Build Audits | **2 parallel tasks** | Security audit + output validation run concurrently. |
-| 8 | Boot Simulators | — | Boot 2-3 simulators, install app on all. |
+| 7 | Audits + Boot Sims | **3 parallel tasks** | Security audit + output validation + boot simulators run concurrently (sim boot is independent, saves ~30-60s). |
+| 8 | Install App | — | Install the build artifact on all (already booted) simulators. |
 | 9 | Interactive Testing | **2-3 parallel subagents** | Each subagent tests its screen batch on its own simulator. Fix bugs if found. |
 | 10 | Maestro Tests | **2-3 parallel subagents** | Each subagent runs its YAML test batch on its own simulator. All must pass. |
-| 11 | Screenshot Collection | — | Capture one clean screenshot per main tab using ai-tester. Save to `screenshots/` for GitHub PRs and README. |
+| 11 | Screenshots + Cleanup | — | Capture one clean screenshot per main tab using ai-tester. Shut down simulators. |
 
 ### Quick Build Workflow
 
@@ -81,19 +81,38 @@ When `--scratch` is used, the workflow changes. The agent reads templates as ref
 
 | Step | Name | Parallelism | What Happens |
 |------|------|-------------|-------------|
-| 0 | Analysis Phase | **4 parallel tasks** | Same as template mode: validate prompt + select 1-3 reference templates + select design brand + select shared modules. |
+| 0 | Analysis Phase | **3 parallel tasks** | Same as template mode: validate prompt + catalog analysis (1-3 reference templates + modules) + design brand. |
 | 1 | Architecture + Content Planning | -- | Read reference templates and module list. Plan screens, models, navigation. Produce content brief with all user-facing strings. Account for which features modules provide. |
 | 2 | Project Scaffolding | -- | Create a new Xcode/Gradle/React Native project from scratch. Verify it compiles. |
 | 3 | Module Integration | -- | Read shared module references from `templates/shared/` and write adapted code into the project. Done before custom code so the agent builds on module APIs. |
 | 4 | Write All Code + Design | -- | Write screens, viewmodels, models, mock data, theme. Apply design brand. Use content brief for all strings. |
 | 5 | Build | -- | Same as template mode. |
-| 6 | Post-Build Audits | **2 parallel tasks** | Same as template mode. |
-| 7 | Boot Simulators | -- | Same as template mode. |
+| 6 | Audits + Boot Sims | **3 parallel tasks** | Same as template mode. |
+| 7 | Install App | -- | Same as template mode. |
 | 8 | Interactive Testing | **2-3 parallel subagents** | Same as template mode. |
 | 9 | Maestro Tests | **2-3 parallel subagents** | Same as template mode. |
 
 Key differences: no clone/rename steps, modules read from `templates/shared/` as reference and adapted into the project, content planned before implementation, agent has full architectural freedom.
 
+### Deep Test Workflow
+
+When `--deep-test <app-name>` is used, AppAgent runs a comprehensive 4-phase testing pipeline on a previously built app. Optionally auto-fixes discovered bugs with `--fix`.
+
+```bash
+appagent --deep-test my-app           # test only
+appagent --deep-test my-app --fix     # test + auto-fix
+appagent --fix my-app                 # standalone fix from existing bug report
+```
+
+| Phase | Name | Parallelism | What Happens |
+|-------|------|-------------|-------------|
+| 1 | Test Plan Generation | -- | Analyze source code offline (Views, ViewModels, AppConfig, MockDataProvider). Produce `10-test-plan.md`. |
+| 2 | Exploratory Testing | **Parallel with Phase 3** | Screenshot + a11y tree driven testing on Simulator 1. Does NOT read source code. Finds visual, a11y, UX, content bugs. |
+| 3 | Structured Testing | **Parallel with Phase 2** | Follows test plan from Phase 1 on Simulator 2+. Marks each test case pass/fail. |
+| 4 | Auto-Fix (optional) | -- | Reads merged bug report, fixes each bug, rebuilds, verifies. Only runs with `--fix`. |
+
+Key differences from `--test`: generates a test plan before testing, adds exploratory testing driven by screenshots + accessibility tree, produces a structured bug report, supports standalone fix mode.
+
 ### Update Workflow
 
 When `--update <source>` is used, AppAgent modifies an existing app instead of creating a new one. The source can be a GitHub URL, a local path, or an app name from `output/`.
@@ -127,9 +146,8 @@ Skills are self-contained documents the agent reads when it reaches a workflow s
 | Step | Skill | Report File |
 |------|-------|------------|
 | 0 | prompt-validator | `01-prompt-validation.md` |
-| 0 | template-selector | `02-template-selection.md` |
+| 0 | catalog-analyzer | `02-catalog-analysis.md` |
 | 0 | design-selector | `03-design-brand.md` |
-| 0 | module-selector | `02b-module-selection.md` |
 | 4 | module-integrator | -- |
 | 2 | app-renaming | -- |
 | 3 | customization-planner | `customization-manifest.md` |
@@ -144,6 +162,9 @@ Skills are self-contained documents the agent reads when it reaches a workflow s
 | 7 | code-auditor | `07-security-audit.md` |
 | 7 | output-validator | `08-validation.md` |
 | 8-10 | ui-tester | `09-ui-testing.md` |
+| deep-test (Phase 1) | test-planner | `10-test-plan.md` |
+| deep-test (Phase 2) | exploratory-tester | `11-bug-report.md` |
+| deep-test (Phase 4) | bug-fixer | `12-fix-report.md` |
 
 Skills that share a step with other activities (e.g., Steps 4's multiple skills all contribute to shared file updates) run sequentially within that step. The `customization-planner` (Step 3) is the key enabler — it produces a manifest that drives all subsequent steps and enables parallel screen customization (Step 5) and parallel UI testing (Steps 8-10).