| name | luxury-mockup-pipeline |
| description | Five-agent design-elevation pipeline for luxury HTML mockups. Audits a design-reference HTML file against brand canon, identifies polish gaps, generates a fix manifest, executes infrastructure changes via Senior Developer, and verifies the result. Use when refining a design mockup from "decent" to "production-grade luxury". Trigger phrases: "elevate this mockup", "luxury polish pass", "5-agent design pipeline", "/luxury-mockup-pipeline". |
Luxury Mockup Pipeline
Composite pipeline that orchestrates five specialist agents to refine a standalone HTML design mockup from rough draft to luxury-grade production-ready artifact.
Token-Aware Runtime Guard (always-on)
This skill runs alongside token-aware-behavior at all times. Apply these rules on every agent dispatch + every synthesis step:
| Budget state | Pipeline behavior |
|---|
nominal | Full agent briefs, full deliverables, all 5 agents parallel |
warn | Brief budgets tightened (200 → 120 word return summaries); deliverable docs stay full |
compress | Emit [PHASE SUMMARY] before Stage 2 synthesis; reference prior agent outputs by path, not by quoted content |
handoff | Stop mid-stage at atomic boundary (after current agent finishes), emit RESUME PROMPT with manifest path + commit SHAs |
critical | Final 3-line summary only; defer Stage 4 to fresh session |
Never: re-quote whole audit docs back to other agents (they get the path, they read it themselves). Never paste >40 lines of prior agent output into Stage 2 synthesis — extract findings, cite paths.
Always: when dispatching parallel agents in a single message, pre-allocate token budget: ~8k per agent × 5 = ~40k synthesis ceiling. If close to ceiling, dispatch in waves of 2 instead of 4 parallel.
Cross-reference: skill userSettings:token-aware-behavior defines the canonical budget thresholds (60/75/88/95). This pipeline inherits them.
Live Documentation Access (mandatory for any external library / API call)
Every agent that touches an external library, framework, API, or web platform feature MUST use these sources in this order:
| Order | Source | Use case |
|---|
| 1 | Context7 MCP (mcp__claude_ai_Context7__resolve-library-id → mcp__claude_ai_Context7__query-docs) | Library/framework API: React, Next.js, Tailwind, Liquid, Three.js, FastAPI, etc. Returns current docs — overrides training-data drift. |
| 2 | Curl + grep | Live HTML inspection, JSON-LD validation, OG/Twitter meta verification, API response shape testing. CRITICAL: never use WebFetch for <script> blocks — it strips them. |
| 3 | WebFetch | Markdown / prose documentation pages (MDN, blog posts, vendor docs), NOT for HTML pages with critical <script> content. |
| 4 | GitHub search (gh search code / gh search repos) | Find adaptable implementations before writing new code. Battle-tested patterns. |
When to invoke each
- Before recommending any CSS feature (e.g.,
animation-timeline, :has(), color-mix(), @scope): Context7 query css-features library + cite browser support matrix from MDN-current.
- Before recommending any JS API (View Transitions, IntersectionObserver, Houdini, container queries): Context7 query for current stability + caniuse data.
- Before claiming a vendor behavior (Vercel, Cloudflare, WP.com, Stripe): Context7 their docs + curl the live API response.
- Before citing JSON-LD / OG tags on a live site:
curl -s "URL?cb=$(date +%s)" | grep -oE (cache-bust, don't trust Batcache).
- Before adopting a new pattern: GitHub search for proven implementations — port battle-tested code over hand-rolling.
Anti-pattern
WRONG: "I'll just use my training knowledge for view-transitions API"
RIGHT: Context7 resolve-library-id → query-docs → then write code with verified API shape
The cost of a Context7 round-trip is < 1k tokens. The cost of writing against stale API knowledge is 10k+ tokens of debugging.
High-Performance Asset Patterns (mandatory invocation)
Every agent that recommends or generates assets MUST encourage the highest-performing pattern available:
Image pipeline (in priority order)
| Source | When | Output |
|---|
| Existing optimized asset | Asset exists in assets/images/<name>.{avif,webp,jpg} with full variant set | Direct reference |
| avifenc (libavif) | Need AVIF variant from source PNG/JPG | avifenc --min 25 --max 35 -s 4 source.png target.avif |
| cwebp (libwebp) | Need WebP variant | cwebp -q 82 -m 6 source.png -o target.webp |
| sharp (npm) | Need batch responsive variants (480w/768w/1280w/1680w + retina) | sharp().resize(width).avif({quality:80}).toFile() |
| squoosh-cli | Need single-asset optimization with multiple format outputs | squoosh-cli --avif '{"cqLevel":28}' --webp '{"quality":82}' source.png |
| rembg (Python) | Need transparent monogram / logo (alpha extraction) | rembg i source.png target.png → re-encode to AVIF/WebP preserving alpha |
| ImageMagick (identify / convert) | Need dimensions, alpha inspection, format conversion | identify -format "%w×%h %[channels]" source.avif |
| ffmpeg | Need hero video loop optimization (silent, < 1MB) | ffmpeg -i source.mp4 -vf scale=1280:-2 -an -c:v libx264 -crf 24 -preset slow -pix_fmt yuv420p -movflags +faststart out.mp4 |
Asset hierarchy enforcement
- Above-fold (cover / hero LCP): AVIF source @ q80 + WebP @ q85 + JPG fallback @ q88.
fetchpriority="high". <link rel="preload" as="image"> in <head>. Master source ≥ 2× rendered viewport width.
- Below-fold collection/product: AVIF + WebP only (no fallback).
loading="lazy". decoding="async". Aspect-ratio CSS.
- Logos / monograms: SVG inline if < 4KB. Otherwise AVIF + WebP with alpha + PNG fallback.
- Background patterns / textures: tileable PNG → AVIF lossless or WebP. Use CSS
background-image with multiple image-set() sources.
Verification commands (run BEFORE recommending in any audit)
identify -format "%w×%h %m %[channels] %B\n" <asset> # dims, format, channels, bytes
file <asset> # mime sanity check
ls -la <asset> # file size + existence
exiftool -ImageWidth -ImageHeight -ImageSize <asset> # full metadata
CDN / serve-time optimization (when platform supports)
- Vercel Image:
next/image with fill + sizes + priority for above-fold
- Cloudflare Images:
<img src="https://imagedelivery.net/<acct>/<id>/<variant>" /> with auto-format negotiation
- Cloudinary:
f_auto,q_auto,w_auto,dpr_auto transformation chain
- WordPress:
wp_get_attachment_image() with loading="lazy" + AVIF plugin (Performance Lab)
Anti-pattern
WRONG: "Use a single 1920×1920 master for hero — it'll scale fine"
RIGHT: Generate 480w/768w/1280w/1680w variants in AVIF+WebP. Master must exceed largest render dim by 2×.
Mobile LCP suffers 0.8–1.2s when desktop-only masters serve mobile viewports. Variant generation is non-negotiable for any hero-class asset.
Memory System (always-on, per-agent + shared)
The pipeline has a file-based memory system at ~/.claude/skills/luxury-mockup-pipeline/memory/. It is the agents' persistent knowledge layer across dispatches.
Layout:
memory/
├── _shared/INDEX.md # facts useful to all 5 agents
├── _shared/<slug>.md # one fact per file (YAML frontmatter + body)
├── ux-architect/INDEX.md # UX-specific facts
├── ui-designer/INDEX.md # UI-specific facts
├── brand-guardian/INDEX.md # canon-specific facts
├── frontend-developer/INDEX.md # perf/asset-specific facts
└── senior-developer/INDEX.md # impl-specific facts
Read protocol (every dispatch):
- Agent reads its own
<agent-slug>/INDEX.md (one-liner index of discipline facts)
- Agent reads
_shared/INDEX.md (one-liner index of cross-agent facts)
- For any entry that matches the current task, agent reads the full fact file
- Agent treats memory as authoritative AT WRITE TIME — if fact references a file path or asset, verify it still exists before recommending action on it
Write protocol (after correction or pattern lock):
- When founder corrects the agent, the orchestrator appends a memory entry
- When the agent discovers a non-obvious pattern that worked, write a memory entry
- One fact per file, YAML frontmatter (
name, description, tags, applies_to, last_verified), body explains WHAT + WHY + HOW TO APPLY
- Append to the INDEX as
- [Title](slug.md) — one-line hook (under 150 chars)
Cross-reference (existing infrastructure):
- DevSkyy project memory:
/Users/theceo/.claude/projects/-Users-theceo-DevSkyy/memory/MEMORY.md
- Claude-mem observation DB:
~/.claude-mem/claude-mem.db (SQLite, project-scoped, ~15k observations)
- OpenWolf cerebrum:
/Users/theceo/DevSkyy/.wolf/cerebrum.md
- Canon docs:
/Users/theceo/DevSkyy/docs/brand/ (read-only — never write from skill memory)
Decay: facts about repo state (file paths, asset dims, function names) carry last_verified: YYYY-MM-DD. If older than 30 days, re-verify on next read. Stale memory > no memory.
Seed entries (already in _shared/):
the-five.md — The Five canonical brands lockscope-policy.md — full-site scope + primary_focus_surfaces disciplinesaas-gate.md — SaaS Product Delivery Standardstop-and-show.md — paid/production/irreversible action protocolaudit-verification.md — multi-agent audit false-positive disciplineno-webfetch-for-scripts.md — WebFetch strips script tags
Agents inherit ALL shared facts by default. Per-agent dirs hold corrections/patterns specific to that discipline.
SaaS Product Delivery Standard (always-on quality contract)
Every agent in this pipeline operates as if they are their own standalone SaaS product. The output they ship is the product. There is no "internal-only draft" stage. Every deliverable — audit report, fix manifest, v2.html commit, asset generation, ROI upgrade — must clear the SaaS gate before it surfaces to the founder.
The SaaS Gate (every deliverable passes ALL):
| Gate | Requirement | Verification |
|---|
| Mobile-first verified | Layout tested at 320 / 375 / 414 / 768 / 1024 / 1440 viewport widths. No horizontal scroll. Touch targets ≥ 44×44 px. Font scale clamps. | Open in browser, throttle to 360px width, screenshot, confirm no overflow + no broken tap targets |
| Images optimized before publish | Every image referenced has: AVIF + WebP + fallback present, dimensions declared (no CLS), proper srcset coverage (480w/768w/1280w/1680w for hero-class), loading attribute correct (eager above-fold / lazy below), decoding="async". Source dims ≥ render dims (no upscale blur). | Run identify on each asset, grep <picture> blocks for variant coverage, fail if any asset upscales |
| Sales-presentation grade | Output reads like a product page section, not raw notes. Every section has a one-line headline + 1–3 supporting lines + verification call. No placeholder text, no "TBD", no "see other doc" without quoted summary. | Read aloud at start of doc — first 200 words must close a sale on the recommendation |
| Accessibility verified | WCAG 2.2 AA min, prefers-reduced-motion honored, all interactive focus-visible, color contrast ≥ 4.5:1 body / 3:1 large text, heading hierarchy intact | Lighthouse a11y ≥ 100 OR axe DevTools 0 violations |
| Performance verified | LCP image preloaded + fetchpriority="high", no blocking JS, critical CSS inlined, font preload, JS bundle < 200 KB compressed | Lighthouse perf ≥ 95 on mobile throttle |
| Self-contained reading | Founder can read the deliverable cold. Every term defined or linked. Every claim cited with file:line. No insider shorthand without translation. | New-reader test: would someone with no context understand it? |
| Conversion-ready CTAs | When the deliverable proposes work (a fix, an upgrade, a swap), it ends with: exact commit message, verification command, one-line "ship it" call to action | Grep deliverable for the 3-element CTA pattern |
Agents that ship raw notes, half-baked drafts, or assets without optimization are out of contract. The orchestrator (this skill) rejects sub-SaaS deliverables and re-dispatches with explicit notes.
Mobile-first verification protocol
Before any agent declares a deliverable DONE:
- Viewport sweep: confirm the artifact (or its target file, in refine mode) renders correctly at 320 / 375 / 414 / 768 / 1024 / 1440 widths. For HTML deliverables: open in headless browser at each width, screenshot, eye-check.
- Touch target audit: every clickable element ≥ 44×44 px (Apple HIG) or ≥ 48×48 px (Material). Tap-zone overlap test.
- Type scale check: heading + body sizes clamp via
clamp(min, vw-based, max). No fixed px in headings ≥ 24px.
- Image flexibility: every
<img> in <picture> has correct sizes attribute matching layout. Source variant matches viewport width served.
- Reflow test: no horizontal scrollbar at any breakpoint. Aspect-ratio maintained or content reflows gracefully.
Image optimization pre-publish gate
Before any agent references an asset in a deliverable, the asset MUST clear:
- Format priority: AVIF source present (best compression) → WebP source present (Safari ≤ 15 fallback) → JPG/PNG fallback (legacy).
- Variant coverage: hero-class assets have 480w/768w/1280w/1680w + 2x retina for above-fold LCP. Non-hero: minimum 480w/960w.
- Source resolution: master source dimension ≥ 2× rendered dimension at largest viewport. No upscale blur.
- Alpha discipline: if the asset needs transparency (logos, monograms), confirm alpha is preserved in AVIF + WebP (not just PNG). Run
identify -format "%[channels]" to verify.
- File-size budget: above-fold hero AVIF ≤ 400 KB, hero WebP ≤ 500 KB, below-fold images ≤ 200 KB at 1280w.
- CDN-ready filename: content-hashed or versioned (e.g.,
name.v2.avif) for long-cache headers.
If any asset fails these gates, the agent flags it in their deliverable with a precise remediation command (cwebp -q 80 ... / avifenc --min 25 ... / rembg ...) and tier-routes the asset upgrade to Tier U or Tier 4 (deferred) — never to Tier 0–3 (would block the fix sprint).
Agent Capability Charter (full-stack theme expertise)
The five agents in this pipeline are end-to-end theme development experts, not mockup tweakers. Each agent operates as if they could ship a complete production-ready theme on any of the platforms below, against any brand/criteria/vertical. The mockup-refinement loop is a subset of their competency.
Platform coverage (agents pick the right stack for the job):
| Platform | When to choose | Senior Developer artifact |
|---|
| WordPress / WooCommerce | Live e-commerce + content site, founder owns CMS, SEO-critical | wordpress-theme/<slug>/ (PHP 8.2 + theme.json + block patterns + WC overrides) |
| Next.js (App Router + RSC) | Headless commerce, marketing, dashboards, anything requiring React + edge | frontend/ (Next 16 + React 19 + Server Components + Cache Components) |
| Shopify (Liquid + Hydrogen) | Native Shopify store, OS 2.0 themes, Storefront API headless | shopify-theme/<slug>/ (Liquid + sections + blocks) or Hydrogen via Remix |
| Astro | Content-heavy marketing, blog, partial-hydration islands | astro-theme/<slug>/ (.astro + content collections) |
| Webflow → Code Export | Founder-designed in Webflow, needs production export hardening | Cleaned Webflow export + tokens extracted |
| Standalone HTML/CSS/JS | Design refs, mockups, single-page landings, internal tools | docs/brand/design-mockups/ (current pipeline default) |
| Wix / Squarespace | Founder-managed, agents author custom-code blocks + DNS guidance | Embedded code blocks + integration spec |
Criteria coverage (agents apply the right system):
| Criteria | Patterns the agents apply |
|---|
| Luxury / fashion | Editorial typography, scene-takeover photography, ambient motion, restrained palette, magazine grid, lockup-image hero |
| SaaS / B2B | Above-fold value prop, gradient/blur backgrounds, social proof rail, pricing table, demo-CTA, dashboard preview |
| E-commerce | PLP/PDP/cart/checkout flows, holo product cards, sticky add-to-cart, size guide, reviews, recommendation slots |
| Marketing / lead-gen | Hero CTA → form, benefit grid, testimonial carousel, FAQ accordion, conversion optimization |
| Editorial / publishing | Long-form typography, reading progress, footnote system, related articles, newsletter capture |
| Portfolio / agency | Case-study spreads, scroll-driven storytelling, project filter, contact form |
Deliverable depth (agents always produce the full set, not partial):
- Visual system: tokens (color, type, spacing, motion, radius, shadow) — design-tokens.css / theme.json / tailwind.config.ts
- Component library: every reusable unit with BEM/utility classes + ARIA + keyboard nav
- Page templates: every canonical surface (home / collection / detail / cart / about / contact / 404 / search)
- Animation system: single source of truth for reveals, parallax, hovers — IntersectionObserver OR scroll-driven CSS
- Performance budget: LCP < 2.5s, CLS < 0.1, INP < 200ms, image sizes documented, font subset declared
- Accessibility: WCAG 2.2 AA minimum —
prefers-reduced-motion, prefers-contrast, focus-visible, ARIA labels
- SEO baseline: title/meta/OG/JSON-LD per template, sitemap, robots
- Deploy pipeline: deploy script + verify gate + rollback path
- Documentation: README + tokens + component reference + handoff doc
When the founder asks "build me a theme" — the pipeline scales to the full stack, not just polish. The mockup-refinement flow is what runs when the artifact already exists; full theme creation runs the same 5-agent pipeline but each agent's audit becomes a build.
Mode switching:
mode=refine (default) — agents audit + propose fixes against existing mockup. Senior Dev applies.mode=build — agents design + scaffold a complete theme from canon docs + spec. Senior Dev assembles the full artifact tree.mode=migrate — agents port an existing theme to a new platform (e.g., WP → Next.js). Senior Dev does the platform translation.mode=harden — agents take a working theme and bring it to production-grade (a11y, perf, SEO, security). Senior Dev ships the upgrades.
The skill orchestrator picks mode from user intent or explicit arg.
High-ROI Upgrade Mandate (per agent — non-negotiable)
Every agent MUST propose exactly 1 high-ROI premium upgrade as part of their deliverable. The upgrade is in addition to (not in place of) their normal audit work. Mandates:
| Agent | Required Upgrade Category | Example |
|---|
| UX Architect | One signature motion / interaction moment — scroll-driven scene takeover, hero loop spec, parallax depth system, view-transitions choreography | "Scroll-snap section reveal with cinematic crossfade between Cover and Hero — 600ms cubic-bezier(0.65,0,0.35,1), <section> opacity + scale + clip-path" |
| UI Designer | One luxury detail system — custom cursor, ambient grain layer, type-rhythm escalator, magnetic hover, frame transition, micro-spacing token | "Magnetic cursor on .spread__tile — 24px attraction radius, transform: translate3d() follow with 80ms lag, GPU-accelerated, prefers-reduced-motion fallback" |
| Brand Guardian | One canon-signature touch — color pulse for brand accent, monogram emergence pattern, signature copy beat, brand-mark micro-interaction | "Rose-gold accent pulse on hover for any element bearing --sr-accent — 1.5s ease loop, opacity 0.4 → 1.0, locked to The Five reference brands' use of color-as-signature" |
| Frontend Developer | One asset upgrade that resolves a known degradation — transparent monogram (rembg pass), AVIF re-encode, color grading LUT applied to hero, missing srcset variant generation | "Generate transparent sr-monogram-rose-gold.{avif,webp} via rembg; outputs to assets/images/branding/sr-monogram-rose-gold-transparent.* — single asset, single PR, immediate visual impact" |
| Senior Developer | One advanced CSS / web platform feature beyond the manifest — CSS scroll-timeline / scroll-driven animations, view-transitions API, CSS Houdini paint worklet, container queries, @scope, :has() selector chains for state-driven design, color-mix() palette derivation | "CSS scroll-driven animation on .hero__bg.parallax via animation-timeline: scroll() — replaces JS rAF parallax with native CSS, deletes 22 lines of JS, runs at 120fps, falls back gracefully on Safari < 18" |
Upgrade must be:
- High ROI — small implementation cost, large perceived-luxury jump
- Self-contained — lands in a single commit, no cross-system refactor
- Production-grade — no proof-of-concept code, no placeholder values
- Accessibility-respectful — honors
prefers-reduced-motion, prefers-contrast, keyboard nav
- Browser-safe — graceful fallback for browsers without the feature
- Documented in deliverable — under header
## ROI Upgrade Proposal with: name, what it does, source inspiration, exact CSS/HTML/JS diff, ROI rationale (1 paragraph), fallback strategy
The synthesis step (Stage 2) must roll all 5 upgrades into the fix manifest as their own tier: Tier U (Upgrades) — applied AFTER Tier 3 polish, BEFORE final commit.
When to invoke
- User has an HTML design-reference mockup (e.g.,
docs/brand/design-mockups/*.html) and asks for "elevation", "polish pass", "professional refinement", or "mix in live homepage polish".
- User explicitly invokes
/luxury-mockup-pipeline or says "use the 5-agent pipeline".
- A design mockup has been hand-reviewed and the user calls out specific issues (sizing, canon misattribution, sloppy execution) that require coordinated multi-discipline fixes.
When NOT to invoke
- Net-new mockup creation from scratch (use
frontend-design skill + brainstorming + writing-plans instead — those build the artifact; this skill refines it).
- Single-issue fix (e.g., "fix this typo") — use direct Edit.
- Production WordPress theme work (use
wordpress-platform-pipeline or direct theme template edits).
The Five Agents
| Stage | Agent | Responsibility | Deliverable |
|---|
| 1a | UX Architect | Compare live production page vs new mockup. Identify polish layers (grain, vignette, parallax, particles, scroll-progress, etc.) worth mixing in. | <docroot>/v2-polish-mix.md |
| 1b | UI Designer | Audit mockup for visual fidelity issues. Image sizing, type rhythm, hover states, spacing, contrast. Produce specific component-level fixes with exact CSS diffs. | <docroot>/v2-visual-fixes.md |
| 1c | Brand Guardian | Enforce brand canon — verify every photo, lockup, color, and copy line against the canon docs. Flag P0/P1/P2 violations. | <docroot>/v2-canon-audit.md |
| 1d | Frontend Developer | Asset triage. Identify transparency / alpha-channel needs, oversized files, missing variants. Recommend asset swaps or generation steps. | <docroot>/v2-asset-audit.md |
| 2 | Senior Developer | Execute the consolidated fix manifest. Premium implementation specialist — applies the CSS/HTML/asset changes from the 4 audit reports atomically with TDD-style commits per fix-group. | Commits + final v2.html state |
Process Flow
digraph luxury_pipeline {
rankdir=TB;
"Detect inputs:\nmockup path + canon docs + live target URL" [shape=box];
subgraph cluster_diagnostic {
label="Stage 1 — Parallel diagnostic (4 agents)";
"UX Architect: polish mix-in" [shape=box];
"UI Designer: visual audit" [shape=box];
"Brand Guardian: canon audit" [shape=box];
"Frontend Developer: asset audit" [shape=box];
}
"Synthesize fix manifest\nfrom 4 reports" [shape=box];
"User review of manifest" [shape=diamond];
"Senior Developer: execute" [shape=box];
"Final verify (single agent or inline)" [shape=box];
"Commit + report" [shape=doublecircle];
"Detect inputs:\nmockup path + canon docs + live target URL" -> "UX Architect: polish mix-in";
"Detect inputs:\nmockup path + canon docs + live target URL" -> "UI Designer: visual audit";
"Detect inputs:\nmockup path + canon docs + live target URL" -> "Brand Guardian: canon audit";
"Detect inputs:\nmockup path + canon docs + live target URL" -> "Frontend Developer: asset audit";
"UX Architect: polish mix-in" -> "Synthesize fix manifest\nfrom 4 reports";
"UI Designer: visual audit" -> "Synthesize fix manifest\nfrom 4 reports";
"Brand Guardian: canon audit" -> "Synthesize fix manifest\nfrom 4 reports";
"Frontend Developer: asset audit" -> "Synthesize fix manifest\nfrom 4 reports";
"Synthesize fix manifest\nfrom 4 reports" -> "User review of manifest";
"User review of manifest" -> "Senior Developer: execute" [label="approved"];
"User review of manifest" -> "Synthesize fix manifest\nfrom 4 reports" [label="refine"];
"Senior Developer: execute" -> "Final verify (single agent or inline)";
"Final verify (single agent or inline)" -> "Commit + report";
}
Inputs (gather before invoking)
| Input | Source | Required |
|---|
| Mockup HTML path | docs/brand/design-mockups/<name>.html | yes |
| Live homepage URL (for mix-in comparison) | Project context (e.g., https://skyyrose.co/) | yes |
| Source PHP template (for polish-layer extraction) | wordpress-theme/<theme>/front-page.php | yes if mixing from production |
| Canon docs path | docs/brand/ (visual-references.md, collection-stories.md, asset-hierarchy.md) | yes |
| Memory canon files | ~/.claude/projects/<project>/memory/feedback_* | yes (read-only) |
Stage 1 — Parallel diagnostic
Dispatch all 4 agents in a single message (parallel tool calls). Each agent gets:
- Structured brief: a JSON file at
prompts/<agent-slug>.json validating against schemas/agent-brief.schema.json. The agent reads this for: mission / scope (header→body→footer) / performance baseline / deliverables / ROI mandate / constraints / return format.
- Layout reference:
references/full-theme-skeleton.html — canonical full-theme structure spanning every page / component / widget / layout slot, with always-on performance + a11y + SEO checklists. Agent reads this for: which surfaces exist, what high-performing defaults look like per slot.
- Inline dispatch prompt: brief pointer to the JSON + HTML files plus the verbatim founder feedback (for emphasis). Avoids restating the contract.
Dispatch contract
The skill's prompt scaffolding lives at:
~/.claude/skills/luxury-mockup-pipeline/
├── SKILL.md # this file
├── schemas/
│ ├── agent-brief.schema.json # JSON Schema for prompt files
│ └── deliverable.schema.json # JSON Schema for outputs
├── references/
│ └── full-theme-skeleton.html # canonical layout contract — header / body / footer / every component+widget+layout slot
└── prompts/
├── ux-architect.json
├── ui-designer.json
├── brand-guardian.json
├── frontend-developer.json
└── senior-developer.json
Every dispatch follows this pattern:
Read your structured brief at <skill-root>/prompts/<agent-slug>.json AND the layout reference at <skill-root>/references/full-theme-skeleton.html. The brief defines mission, scope (header→body→footer), performance baseline, deliverables, mandatory ROI upgrade, constraints. The HTML reference is the canonical layout contract — every page/component/widget/layout slot you must consider. Founder verbatim feedback: "". Produce your deliverable per the JSON brief's deliverables[] and return_format.
This pattern stays constant across mode=refine / build / migrate / harden. Only the JSON brief contents change per mode.
Highest-performing features mandate (always on)
Every agent encourages and verifies the highest-performing default for every slot they touch. Defaults are encoded in references/full-theme-skeleton.html:
| Surface | Highest-performing default the agent must encourage |
|---|
| Header | Sticky w/ shadow-on-scroll, transparent over hero, inline SVG monogram, mega-menu (hover + focus), focus-trapped mobile drawer, search overlay (debounced instant results), cart drawer |
| Hero / Cover | <picture> w/ avif+webp+img, fetchpriority="high", preload tag, aspect-ratio CSS (no CLS), <source> w/ proper sizes |
| Page body | Skip link first focusable, ARIA live regions, semantic landmarks, heading hierarchy h1→h2→h3, every interactive focus-visible |
| Collection grid | 4 evenly aligned tiles desktop / 2 tablet / 1 mobile, scene photo per tile (avif/webp/img), explicit dimensions, lazy below-fold |
| Product card | Wishlist + quick-view, <picture> responsive, price w/ visually-hidden label, hover-state for keyboard parity |
| Newsletter | Native form validation + ARIA-live status, autocomplete=email, error linkage |
| Footer | 4-col link grid + newsletter + payment icons + legal + founder signature + back-to-top |
| Widgets | Toast (ARIA polite), modal (focus-trap), cookie consent (GDPR opt-in), scroll progress (decorative aria-hidden), back-to-top (IO-driven appearance) |
| Performance | Critical CSS < 14KB inlined, fonts self-hosted woff2, JS deferred, gzip/brotli, content-hash filenames, HTTP/2+ |
| A11Y | WCAG 2.2 AA min, prefers-reduced-motion + prefers-contrast honored, keyboard nav complete |
| SEO | Unique title/desc/canonical/OG/Twitter, JSON-LD per page type, sitemap+robots, hreflang if multi-locale |
Agents that touch a surface MUST verify these defaults are present (refine mode) or generate them (build mode). They do not need to re-explain the defaults in their deliverable — only flag gaps.
Stage 1a — UX Architect prompt template:
Compare the live <live-url> homepage against the new mockup at <mockup-path>. Identify polish layers from production worth porting into the standalone mockup. For each layer: source location (CSS file + line), visual effect, mix-in recommendation (YES/NO/OPTIONAL), implementation difficulty. Plus: propose exactly 1 high-ROI motion / interaction upgrade per the Upgrade Mandate (see skill header) — append as ## ROI Upgrade Proposal section in your deliverable. Output: <docroot>/v2-polish-mix.md. Return: top 3 Tier 1 mix-ins + 1-line ROI upgrade name.
Stage 1b — UI Designer prompt template:
Audit <mockup-path> for visual fidelity issues. Image sizing, type scale, hover states, spacing rhythm, contrast. For each issue: file:line, problem, root cause, exact CSS/HTML fix diff. Plus: propose exactly 1 high-ROI luxury detail system per the Upgrade Mandate (cursor / grain / type rhythm / magnetic hover / frame transition) — append as ## ROI Upgrade Proposal section. Output: <docroot>/v2-visual-fixes.md. Return: top 5 fixes ranked by impact + 1-line ROI upgrade name.
Stage 1c — Brand Guardian prompt template:
Audit <mockup-path> against <canon-docs>. Verify every photo asset, collection lockup, palette use, and copy line. Classify violations P0 (canon-breaking) / P1 (canon-adjacent inconsistency) / P2 (stylistic concern). Plus: propose exactly 1 high-ROI canon-signature touch per the Upgrade Mandate (accent pulse / monogram emergence / signature beat) — append as ## ROI Upgrade Proposal section. Output: <docroot>/v2-canon-audit.md. Return: per-violation summary with severity + 1-line ROI upgrade name.
Stage 1d — Frontend Developer prompt template:
Asset triage for <mockup-path>. For each image asset: identify dimensions, file size, alpha channel presence, where it's used, whether transparency is needed. Recommend swaps or remediation (rembg / cwebp / new export). Plus: propose exactly 1 high-ROI asset upgrade per the Upgrade Mandate (transparent monogram / AVIF re-encode / color-grade LUT / variant generation) — append as ## ROI Upgrade Proposal section. Recommend only — do NOT execute paid or compute-heavy operations. Output: <docroot>/v2-asset-audit.md. Return: blocker count + specific swap paths + 1-line ROI upgrade name.
Stage 1.5 — Automated deliverable validation (NEW)
After each Stage 1 agent reports DONE, the orchestrator runs:
bash <skill-root>/scripts/dispatch.sh <agent-slug> <deliverable-manifest.json> --html <target-html-if-any>
This wraps three automated checks:
-
validate-deliverable.sh — runs the deliverable against schemas/deliverable.schema.json. Verifies:
- JSON parse + required fields
- All 7 SaaS gates marked
passed: true
roi_upgrade.proposed: true + prefers_reduced_motion_safe: truememory_writes array has ≥ 1 entry (enforces memory write mandate)return_summary.word_count ≤ 280 (token-aware compliance)
-
saas-gate.sh — runs the 13 automated checks on any HTML deliverable (AVIF coverage, preload, skip link, focus-visible, asset paths resolve, etc.)
-
Memory verification — confirms the agent's memory dir grew by ≥ 1 fact file since dispatch start
If any check fails: deliverable is REJECTED. The orchestrator re-dispatches the agent with the specific failure notes. Re-dispatch limit: 3 attempts. After that, surface BLOCKED to founder.
If all checks pass: deliverable enters Stage 2 synthesis. Manifest is added to the synthesis pool.
This gate is non-skippable — manifest dispatches that bypass validation are out of contract.
Stage 2 — Synthesize fix manifest
Read the 4 deliverable docs. Produce a single consolidated manifest at <docroot>/v2-fix-manifest.md that:
- Groups fixes by surface (e.g., F01 Cover, F02 Hero, F04 Spread, etc.) so Senior Developer can apply them in spatial order.
- Ranks by priority: P0 canon violations > Visual blockers > Polish mix-ins > Asset optimizations.
- For each fix: exact file:line + before/after diff + which source audit it came from + verification step.
- Flags conflicts between agent recommendations (e.g., UI Designer says larger lockup, UX Architect says add particle layer at same z-index). Resolve in the manifest or surface to user.
Stage 3 — User review gate
Present the fix manifest to the user. Get explicit approval before executing. Auto Mode behavior: if user has pre-approved the pipeline + their previous interactions show no canon-blocking concerns, skip to Stage 4. Otherwise pause for sign-off.
Stage 4 — Senior Developer execution
Dispatch the Senior Developer agent (subagent_type: Senior Developer) with the fix manifest. The agent is the premium implementation specialist — masters advanced CSS, Three.js integration, Laravel/Livewire/FluxUI, and standalone HTML/CSS/JS pipelines.
Senior Developer prompt template:
You are executing the fix manifest at <manifest-path> against <mockup-path>. Apply fixes in priority order grouped by surface (Tier 0 → 1 → 2 → 3 → U). After each fix-group, commit atomically with conventional commit messages (fix(<scope>): <description> / feat(<scope>): <addition>). Run HTML parse verification + asset path verification after each group. Stop and surface BLOCKED if any fix conflicts with existing markup or canon. Plus: implement exactly 1 high-ROI advanced web-platform feature per the Upgrade Mandate (scroll-driven animations / view-transitions / Houdini / container queries / :has() selectors / color-mix()) as Tier U commit — production-grade only, with graceful fallback, honoring prefers-reduced-motion. Append a ## ROI Upgrade Implemented section to the final report with: feature name, commit SHA, lines added/removed, browser support matrix, fallback strategy. Final report: commit SHAs per fix-group + Tier U upgrade SHA + before/after line counts + acceptance criteria pass/fail.
Senior Developer SHOULD:
- Apply fixes atomically per surface or per priority tier
- Verify HTML parses after each commit
- Verify canon-doc references are intact
- Use the existing
.cover__* / .hero__* / .voice__* / .spread__* BEM namespaces from the mockup
- Add new CSS classes only when an existing class doesn't fit
Senior Developer MUST NOT:
- Introduce Three.js or WebGL into a standalone-mockup context (unless spec explicitly permits)
- Reference locked-out brands or break canon
- Re-fetch assets from CDNs
- Skip verification steps
Stage 4.5 — Loop integration (drives Stage 4 to completion)
After dispatching Senior Developer (Stage 4) the orchestrator wraps execution in a /loop cycle so the pipeline iterates against the manifest's acceptance criteria until every fix lands or a hard block surfaces.
Loop invocation:
/loop "execute v2-fix-manifest.md until all tiers complete and acceptance criteria pass" \
--target docs/brand/design-mockups/v2.html \
--manifest docs/brand/design-mockups/v2-fix-manifest.md \
--on-cycle "dispatch Senior Developer with next-unlanded tier" \
--on-block "stop loop, surface BLOCKED report to user" \
--max-cycles 6 \
--acceptance-check "html parses + grep canon-violation patterns = 0 + git diff --name-only shows only target file"
Loop cycle (one iteration):
- Read manifest, identify lowest-tier fix not yet committed
- Dispatch Senior Developer (or appropriate agent) for that fix-group only
- After agent reports DONE: run acceptance check
- If pass and more fixes remain → next cycle
- If pass and all done → exit loop, advance to Stage 5
- If BLOCKED → exit loop, surface to user with state + commit SHAs landed so far
Why a loop: the manifest can be 10–20 fixes across 5 tiers. A single Senior Developer dispatch occasionally returns DONE_WITH_CONCERNS or hits a partial block (one fix conflicts with a prior fix's edit). The loop lets the pipeline:
- Auto-retry the failing fix with refined instructions
- Add a new agent (e.g., re-dispatch Brand Guardian) mid-stream if a canon question surfaces
- Stop cleanly when human input is required (rembg, founder asset call, ambiguous canon)
Loop guards:
- Hard ceiling:
--max-cycles 6 (prevents runaway)
- Atomic boundary: loop only advances at full fix-group completion, never mid-fix
- Token-aware integration: if budget state ≥
handoff, loop exits with RESUME PROMPT
- Branch protection: loop NEVER force-pushes, NEVER skips hooks, NEVER amends prior commits
When NOT to wrap in /loop:
- Manifest has ≤3 fixes (overhead exceeds benefit — use direct dispatch)
- All fixes share a single file with no inter-fix dependency (one Senior Developer dispatch is enough)
- User is actively reviewing — loop interrupts the human-in-loop pattern
For SkyyRose v2 work (12+ fixes typical, multi-tier): always wrap.
Stage 5 — Final verify
Either:
- Dispatch a final review agent (subagent_type:
Reality Checker or Accessibility Auditor) for a fresh-eyes pass
- OR inline: run HTML parse + grep for canon-violation patterns + diff summary
Acceptance criteria (mockup-specific, document in the manifest):
- HTML parses
- All canon docs unmodified during execution
- Zero locked-out brand references
- All asset paths resolve (no 404s on local file://)
- Each fix-group has a corresponding commit
Stage 6 — Commit + report
Final report to user includes:
- Commit list (SHA + message per fix-group)
- Before/after line count
- Acceptance criteria pass/fail table
- Remaining items (deferred to production translation or future passes)
Anti-Patterns to Avoid
- ❌ Dispatching agents sequentially when they're independent (always parallel in Stage 1)
- ❌ Skipping Stage 2 synthesis — Senior Developer should NOT read 4 raw reports, only the consolidated manifest
- ❌ Letting Senior Developer make canon decisions — those belong in Stage 1c (Brand Guardian) and locked before Stage 4
- ❌ Approving Stage 3 without surfacing the manifest to user when canon-breaking fixes are present
- ❌ Running Stage 4 without Stage 3 user gate (unless Auto Mode + pre-approved scope)
- ❌ Final verify (Stage 5) executed by Senior Developer themselves — must be independent
Integration with other skills
token-aware-behavior runs ALONGSIDE this skill at all times. Budget thresholds (60/75/88/95) govern dispatch density, return-summary length, and synthesis behavior. See "Token-Aware Runtime Guard" section above./loop runs INSIDE this skill at Stage 4.5. Drives Senior Developer to manifest-complete or surfaces clean BLOCKED state. See "Stage 4.5 — Loop integration" above.brainstorming runs BEFORE this skill (creates the mockup spec). This skill is the REFINEMENT loop.writing-plans runs BEFORE this skill (creates the initial implementation plan). This skill polishes the result.subagent-driven-development is the orchestration pattern this skill uses internally for Stage 1 + 4.finishing-a-development-branch runs AFTER this skill (merge / PR / cleanup).
Reference invocation
For SkyyRose v2 mockup refinement:
Inputs:
mockup-path = docs/brand/design-mockups/v2.html
live-url = https://skyyrose.co/
source-template = wordpress-theme/skyyrose-flagship/front-page.php
canon-docs = docs/brand/visual-references.md + collection-stories.md + asset-hierarchy.md
memory-canon = ~/.claude/projects/-Users-theceo-DevSkyy/memory/feedback_collection_canon_attribution.md
Outputs land at:
docs/brand/design-mockups/v2-polish-mix.md (UX Architect)docs/brand/design-mockups/v2-visual-fixes.md (UI Designer)docs/brand/design-mockups/v2-canon-audit.md (Brand Guardian)docs/brand/design-mockups/v2-asset-audit.md (Frontend Developer)docs/brand/design-mockups/v2-fix-manifest.md (synthesis)- Modified
docs/brand/design-mockups/v2.html (Senior Developer execution)
- New asset variants if Frontend Developer flagged any (e.g., transparent monogram export)
Quick reference card
luxury-mockup-pipeline =
token-aware guard (always-on)
+ 4 parallel auditors (each delivers 1 ROI upgrade)
→ manifest (Tiers 0–3 + Tier U upgrades)
→ 1 executor wrapped in /loop (max 6 cycles)
(executor also delivers 1 ROI upgrade)
→ 1 verifier
Auditors: UX Architect / UI Designer / Brand Guardian / Frontend Developer
Executor: Senior Developer (wrapped in /loop)
Verifier: Reality Checker OR Accessibility Auditor OR inline
Guards: token-aware-behavior (budget) + /loop --max-cycles 6 (iteration ceiling)
Mandatory ROI upgrades: 5 (one per agent), all rolled into manifest Tier U
