From wix
Builds complete Wix Managed Headless sites from single prompts, orchestrating subagents for discovery, design, feature wiring, and preview on new-site requests.
npx claudepluginhub wix/skills --plugin wixThis skill uses the workspace's default tool permissions.
Single orchestrator for the full site build. Linear flow with parallel subagent workers coordinated through design tokens and structured agent returns.
references/DISCOVERY.mdreferences/ORCHESTRATION.mdreferences/SETUP.mdreferences/blog/BLOG_CONTENT.mdreferences/blog/BLOG_PAGES.mdreferences/blog/BLOG_SETUP.mdreferences/blog/INSTRUCTIONS.mdreferences/cms/CMS_FOUNDATIONS.mdreferences/cms/FAQ_KNOWLEDGE_BASE.mdreferences/cms/INSTRUCTIONS.mdreferences/cms/PORTFOLIO.mdreferences/cms/RESOURCE_LIBRARY.mdreferences/cms/TEAM_DIRECTORY.mdreferences/commands/install-app.mdreferences/commands/known-apps.jsonreferences/commands/mcp-bootstrap.mdreferences/designer/INSTRUCTIONS.mdreferences/ecom/CART_PAGES.mdreferences/ecom/CART_WIRING.mdreferences/ecom/COMPONENTS_CSS.mdGuides creation of production-ready Power Pages code sites as SPAs using React, Angular, Vue, or Astro, from requirements discovery to deployment with live dev server previews and git commits.
Generates modern responsive websites from text prompts via EvoWeb AI API. Polls status to retrieve live URL and editor link for landing pages, portfolios, stores, and blogs.
Builds landers (1-page), minisites (~4 pages), or full websites from business context files, routes to shape-specific flows, deploys to Cloudflare Pages with git auto-deploy. For new sites, updates, upgrades, or previews.
Share bugs, ideas, or general feedback.
Single orchestrator for the full site build. Linear flow with parallel subagent workers coordinated through design tokens and structured agent returns.
Your CWD at runtime is the project directory, not the skill root. Compute <SKILL_ROOT> from this file's path: this file is at <SKILL_ROOT>/SKILL.md — strip the trailing /SKILL.md. Hold the absolute path in session scratch for the whole run.
| What | Absolute path |
|---|---|
| Shared return contract | <SKILL_ROOT>/references/shared/RETURN_CONTRACT.md |
| Shared MCP prefix guide | <SKILL_ROOT>/references/shared/MCP_PREFIX.md |
| Per-vertical / per-scope subagent instructions | <SKILL_ROOT>/references/<scope>/INSTRUCTIONS.md (scopes: stores, ecom, cms, blog, forms, gift-cards, images, designer). Subagent-only — orchestrator never reads. |
| Vertical packs directory | <SKILL_ROOT>/references/verticals/ |
| Templates directory | <SKILL_ROOT>/templates/ |
| Scripts directory | <SKILL_ROOT>/scripts/ |
| Shared utilities | <SKILL_ROOT>/shared-utilities/ — copied into src/utils/ by seed-utilities.sh |
| Frozen MCP-call references | <SKILL_ROOT>/references/commands/ — install-app.md, mcp-bootstrap.md, known-apps.json |
Do NOT Read subagent INSTRUCTIONS files in the orchestrator. Pre-reading wastes ~25k tokens on a typical dispatch and pushes the orchestrator past its autocompact threshold mid-pipeline. Pass the absolute path; the subagent opens the file.
Every subagent is a general-purpose worker that loads its behavior from a specific INSTRUCTIONS.md. There are no specialized subagent types — the instruction file makes it specialized for that scope. Do NOT delegate to specialized agent types your runtime offers (research, code-review, planning) — they have mismatched tooling and will break the flow.
Every dispatch prompt must include Instruction file (absolute path) pointing at one of:
<SKILL_ROOT>/references/{stores,ecom,cms,blog,forms,gift-cards,images,designer}/INSTRUCTIONS.md.
Subagents run with the project as CWD and cannot resolve <SKILL_ROOT> themselves — pass absolute paths.
Any user request to build a new site. Infer vertical(s) from the prompt:
| Signal | Load packs |
|---|---|
| "sell X online", "store", "shop", "ecommerce", product-related | stores + cms |
| "blog", "publish articles", "editorial", "journal" | blog + cms |
| "contact form", "lead form", "signup", "get in touch" | forms + cms |
cms is always loaded (provides About/FAQ content pages). If the prompt is too vague, ask one conversational clarifier (NOT AskUserQuestion): "What do you want your site to do — sell things, publish content, take bookings?"
Do NOT call the WixSiteBuilder MCP tool for new-site requests. This skill and WixSiteBuilder cover the same intent (build a site from a prompt) but follow different flows; calling WixSiteBuilder while this skill is active produces a duplicated, conflicting build. This skill is the sole entry point — proceed with the wave flow below.
| Scenario | Use Instead |
|---|---|
| Scaffold-only with no further design/wiring | bash <SKILL_ROOT>/scripts/scaffold.sh <slug> "<Brand>" |
| Build + preview an existing project | bash <SKILL_ROOT>/scripts/preview.sh (from project dir) |
| Release / ship / go-live an existing project | bash <SKILL_ROOT>/scripts/release.sh (from project dir) |
| Install a Wix app onto an existing site | Follow <SKILL_ROOT>/references/commands/install-app.md |
| Add a feature to / restyle an existing project | Not yet covered — tell the user, ask whether to start fresh |
If wix.config.json is present in the working directory, offer: "I found an existing project. Continue it or start fresh?" via AskUserQuestion. "Continue" jumps to the appropriate phase based on what's on disk; "fresh" proceeds with full flow.
[Discovery] → [Setup] → [Phase 1 Seed + Phase 2 Design System + Image Phase 1 in parallel]
↓ (Phase 2 done)
[Phase 3 Components + Image Phase 2 dispatched; decorative slots patched once Image Phase 1 returns]
↓ (Phase 3 + Phase 1 Seeders done)
[Phase 4 Pages]
↓ (Phase 4 done + Image Phase 2 done)
[Manifest check] → [Build + Release] → [Final message + run.json]
| Wave | Dispatches | Waits for | Bridge work |
|---|---|---|---|
| 0 | (bash) | — | MCP prefix discovery, schema bootstrap, capture runStartedAt |
| 1 | (Q&A) | user | brand/vibe/aesthetic; scaffold launches in background after Q1 |
| 2 | apps install + env-pull + npm-install (bg) + seed-utilities | — | init-site-json.mjs |
| 3 | seeders + design-system + image-phase-1 | design-system (fg) | merge designTokens into site.json; emit-design-tokens.mjs; grep Layout.astro CSS imports |
| 4 | components + components-css + image-phase-2 (all bg) | (none — all backgrounded) | copy-utility-templates.mjs components; on Image Phase 1 return: patch-decorative-slots.mjs; on Phase 3 return: check-manifest.mjs components |
| 5 | pages | components done + Phase 1 seeders done | copy-utility-templates.mjs pages |
| 6 | (bash) | pages done + image-phase-2 done | check-manifest.mjs pages; release.sh; finalize-run-json.mjs |
Phase axis. Core pipeline: Phase 1 (Seed) → Phase 2 (Design System) → Phase 3 (Components) → Phase 4 (Pages). Image pipeline runs in parallel: Image Phase 1 (Decorative) alongside Phases 1–2; Image Phase 2 (Entity) alongside Phase 3 (depends only on Phase 1 Seed entity IDs + brand). Each Phase 4 agent writes its routes ONCE with both visual design and data queries — no placeholder-then-rewrite split.
The orchestrator is the only writer of .wix/site.json — it merges each Seeder's data block into seeded.<vertical> and the Designer's data.designTokens block into designTokens as subagent results arrive. Subagents never write site.json themselves.
Each parallel-dispatch step is one concurrent batch with no narration between dispatches. Interleaved status updates, file writes, or text like "Launching agents…" splits the batch into separate turns and adds 12–39s of inter-dispatch latency per gap. Make every subagent that doesn't block downstream work a background subagent (only Phase 2 Design System is foreground) — background dispatch alone gives ~2× compression by overlapping execution.
Every dispatch prompt includes:
Instruction file (absolute path) — <SKILL_ROOT>/references/<scope>/INSTRUCTIONS.mdPhase instruction / Scope — exact scope stringMCP tool prefix — from Wave 0, verbatimProject directory (absolute path) — project CWDsiteId — from wix.config.jsonBrand context — name, vibe, aesthetic direction, colors, fontsSee references/SETUP.md § "MCP Prefix Discovery + Schema Bootstrap".
runStartedAt via date -u +%Y-%m-%dT%H:%M:%SZ and hold in scratch (used at end-of-run for run.totalSeconds).WixREADME, strip the trailing suffix from the returned name. Call <prefix>WixREADME to verify connectivity. On failure, stop and tell the user the Wix MCP server isn't connected.<SKILL_ROOT>/references/commands/mcp-bootstrap.md and follow its single ToolSearch invocation. Capture { phase: "mcp-bootstrap", seconds: <duration> } in run.json.phases[].See references/DISCOVERY.md for full mechanics.
Infer vertical(s) from the user's opening message; if too vague, one conversational clarifier.
Q1 (AskUserQuestion): brand name. On answer, launch scaffold in background: bash <SKILL_ROOT>/scripts/scaffold.sh <slug> "<Brand>". Slug-derivation + timing capture rules in references/DISCOVERY.md § "Scaffold dispatch".
Q2 (AskUserQuestion): vibe.
Craft a 2–3 sentence aesthetic direction in scratch (do not print standalone).
Present the plan as markdown (Design Direction → Features → Pages → CMS Collections → Apps & SDK). Pages, CMS Collections, and Apps & SDK MUST be markdown tables.
Before typing any table, open
references/DISCOVERY.md§ "Plan structure" and copy each section's header skeleton verbatim. Do NOT type column headers from memory — root cause of every plan-format regression. DISCOVERY.md leads with the exact| ... |header to copy and a STOP cue listing wrong shapes.
AskUserQuestion for approval.
See references/SETUP.md. After approval, run one concurrent batch with no narration between operations.
App install for every entry in apps[*] of every loaded vertical. Follow <SKILL_ROOT>/references/commands/install-app.md — owns the CallWixSiteAPI body shape, appName → appDefId lookup, and recovery ladder. An empty apps: [] array means install nothing for that pack — gift-cards, ecom, cms all ship apps: []. Do not invent an appName from the pack name or SDK packages. Capture APP_INSTALL_START/END via date -u +%s around the CallWixSiteAPI invocation; record { phase: "app-install-<appName>", seconds }.
npx @wix/cli env pull (foreground, fast). Produces .env.local with WIX_CLIENT_ID. On auth error: surface "Run \npx @wix/cli login` and retry."and stop. Record{ phase: "env-pull", seconds }`.
rm -f package-lock.json && npm install … as a background shell with the union of all loaded verticals' packages arrays plus the always-packages (@wix/sdk tailwindcss @tailwindcss/vite). Flags: --no-fund --no-audit --legacy-peer-deps. Bake NPM_INSTALL_START=$(date -u +%s) and NPM_INSTALL_END=$(date -u +%s) into the SAME background bash command so the values land in its output. Record { phase: "npm-install", seconds } when the install finishes. Do not add packages beyond this set — see SETUP.md § anti-hallucination rule.
bash <SKILL_ROOT>/scripts/seed-utilities.sh — copies <SKILL_ROOT>/shared-utilities/*.ts (wix-image.ts, analytics.ts, ricos.ts) into src/utils/ with cp -n and strips the Astro starter cruft. Record { phase: "seed-utilities", seconds }.
Memory writes — project memory with brand/apps/pages/phase.
User-facing roadmap × N — emit a tracker entry per phase boundary. Target 6–8 entries: "Install apps", "Seed data", "Design site", "Wire features", "Generate images", "Install dependencies", "Build and preview".
No ampersands in roadmap titles. Some progress trackers HTML-escape input —
"Build & preview"renders as literalBuild & preview. Spell out "and"; same for<,>,".
mkdir -p .wix — minimal. No .wix/logs/.
node "<SKILL_ROOT>/scripts/init-site-json.mjs" "$(pwd)" "<brand>" "<one-line aesthetic from Q2>" "<verticals-csv>" — wraps in PHASE_START/PHASE_END; record { phase: "init-site-json", seconds }. Writes the canonical initial .wix/site.json:
{"brand": {"name": "...", "description": "..."}, "seeded": {}, "designTokens": {}, "verticals": ["..."]}
.wix/site.json is the single source of truth that every downstream phase reads. Only the orchestrator writes — it merges Seeder data into seeded.<vertical> and Designer data.designTokens into designTokens as returns arrive.
Per loaded vertical:
seed config. Returns its data via the standard return JSON; orchestrator merges into .wix/site.json.seeded.<vertical>.Always:
Scope: image-phase-1-decorative + page list + decorativeSlots: string[] (REQUIRED). Compose decorativeSlots from the canonical vocabulary in references/designer/INSTRUCTIONS.md § common rule #7: always ["hero", "about"], plus "productsHeader" if stores loaded, plus "cmsHeader" if you want a CMS page-header decorative. Designer is restricted to the same vocabulary; the two MUST match exactly.design-system, instruction file <SKILL_ROOT>/references/designer/INSTRUCTIONS.md. Writes global.css, Layout.astro, Navigation.astro, Footer.astro, astro.config.mjs, index.astro shell, returns designTokens JSON.The Designer prompt additionally requires:
Navigation links: [...] — JSON array of {href, label} for top-level nav links the designer hardcodes. Compose by filtering loaded packs: include a route ONLY if its pack does not declare a <!-- nav:links --> entry in contributes:. With today's packs:
/about, /faq are designer-owned./products is NOT designer-owned (stores splices a Shop submenu at <!-- nav:links --> in Phase 4 pages-home-and-nav)./gift-cards is NOT designer-owned (gift-cards splices a probe-gated link, AND it's disabled: true).<!-- nav:actions --> (CartBadge mount).[{href:"/about",label:"About"},{href:"/faq",label:"FAQ"}]. Including /products or /gift-cards produces duplicate Products+Shop links.Disabled packs: [...] — names of loaded packs with disabled: true. The designer must not add hero CTAs, footer links, or any other surfaces pointing at their routes. Without this, the designer composes a "Send a gift card" CTA pointing at /gift-cards even when the user hasn't enabled gift-cards.Phase 2 completes (~2–3 min). Inline orchestrator work, in this exact order:
data.designTokens into .wix/site.json.designTokens.node "<SKILL_ROOT>/scripts/emit-design-tokens.mjs" "$(pwd)" — deterministically projects .wix/site.json.designTokens → .wix/design-tokens.css + .wix/site.d.ts. Wrap in PHASE_START/PHASE_END; record { phase: "emit-design-tokens", seconds }.src/layouts/Layout.astro. For every loaded vertical whose pack declares a components entry (stores, ecom, blog, forms), there MUST be a matching import '../styles/components-<pack>.css' in the frontmatter. If any is missing, inline-patch Layout.astro now — Phase 3 agents write components-<pack>.css expecting the designer to have imported it; if forgotten, every React island that uses scoped contract classes renders unstyled.Phase 1 seeders are still running. Image Phase 1 is still running. Do not block on either — proceed to Wave 4.
Read .wix/design-tokens.css + .wix/site.d.ts once (orchestrator pastes them inline into Phase 3 prompts).
Pre-dispatch bridge: node "<SKILL_ROOT>/scripts/copy-utility-templates.mjs" "$(pwd)" components (sibling of the dispatch in the same orchestration step). Deterministically copies templated SDK-wrapper utility files for the components phase into src/utils/ (today: back-in-stock.ts if stores loaded; discounts.ts if ecom loaded). Reads .wix/site.json.verticals to know which packs are loaded; uses cp -n. Wrap in PHASE_START/PHASE_END; record { phase: "copy-utility-templates-components", seconds }. The hardcoded mapping (template → destination, per pack + phase) lives at the top of the script — single source of truth.
Per loaded vertical with a components entry:
Per loaded vertical with a componentsCss entry (today: stores, ecom):
components sibling — TSX→CSS link is build-time via class names. Reading set is much smaller (see <SKILL_ROOT>/references/<vertical>/COMPONENTS_CSS.md). Skip silently for packs without this entry.If any pack produces entities (stores products, CMS items, blog posts) AND the relevant Phase 1 Seeder has returned:
Image Phase 2 Entity subagent (background). Generates + PATCHes entity images. Prompt adds Scope: image-phase-2-entity + Phase 1 Seed return data (products, collections, blogPosts — same inline format used for Phase 4 scopes) + brand context.
Gate. If a Phase 1 Seeder is still running, hold Image Phase 2 until that seeder returns and merges. Phase 3 dispatch does not wait — Phase 3 agents don't need entity data.
Credit-exhaustion skip. If Image Phase 1 returned
status: "failed"AND anyerrors[].codematchesREQUEST_NOT_ELIGIBLE/INSUFFICIENT_CREDITS/ quota-exhaustion patterns (messages containingnot eligible for credits,quota exceeded,resets at), DO NOT dispatch Image Phase 2 — both phases hit the same Wix AI credit pool. Record{phase: "image-phase-2-entity", status: "skipped", seconds: 0, notes: "Phase 1 confirmed credit exhaustion via <code>"}and surface in the final message ("No imagery shipped — you can upload images from the Wix dashboard"). Per-request transient errors (5xx, timeout) do NOT trigger this skip.
Do not enumerate files in the Phase 3 Components prompt. The agent's INSTRUCTIONS.md and the vertical pack's
creates:list (filtered byphase: components) own which files the agent writes. A hand-typed file list omits a file the pack declares, the agent skips it, downstream pages import it, build breaks.
Phase 2 designer wrote index.astro with data-decorative-slot="<key>" placeholder <div>s. Once Image Phase 1 returns:
status: "failed" or timed out, skip — placeholders look complete on their own. (You can also unconditionally invoke the script — it self-skips when .wix/image-urls.md is missing.)node "<SKILL_ROOT>/scripts/patch-decorative-slots.mjs" "$(pwd)" — reads .wix/image-urls.md, walks src/pages/**/*.astro, injects <img …class="decorative-slot-img" /> as the first child of each matching slot div. Idempotent + safe (won't clobber a div with non-<img> child content). JSON return: { status, imageUrls, filesScanned, patched, skipped, warnings }.warnings[] is non-empty, append {code: "DECORATIVE_SLOT_DIV_OCCUPIED", file, slot} per warning to the Phase 2 Design System entry's errors in run.json. If imageUrls[] is non-empty but patched[] is empty AND warnings[] is empty, the designer emitted no data-decorative-slot= attributes at all — append {code: "NO_DECORATIVE_SLOTS_FOUND"}. Both non-fatal.Wrap in PHASE_START/PHASE_END; record { phase: "decorative-slot-patch", seconds }.
When all Phase 3 sub-agents return: node "<SKILL_ROOT>/scripts/check-manifest.mjs" "$(pwd)" components "<packs-csv>". Verifies every creates: entry tagged phase: components exists on disk and recovers missing files from canonical templates. JSON output: present, recovered, missing arrays. Exit 0 = happy or fully recoverable; exit 1 = unrecoverably missing.
For each recovered entry, append to run.json.recoveries[]. For each missing entry, surface the remediation hint to the user before Wave 5 dispatches — Phase 3 React islands that Phase 4 imports are critical-path; if any are unrecoverable, do NOT continue. Record { phase: "manifest-check-components", seconds }.
Wait gate: before dispatching, confirm:
.wix/site.json.seeded.<vertical>.src/components/* and src/styles/components-<vertical>.css..wix/site.json.designTokens, .wix/design-tokens.css, .wix/site.d.ts all exist.If a Phase 1 Seeder returned without a parseable JSON block, re-request it (see <SKILL_ROOT>/references/shared/RETURN_CONTRACT.md) — do NOT dispatch with empty data and rely on subagents to re-query.
Pre-dispatch bridge: node "<SKILL_ROOT>/scripts/copy-utility-templates.mjs" "$(pwd)" pages — same script as Wave 4, invoked with pages. Today copies templates/stores/categories.ts → src/utils/categories.ts when stores loaded. Without it, pages-products and pages-home-and-nav start before pages-categories writes categories.ts and trigger spurious "missing import" recovery paths. Record { phase: "copy-utility-templates-pages", seconds }.
Per loaded vertical's pages:
Example for stores + cms run:
product-pages — products/index.astro, products/[slug].astro, ProductCard.astrocategory-pages — category/[slug].astro, CategoryRail.astro, utils/categories.tscart-checkout — cart.astro, thank-you.astrohome-and-nav — patch index.astro home product grid; patch Navigation.astro (CartBadge mount + Shop submenu insert)cms-pages — wire about + FAQEach prompt includes the standard fields PLUS:
Scope string (names the files it owns)
.wix/site.json path reference (MANDATORY). Agents read seeded data from .wix/site.json.seeded.<vertical>:
.wix/site.json.seeded.stores.products (id, name, slug, variantId, price, sku, inventory). .wix/site.json.seeded.stores.categories is always [] — categories are merchant-driven, live-queried by the frontend..wix/site.json.seeded.cms.collections..wix/site.json.seeded.blog.posts.site.json is missing a required key, return status: "failed", errors: [{code: "SITE_JSON_INCOMPLETE", missing: "..."}] rather than re-fetching. Re-querying would mask a seeder bug and adds 5–15 s per agent.Styling contract (full JSON inline — same pattern as Phase 3 Components).
ProductCard interface (for product-pages and home-and-nav only). Both subagents touch ProductCard.astro — product-pages owns and rewrites it, home-and-nav reads it to wire the home grid. Tell both subagents the interface up front to eliminate the read-timing race:
ProductCard.astro accepts a single prop: { product } where product is the full Wix product object from productsV3. Usage: <ProductCard product={p} />
Include verbatim in both prompts. Without this, home-and-nav reads the designer's placeholder ProductCard (which may have flat props) before product-pages rewrites it.
Image Phase 2 is NOT dispatched here. It was launched in Wave 4; the Wave 6 hard gate waits for it before release.
HARD GATE: Do NOT invoke
release.shuntilimage-phase-2-entityhas completed or timed out (120s). Skipping has shipped sites with no product images andrun.jsonrecordingimage-phase-2-entityas"in_progress".
Wait for ALL Phase 4 subagents AND image-phase-2-entity. If Phase 4 finishes before Image Phase 2, wait up to 120s. With Image Phase 2 dispatched in Wave 4 this is usually a no-op.
Observability fallback. Subagent return signals are not always reliable — silent gaps happen. If 3 minutes pass past the expected completion window with no signal, do NOT keep waiting indefinitely. Trigger the post-Phase-4 manifest check directly — if files exist, the subagents finished; if not, treat the gap as a failure and surface to the user.
Rate-limit recovery for image-phase-2-entity. If the subagent returns status: "failed" with an error matching /limit|quota|resets/i, do NOT stall or retry the subagent. Run the inline recovery in the orchestrator: batched generate (one call) → concurrent imports (one batch) → concurrent product/CMS PATCHes (one batch). Procedure encoded in references/shared/IMAGE_GENERATION.md.
Post-Phase-4 manifest check. node "<SKILL_ROOT>/scripts/check-manifest.mjs" "$(pwd)" pages "<packs-csv>". Same recovery rules as Phase 3 check. Surface any unrecoverable missing[] entries (exit code 1) before invoking release — those are page files Phase 4 didn't write that have no template fallback. Record { phase: "manifest-check-pages", seconds }.
Wait for npm install — the background install from Wave 2. Wait on its handle; do not sleep-poll. On non-zero exit follow the recovery ladder in references/SETUP.md § "npm install recovery" (foreground retry with timeout, never delete the lockfile).
bash <SKILL_ROOT>/scripts/release.sh — runs npx @wix/cli build + release, extracts the URL from Site published on <url>, prints the URL on stdout. Capture build / release timings via date -u wrappers and record { phase: "build", seconds } and { phase: "release", seconds }. The script's stdout becomes outcome.releaseUrl in run.json. This populates the Frontend link in headless settings so transactional emails link to the deployed frontend. On build failure, surface the compiler error and stop — do NOT deploy a broken site.
Use bash <SKILL_ROOT>/scripts/preview.sh (not this step) only when the user is iterating on an existing site and explicitly asks for a fast preview without touching production.
On non-fatal build warnings, see <SKILL_ROOT>/references/shared/BUILD_NOISE.md — read only if a warning surfaces.
No standalone verify phase. The post-phase manifest check catches missing files with auto-recovery; type/module/template errors surface from
astro builda few seconds later.
<SKILL_ROOT>/scripts/check-manifest.mjs is invoked from both Wave 4 (after Phase 3, with phase: components) and Wave 6 (after Phase 4, with phase: pages). Cost on the happy path: < 1 s per phase boundary. Recovery cost: ~10 ms per file copied from a template.
For every loaded pack, for every creates: entry where phase == <given>:
present.<SKILL_ROOT>/templates/<pack>/<tail> → copy it; record as recovered with {source: "template-copy", template}.missing with a PHASE_FILE_MISSING code and a remediation hint.The script outputs JSON; the orchestrator appends recovered[] to run.json.recoveries[], missing[] to run.json.errors[]. On any unrecoverable miss (exit 1), critical-path files (Phase 3 React islands that Phase 4 imports) → stop; optional ancillary files → log and continue.
The orchestrator never invents stub content for missing files — template-copy is the only recovery path. Stubs hide bugs (e.g. a no-op discounts.ts ships green builds with silently-broken discount rendering).
Backward compat. PHASE4_FILE_MISSING (used historically) remains as an alias for {code: "PHASE_FILE_MISSING", phase: "pages"}.
No visual or browser-based verification. After the build succeeds, do NOT open the URL in Playwright, take screenshots, or run smoke tests on your own initiative. Visual verification is opt-in only when the user explicitly requests it.
One concluding turn containing, in order:
Release URL text first — bold heading / link at the top so the user sees it immediately.
Compose the draft run.json blob in scratch. Aggregate every subagent return into phases[], set outcome.previewUrl, fill run.started (from runStartedAt) / run.ended (capture now via date -u), compute run.totalSeconds, and compose requiredPhases[] — phases that MUST have a captured duration:
mcp-bootstrap, init-site-json, scaffold, env-pull, seed-utilities, emit-design-tokens, manifest-check-components, manifest-check-pages, decorative-slot-patch, npm-install, build, release (or preview if preview.sh was used).app-install-<appName>.copy-utility-templates ran: copy-utility-templates-components and/or copy-utility-templates-pages.image-phase-2-entity's duration arrives via its return; record from there if any pack produced entities.echo "$RUN_JSON_DRAFT" | node "<SKILL_ROOT>/scripts/finalize-run-json.mjs" "$(pwd)" — applies the timing-completeness gate (any requiredPhases entry without a captured duration becomes seconds: null + {code: "MISSING_TIMING"} in errors[]), writes the canonical .wix/run.json, prints {perfLine, missingTiming[]} on stdout.
Emit the perf one-liner verbatim as the last line of the message body, from the script's perfLine:
Built in <Nm Ss> — design-system <n>s · images (phase 1 + phase 2) <n>s · build+release <n>s
Three buckets only — don't dump every phase. Missing buckets render as – rather than fabricated. If missingTiming[] is non-empty, surface those names on a separate line below the perf one-liner.
Do not re-read anything from disk to compose run.json. Use the agent return data already in session context.
For phases the skill runs directly (scaffold, app-install-*, env-pull, seed-utilities, npm-install, scripts, build, preview):
PHASE_START=$(date -u +%s)
# … invoke …
PHASE_END=$(date -u +%s)
# record: { "phase": "<name>", "seconds": $((PHASE_END - PHASE_START)) }
For background subagents / shells, capture PHASE_START at dispatch time and PHASE_END when the result arrives — not when you check output. A missed capture = MISSING_TIMING in run.json.
For per-phase seconds from subagent returns: compute from the agent's started/ended fields (per RETURN_CONTRACT.md). If omitted, set seconds: null and add {code: "MISSING_TIMING"} rather than faking — null makes the omission visible.
The final message emits exactly two URLs, copy-pasted verbatim:
npx @wix/cli release stdout, on the line Site published on <url>. Copy the exact string; do not retype, modify, or fill in digits from memory.https://manage.wix.com/dashboard/<siteId> where <siteId> comes from wix.config.json.Do NOT emit any URL constructed by modifying the release URL (swapping subdomains, changing digits, removing path segments) or any URL not present verbatim in tool output / config. Prior failure: a run emitted ...alexp575.wix-host.com next to the real ...alexp775.wix-host.com — the second was typo-constructed and 404'd.
On "going live": the flow deploys via release.sh, a real production release that populates the Frontend link so transactional emails link to the deployed frontend. Accepting real payments still requires a paid plan + payment provider — mention if asked.
Verticals live in references/verticals/ and declare how a vertical plugs into the flow: app installs, SDK packages, seed/components/pages agent configs, creates: and contributes: file-ownership.
Current verticals:
stores.md — product catalog (requires ecom, gift-cards)ecom.md — vertical-agnostic cart/checkout (co-loaded via requires)gift-cards.md — passive pack: ships in storefront sites; lights up only when the dashboard's Wix Gift Card app is enabledcms.md — About/FAQ + use-case recipes (always loaded)blog.md — blog posts with Ricos rich content, RSS/sitemapforms.md — contact, lead, signup forms with CRM integrationrequires: resolution: when a pack is loaded via discovery, every name in its requires: is also loaded transitively. Current chain: stores → [ecom, gift-cards] and gift-cards → [ecom].
Schema: references/verticals/_schema.md (human-readable) and _schema.json (machine-validated at session start). Adding a vertical: create references/verticals/<name>.md, references/<name>/INSTRUCTIONS.md, and any per-vertical references / templates. No changes to this skill file are needed.
Agents return structured data in their completion message, not via sidecar files. The skill parses return JSON and merges seeders' data blocks into .wix/site.json.seeded.<vertical>. At end of run, the skill writes .wix/run.json — a single observability record. See references/shared/RETURN_CONTRACT.md for schema and aggregation rules.
Skill-level:
references/DISCOVERY.md — discovery flow, plan format, aesthetic direction craftingreferences/SETUP.md — MCP prefix, app install, env pull, npm install recoveryreferences/ORCHESTRATION.md — phase-dispatch mechanics, wait conditions, data carry-forwardreferences/verticals/_schema.md — vertical pack schemaShared (with agents):
references/shared/RETURN_CONTRACT.md — agent return JSON schema, run.json aggregationreferences/shared/MCP_PREFIX.md — prefix discovery + recoveryreferences/shared/IMAGE_GENERATION.md — image agent contractreferences/shared/STYLING.md — three styling categories, ownership, decision rulesreferences/shared/IMPLEMENTER.md — shared implementer behavior