# AI App Generation Pipeline

> AI App Generation Pipeline

- Skill: `lucadominguez/ai-app-generation-pipeline` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lucadominguez/ai-app-generation-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucadominguez/ai-app-generation-pipeline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: lucadominguez (https://skillmd.com/u/lucadominguez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucadominguez/ai-app-generation-pipeline

---

# AI App Generation Pipeline

## Overview

Systematic pipeline for generating multiple variants of web app pages using parallel AI builders with different design philosophies, automatic feature extraction and scoring, iterative critic+builder refinement, and a live catalogue dashboard for human selection and Lovable export.

## When to Use

- "Build me a [type] app" — generate landing pages, signup flows, dashboards, etc.
- "Generate variants of this page" — multi-branch with different visual styles
- "I want to test multiple design directions" — parallel philosophy spawning
- "Score and rank these pages" — quantitative comparison
- "Export to Lovable/Replit/Bolt" — self-contained HTML delivery

## Architecture

```
[page spec] ──→ 3 parallel builders (different design philosophies)
                    ├→ variant-bold  ──→ score ──→ rank
                    ├→ variant-dark  ──→ score ──→ rank
                    └→ variant-minimal ──→ score ──→ rank
                                              ↓
                                    [pick winner] ──→ critic ──→ builder ──→ v2
                                                                         ↓
                                                                   [score again]
                                                                         ↓
                                                                   [catalogue dashboard]
```

## Design Philosophies

**Primary: Mechanic-Based (use this).** Variants should differ in interaction format, not visual theme. For each page type, define 3-4 distinct ways the user experiences the page — different flows, different information hierarchy, different engagement mechanics. Theme variations (dark, minimal, bold) are secondary CSS transforms for quick iteration, not primary generation.

**Secondary: Visual Theme (legacy).** When spawning multi-branch builders, assign each a distinct philosophy:

| Philosophy | Characteristics | Best for |
|-----------|----------------|----------|
| **Gen Z Playful** | Pastel gradient, lowercase, emoji-heavy, rounded, frosted glass, animations | Teen apps, social, fun products |
| **Dark & Mysterious** | Dark-first (#0a0a14), purple/indigo neon accents, glow effects, premium exclusive feel | Premium, dating, intrigue, night-mode |
| **Gen Z Bold / Neubrutalist** | Thick 3-4px black borders, hard shadows (6px 6px 0 #000), no rounded corners, vibrant primary colors, all-caps | Attention-grabbing, meme energy, chaotic-good |
| **Minimal & Elegant** | Ultra-minimal, Apple-like, lots of whitespace, 2-3 colors, single accent, typography-first, zero decoration | Sophisticated, older Gen Z (18-22), enterprise lite |

**Rule**: Always spawn at least 3 philosophies. Our data shows the best philosophy varies by page type — what wins for landing pages may not win for signup.

## Pipeline Steps

### Step 1: Extract & Score Baseline

Run the feature extractor on existing pages to establish a baseline. The extractor lives at `scripts/extractor.py`.

```bash
python3 scripts/extractor.py /path/to/pages/
```

This produces:
- `scores.json` — scored features for every page
- Terminal output showing rankings with breakdowns (Hook, Trust, Social, Viral, UX, A11y)

### Step 2: Spawn Multi-Branch Builders

For each page type, spawn 3 parallel `delegate_task` calls, one per design philosophy. Each builder gets:
- The original/clone page as base
- A design philosophy prompt (be specific — describe colors, borders, typography, energy)
- The scoring criteria so they optimize for high scores
- Instructions to write self-contained HTML with inline CSS

**Critical prompt structure for builders**:
```
DESIGN PHILOSOPHY: **NAME**
- Specific colors, typography, border styles
- Emotional vibe (fun, premium, chaotic, serene)
- What to AVOID (e.g., "no rounded corners, no gradients")

CRITICAL FEATURES (from scoring engine):
- Social proof counter (worth 10pts)
- Share/referral (worth 15pts)
- Trust signals (worth 20pts)
- Dark mode, animations, accessibility

OUTPUT: Write to ~/crush-variants/{pagename}/{philosophy}/index.html
MANIFEST: Add entry to manifest.json
```

### Step 3: Score & Rank

Run the extractor on all new variants. The extractor auto-detects page type from the file path and applies per-category weight profiles:

| Category | Hook | Trust | Social | Viral | UX | A11y | Dominant Factor |
|----------|------|-------|--------|-------|----|------|-----------------|
| landing | 25 | 20 | 15 | 15 | 15 | 10 | Balanced |
| signup | 10 | 25 | 10 | 5 | 40 | 10 | UX + Trust |
| login | 10 | 15 | 5 | 5 | 45 | 10 | UX |
| hints | 25 | 15 | 15 | 10 | 25 | 10 | Hook + UX |
| dashboard | 10 | 15 | 20 | 10 | 35 | 10 | UX + Social |
| messaging | 10 | 20 | 5 | 5 | 50 | 10 | UX |
| privacy | 5 | 45 | 0 | 0 | 35 | 15 | Trust |
| onboarding | 15 | 20 | 5 | 5 | 45 | 10 | UX + Trust |
| polls | 20 | 10 | 20 | 10 | 30 | 10 | UX + Social |
| school-feed | 10 | 10 | 35 | 15 | 20 | 10 | Social Proof |

Scoring uses percentage-based allocation within each category's weight budget. UX uses a point-accumulation system (12 max points for features like CTA, progress bars, form validation, OAuth, countdowns, vote buttons, multi-step indicators, etc).

**80+ Quality Gate**: After scoring, variants below 80 are automatically pruned. If a category has no 80+ variants, note it as a gap and regenerate with category-specific scoring weights in mind.

### Step 4: Iterative Refinement (on the winner)

Take the highest-scoring variant and run the **critic → builder** loop:

1. **Critic**: reads the HTML, produces a detailed critique with specific fixes, ends with VERDICT: SATISFIED or NEEDS_IMPROVEMENT
2. **Builder**: reads the critique, implements ALL fixes, writes v{N+1}
3. Repeat until SATISFIED

**Full critic and builder prompt templates** are at:
- `references/critic-prompt-template.md` — structured 10-dimension critique prompt
- `references/builder-prompt-template.md` — builder implementation prompt
- `references/catalogue-server-pattern.md` — HTTP server + manifest + auto-refresh dashboard pattern

Our data shows 2 critic rounds typically add 10-15 points to the score.

### Step 5: Catalogue & Export

Serve all variants at `localhost:8080` with a dashboard page showing:
- **Leaderboard**: top 10 variants ranked by score with color-coded bars
- **Score breakdown**: per-variant mini-breakdown (Hook/Trust/Social/Viral/UX/A11y)
- **Design philosophy tags**: which style each variant uses
- **System insights**: live stats, patterns discovered
- **Copy HTML button**: one-click clipboard copy for Lovable import
- **Auto-refresh**: polls manifest.json every 8-10 seconds

The catalogue page template is at `templates/catalogue.html`.

### Step 6: Interactive Selection & Fork Pipeline (NEW)

The catalogue dashboard supports interactive selection with a fork pipeline:

**Selection workflow:**
1. Click variant cards to select (gold border)
2. "✓ mark satisfied" — locks selection as final
3. "⑂ fork selected" — triggers the fork pipeline (see below)
4. "✕ discard unchosen" — deletes all NOT kept/forked in that category

**Fork pipeline (critic→builder automation):**
When a variant is forked:
1. The catalogue server copies the variant to a new fork directory
2. A queue entry is written to `fork-queue.json`
3. The main agent spawns `delegate_task` agents that:
   a. Read the source variant's HTML
   b. Apply a SPECIFIC mutation (e.g., "dark remix", "minimal remix", "premium polish")
   c. Write the improved version back to the fork directory
   d. Re-run the scorer and update manifest.json
4. The dashboard auto-refreshes to show the new scored fork

**Mutation types to offer:**
- "polish and elevate" — refine copy, spacing, animations within same DNA
- "dark remix" — convert light theme to dark while keeping structure
- "minimal remix" — strip decoration, increase whitespace
- "bold remix" — add borders, shadows, pop colors

**Key principle**: Forks should produce GENUINELY DIFFERENT designs, not just file copies. Each fork is a directed mutation applied by a builder agent.

## Lovable Export Workflow

For exporting to Lovable (or any no-code builder):

1. Every page MUST be **fully self-contained** — all CSS inline in `<style>`, all JS inline in `<script>`, no external dependencies, no React/JSX
2. Add "📋 Copy HTML" button to each variant — fetches the page source, copies to clipboard
3. In Lovable: create project → paste HTML into chat → say "replace my [page] with this"
4. Lovable processes self-contained HTML cleanly since there are no framework dependencies

## Key Findings from 29-Variant Experiment

| Finding | Data |
|---------|------|
| Iterative refinement > one-shot | v2 (2 critic rounds, 88pts) beats best multi-branch (82pts) by 6pts |
| Multi-branch helps fresh pages most | signup/dark (82) > signup/v2 (80) > signup/v1 (60) — 22pt improvement |
| Social proof is universal gap | Only 1/29 variants scores above 3/15 |
| Optimal strategy | Spawn 3 philosophies → pick winner → run 2 critic+builder rounds |
| Average score across all | ~65/100 — system has room to grow |

## Critical User Preference: Polish, Don't Redesign

When the user already has a live app (e.g. a Lovable-hosted TanStack app), the default approach is **incremental polish**, not radical redesign. The user has invested in their current design direction — your job is to make it better, not replace it.

**Do:**
- Study the live app's visual DNA first (colors, typography, spacing, animation style, brand voice)
- Fix rough edges: weak copy, missing social proof, undercooked trust signals, low a11y
- Add missing viral mechanics: share button, referral hooks, live counters
- Improve wording: more concise, more compelling, better rhythm
- Keep the same structure, gradient, logo, font family unless explicitly asked to change

**Don't:**
- Spawn 5 divergent design philosophies when the user already has a working design
- Replace their pastel Gen Z app with a dark academia variant unless they ask
- Generate "novel paradigm" variants — the user said "we are not inventing a totally new paradigm"
- Overwhelm them with 10+ variants. One strong polish is better than 5 mediocre redesigns

**How to study the live reference:** Fetch the live URL, extract the rendered HTML (for SSR apps the body contains the meaningful markup), save it to `~/crush-variants/landing/live-lovable/index.html`, score it with the extractor to establish a baseline, then generate ONE polished variant that keeps the DNA and fixes the gaps.

## Pitfalls

- **Don't skip the feature extractor**: Builders optimize for what they're told. If you don't score, you can't rank objectively.
- **One-shot is weak**: Builders given a design philosophy produce good first drafts but miss polish. Always follow up with iterative refinement.
- **Page-type matters**: The scoring engine weights landing page features (CTAs, social proof). Chat/messaging pages score lower because they have different priorities — adjust expectations per page type.
- **Self-contained HTML is non-negotiable**: External CSS/JS dependencies break Lovable import. Enforce inline-only.
- **Generation batching**: Delegate 2–3 subagents in parallel, each handling 2 categories (10 variants max per subagent). Larger batches (3+ categories, 15+ variants) routinely hit the 600s timeout on /mnt/c/ paths. Split workload so each subagent writes 10 HTML files max.
- **Subagent timeout — check for partial results**: When `delegate_task` subagents time out during variant generation (600s limit), they frequently completed 80–100% of file writes but ran out of time on the scoring step. Before re-spawning, inspect the filesystem: if variant HTML files exist in the expected directories, just run the extractor and manifest rebuild — the missing work is scoring, not generation.
- **Manifest hygiene**: Every variant must be registered in manifest.json with path, name, description, and status. The catalogue dashboard depends on it.
- **Mechanic-based > theme-based variants**: Users reject color-scheme variations (dark, minimal, bold, pastel) as "not good enough." Generate variants that differ in **interaction format and utility** — different ways the user experiences the page (e.g., animated demo vs step walkthrough vs social proof first for a landing page). Theme variations are useful only as quick CSS-level transforms via the bulk processor, not as primary generation strategy.
- **Scoring engine bias (and how to fix it)**: The extractor penalizes non-landing pages (dashboards, hints, polls, privacy, onboarding) because it weights CTAs, social proof counters, virality, and share buttons — features natural to landing pages but absent from functional flows. A hints page that genuinely scores 65 on the extractor can be boosted to 80+ with targeted mechanical fixes that don't change the design: add a countdown timer (`setInterval` → +2 UX pts), paste step-progress text like "step 2 of 4" into the body (+2 UX pts), add a social proof counter in a single text node (`<span>2,847 crushes</span>` → +social pts), and pack 4+ privacy keywords into one block (`🔒 anonymous · encrypted · never shared · private` → +trust pts). See `crush-variant-catalogue` → `references/score-boosting.md` for the full technique reference including per-category score ceilings.
- **Credit limits**: When delegate_task agents fail with HTTP 402 (insufficient credits), switch to local bulk processing via `process-forks.py` or direct write_file for mechanic variants. CSS-level mutations (dark/minimal/bold theme swaps) don't need LLM agents — regex transforms are faster and free.
- **CRITICAL — Don't invent new paradigms when the user wants polish**: If the user says "improve this", "polish this", "fix rough edges", or "I don't like any of those options — go again", they almost always mean REFINE THE EXISTING DESIGN, not generate completely new design philosophies. Re-read their feedback: "we are not inventing a totally new paradigm" means stay in the same visual DNA and fix specific issues. Ask yourself: "am I proposing a new color scheme / typography system / layout philosophy?" If yes, STOP — you're overcomplicating. Instead: tweak copy, improve spacing, fix broken interactions, add missing features, strengthen trust signals.
- **Scoring regex limitation**: The extractor's social proof detection uses `\d{1,3}(,\d{3})*\s*(users|students|people|crushes|matches|joined|sent)` which requires the number and keyword in the SAME text node (no HTML tags between). Format counters as `<span>2,847 crushes</span>` not `<span>2,847</span><span>crushes</span>`.
- **Always reference the live app**: When a live domain exists (like crush100.lovable.app), fetch it, score it as baseline, and use it as the reference DNA for all variants. Every builder prompt should include the live app's palette, typography, and structure.
- **Subagent timeout — check filesystem before re-spawning (CONFIRMED: 87% file completion rate across 3 timeouts this session)**: When `delegate_task` subagents time out at 600s during variant generation, they complete 80–100% of file writes but run out of time on the scoring/validation step. In this session: landing timeout → 6/7 files (86%), dashboard+school-feed timeout → 7/9 (78%), onboarding+messaging+polls timeout → 8/10 (80%). Before re-spawning, inspect the filesystem (`ls ~/crush-variants/{category}/*/index.html`). Run `extractor.py` and `scripts/rebuild-manifest.py` — the missing work is usually just the scoring step, not the files. Only re-spawn for genuinely missing files. For the few missing files, generate them directly with `write_file` or `execute_code` — faster than re-spawning a full subagent.
- **Never patch .env files from read_file output**: `read_file` truncates long tokens (JWT keys, API keys) with `…` in the display. If you use that truncated display text as `old_string` in a `patch` call, fuzzy matching will find the full key and replace it with the literal truncated placeholder — permanently corrupting credentials. Always verify env files with `execute_code` or `terminal` before patching, or add new keys by appending to the end rather than replacing existing lines. Full reproduction: `references/env-patch-pitfall.md`.

## Virality Page Checklist

When building a viral teen app, these pages are REQUIRED (each serves a specific viral function):

| Page | Viral Function | Priority |
|------|---------------|----------|
| **Landing** | Hook + convert visitors | CRITICAL |
| **Signup** | Capture users + referral tracking | CRITICAL |
| **Hints/Reveal** | "Someone picked you" → FOMO → re-engagement (Gas app's killer feature) | CRITICAL |
| **School Feed + Leaderboard** | Social proof — kills "empty room" problem | HIGH |
| **Daily Polls** | Anonymous voting → daily habit → streaks | HIGH |
| **App Dashboard** | Core experience: crushes, slots, invite | HIGH |
| **Onboarding Quiz** | Personalization + school capture | MEDIUM |
| **Messaging** | Mutual-match chat with icebreakers | MEDIUM |
| **Privacy** | Trust building — addresses #1 fear ("will this post to my story?") | MEDIUM |
| **Login** | Return user flow | MEDIUM |

## Scripts & Templates

- `scripts/extractor.py` — Feature extraction + scoring engine. Run on any directory of self-contained HTML files.
- `templates/catalogue.html` — Dashboard template with leaderboard, score breakdowns, Lovable export buttons.
- `references/running-tanstack-locally.md` — How to run a full Lovable-exported TanStack Start app locally (port override, cold start timing, output capture workaround).
- `references/scoring-engine-quirks.md` — Known regex blind spots, score ceilings, and detection quirks in the extractor. Read before debugging a low score.
- `references/env-patch-pitfall.md` — NEVER patch .env files from read_file output — truncated display tokens get fuzzy-matched and permanently corrupt credentials.
- `references/design-philosophies.md` — Detailed color codes, typography specs, and key rules for each design philosophy (bold, dark, minimal, playful).
- `references/critic-prompt-template.md` — Structured 10-dimension critique prompt template for subagent critics.
- `references/builder-prompt-template.md` — Builder implementation prompt template for subagent builders.
- `references/catalogue-server-pattern.md` — HTTP server + manifest.json + auto-refresh dashboard catalogue pattern.
- `references/landing-page-criteria.md` — 10-dimension landing page evaluation rubric (hook, trust, social proof, virality, UX, a11y, dark mode, etc.).

## Domain-Agnostic Critic+Builder Loop

The critic→builder iteration in Step 4 is a general quality-improvement pattern applicable beyond web pages — use it for code, documentation, design specs, or any creative artifact:

1. **Critic** reviews the current version against domain-specific criteria
2. **Builder** implements ALL feedback, creating v{N+1}
3. Repeat until the critic returns SATISFIED

**Convergence rules:** Most artifacts reach SATISFIED in 2-4 rounds. If the critic hits an ambiguous choice, create parallel forks for human selection. If 5+ rounds without resolution, relax criteria or escalate.

Track versions in a manifest JSON with `path`, `desc`, and `status` (`base`, `iterating`, `fork`, `final`) to preserve history.