@shaykec/app-agent 1.0.0

package/README.md

@@ -0,0 +1,814 @@
+# AppAgent CLI
+
+AI-powered mobile app generator that turns a natural language description into a fully customized iOS or Android app using [Cursor CLI](https://cursor.com/cli) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code) agents and a library of production-ready templates.
+
+## How It Works
+
+```
+"A pet grooming appointment     ┌─────────────┐     output/pawspa-ios/
+ booking app called PawSpa"  -> │  AppAgent    │ ->  (ready-to-build
+                                │  CLI + Agent │      Xcode / Gradle project)
+                                └─────────────┘
+```
+
+1. You describe the app you want in plain English
+2. AppAgent picks the best template from a catalog of 14 categories + selects a design brand and shared modules
+3. An AI agent (Cursor CLI or Claude Code) clones the template, integrates shared modules, and customizes everything -- app name, branding, screens, mock data, navigation, theme
+4. Specialized skills verify the build compiles, validate consistency, and UI-test on a simulator
+5. Every step writes a structured report to `reports/` for full auditability
+6. Optionally pushes the finished app to a new GitHub repo
+
+## Features
+
+- **14 app templates** -- Shop, Track, Book, Social, Finance, Chat, Learn, Health, Task, Media, Map, Dash, Family, Game -- each with 13-17 screens
+- **49 shared modules** -- reference implementations for auth, payments, push notifications, analytics, and more -- selected by keyword matching and adapted by the agent into each app
+- **13 design brands** -- Modern Minimal, Vibrant Playful, Corporate Professional, Dark Luxe, Kids Playful, Medical Clinical, and more
+- **Dual platform** -- iOS (Swift/SwiftUI) and Android (Kotlin/Jetpack Compose), with parallel builds via `-p both`
+- **AI-driven selection** -- the agent picks the best template, design brand, and shared modules for your app
+- **Deep customization** -- renames the entire project, updates AppConfig, rewrites mock data, adjusts navigation, theme, and app icon
+- **Content generation** -- writes all user-facing strings (onboarding, labels, CTAs, errors) with consistent voice
+- **Self-healing pipeline** -- hooks validate output and auto-retry on failure (up to 3 times)
+- **Security gates** -- two-layer prompt validation (regex sanitizer + AI auditor) and post-build code audit
+- **Live UI testing** -- simulator/emulator testing via [ai-tester](https://github.com/shayke-cohen/ai-tester) MCP + Maestro regression tests
+- **Report files** -- every step writes a markdown report + machine-readable `summary.json`
+- **GitHub integration** -- creates a repo and pushes the finished app with one confirmation
+- **From-scratch mode** -- generate apps from scratch using templates as architectural reference, with full creative freedom on architecture
+- **Quick build mode** -- skeleton template + fast inline customization + smoke test, no analysis overhead
+- **App management** -- list all previously built apps and re-launch any of them on a simulator/emulator
+- **Standalone UI testing** -- re-run UI testing on a previously built app without rebuilding from scratch
+
+## Prerequisites
+
+- **Node.js** 18+
+- **Agent engine** (at least one):
+  - **Cursor IDE** with CLI access (`cursor` command in PATH) -- default engine
+  - **Claude Code** CLI (`claude` command in PATH) -- alternative engine, install via `curl -fsSL https://claude.ai/install.sh | bash`
+- **Xcode** (for iOS builds) and/or **Android Studio** (for Android builds)
+- **GitHub CLI** (`gh`) -- optional, for auto-pushing to GitHub
+
+## Quick Start
+
+### Run with npx (no install required)
+
+```bash
+# Generate an iOS app in your current directory
+npx app-agent -d "A pet grooming booking app called PawSpa"
+
+# Interactive mode -- prompts for description, platform, engine, model
+npx app-agent
+```
+
+When running via `npx`, AppAgent scaffolds a temporary workspace in your current directory (symlinks for templates, skills, and config files), runs the agent, and cleans up after. The generated app is written to `output/` in your current directory.
+
+### Run from source (development)
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Or build and run
+npm run build
+npm start
+```
+
+The CLI will prompt you for:
+
+1. **App description** -- describe what your app does
+2. **Platform** -- iOS (default) or Android
+3. **Agent engine** -- Cursor CLI (default) or Claude Code
+4. **AI model** -- which LLM to use (default: sonnet-4.5)
+
+5. **Build mode** -- Template (default), Quick (fast skeleton-based), or From Scratch
+
+Then it launches the selected agent engine, which takes 3-30 minutes depending on mode.
+
+### Non-Interactive (CI/scripting)
+
+```bash
+# Build with Cursor CLI (default engine, default platform ios)
+npx app-agent -d "A pet grooming booking app called PawSpa"
+
+# Explicit platform and engine
+npx app-agent -d "A pet grooming booking app called PawSpa" --platform android --engine claude
+
+# Push the finished app to a new private GitHub repo
+npx app-agent -d "A pet grooming booking app called PawSpa" --push
+
+# Push with a custom repo name
+npx app-agent -d "A pet grooming booking app called PawSpa" --push --repo-name pawspa-ios
+
+# Build both iOS and Android in parallel
+npx app-agent -d "A social media app called Chirper" -p both --push
+
+# Or using npm start from source
+npm start -- -d "A pet grooming booking app called PawSpa"
+```
+
+| Flag | Description |
+|------|-------------|
+| `-d`, `--description` | App description (required for build) |
+| `-p`, `--platform` | `ios` (default), `android`, or `both` (parallel dual-platform build -- all modes except update) |
+| `-e`, `--engine` | Agent engine: `cursor` (default) or `claude` |
+| `--model` | AI model to use (default: `sonnet-4.5`) |
+| `--push` | Create a private GitHub repo and push the generated app |
+| `--repo-name` | Custom repository name (default: derived from app directory name) |
+| `-l`, `--list` | List all previously built apps in `output/` |
+| `-r`, `--run <name>` | Launch a built app on a simulator/emulator by directory name |
+| `-t`, `--test <name>` | Run UI testing on a previously built app (interactive testing + Maestro) |
+| `-s`, `--scratch` | Build from scratch using templates as reference instead of cloning (slower, more flexible) |
+| `-q`, `--quick` | Quick build -- skeleton template, fast inline customization, smoke test only |
+| `-u`, `--update <source>` | Update an existing app from a GitHub URL, local path, or app name. Creates a branch and PR. |
+
+Defaults can also be set via environment variables: `APPAGENT_ENGINE=cursor` or `APPAGENT_PLATFORM=android`.
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `APPAGENT_ENGINE` | Default engine (`claude` or `cursor`) |
+| `APPAGENT_PLATFORM` | Default platform (`ios` or `android`; `both` only via CLI flag) |
+| `CLAUDE_CODE_PATH` | Custom path to the `claude` binary |
+| `CURSOR_CLI_PATH` | Custom path to the `cursor` binary |
+| `AI_TESTER_PATH` | Path to the ai-tester installation (for UI testing) |
+| `APPAGENT_MCP_CONFIG` | Custom path to `.mcp.json` for Claude Code |
+
+## Usage Example
+
+```
+$ npm run dev
+
+◇  Describe the app you want to build:
+│  A vintage vinyl record shop called VinylVault where collectors can browse
+│  rare records, check prices, and place orders for delivery
+
+◇  Which platform?
+│  iOS (Swift / SwiftUI)
+
+◇  Which agent engine?
+│  Cursor CLI
+
+◇  Which AI model?
+│  Claude 4.5 Sonnet
+
+◇  Launching Cursor CLI agent...
+│
+●  [0s]   Model: claude-sonnet-4-5-20250929
+●  [3s]   SUBAGENT dispatched: Select best iOS template
+●  [3s]   SUBAGENT dispatched: Select best design brand
+●  [10s]  Report: 02-template-selection.md
+●  [11s]  SHELL: cp -r templates/ios/ShopTemplate/ output/vinylvault-ios/
+●  [30s]  Report: 05-content-brief.md
+●  [60s]  Progress: 48 tool calls, 15 writes, 28 reads
+●  [75s]  SUBAGENT dispatched: Customize iOS features
+●  [120s] Progress: 95 tool calls, 38 writes, 52 reads
+●  [140s] SUBAGENT dispatched: Build VinylVault iOS app
+●  [155s] SHELL: xcodebuild -project VinylVault.xcodeproj -scheme VinylVault...
+●  [180s] SUBAGENT dispatched: Security audit of generated code
+●  [180s] SUBAGENT dispatched: Validate output completeness
+│
+┌ Agent Summary ────────────────────────────────┐
+│ Completed in 12m 34s                          │
+│   Tool calls: 230                             │
+│   Files written: 42 | Files read: 128         │
+│   Subagents: 6 (template, design, customize,  │
+│     build, security, validate)                 │
+│   Shell commands: 18                           │
+└───────────────────────────────────────────────┘
+
+◇  Push to GitHub? (Y/n)
+│  Y
+
+◇  Done! Your app is at: https://github.com/you/vinylvault-ios
+```
+
+## Managing Built Apps
+
+All generated apps are preserved in `output/`. You can list them and re-launch any of them on a simulator without rebuilding.
+
+### List all apps
+
+```bash
+npm start -- --list
+```
+
+Example output:
+
+```
+  Directory              App Name           Platform   Template           Build        Status
+  ─────────              ────────           ────────   ────────           ─────        ──────
+  vinylvault-ios         VinylVault         ios        ShopTemplate       ✓ SUCCESS    ✓ PASS (runnable)
+  pawspa-android         PawSpa             android    BookTemplate       ✓ SUCCESS    ✓ PASS (runnable)
+  taskly-ios             Taskly             ios        TrackTemplate      — —          … in-progress
+```
+
+### Run a previously built app
+
+```bash
+# Launch on iOS Simulator
+npm start -- --run vinylvault-ios
+
+# Launch on Android emulator
+npm start -- --run pawspa-android
+```
+
+The CLI reads the app's `summary.json` to find the platform, bundle ID, and build artifact, then uses `xcrun simctl` (iOS) or `adb` (Android) to install and launch the app on a simulator.
+
+### Test a previously built app
+
+Run UI testing independently on an app that's already been built. This is useful when:
+- The full pipeline timed out before reaching UI testing
+- You want to re-test after making manual code changes
+- UI testing failed and you want to retry without rebuilding from scratch
+- The build artifact was cleaned and needs to be rebuilt before testing
+
+```bash
+# Run UI testing with default engine and model
+npm start -- --test vinylvault-ios
+
+# Specify engine and model
+npm start -- --test vinylvault-ios --engine claude --model sonnet-4.5
+
+# With npx
+npx app-agent --test vinylvault-ios
+```
+
+The `--test` command reads the app's `summary.json` and `customization-manifest.md` to understand the app context, then launches an AI agent focused exclusively on:
+
+1. Booting simulators and installing the app
+2. Interactive testing of every screen and interactive element
+3. Fixing any bugs found (with rebuild if needed, max 3 cycles)
+4. Generating Maestro regression tests
+5. Running all Maestro tests until they pass
+
+If the build artifact has been cleaned (e.g., DerivedData was deleted), the agent will automatically rebuild the app before testing.
+
+### Build from scratch
+
+By default, AppAgent clones a template and customizes it. The `--scratch` flag enables a from-scratch mode where the agent reads templates as architectural reference and writes all code itself. This is useful when:
+
+- Your app is a hybrid of multiple categories (e.g., "a social fitness tracker with marketplace")
+- Your app doesn't fit neatly into any single template category
+- You want cleaner output without any template artifacts
+- You need full architectural freedom (custom screen count, navigation, directory layout)
+
+```bash
+# From scratch with default engine and model
+npm start -- -d "A social fitness tracker with marketplace" --scratch
+
+# From scratch with specific platform
+npm start -- -d "A social fitness tracker with marketplace" --scratch --platform android
+
+# With npx
+npx app-agent -d "A social fitness tracker with marketplace" --scratch
+```
+
+The from-scratch workflow:
+
+1. Selects 1-3 reference templates and reads them for architectural patterns (MVVM, navigation, theming)
+2. Plans the app architecture and content, accounting for which features shared modules provide
+3. Scaffolds a new Xcode/Gradle project from scratch
+4. Integrates shared modules (before writing custom code, so the agent builds on module APIs)
+5. Writes all custom code -- screens, viewmodels, models, mock data, theme
+6. Builds, audits, and UI-tests the app (same as template mode)
+
+Note: From-scratch mode takes 2-3x longer than template mode and uses more tokens. Use template mode (the default) when your app fits one of the 14 template categories.
+
+### Quick build
+
+The `--quick` flag (or `-q`) enables a fast-track mode that skips template selection, design brand matching, shared module integration, and the full planning pipeline. Instead, the orchestrator pre-clones a domain-agnostic **Skeleton template** before the agent starts, and the agent focuses purely on filling in domain-specific content.
+
+```bash
+# Quick build (non-interactive)
+npx app-agent -q -d "A pet grooming booking app called PawSpa"
+
+# Quick build for Android
+npx app-agent --quick -d "Coffee shop ordering app" --platform android
+
+# From source
+npm start -- -q -d "A pet grooming booking app called PawSpa"
+```
+
+The quick build workflow:
+
+1. **Orchestrator** clones `templates/{platform}/Skeleton/` into `output/{app-name}/` and generates the Xcode project (iOS)
+2. **Agent** fills AppConfig CUSTOMIZE markers with domain values
+3. **Agent** rewrites MockDataProvider with realistic domain data
+4. **Agent** customizes screen Views and ViewModels with domain content
+5. **Agent** adjusts theme colors if the domain implies them
+6. **Agent** builds the app (using the `build-tester` skill, max 3 rebuild cycles)
+7. **Agent** boots one simulator, installs the app, and smoke tests each tab
+
+What's skipped vs. template mode: no template/brand/module selection, no customization manifest, no parallel subagents, no security audit, no output validation, no Maestro tests. This makes quick builds significantly faster -- typically 3-5 minutes vs. 15-30 minutes for template mode.
+
+The Skeleton template provides:
+- **4 tabs** (Home, Explore, Favorites, Profile) with working navigation
+- **6 screens** (Home list, Explore search, Detail, Favorites, Profile, Create form)
+- **MVVM architecture** already wired (Views + ViewModels + Models + MockDataProvider)
+- **Theme system** with centralized colors, typography, spacing
+- **Accessibility identifiers** on all interactive elements
+- **Compiles out of the box** -- the agent starts with a working app
+
+#### Dual-platform builds (`-p both`)
+
+You can build both iOS and Android simultaneously by passing `-p both`. The orchestrator runs two AI agents in parallel -- one for each platform -- and produces a monorepo structure:
+
+```bash
+# Quick mode (fastest)
+npx app-agent -q -d "A Twitter clone called Chirper" -p both
+
+# Template mode
+npx app-agent -d "A recipe sharing app called Yumbook" -p both
+
+# From-scratch mode
+npx app-agent -s -d "A social fitness tracker" -p both
+
+# With GitHub push
+npx app-agent -d "A Twitter clone called Chirper" -p both --push
+```
+
+This creates a monorepo structure:
+
+```
+output/chirper/
+├── ios/          # Full iOS project (Swift/SwiftUI)
+│   ├── Chirper.xcodeproj
+│   ├── Chirper/
+│   └── ...
+└── android/      # Full Android project (Kotlin/Compose)
+    ├── app/
+    ├── build.gradle.kts
+    └── ...
+```
+
+Two independent agents run concurrently -- one customizes the iOS project, the other customizes the Android project. Each agent independently selects templates/brands, fills in domain content, builds, and tests. The orchestrator waits for both to finish, validates each platform, and optionally pushes the combined monorepo to GitHub as a single repository. Logs from each agent are prefixed with `[ios]` / `[android]` for clarity.
+
+Note: `-p both` is supported in all build modes (template, quick, from-scratch) but not in update mode, where the platform is auto-detected from the target app.
+
+### Update an existing app
+
+The `--update` flag (or `-u`) modifies an existing app based on a change description. It can take a GitHub URL, a local path, or an app name from `output/`.
+
+```bash
+# Update from a GitHub URL (clones, branches, creates PR)
+npx app-agent --update https://github.com/user/my-app -d "add dark mode toggle to settings"
+
+# Update an app previously built by AppAgent
+npx app-agent --update pawspa-ios -d "add search feature to explore tab"
+
+# Update a local project
+npx app-agent --update ./path/to/my-app -d "fix crash on login screen"
+
+# From source
+npm start -- --update https://github.com/user/my-app -d "add push notification support"
+```
+
+The update workflow:
+
+1. **Orchestrator** resolves the source: clones the repo (GitHub URL) or finds the local directory
+2. **Orchestrator** auto-detects the platform (iOS/Android) from project files
+3. **Orchestrator** creates a git branch: `appagent/{slug-from-description}`
+4. **Agent** explores the codebase to understand the architecture and code patterns
+5. **Agent** plans and implements the requested changes
+6. **Agent** builds and smoke tests the changes
+7. **Orchestrator** commits the changes on the branch
+8. **Orchestrator** pushes and creates a PR (GitHub sources) or offers to push (local sources)
+
+Two speed tiers:
+- **AppAgent-generated apps** (detected via `reports/summary.json`) -- agent knows the MVVM architecture, skips codebase exploration
+- **Unknown repos** -- agent explores the codebase first (README, directory structure, architecture patterns)
+
+## Project Structure
+
+```
+.
+├── src/                          # Orchestrator CLI (TypeScript)
+│   ├── index.ts                  # Main entry point
+│   ├── cli.ts                    # Interactive user input + arg parsing
+│   ├── config.ts                 # Constants, schemas, engine/model config
+│   ├── workspace.ts              # Workspace scaffolding for npx execution
+│   ├── engines/                  # Agent engine abstraction layer
+│   │   ├── types.ts              # AgentEngine interface and shared types
+│   │   ├── cursor-engine.ts      # Cursor CLI engine implementation
+│   │   ├── claude-engine.ts      # Claude Code engine implementation
+│   │   ├── factory.ts            # createEngine() factory
+│   │   └── index.ts              # Barrel exports
+│   ├── app-manager.ts            # List and run previously built apps
+│   ├── prompt-builder.ts         # Builds the agent prompt
+│   ├── prompt-sanitizer.ts       # Layer 1 prompt security (regex-based)
+│   ├── agent-runner.ts           # Legacy Cursor CLI runner (kept for reference)
+│   ├── validator.ts              # Validates generated app output + reports
+│   ├── github.ts                 # GitHub repo creation, push, clone, PR
+│   └── updater.ts                # Update mode: source resolution, platform detection, branching
+│
+├── prompts/
+│   ├── agent-prompt.md           # Template-mode build prompt (default)
+│   ├── scratch-agent-prompt.md   # From-scratch build prompt (used by --scratch)
+│   ├── quick-agent-prompt.md     # Quick build prompt (used by --quick)
+│   ├── update-agent-prompt.md   # Update mode prompt (used by --update)
+│   └── test-agent-prompt.md      # UI testing prompt template (used by --test)
+│
+├── CLAUDE.md                     # Claude Code always-applied rules (workflow + safety)
+│
+├── .cursor/                      # Cursor CLI engine configuration
+│   ├── skills/                   # Skills (step-by-step procedures the agent follows)
+│   │   ├── prompt-validator/     # Step 0: Validate prompt for injection/malice
+│   │   ├── template-selector/    # Step 0: Pick the best template
+│   │   ├── design-selector/      # Step 0: Pick the best design brand
+│   │   ├── module-selector/      # Step 0: Pick shared modules by keyword
+│   │   ├── module-integrator/    # Step 4: Read module references and write adapted code
+│   │   ├── app-renaming/         # Step 2: Rename app consistently
+│   │   ├── customization-planner/ # Step 3: Produce customization manifest
+│   │   ├── design-system/        # Step 4: Apply design tokens
+│   │   ├── content-writer/       # Step 4: Generate all user-facing strings
+│   │   ├── appconfig-customization/  # Step 4: Update AppConfig markers
+│   │   ├── mock-data-update/     # Step 4: Rewrite mock data
+│   │   ├── ios-customizer/       # Step 5: SwiftUI/Xcode customization
+│   │   ├── android-customizer/   # Step 5: Compose/Gradle customization
+│   │   ├── build-tester/         # Step 6: Compile and report errors
+│   │   ├── code-auditor/         # Step 7: Security code audit
+│   │   ├── output-validator/     # Step 7: Completeness/consistency check
+│   │   └── ui-tester/            # Steps 8-10: Simulator testing + Maestro
+│   │
+│   ├── agents/                   # Subagent definitions (read inline by Cursor)
+│   ├── rules/                    # Agent rules (always-on guardrails)
+│   ├── hooks/                    # Lifecycle hooks (shell scripts)
+│   ├── hooks.json                # Hook configuration
+│   └── mcp.json                  # MCP server config (ai-tester)
+│
+├── .claude/                      # Claude Code engine configuration
+│   ├── agents/                   # Native subagents (spawned as isolated processes)
+│   ├── skills/                   # Skills with Claude Code frontmatter
+│   └── settings.json             # Hooks and permissions
+│
+├── designs/                      # Design brand system
+│   ├── DESIGN_CATALOG.md         # Brand decision matrix
+│   ├── DESIGN_PRINCIPLES.md      # Shared mobile design guidelines
+│   └── brands/                   # 13 pre-built design brands
+│       ├── modern-minimal.md
+│       ├── vibrant-playful.md
+│       ├── corporate-professional.md
+│       ├── dark-luxe.md
+│       ├── soft-gradient.md
+│       ├── nature-organic.md
+│       ├── neo-brutalist.md
+│       ├── tech-dynamic.md
+│       ├── kids-playful.md
+│       ├── medical-clinical.md
+│       ├── retro-vintage.md
+│       ├── sport-athletic.md
+│       └── accessible-high-contrast.md
+│
+├── scripts/
+│   └── generate-app-icon.swift   # Generates iOS app icons from SF Symbols
+│
+├── templates/                    # App templates (DO NOT MODIFY)
+│   ├── CATALOG.md                # Machine-readable template index
+│   ├── ios/                      # 15 iOS templates (Swift/SwiftUI) + Skeleton
+│   │   └── Skeleton/             # Domain-agnostic skeleton for quick build mode
+│   ├── android/                  # 15 Android templates (Kotlin/Compose) + Skeleton
+│   │   ├── Skeleton/             # Domain-agnostic skeleton for quick build mode
+│   │   └── ICON_VECTORS.md       # Android adaptive icon vector library (~20 domains)
+│   └── shared/                   # Shared modules library
+│       ├── MODULES_CATALOG.md    # Module index with tiers and keywords
+│       ├── MODULE_CHECKLIST.md   # Integration verification checklist
+│       ├── ios/                  # 49 iOS module implementations (SwiftUI)
+│       ├── android/              # 49 Android module implementations (Compose)
+│       └── tests/                # Unit tests + Maestro tests for all modules
+│
+└── output/                       # Generated apps land here (preserved across runs, gitignored)
+    └── {app-name}/
+        ├── {app source files}
+        ├── reports/              # Audit trail from each workflow step
+        │   ├── 01-prompt-validation.md
+        │   ├── 02-template-selection.md
+        │   ├── 02b-module-selection.md
+        │   ├── 03-design-brand.md
+        │   ├── customization-manifest.md
+        │   ├── 04-content-brief.md
+        │   ├── 05-customization.md
+        │   ├── 06-build.md
+        │   ├── 07-security-audit.md
+        │   ├── 08-validation.md
+        │   ├── 09-ui-testing.md
+        │   └── summary.json
+        └── tests/                # Maestro regression tests
+            └── *.yaml
+```
+
+## Agent Pipeline
+
+The agent (Cursor CLI or Claude Code) follows an 11-step workflow with 5 parallel execution groups. Each step uses a specialized skill and writes a report.
+
+| Step | Action | Parallelism | Skill | Report |
+|------|--------|-------------|-------|--------|
+| 0 | Validate prompt + select template + select design + select modules | **4 parallel tasks** | `prompt-validator`, `template-selector`, `design-selector`, `module-selector` | `01-prompt-validation.md`, `02-template-selection.md`, `03-design-brand.md`, `02b-module-selection.md` |
+| 1 | Clone template to `output/` | -- | -- | -- |
+| 4 | Integrate shared modules | -- | `module-integrator` | -- |
+| 2 | Rename the app | -- | `app-renaming` | -- |
+| 3 | Plan customization (produce manifest) | -- | `customization-planner` | `customization-manifest.md` |
+| 4 | Apply design tokens, content, AppConfig, mock data | -- | `design-system`, `content-writer`, `appconfig-customization`, `mock-data-update` | `04-content-brief.md`, `05-customization.md` |
+| 5 | Customize screens and navigation | **2-3 parallel subagents** | `ios-customizer` / `android-customizer` | -- |
+| 6 | Build the app | -- | `build-tester` | `06-build.md` |
+| 7 | Security audit + validate output | **2 parallel tasks** | `code-auditor`, `output-validator` | `07-security-audit.md`, `08-validation.md` |
+| 8-9 | Interactive UI testing + fix bugs | **2-3 parallel simulators** | `ui-tester` | `09-ui-testing.md` |
+| 10 | Run Maestro regression tests | **2-3 parallel simulators** | `ui-tester` | `09-ui-testing.md` |
+
+### Report Files
+
+Every skill writes a markdown report to `output/{app-name}/reports/`. A `summary.json` file provides a machine-readable rollup that the orchestrator reads after the agent finishes:
+
+```json
+{
+  "appName": "VinylVault",
+  "platform": "ios",
+  "template": "ShopTemplate",
+  "designBrand": "DarkLuxe",
+  "steps": [
+    { "step": 0, "name": "prompt-validation", "result": "PASS" },
+    { "step": 1, "name": "template-selection", "result": "PASS", "template": "ShopTemplate" },
+    { "step": 9, "name": "build", "result": "SUCCESS", "artifactPath": "..." },
+    { "step": 12, "name": "ui-testing", "result": "PASS", "maestroTests": { "total": 6, "passed": 6 } }
+  ],
+  "overallResult": "PASS"
+}
+```
+
+## Template Catalog
+
+14 production-ready templates, each available for both iOS (Swift/SwiftUI) and Android (Kotlin/Jetpack Compose):
+
+| Template | Category | Best For | Screens |
+|----------|----------|----------|---------|
+| ShopTemplate | E-commerce | Product browsing, cart, checkout, orders, payments, wishlist | 15+ |
+| TrackTemplate | Habit Tracker | Daily habits, streaks, achievements, heatmap, statistics | 13 |
+| BookTemplate | Booking | Service discovery, calendar scheduling, appointment management | 16 |
+| SocialTemplate | Social Media | Feed, stories, profiles, messaging, search, notifications | 17 |
+| FinanceTemplate | Finance | Accounts, transactions, budgets, goals, spending insights | 15 |
+| ChatTemplate | Messaging | Real-time messaging, group chats, voice messages, calls | 14 |
+| LearnTemplate | Education | Courses, lessons, quizzes, flashcards, progress tracking | 15 |
+| HealthTemplate | Health/Fitness | Workouts, nutrition, health metrics, progress tracking | 15 |
+| TaskTemplate | Productivity | Tasks, projects, kanban, calendar view, tags | 14 |
+| MediaTemplate | Content/Media | Audio/video player, playlists, downloads, mini-player | 14 |
+| MapTemplate | Location | Map interface, place discovery, directions, favorites | 14 |
+| DashTemplate | Dashboard | Widget grid, charts, real-time metrics, alerts | 13 |
+| FamilyTemplate | Family | Member profiles, chores, shared calendar, rewards | 14 |
+| GameTemplate | Casual Game | Scoring, levels, achievements, leaderboard, shop | 13 |
+
+A 15th template (`ReferenceTemplate`) is included as an internal integration reference for shared modules.
+
+## Shared Modules
+
+49 reference implementation modules that the agent selects by keyword matching and adapts into each app. Each module includes screens, managers, models, string resources, unit tests, and Maestro tests. The agent reads modules from `templates/shared/` and writes adapted code into the target app -- no blind copying.
+
+| Category | Modules |
+|----------|---------|
+| Privacy & Compliance | ConsentPrivacy, AccountDeletion |
+| UX Infrastructure | EmptyStates, ErrorHandling, SkeletonLoading, NetworkBanner, ForceUpdate |
+| Monetization | Paywall, PaymentMethods |
+| Auth & Security | BiometricAuth, SocialLogin, TwoFactorAuth, PinLock |
+| Media & Input | MediaPicker, Camera, VoiceRecording, DrawingCanvas, RichTextEditor |
+| Communication | PushNotifications, NotificationCenter, ShareSheet |
+| Navigation & Discovery | DeepLinking, FiltersSortSheet, SpotlightIndexing, QRCode |
+| Data & Sync | CloudSync, RealTimeSyncEngine, ImportExport, DownloadManager |
+| Engagement | GamificationKit, ReviewsRatings, ReferralInvite, AppRatingPrompt, OnboardingCoachMarks |
+| Scheduling | CalendarDateRange, MultiStepWizard |
+| Visualization | ChartsLibrary |
+| Platform Features | Widgets, LiveActivities, SiriShortcuts, AppClips, WatchCompanion |
+| Settings & Preferences | ThemeSwitcher, LanguagePicker, WhatsNew, FeedbackSupport |
+| Social | ContentModeration, AnalyticsAbstraction |
+
+## Design Brands
+
+13 pre-built design brands, each with a complete color palette, typography scale, spacing tokens, component styles, and icon guidance:
+
+| Brand | Tone | Best For |
+|-------|------|----------|
+| Modern Minimal | Clean, spacious | Productivity, utilities, tools, SaaS |
+| Vibrant Playful | Colorful, energetic | Fun, social, entertainment |
+| Corporate Professional | Trustworthy, structured | Finance, legal, medical, enterprise |
+| Dark Luxe | Premium, sophisticated | Fashion, food, nightlife, luxury |
+| Soft Gradient | Warm, approachable | Wellness, lifestyle, meditation, self-care |
+| Nature Organic | Earthy, sustainable | Eco, gardening, outdoor, sustainability |
+| Neo Brutalist | Bold, raw | Creative, media, agency, art |
+| Tech Dynamic | Futuristic, data-rich | Fitness, sport, automotive, gaming |
+| Kids Playful | Fun, rounded | Children ages 3-12, education, COPPA-compliant |
+| Medical Clinical | Clinical, trustworthy | Health, telemedicine, patient portals, HIPAA |
+| Retro Vintage | Nostalgic, warm | Vintage, coffee, artisan, handmade |
+| Sport Athletic | Energetic, bold | Athletic, training, competition, performance |
+| Accessible High Contrast | Inclusive, clear | WCAG AAA, elderly, vision-impaired users |
+
+## App Icons
+
+Every template ships with a domain-specific app launcher icon, and generated apps get a custom icon matched to their domain and brand colors.
+
+**iOS**: Each template includes a pre-rendered 1024x1024 PNG in `Assets.xcassets/AppIcon.appiconset/`. During customization, the `ios-customizer` runs `scripts/generate-app-icon.swift` to regenerate the icon with the app's chosen SF Symbol and primary color.
+
+**Android**: Each template includes an XML adaptive icon (`ic_launcher_foreground.xml` vector + `ic_launcher_background` color). During customization, the `android-customizer` selects a domain-matched vector from `templates/android/ICON_VECTORS.md` and updates the background to the app's primary color.
+
+| Template | Icon | iOS SF Symbol | Android Vector |
+|----------|------|---------------|----------------|
+| ShopTemplate | Shopping bag | `bag.fill` | `shopping` |
+| TaskTemplate | Checkmark | `checkmark.circle.fill` | `task` |
+| HealthTemplate | Heart | `heart.fill` | `health` |
+| ChatTemplate | Chat bubble | `bubble.left.fill` | `chat` |
+| MapTemplate | Map pin | `mappin.circle.fill` | `map` |
+| MediaTemplate | Play button | `play.circle.fill` | `media` |
+| FinanceTemplate | Dollar sign | `dollarsign.circle.fill` | `finance` |
+| SocialTemplate | Two people | `person.2.fill` | `social` |
+| BookTemplate | Open book | `book.fill` | `book` |
+| GameTemplate | Gamepad | `gamecontroller.fill` | `game` |
+| TrackTemplate | Bar chart | `chart.bar.fill` | `tracking` |
+| DashTemplate | Grid | `square.grid.2x2.fill` | `dashboard` |
+| LearnTemplate | Graduation cap | `graduationcap.fill` | `education` |
+| FamilyTemplate | House | `house.fill` | `house` |
+| ReferenceTemplate | Star | `star.fill` | `star` |
+
+The Android vector library (`ICON_VECTORS.md`) includes additional domains beyond the templates: `food`, `camera`, `music`, `fitness`, `travel`, `pet`, and `weather`.
+
+## Architecture: How It Steers the Agent
+
+AppAgent supports two agent engines that share the same prompt, skills, and workflow. The orchestrator (`src/`) abstracts the engine behind an `AgentEngine` interface so the rest of the pipeline is engine-agnostic.
+
+### Engine Comparison
+
+| Feature | Cursor CLI | Claude Code |
+|---------|-----------|-------------|
+| **Command** | `cursor agent -p` | `claude -p` |
+| **Configuration** | `.cursor/` directory | `.claude/` directory + `CLAUDE.md` |
+| **Rules** | `.cursor/rules/*.mdc` (auto-applied) | `CLAUDE.md` at project root (auto-applied) |
+| **Skills** | `.cursor/skills/*/SKILL.md` (read inline) | `.claude/skills/*/SKILL.md` (YAML frontmatter) |
+| **Subagents** | Markdown instruction files | Native child processes with isolated context |
+| **Hooks** | `.cursor/hooks.json` + shell scripts | `.claude/settings.json` (PreToolUse/PostToolUse/Stop) |
+| **MCP** | `.cursor/mcp.json` | `.claude/settings.json` `mcpServers` section |
+| **Output format** | `--output-format stream-json` | `--output-format stream-json` |
+| **Model mapping** | Uses model name directly | Maps to Claude Code aliases (see `CLAUDE_MODEL_MAP`) |
+
+### Steering Mechanisms
+
+| Mechanism | Cursor CLI | Claude Code | Purpose |
+|-----------|-----------|-------------|---------|
+| **Prompt** | `prompts/agent-prompt.md` | `prompts/agent-prompt.md` | Primary task instructions |
+| **Rules** | `.cursor/rules/*.mdc` | `CLAUDE.md` | Always-on guardrails |
+| **Skills** | `.cursor/skills/*/SKILL.md` | `.claude/skills/*/SKILL.md` | Step-by-step procedures |
+| **Hooks** | `.cursor/hooks/*.sh` | `.claude/settings.json` | Quality gates (lint, validate, retry) |
+| **MCP** | `.cursor/mcp.json` | `.claude/settings.json` | Device interaction via ai-tester |
+| **Orchestrator** | `src/engines/cursor-engine.ts` | `src/engines/claude-engine.ts` | CLI invocation and stream parsing |
+
+Skills are the primary mechanism for guiding the agent. Each skill is a self-contained procedure with instructions, output format, and rules. The agent reads them inline and follows them step by step. Both engines use the same set of skills; the Claude Code versions add YAML frontmatter for native tool/permission/model configuration.
+
+## Agent Engines
+
+AppAgent supports two interchangeable agent engines. You can select the engine per invocation via `--engine` flag, the interactive prompt, or the `APPAGENT_ENGINE` environment variable.
+
+### Claude Code (alternative)
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's agentic coding CLI. It supports native subagents, skills, hooks, and MCP out of the box.
+
+```bash
+# Install Claude Code
+curl -fsSL https://claude.ai/install.sh | bash
+# -- or update to latest --
+claude update
+
+# Verify installation and authentication
+claude --version
+claude auth status
+
+# Run with Claude Code
+npm start -- -d "A habit tracker app called Streaky" --engine claude
+```
+
+Claude Code reads its configuration from:
+- `CLAUDE.md` at the project root -- always-applied rules (workflow + safety guardrails)
+- `.claude/settings.json` -- hooks (PreToolUse, PostToolUse, Stop) and permissions
+- `.claude/agents/*.md` -- subagent definitions with YAML frontmatter
+- `.claude/skills/*/SKILL.md` -- skills with tool restrictions and context modes
+
+Model mapping is handled automatically. The orchestrator translates model names (e.g., `sonnet-4.5`) to Claude Code aliases (e.g., `sonnet`). See `CLAUDE_MODEL_MAP` in `src/config.ts`.
+
+#### Subagent Delegation
+
+When using Claude Code, heavy workflow steps are delegated to native subagents via the `Task` tool. Each subagent runs in an isolated context with focused instructions, improving reliability and enabling parallel execution.
+
+| Step | Mode | Subagent Model | Description |
+|------|------|---------------|-------------|
+| 0 | **4 parallel subagents** | haiku | Prompt validation, template selection, design brand selection, module selection |
+| 1-2 | Inline | -- | Clone + integrate modules + rename |
+| 3 | Inline | -- | Customization planning (produce manifest) |
+| 4 | Inline | -- | Design, content, config, mock data |
+| 5 | **2-3 parallel subagents** | sonnet | Screen customization (batch mode) |
+| 6 | **Subagent** | sonnet | Build |
+| 7 | **2 parallel subagents** | haiku | Security audit + validation |
+| 8-10 | **2-3 parallel subagents** | sonnet | Interactive UI testing + Maestro tests |
+
+Step 0 runs 4 tasks in parallel (prompt validation + template + design + modules). Step 5 distributes screen files across 2-3 subagents. Step 7 runs security audit + validation concurrently. Steps 8-10 test across 2-3 simulators in parallel.
+
+### Cursor CLI (default)
+
+The default engine. Requires [Cursor IDE](https://cursor.com) with CLI access.
+
+```bash
+# Verify installation
+cursor --version
+
+# Run with Cursor (default -- no --engine flag needed)
+npm start -- -d "A habit tracker app called Streaky"
+
+# Explicit engine flag
+npm start -- -d "A habit tracker app called Streaky" --platform ios --engine cursor
+```
+
+Cursor reads configuration from `.cursor/` -- rules, skills, hooks, and MCP config are all picked up automatically when the agent runs in the workspace.
+
+## Configuration
+
+### AI Models
+
+Available models (configured in `src/config.ts`):
+
+| Model | Description |
+|-------|-------------|
+| `sonnet-4.5` | Default -- good balance of speed and quality |
+| `sonnet-4.5-thinking` | Sonnet with extended thinking |
+| `opus-4.5` | High quality |
+| `opus-4.5-thinking` | Opus with extended thinking |
+| `opus-4.6` | Latest Opus |
+| `opus-4.6-thinking` | Highest quality, slower, reasoning model |
+| `gpt-5.2-codex` | OpenAI alternative (Cursor engine only) |
+| `gemini-3-pro` | Google alternative (Cursor engine only) |
+| `auto` | Let the engine choose |
+
+When using Claude Code, model names are mapped automatically (e.g., `sonnet-4.5` becomes `sonnet`). Non-Claude models (GPT, Gemini) are only supported with the Cursor engine.
+
+### MCP Servers
+
+The `.cursor/mcp.json` (Cursor) and `.claude/settings.json` (Claude Code) configure the [ai-tester](https://github.com/shayke-cohen/ai-tester) MCP server for live UI testing. The agent can boot simulators, install apps, tap through screens, and generate Maestro regression tests.
+
+### Progress Logging
+
+Both engines provide real-time persistent progress output during builds. Instead of just a spinner, you'll see:
+
+- **Timestamped milestones** -- subagent dispatches, build commands, report writes
+- **Periodic summaries** -- tool call counts, file read/write counts (every 60 seconds)
+- **Final summary box** -- total duration, tool calls, subagent count, MCP calls, Maestro test results
+
+Progress is logged to stdout. A detailed debug log of all tool calls is also written to `output/.agent-debug-claude.jsonl` (Claude) or `output/.agent-debug.jsonl` (Cursor) for post-run analysis. When running dual-platform builds (`-p both`), each agent writes to a separate debug log with a platform suffix (e.g., `.agent-debug-claude-ios.jsonl`).
+
+## npx Distribution
+
+When installed via `npx` (or `npm install -g`), AppAgent automatically detects that it's running outside the source repo and scaffolds a temporary workspace in the user's current directory.
+
+### How it works
+
+1. **Detection** -- `IS_INSTALLED` flag checks whether `src/` exists alongside `dist/`. If not, we're running as an installed package.
+2. **Scaffolding** -- Before the agent engine starts, `scaffoldWorkspace()` creates:
+   - **Symlinks** for large directories: `templates/`, `designs/`, `scripts/` (pointing to the npm package)
+   - **Selective `.claude/` structure**: symlinks for `skills/` and `agents/`, copied `settings.json`
+   - **Selective `.cursor/` structure**: symlinks for `rules/`, `skills/`, `agents/`, `hooks/`, copied config files
+   - **Root config files**: `CLAUDE.md`, `AGENTS.md` (copied)
+   - **Portable `.mcp.json`**: generated with a dynamically resolved ai-tester path
+3. **Engine runs** -- with `cwd` set to the user's directory, so the agent finds all config via standard discovery
+4. **Output** -- the generated app is written to `output/` in the user's current directory
+5. **Cleanup** -- after the run, scaffolded symlinks and copies are removed
+
+### ai-tester MCP resolution
+
+For UI testing (Steps 8-10), AppAgent needs the [ai-tester](https://github.com/shayke-cohen/ai-tester) MCP server. The path is resolved in this order:
+
+1. `AI_TESTER_PATH` environment variable (directory or direct path to the entry point)
+2. Global npm modules (`npm root -g`)
+3. Local `node_modules/` in the package
+
+If not found, a warning is shown and UI testing is skipped.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in dev mode (uses tsx for direct TypeScript execution)
+npm run dev
+
+# Build to dist/
+npm run build
+
+# Run built version
+npm start
+```
+
+### Publishing
+
+```bash
+# Build is run automatically via prepublishOnly
+npm publish
+```
+
+The `files` field in `package.json` ensures `dist/`, `templates/`, `.cursor/`, `.claude/`, `designs/`, `prompts/`, `scripts/`, `CLAUDE.md`, and `AGENTS.md` are included in the published package.
+
+## License
+
+MIT