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:

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.

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:

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

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):

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.