storefront-engine

name	storefront-engine
description	Route broad or multi-step Lexsis storefront work to focused skills, MCP tools, and reference knowledge. Do not use when a focused workflow skill clearly matches.

Storefront Engine — Core Orchestrator

This is the routing and orchestration layer for all Lexsis AI storefront operations.

How This Works

1. Focused skills handle generate, optimize, remix, experiments, Cart V2, publishing, CRO analysis, and page building. Select one when its scope matches.
2. Reference files in reference/ contain deep knowledge — read only what the selected workflow needs.
3. Use Lexsis AI MCP tools for storefront operations.
4. For URL analysis, use Codex Browser when available (see browser-analyze); otherwise use Lexsis server-side design extraction.

Use this skill for broad requests that span several focused workflows or when no focused skill is a clear match. Codex skills are invoked implicitly from their descriptions or explicitly with $skill-name; plugin-defined slash commands are not available.

---

Workflow Orchestration — Execution Engine

Load after craft-guide. Defines optimal tool sequences, parallelization rules, and flow selection.

---

Flow Selection

What did the user provide?
│
├─ Ad creative (image URLs / screenshot)
│  → AD-TO-PAGE FLOW (analyze creative → extract style → generate matched page)
│
├─ Reference URL (competitor / inspiration)
│  → DESIGN-FIRST FLOW (Codex Browser screenshots URL → extracts tokens → uses as theme → generate)
│
├─ Brand brief only (name, industry, tone)
│  → STANDARD FLOW (context → assets → generate → validate → write)
│
├─ Existing page (wants edits)
│  → EDIT FLOW (read page → modify sections → validate → write)
│
├─ Product focus (PDP, collection)
│  → PRODUCT FLOW (list_products first → build around real product data)
│
└─ Multiple inputs (ad + products + brand)
   → STANDARD FLOW with enriched context

---

Standard Flow (5 Phases)

Phase 0: Context Gathering ✅ ALL PARALLEL

Fire simultaneously — no dependencies:

┌─ get_storefront_skills({ brief, page_type })    → system prompt + island catalog + schema
├─ get_design_md()                                 → brand voice/guidelines
├─ list_products(limit: 10)                        → product catalog (names, images, prices)
├─ search_design_library({ query: "hero" })        → existing brand assets
└─ get_connected_stores()                          → store_id (for publish later)

Output: Full context for generation — brand tokens, product data, asset URLs, island reference.

---

Phase 1: Asset Generation ✅ PARALLEL PER SECTION

For each section that needs a custom image (hero backgrounds, lifestyle shots, textures):

┌─ search_design_library({ query: "hero background" })  → prefer existing over generating
│
├─ generate_asset({ prompt: "descriptive prompt here", style: "photography", purpose: "hero_bg", aspect: "landscape", brand_colors })
│  → returns { asset_id, url, width, height }
│
├─ [If compositing needed] edit_asset({ source_images: [product_url, bg_url], prompt: "Product on marble surface" })
│  → returns composited image URL
│
└─ view_asset(asset_id) → visually verify before using

Decision tree for images:

1. search_design_library first — if brand has relevant assets, USE THEM
2. If no good match → generate_asset (write your own descriptive prompt)
3. If need product-on-background → edit_asset with product image + generated/library background
4. If need transparent overlay → generate_asset with transparent: true

Collect all image URLs before Phase 2.

---

Phase 2: HTML Generation (Agent writes VibePage)

Using context from Phase 0 + asset URLs from Phase 1:

1. Set theme_css from brand tokens (map flat columns → CSS vars)
2. Write each section's HTML using Tailwind classes + CSS vars
3. Place island markers where interactive commerce needed
4. Embed generated/library image URLs directly in <img src="..."> and background-image
5. Add section css only for custom keyframes/animations
6. Add section js only for scroll-triggered reveals (IntersectionObserver)

---

Phase 3: Validate ❌ SEQUENTIAL

validate_vibe_page({ page }) → { valid, errors, warnings }

If errors: fix the issues (usually JSON parsing in data-props, or invalid island names). Re-validate.

---

Phase 4: Write + Preview ✅ SEQUENTIAL

write_vibe_page({ slug, page }) → { url, path, validation }
preview_vibe_page({ slug }) → { url }

Report the preview URL to the user.

---

Ad-to-Page Flow

Phase 0: Context
├─ analyze_ad_creative({ image_urls, ad_format })  → visual signals, CTA, headline
├─ get_storefront_skills({ brief from ad analysis, page_type: "landing" })
└─ list_products()

Phase 1: Assets
├─ Use ad creative images directly where appropriate
├─ generate_asset for additional sections (testimonial bg, trust section bg)
└─ edit_asset to adapt ad images (crop, extend, composite)

Phase 2-4: Same as Standard Flow

---

Design-First Flow (Reference URL)

Phase 0:
├─ Codex Browser screenshots URL       → extracted palette, fonts, spacing, tone
├─ get_storefront_skills(brief)
└─ list_products()

Phase 1: Use extracted tokens as theme_css base
Phase 2-4: Same as Standard Flow

---

Edit Flow (Safe Iteration)

1. find_page({ query })                              → locate page by handle/title/UUID
2. get_page_content({ page_id })                     → read current sections + head
3. Identify which sections to modify
4. preview_section_update({ page_id, section_id, html })  → dry-run validation (repeat per section)
5. update_page_section({ page_id, section_id, html })     → commit change (bumps version)
6. check_page_integrity({ page_id, archetype })           → structural QA pass
7. [Optional] diff_page_versions({ page_id, version_a, version_b })  → review all changes
8. [If broken] rollback_page_version({ page_id, target_version })    → revert to prior version

Key rules:

• Always preview_section_update before update_page_section — catches validation errors without bumping version
• Run check_page_integrity after all edits complete — catches archetype violations (e.g. PDP without BuyBox)
• Use diff_page_versions to verify your changes look correct before publishing
• Use rollback_page_version if integrity check fails — creates a new forward version, preserves history

---

Duplication Flow (Idempotent)

1. find_page({ query })                                     → locate source page
2. duplicate_page({ page_id, handle, idempotency_key })     → safe clone (retries won't create extras)
3. Edit sections on the duplicate (use Edit Flow above)
4. check_page_integrity({ page_id, archetype })             → final QA

Idempotency key: Pass a deterministic string (e.g. "${handle}-v2-from-${source_handle}") so that retrying the same operation returns the existing duplicate instead of creating another.

---

Parallelization Rules

Can parallelize	Cannot parallelize
All Phase 0 context calls	Phase 1 needs Phase 0 results (brand_colors for asset gen)
Multiple generate_asset calls	validate must complete before write
Asset gen for different sections	edit_asset needs source image URLs first

---

Cost Control

• search_design_library before generate_asset — existing assets are free
• Use quality: "medium" for most assets, "high" only for hero images
• One hero image + one lifestyle shot usually enough for a PDP
• Landing pages: hero + 2-3 section backgrounds max
• Skip asset gen for sections using solid color/gradient backgrounds

---

Page Type Defaults

PDP Sections (6-8)

hero (product gallery + buybox) → trust-badges → benefits → ingredients → reviews → faq → sticky-cta → cart-drawer

Landing Page Sections (7-10)

hero → trust-bar → problem/solution → features → before-after → testimonials → pricing → faq → cta → exit-intent

Homepage Sections (5-7)

hero → featured-products → brand-story → social-proof → collections → newsletter → footer

Collection Sections (4-6)

collection-header → filters → product-grid → featured-pick → trust-bar → newsletter

---

Credit Costs

Always call get_credits_balance before expensive operations. If balance is 0, inform the user before proceeding.

Tool	Cost	Notes
generate_asset	credits	AI image generation
edit_asset	credits	AI image editing/compositing
publish_vibe_page	credits	Page generation (only on publish, not drafts)
create_page_variation	credits	A/B variant creation (requires Pro plan)
create_ab_test	credits	Experiment setup (requires Pro plan)
update_page_section	credits	Section regeneration
validate_vibe_page	FREE	Always validate before publishing
check_page_integrity	FREE	Structure/accessibility check
All read/list/get tools	FREE	No cost for browsing data

Preflight pattern:

get_credits_balance → check cost → warn if insufficient → proceed or abort

Hand-authored VibePage JSON persisted via publish_vibe_page still costs credits (it's the publish action, not the AI generation, that bills). Draft previews (draft: true) also consume credits.

---

Reference Files

Read reference/{name}.md when you need specific knowledge. Do NOT load all at once.

Knowledge (domain expertise)

• generation-protocol.md — How Pages Are Built
• cro-research.md — 2026 Landing Page Best Practices
• storefront-craft.md — Start Here
• workflow-orchestration.md — Execution Engine
• conversion-psychology.md — Storefront Design Intelligence
• visual-craft.md — Typography, Spacing, Color & Polish
• island-patterns.md — Wrapper HTML & Combination Recipes
• qa-recipe.md — QA Recipe

Operational (workflow procedures)

• page-generation.md — Storefront Page Generation
• design-assets.md — Design Assets & Brand Management
• publishing.md — Storefront Publishing & Lifecycle
• page-editing.md — Storefront Page Editing
• analytics.md — Storefront Analytics & Experiments
• generate-pdp.md — Product Detail Page (PDP) Generation
• generate-landing-page.md — Campaign / Ad Landing Page Generation
• generate-homepage.md — Brand Homepage Generation
• generate-collection.md — Collection / Category Page Generation
• generate-listicle.md — SEO Listicle / Comparison Page Generation
• generate-bundle-page.md — Bundle Builder Page Generation
• generate-editorial.md — Editorial / Magazine-Style Page Generation
• ad-to-page.md — Ad Creative to Landing Page
• page-redesign.md — Page Redesign (Modernize/Refresh Existing Page)
• competitor-remix.md — Competitor Remix (Rebuild from Reference URL)
• personalization-variant.md — Personalization Variant (Persona-Specific Page Versions)
• ab-test-variant.md — A/B Test Variant (Hypothesis-Driven Experiment)
• section-library.md — Quick Section Insert
• cart-composition.md — DrawerShell + Atomic Islands
• cart-v2-management.md — MCP Workflow