@shaykec/app-agent 1.0.10 → 1.0.12

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

@@ -0,0 +1,55 @@
+# Web Analyzer Skill
+
+Analyze web crawl report + screenshots to produce a web-to-app manifest for the build pipeline.
+
+## Inputs
+- `reports/02-web-crawl-report.md` — crawl data
+- `web-crawl/screenshots/*.png` — passed as image attachments
+- Focus directive (optional), platform
+
+## Process
+
+### 1. Page-to-Screen Mapping
+| Web Pattern | Mobile Pattern |
+|-------------|---------------|
+| Home/landing | Home tab |
+| List/catalog | List screen (scrollable) |
+| Detail page | Detail screen (push nav) |
+| Search | Explore tab or search overlay |
+| Category/filter | Filter sheet or Explore tab |
+| User profile | Profile tab |
+| Favorites/saved | Favorites tab |
+| Form (create) | Create screen (modal/push) |
+| Cart/checkout | Cart tab (e-commerce) |
+
+Tab bar: max 4-5 tabs. Home + Explore + Favorites + Profile is the default.
+
+### 2. Brand Tokens
+Extract from crawl report + visual screenshots:
+- Colors: primary, secondary, background, surface, textPrimary, textSecondary, error, success
+- Dark mode variants (lighten primary, dark backgrounds)
+- Layout: cornerRadius, shadowStyle, spacingScale
+- Typography: fontStyle mapped to system fonts
+
+### 3. Data Model
+Map each entity to struct/class: id, name, description, imageUrl, category, etc.
+
+### 4. Content Brief
+Adapt website copy: app name, tab labels, screen titles, empty states, CTAs, category names.
+
+### 5. Template Selection
+Compare against CATALOG.md. If 70%+ screen match → use template. Otherwise → scratch or Skeleton.
+
+### 6. Parallel Batches
+Divide into 2-3 batches for screen customization, UI testing, and Maestro tests.
+
+## Output: `reports/03-web-to-app-manifest.md`
+
+Include: screen mapping table, tab bar spec, brand tokens (light + dark), data model, content brief, mock data spec, AppConfig values, per-screen change list with reference screenshots, parallel batches.
+
+## Key Principles
+1. Mobile-first: concise screens, not infinite scroll
+2. Tab bar is backbone: 4-5 tabs max
+3. Brand fidelity: match website colors/typography/patterns
+4. Content fidelity: use real website content, not placeholders
+5. Platform conventions: respect HIG/Material Design within the brand

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

@@ -0,0 +1,54 @@
+# Web Crawler Skill
+
+Crawl a website using ai-tester MCP to capture structure, brand, content, and functionality.
+
+## Tools (ai-tester MCP only)
+
+- `inspect({ platform: "web", url: "...", saveBaseline: "...", label: "..." })` — screenshot + element tree
+- `navigate({ url: "..." })` — go to page
+- `act({ action: "tap", selector: "..." })` — click elements
+- `act({ action: "swipe", direction: "down" })` — scroll
+- `wait({ for: "duration", duration: 2000 })` — wait for load
+
+## Crawl Strategy
+
+### Phase 1: Home Page
+1. `inspect({ platform: "web", url: "{url}", saveBaseline: "page-home", label: "Home" })`
+2. Analyze element tree: nav links, hero sections, content sections, brand signals
+
+### Phase 2: Navigation Discovery
+From home page element tree, build page queue:
+- Primary nav links (always visit)
+- Focus directive pages (if provided)
+- Secondary nav (if under 10 total)
+- Skip: external links, auth pages, legal pages
+
+### Phase 3: Page-by-Page Crawl (max 10 pages, depth 2)
+For each page:
+1. `navigate({ url: "{pageUrl}" })`
+2. `wait({ for: "duration", duration: 2000 })`
+3. `inspect({ saveBaseline: "page-{slug}", label: "{Title}" })`
+4. Scroll + capture: `act({ action: "swipe", direction: "down" })` then `inspect` again
+5. Record: URL, title, screenshot paths, element summary, content type, entities
+
+### Phase 4: Brand Extraction
+From screenshots + element trees:
+- **Colors**: primary (buttons/headers), secondary (accents), background, surface, text colors
+- **Typography**: heading/body font style, size scale
+- **Layout**: card style, grid columns, spacing rhythm
+- **Logo/imagery**: logo description, image style
+
+### Phase 5: Functionality Inventory
+Catalog: search, forms (fields only — don't submit), filters, auth indicators, CRUD, e-commerce, social features.
+
+## Output: `reports/02-web-crawl-report.md`
+
+Include: site map table, navigation structure, brand palette, content model (entities + fields), functionality inventory, per-page details with screenshot references.
+
+## Limits
+- Max 10 pages, depth 2
+- 5s timeout per page
+- No login/auth, no form submission, no payments
+- Skip external links
+- 1-2s between navigations
+- If focus directive: prioritize those sections at depth 2, others at depth 1

package/.cursor/rules/workflow.mdc

@@ -47,6 +47,8 @@ Specialised skills are in `.cursor/skills/`. For each workflow step that referen
 | deep-test | `test-planner` | Analyze code and produce structured test plan (Phase 1) |
 | deep-test | `exploratory-tester` | Screenshot + a11y tree driven exploratory testing (Phase 2) |
 | deep-test | `bug-fixer` | Read bug report and fix bugs systematically (Phase 4) |
+| 0 (web-clone) | `web-crawler` | Crawl website using ai-tester MCP — screenshots, element trees, brand |
+| 1 (web-clone) | `web-analyzer` | Analyze crawled data — map pages to screens, extract brand, produce manifest |
 
 When a step references a skill, read `.cursor/skills/{name}/SKILL.md` and follow its instructions. Each skill file contains the full expert-level instructions for that task.
 
@@ -292,6 +294,33 @@ Phase 1 runs offline. Phases 2+3 run in parallel on separate simulators. Phase 4
 
 Key: the exploratory tester does NOT read source code — it tests purely from screenshots and the accessibility tree.
 
+## Web Clone Workflow
+
+When `--url <website-url>` is used (or "Clone from website" is selected interactively), AppAgent crawls a live website using ai-tester MCP and generates a native mobile app mirroring its structure, brand, and content.
+
+### CLI Usage
+
+```bash
+appagent --url https://example.com -p ios
+appagent --url https://example.com -p android -d "focus on the shop and checkout flow"
+appagent --url https://example.com -p both
+```
+
+### Web Clone Steps
+
+| Step | Name | Parallelism | What Happens |
+|------|------|-------------|-------------|
+| 0 | Validation + Web Crawl | **2 parallel tasks** | Validate prompt + crawl website (screenshots + element trees) |
+| 1 | Web Analysis + Template Selection | — | Map pages to screens, extract brand, select template |
+| 2 | Clone + Rename | — | Clone selected template, rename app |
+| 3 | Apply Brand + Content | — | Apply website brand tokens and content |
+| 4 | Screen Customization | **2-3 parallel subagents** | Each receives website screenshots as visual reference |
+| 5 | Build | — | Compile, fix errors |
+| 6 | Audits + Boot Sims | **3 parallel tasks** | Security + validation + boot simulators |
+| 7-10 | UI Testing | **parallel** | Interactive testing + Maestro tests |
+
+Key differences: brand from website screenshots (not `designs/brands/`), content from website, screenshots as visual context for subagents, `web-crawler` + `web-analyzer` skills, new reports (`02-web-crawl-report.md`, `03-web-to-app-manifest.md`).
+
 ## Update Workflow
 
 When the user passes `--update <source>` (or `-u <source>`), the agent 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/`.

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