@wix/agent-skills 1.0.0

package/skills/wix-headless/references/DISCOVERY.md

@@ -0,0 +1,332 @@
+# Discovery
+
+Infer as much as possible from the user's opening message; ask only what's genuinely unknown. Target: **~1:30 of discovery** including user think-time.
+
+## Step 0 — Infer Vertical(s) and Business Context
+
+The user's opening message typically names what they want: *"build me a skincare store"*, *"I want to sell handmade jewelry"*, *"create a coffee shop website"*.
+
+From the opening message, extract:
+- **Vertical(s)** — which packs to load. See the routing table in `SKILL.md` § "When This Skill Triggers".
+- **Business / product context** — feeds into brand-name suggestions, vibe options, product templates, image prompts.
+
+If the opening message is too vague to infer a vertical (e.g., *"build me a site"*, *"I want to go online"*), ask **one conversational clarifier** (NOT an `AskUserQuestion`): *"What do you want your site to do — sell things, publish content, take bookings?"* One sentence. Only ask if you genuinely cannot infer.
+
+**Do not ask the user what features they want.** Features are determined by the inferred vertical(s). The user reviews and adjusts the plan at Step 3.
+
+---
+
+## Step 1 — Brand Name
+
+Use `AskUserQuestion` with a single-select question.
+
+Generate **3–4 brand name suggestions** relevant to the business context, plus a "Type my own" option:
+
+> *"What should we call your brand?"*
+
+Options: [3–4 generated names], Type my own.
+
+Guidelines for generated names:
+- Short (1–3 words), memorable, relevant to the business context
+- Mix styles: one punchy/modern, one descriptive, one abstract/evocative
+- Avoid generic filler (*"Pro Store"*, *"Best Shop"*)
+
+If the user picks *"Type my own"*, follow up conversationally: *"Sure — what should I call it?"*
+
+If the user already named the brand in the opening message, skip this step.
+
+### Background actions on Q1 answer
+
+Immediately after the brand name is confirmed (before Q2), emit **one concurrent batch** containing both the scaffold dispatch AND prefetch reads of the shared contract docs. These reads cost nothing during Q2 + plan review wait time but save ~1 min of post-approval latency that prior runs spent reading these docs serially.
+
+1. **Scaffold dispatch.** Derive the project slug from the brand, validate it, then run `bash <SKILL_ROOT>/scripts/scaffold.sh <slug> "<Brand>"` as a background shell. The script handles the npm-create invocation + slug pre-flight (regex `^[a-z0-9]{3,20}$`); the orchestrator handles slug derivation from the human-readable brand.
+
+   **Slug derivation (apply to brand before invoking the script):**
+   1. Lowercase
+   2. Strip every char that isn't `[a-z0-9]` (drop hyphens, spaces, punctuation, accents — the Wix CLI rejects them)
+   3. Truncate to 20 chars
+   4. If the result is shorter than 3 chars, ask the user explicitly for a slug (`AskUserQuestion`)
+
+   Examples: `"Acme-Co" → "acmeco"`; `"Sole Society" → "solesociety"`; `"E&E Co." → "eeco"`; `"AB" → ask the user`.
+
+   The Wix CLI requires `[a-z0-9]{3,20}` — hyphens, underscores, uppercase, and other punctuation are rejected.
+
+   **Pre-flight validation (orchestrator-side, before invoking the script).** Both must pass; if either fails, regenerate the slug or re-prompt the user — do NOT rely solely on the script's pre-flight (it'll exit non-zero, but that costs a round-trip):
+   - `slug` matches `^[a-z0-9]{3,20}$`
+   - `brand` is non-empty after trimming whitespace
+
+   **The scaffold call (background shell, with timing capture):**
+
+   ```bash
+   STARTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+   bash "<SKILL_ROOT>/scripts/scaffold.sh" "<slug>" "<brand>"
+   ENDED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+   ```
+
+   - Substitute `<brand>` with the user's confirmed brand (preserve original case; quotes are passed by the shell). Substitute `<slug>` with the validated slug.
+   - The script pins `--site-template-id` to the pure-headless blank template (`212b41cb-0da6-4401-9c72-7c579e6477a2`). Vibe-compatible templates trigger an interactive prompt that blocks non-TTY runs — the template ID is intentionally hardcoded inside the script.
+   - Append timing to `.wix/run.json.phases[]` as `{ phase: "scaffold", seconds: <duration>, started: $STARTED_AT, ended: $ENDED_AT }`.
+
+   **Strict-then-recover:**
+   1. Script exit 2 (slug or brand validation failed) → orchestrator-side bug; the orchestrator should have caught this in pre-flight. Fix the slug derivation and retry.
+   2. Auth error from npm/Wix CLI → surface `"Run \`npx @wix/cli login\` and retry."` and stop.
+   3. `invalid template` error → the template ID inside `scaffold.sh` is stale. Look up the current ID via `<prefix>SearchWixCLIDocumentation` query `create headless template`, edit the script's `TEMPLATE_ID` constant, retry once, log to `.wix/run.json.commandDrift[]` so the script can be tightened.
+   4. Other errors → surface stderr to the user.
+
+   Launch with background.
+
+2. **Prefetch shared contracts** — siblings in the same concurrent batch (resolve `<SKILL_ROOT>` per SKILL.md § "Path resolution"):
+   - `Read <SKILL_ROOT>/references/shared/RETURN_CONTRACT.md`
+   - `Read <SKILL_ROOT>/references/shared/IMAGE_GENERATION.md`
+   - `Read <SKILL_ROOT>/references/shared/MCP_PREFIX.md`
+
+3. **Prefetch loaded pack files** — siblings in the same message:
+   - `Read <SKILL_ROOT>/references/verticals/<pack>.md` for each loaded pack
+
+Then continue to Q2. The scaffold runs during Q2 + plan review (~30–60s, usually finishes before approval); the reads resolve near-instantly and pre-load the docs the orchestrator needs at Step 3 and Step 7, eliminating mid-flow read churn.
+
+**Do NOT also prefetch these docs after plan approval.** Reading them between plan approval and Step 3 adds ~1 min of user-visible wait with zero overlap to useful work.
+
+---
+
+## Step 2 — Vibe
+
+Use `AskUserQuestion` with a single-select question. Generate **4 brand personality options** tailored to the inferred business context, plus "Something else":
+
+> *"What's the vibe for [brand name]?"*
+
+Example options for a jewelry store:
+- **Bold & premium** — luxury feel, dark tones, sharp typography
+- **Clean & modern** — minimal, lots of whitespace, crisp lines
+- **Warm & approachable** — friendly, inviting, earthy tones
+- **Something else** — let me describe it
+
+If the user picks "Something else", follow up with `AskUserQuestion` using a text input.
+
+### Craft the aesthetic direction (in session scratch)
+
+Based on vertical + brand personality + audience, craft a **2–3 sentence aesthetic direction** like a designer would. Decide — don't ask more questions.
+
+Example:
+> *"For Bloom & Root, I'm going with an organic editorial aesthetic — think Kinfolk magazine meets a botanical garden. Warm cream backgrounds, deep forest green accents, Playfair Display for headings paired with Source Sans 3 for body text. Subtle leaf-pattern overlays and generous whitespace to let the products breathe."*
+
+> **Do NOT print this aesthetic direction as a standalone message.** Hold it in session scratch and weave it into the plan (Step 3) as the opening **Design Direction** section. Printing it above the plan detaches the most emotionally important content from the rest. Keep Q2 → plan presentation tight.
+
+---
+
+## Step 3 — Present the Plan
+
+Present the plan as formatted markdown. After presenting, use `AskUserQuestion` for approval.
+
+> **Do NOT show implementation details.** Users do not want to read about scaffolding, `npm install`, `env pull`, MCP calls, phase agents, designer handoffs, sidecars, or build/preview steps. They care about their site. The TaskList conveys progress; the plan conveys outcome. Never open with SDK packages or CMS collection fields.
+
+The plan is composed from the loaded vertical packs. Each pack contributes: apps, packages, pages, CMS collections, features blurbs. The skill assembles; the packs supply.
+
+### Plan structure (in order)
+
+The plan has TWO halves: a short **decision card** (Sections A + B — what the user actually weighs in on) and a longer **technical scope** block (Sections C + D + E — what comes "for free" from the loaded packs). The user reads A and B carefully; C–E are reference material they skim or skip.
+
+> **Sections C, D, E are markdown tables.** Each section below leads with the exact header skeleton — copy it verbatim. Do NOT type column headers from memory: that's the root cause of every plan-format regression.
+
+**Section A: Design Direction** — Lead with this. Open with the aesthetic paragraph crafted in Step 2, then a compact detail block:
+- Aesthetic tone (e.g., "organic editorial")
+- Color palette (2–3 dominant colors with hex codes)
+- Typography pairing (display + body)
+- Mood and key visual elements
+- Page color strategy: Uniform Light / Uniform Dark / Defined Hybrid
+
+**Section B: Features** — 1–2 line descriptions of user-facing functionality from each pack. Bullet list is correct here. Explain what the user's visitors will be able to do. Tag CMS-powered features with **(CMS-based)** so the user knows which content they can edit from the dashboard.
+
+**Skip features from packs with `disabled: true`** (today: only `gift-cards`). Its surfaces are inactive by default — they light up only when the user enables the matching Wix app from the dashboard. The plan must not promise a feature that isn't active out of the box. The code still ships (the `/gift-cards` page file is created plus the nav/home contributions) so activation is instant once the user opts in — but the plan stays silent until then. Packs without `disabled: true` (including transitive ones like ecom) contribute their features normally.
+
+→ **Verify B:** No bullet derives from a `disabled: true` pack. Today: no "Gift cards" bullet, no "(when enabled)" / "(auto)" markers anywhere in B.
+
+> **Visual separator before the technical scope.** After Section B, emit a `---` rule and a single line: *"Technical scope below — auto-decided from the features above. Skim if you want; not required reading."* This signals to the user that the decision is essentially made and the rest is reference material. Without the cue, users feel obligated to read every table cell before approving and stall the build for tens of minutes.
+
+---
+
+**Section C: Pages.** Emit exactly this header, then one row per loaded pack's `routes:` entry:
+
+```
+| Page | Route | Source |
+|------|-------|--------|
+```
+
+> **STOP if you typed anything else.** `| Route | Purpose |` (drops Source), `| Page | Route |` (no Source), bullet list `- **Cart** (/cart)`, or Source merged into Route (`/cart (Stores)`) — each is a known regression. **Three columns, exact names, in that order.** Re-read the skeleton above before typing rows; do not type column headers from memory.
+
+**Compose rows from each loaded pack's `routes:` array.** Do not hardcode rows; do not omit declared rows; do not invent rows. For every loaded pack (top-level OR transitive via `requires:`), iterate its `routes:` array.
+
+**Skip rule.** Skip every route from any pack with `disabled: true`. Today that's only `gift-cards` — its `/gift-cards` row does NOT appear in the plan. The page file still ships so the runtime probe lights up the surface the moment the user enables the Wix Gift Card app from the dashboard, but the plan must not promise a surface the user did not ask for. Surfacing it with a `Source: "Wix Stores (auto)"` marker has been tried and rejected — users push back ("Giftcard shouldn't appear unless the user asked for it").
+
+Each surviving entry → one table row:
+
+```
+Page name (Page cell):
+  - Use the entry's `name:` field if present (override).
+  - Else derive from the route path:
+      "/"               → "Home"
+      "/<seg>/[slug]"   → title-case(seg, singular) + " Detail"
+      otherwise         → title-case the last static segment, replacing
+                          "-" with space  ("/thank-you" → "Thank You")
+
+Route cell:
+  - The entry's `route:` value verbatim (e.g. "/cart" — or the literal
+    string "Hosted by Wix" for Wix-hosted endpoints with no path).
+
+Source cell:
+  - For top-level packs with non-empty `apps:`, use apps[0].name
+    (e.g. "Wix Stores", "Wix Blog").
+  - For transitive packs (loaded via another pack's `requires:`),
+    walk up the requires chain to the top-level puller and use ITS
+    apps[0].name. So ecom's "/cart" shows Source: "Wix Stores"
+    (because stores requires ecom and the user opted into "selling
+    things", not into "an ecommerce SDK").
+  - For the `cms` pack, use the literal "CMS (builtin)".
+  - No suffixes (no "(auto)", no "(passive)", etc.) — disabled packs
+    don't contribute rows at all.
+```
+
+**Order rows by user-facing flow:** CMS pages first (Home, About, FAQ), then catalog/content pages, then transactional pages (cart, thank-you, checkout). Within a pack, preserve declaration order from the pack's `routes:` array.
+
+→ **Verify C:** Header is exactly `| Page | Route | Source |`. Row count = sum of `routes:` entries across all loaded packs that are NOT `disabled: true`. Every Route is either a `/`-prefixed path matching the slugified Page name OR the literal `Hosted by Wix`. No "(auto)"/"(passive)" suffixes anywhere. No "Gift Cards" row when gift-cards loads transitively.
+
+---
+
+**Section D: CMS Collections.** Emit exactly this header, then one row per `cmsCollections:` entry from each loaded pack:
+
+```
+| Collection | Key Fields |
+|------------|------------|
+```
+
+> **STOP if you typed `Fields` instead of `Key Fields`.** Re-read the skeleton above.
+
+Iterate `cmsCollections:` from each loaded pack and emit one row per collection (collections from the `cms` pack always appear; other packs may declare their own).
+
+→ **Verify D:** Header is exactly `| Collection | Key Fields |`.
+
+---
+
+**Section E: Apps & SDK Packages.** Last. Reference table for developer-minded users. Emit exactly this header, then **one row per loaded pack** (NOT one row per package):
+
+```
+| App | SDK Packages |
+|-----|--------------|
+```
+
+> **STOP if you wrote one row per package.** `| Item | Type |` with `@wix/stores | SDK`, `@wix/ecom | SDK`, … is the wrong shape. Two columns, comma-joined packages in cell two, **one row per App**, not per SDK. Re-read the skeleton above.
+
+**Compose Section E from loaded pack frontmatter:**
+
+```
+A pack contributes a Section E row iff:
+  - Its `apps:` array is non-empty (top-level user-facing app), OR
+  - Its `include: true` (the cms pack — built-in, no app to install).
+
+The "App" cell:
+  - For packs with non-empty `apps:`: apps[0].name (e.g. "Wix Stores").
+  - For the cms pack: the literal "CMS (builtin)".
+
+The "SDK Packages" cell:
+  - This pack's `packages:` ∪ packages from every pack in its transitive
+    `requires:` chain — deduped, in declared order.
+  - So when stores is loaded (and pulls in ecom + gift-cards via requires),
+    the "Wix Stores" row's SDK Packages cell is the union of stores +
+    ecom + gift-cards packages — typically: @wix/stores, @wix/ecom,
+    @wix/redirects, @wix/site, @wix/essentials.
+
+Packs with `apps: []` AND `include: false` (ecom, gift-cards) do
+NOT get their own row. Their packages roll up under whichever loaded
+top-level pack pulled them in. There is no "@wix/gift-cards" SDK on
+npm; the gift-cards pack is runtime-detected via REST and contributes
+zero npm packages of its own.
+```
+
+→ **Verify E:** Header is exactly `| App | SDK Packages |`. One row per loaded pack with non-empty `apps:` OR `include: true`. SDK Packages cell is comma-joined within a single cell, NOT split across rows. No "Wix Gift Cards" row when gift-cards loads transitively (no `@wix/gift-cards` SDK exists).
+
+### Example (skincare ecommerce brand)
+
+```markdown
+Here's my plan for **Bloom & Root**:
+
+## Design Direction
+
+For Bloom & Root, I'm going with **clean luxury with organic warmth** —
+think a curated boutique where every product feels considered. Warm cream
+backgrounds paired with deep charcoal text and rose gold accents. Cormorant
+Garamond headlines bring editorial gravity; DM Sans keeps the body text
+tactile and approachable.
+
+- **Colors:** Warm cream (#FFF8F0), deep charcoal (#1A1A1A), rose gold (#B76E79)
+- **Fonts:** Cormorant Garamond (headings) + DM Sans (body)
+- **Mood:** Premium, approachable, tactile
+- **Color strategy:** Uniform Light
+
+## Features
+
+- **Product catalog** — Browse all products with images, prices, and variants.
+- **Cart & checkout** — Add to cart, review, check out via Wix's hosted checkout.
+- **About (CMS-based)** — Brand story, editable from the Wix dashboard.
+- **FAQ (CMS-based)** — Q&A about products, editable from the dashboard.
+
+---
+
+*Technical scope below — auto-decided from the features above. Skim if you want; not required reading.*
+
+## Pages (8)
+
+| Page           | Route             | Source        |
+|----------------|-------------------|---------------|
+| Home           | /                 | CMS (builtin) |
+| About          | /about            | CMS (builtin) |
+| FAQ            | /faq              | CMS (builtin) |
+| Products       | /products         | Wix Stores    |
+| Product Detail | /products/[slug]  | Wix Stores    |
+| Cart           | /cart             | Wix Stores    |
+| Thank You      | /thank-you        | Wix Stores    |
+| Checkout       | Hosted by Wix     | Wix Stores    |
+
+## CMS Collections
+
+| Collection     | Key Fields                  |
+|----------------|-----------------------------|
+| About Content  | heading, body, image        |
+| FAQ            | question, answer, sortOrder |
+
+## Apps & SDK Packages
+
+| App           | SDK Packages                                                       |
+|---------------|--------------------------------------------------------------------|
+| Wix Stores    | @wix/stores, @wix/ecom, @wix/redirects, @wix/site, @wix/essentials |
+| CMS (builtin) | @wix/data, @wix/essentials                                         |
+
+Should I proceed?
+```
+
+The Cart, Thank You, and Checkout rows show `Source: Wix Stores` — not "Wix eCommerce" — because ecom is loaded transitively via stores's `requires:` and the orchestrator walks up the chain. The user opted into "selling things", not into "an ecommerce SDK".
+
+### Final scan (MANDATORY)
+
+Before sending the plan, confirm each inline → Verify above (B, C, D, E) passed. If any failed, regenerate that section and re-scan before emitting. Plans that violate multiple inline checks at once cost a full plan replay (~25 min of user time) when caught post-hoc. The inline → Verify lines exist to catch them before sending.
+
+### Approval
+
+Use `AskUserQuestion`: *"Ready to build?"* Options: **Yes, build it** / **Adjust something**.
+
+If the user wants to adjust, handle it conversationally (swap brand, change vibe, add/remove a page). Re-present the plan and re-ask for approval.
+
+---
+
+## After Approval
+
+Save the project context to memory (type: `project`) so future sessions can resume:
+- Brand name, vertical(s) inferred
+- Apps, packages, pages from the loaded packs
+- Project name + absolute project directory
+- Current phase: `scaffolding`
+
+> **Do NOT narrate the internal sub-steps.** After approval, proceed silently through setup, launch phases, etc. The user tracks progress via TaskList — that's enough. No *"Now I'll install Wix Stores via MCP"*, no *"Launching Phase 1 agents"*, no MCP / sidecar / agent-name / `.wix/` leakage.
+
+Brief transition messages are fine when major milestones complete (e.g., *"Products seeded, designing pages now"* or the final preview URL), but never surface tool-layer mechanics.
+
+Proceed to **Setup** (see `SETUP.md`).

package/skills/wix-headless/references/ORCHESTRATION.md

@@ -0,0 +1,269 @@
+# Orchestration — Concurrency Model
+
+This file describes **what runs in parallel and what blocks**. It does not prescribe a specific tool API — map each step to whatever subagent / parallel-execution primitive your runtime offers.
+
+## Concurrency vocabulary
+
+The terms below appear throughout this skill. They describe the *shape* of work; the runtime decides how to implement them:
+
+- **Subagent** — an isolated worker with its own context. The orchestrator sends it a prompt (an `Instruction file` path + inputs); the subagent reads the instruction file, performs the scope, and returns a structured result.
+- **Concurrent batch** — N subagents (or N tool calls) launched together so they execute in parallel rather than serially. Whether this is concurrent sibling calls, async tasks, threads, or a parallel-fan-out primitive doesn't matter — only that they overlap in execution.
+- **Background subagent** — a subagent the orchestrator does not block on; it runs while the orchestrator continues with downstream work and reports its result asynchronously.
+- **Foreground subagent** — a subagent the orchestrator blocks on before continuing.
+- **Wait (gate)** — the orchestrator pauses until specified background subagents finish.
+- **Result** — the structured JSON block each subagent returns at the end of its run, per `references/shared/RETURN_CONTRACT.md`.
+
+## Phase axis
+
+| Phase | What | Dispatched at |
+|---|---|---|
+| **Phase 1 — Seed** | Per-vertical MCP data → `.wix/site.json.seeded.<vertical>` | Step 3 (concurrent with Phase 2 + Image Phase 1) |
+| **Phase 2 — Design System** | Designer writes tokens + Layout + Nav + Footer | Step 3 (foreground) |
+| **Phase 3 — Components** | Per-vertical React islands, with styling contract inlined into each prompt | Step 4.5 (after Phase 2 completes) |
+| **Phase 4 — Pages** | Per-vertical routes; each page agent writes its routes once with both visual design and live data queries | Step 7 (concurrent with Image Phase 2) |
+| **Image Phase 1 — Decorative** | Hero/about/page-header decoratives | Step 3 (concurrent with Phases 1 + 2) |
+| **Image Phase 2 — Entity** | Product / blog post / CMS item images | Step 4.5 (concurrent with Phase 3 Components) — depends only on Phase 1 Seed entity IDs + brand context |
+
+## Why batching matters
+
+Historical runs lost 1–2 minutes per phase to serialized dispatch — N subagents emitted one-per-turn instead of in a single concurrent batch. Even when each subagent ran fast, the inter-dispatch gaps (12–39s in measured runs) accumulated to >25% overhead per phase.
+
+Two mitigations exist; use both:
+
+1. **State the batch as a single concurrent step.** The skill's dispatch sections below say "launch N subagents concurrently" — that is one orchestration step, not N. Implement it as a single batch.
+2. **Use background-on-dispatch for subagents that don't block downstream work.** Even if the runtime serializes the launch turns, background dispatch lets subagents overlap in execution. Measured compression on a sequential-launch / background-execute model: ~2× wall-time vs. serial.
+
+If your runtime forces serialization across the orchestrator's turns, make every subagent that can run in the background a background subagent. Only the Phase 2 Design System is foreground (because Step 4.5 needs `.wix/design-tokens.css` on disk before continuing).
+
+---
+
+## Step 3 Dispatch — Phase 1 (Seed) + Phase 2 (Design System) + Image Phase 1 (Decorative)
+
+Runs immediately after Step 2 (Setup) completes.
+
+### Concurrent batch
+
+For each loaded vertical pack (stores, cms, blog, …):
+- Phase 1 Seeder — **background**
+
+Always:
+- Image Phase 1 Decorative subagent — **background**. Generates decoratives from brand context only; no Phase 1 Seed dependency. Internally it issues ONE batched generation call for all slots — no per-image sequential calls.
+- Phase 2 Design System subagent — **foreground** (orchestrator waits for this before Step 4 / Step 4.5 / Step 7). Writes `global.css`, `Layout.astro`, `Navigation.astro`, `Footer.astro`, `astro.config.mjs`, `index.astro` shell, and returns `designTokens` JSON. The orchestrator emits `.wix/design-tokens.css` + `.wix/site.d.ts` deterministically from the merged JSON via `<SKILL_ROOT>/scripts/emit-design-tokens.mjs` in Step 4 (the agent does not write either file).
+
+**Phase 3 Components is not dispatched here.** It runs in Step 4.5 with the design tokens inlined into each prompt — see § "Styling contract coordination" below.
+
+**Image Phase 2 (entity images) is not dispatched here.** It runs in Step 4.5 (alongside Phase 3 Components, gated on Phase 1 Seed having returned) with Phase 1 Seed entity IDs inlined — see § "Wait: Phase 2 → Step 4.5" below.
+
+### Example (ecommerce run — stores + cms packs loaded)
+
+Four subagents launched concurrently, each pointed at a vertical instruction file:
+
+1. Phase 1 stores seeder (bg) — instruction file: `<SKILL_ROOT>/references/stores/INSTRUCTIONS.md`, scope: `seed-seed`
+2. Phase 1 CMS seeder (bg) — instruction file: `<SKILL_ROOT>/references/cms/INSTRUCTIONS.md`, scope: `seed-seed`
+3. Image Phase 1 Decorative (bg) — instruction file: `<SKILL_ROOT>/references/images/INSTRUCTIONS.md`, scope: `image-phase-1-decorative`
+4. Phase 2 Design System (fg) — instruction file: `<SKILL_ROOT>/references/designer/INSTRUCTIONS.md`, scope: `design-system`
+
+### Subagent prompt template
+
+Every dispatch sends a self-contained prompt with these fields:
+
+```
+Instruction file (absolute path): <SKILL_ROOT>/references/<vertical>/INSTRUCTIONS.md
+  Read this file in full before doing anything else. It defines your role,
+  scope routing, and return contract.
+Phase instruction: <exact phase/scope string from the pack>
+Scope: <scope string>
+Project directory (absolute path): <project path>
+siteId: <from wix.config.json>
+MCP tool prefix: <prefix>
+  Use this prefix for every Wix MCP call. Example: <prefix>CallWixSiteAPI, <prefix>WixREADME.
+Brand context: name, vibe, aesthetic direction, colors, fonts, mood, page color strategy
+Design tokens: .wix/design-tokens.css (generated from site.json.designTokens)
+```
+
+**`Instruction file` must point to one of these vertical instruction files:**
+- `<SKILL_ROOT>/references/stores/INSTRUCTIONS.md` — Phase 1 Seed + Phase 3 Components + Phase 4 Pages
+- `<SKILL_ROOT>/references/ecom/INSTRUCTIONS.md` — Phase 1 Seed + Phase 3 Components (cart/checkout — passive, required by stores)
+- `<SKILL_ROOT>/references/cms/INSTRUCTIONS.md` — Phase 1 Seed + Phase 4 CMS Pages
+- `<SKILL_ROOT>/references/blog/INSTRUCTIONS.md` — Phase 1 Seed + Phase 3 Components + Phase 4 Pages
+- `<SKILL_ROOT>/references/forms/INSTRUCTIONS.md` — Phase 1 Seed + Phase 3 Components + Phase 4 Pages
+- `<SKILL_ROOT>/references/gift-cards/INSTRUCTIONS.md` — Phase 1 Seed + Phase 3 Components + Phase 4 Pages (passive/dashboard-gated)
+- `<SKILL_ROOT>/references/images/INSTRUCTIONS.md` — `image-phase-1-decorative` + `image-phase-2-entity`
+- `<SKILL_ROOT>/references/designer/INSTRUCTIONS.md` — Phase 2 Design System + all Phase 4 Page designers
+
+For **image subagents**, the prompt additionally includes: page list (for decorative brief), entity types to cover (products, about-content, etc.).
+
+Phase 3 Components subagents (Step 4.5) additionally receive the full styling-contract JSON inlined in their prompt — they do not read `.wix/design-tokens.css` + `.wix/site.d.ts` from disk. See § "Styling contract coordination" below.
+
+### Subagent return
+
+Every subagent returns a structured JSON block at the end of its run, per `references/shared/RETURN_CONTRACT.md`. The orchestrator parses each return as it arrives.
+
+---
+
+## Wait: Phase 2 → Step 4.5 (Phase 3 Components + Image Phase 2) → Step 7 (Phase 4 Pages)
+
+Phase 2 completes (~2–3 min) in the foreground — the orchestrator resumes automatically. Verify `.wix/design-tokens.css` + `.wix/site.d.ts` exist on disk before launching Step 4.5.
+
+### Step 4.5 — Phase 3 Components + Image Phase 2 Entity (one concurrent batch, all background)
+
+Read `.wix/design-tokens.css` + `.wix/site.d.ts` once, then dispatch in a single concurrent batch:
+
+1. **One Phase 3 Components subagent per loaded pack** that declares `components`. Each prompt carries:
+   - All standard fields (see "Subagent prompt template" above)
+   - The **full styling-contract JSON inlined** — not a file path
+
+2. **One Image Phase 2 Entity subagent** (when any pack produced entities — stores products, CMS items, blog posts), provided the relevant Phase 1 Seeder has returned. Prompt carries Phase 1 Seed return data inline + brand context. The image agent reads `<SKILL_ROOT>/references/images/INSTRUCTIONS.md` § "Scope: image-phase-2-entity".
+
+Both groups are **background**. They start immediately and continue running through Step 7 dispatch — no polling.
+
+**Why Image Phase 2 lives here, not in Step 7.** Image Phase 2 only depends on Phase 1 Seed entity IDs/names/descriptions + brand context. It does not read or write anything Phase 3 Components or Phase 4 Pages produce — its PATCH/PUT targets are Wix-side entities (`stores/v3/products`, `wix-data/v2/items`, `blog/v3/posts`). Launching it here lets it overlap entirely with Phase 3 (and often Phase 4 too) instead of becoming a post-Phase-4 tail blocker.
+
+**Gate.** If a Phase 1 Seeder is still running when this batch is dispatched, hold Image Phase 2 back until that seeder returns. Phase 3 Components dispatch does not wait — Phase 3 agents don't need entity data. In practice Phase 1 Seeders (~99–121 s typical) finish well before Phase 2 DS (~500 s typical), so this gate rarely fires.
+
+### Then Phase 4 (Pages)
+
+Phase 4 launches in Step 7. Phase 1 Seeders, Phase 3 Components, and Image Phase 2 are typically still running (or finished) at that point. Step 6 explicitly waits for Phase 1 + Phase 3 before Step 7 dispatches; Image Phase 2 is allowed to continue running through Phase 4 and is gated only at Step 8 / Build.
+
+---
+
+## Wait: Phase 3 + Phase 1 → Step 7 (Phase 4 Pages)
+
+Both must complete before Step 7 dispatches:
+
+1. **Phase 1 Seeders** — return data includes product slugs, CMS item IDs, etc. that Phase 4 subagents need for wiring.
+2. **Phase 3 Components** — writes the React islands that Phase 4 Pages mount.
+
+If one is still running when the other finishes, wait for its return. Do NOT launch Phase 4 prematurely — Phase 4 subagents would fail reading missing islands or missing product slugs.
+
+### Data carry-forward
+
+Parse these from Phase 1 Seed returns into session scratch for Phase 4 subagent prompts:
+- **Stores Phase 1 return** → `products: [{id, name, slug, variantId, price, inventory, sku}]`
+- **CMS Phase 1 return** → `collections: [{name, items: [{id, …}]}]`
+
+Since 2026-04 the orchestrator also merges each Seeder's `data` block into `.wix/site.json.seeded.<vertical>` — Phase 4 prompts reference the `site.json` path rather than re-inlining the raw data, but the shape above is what Phase 4 subagents ultimately read.
+
+---
+
+## Step 7 Dispatch — Phase 4 (Pages)
+
+### Concurrent batch
+
+For each loaded pack's `pages`:
+- One Phase 4 subagent per scope — **background**. Each writes its routes ONCE with both visual design and live data queries (the merged design+wire model — see SKILL.md Step 5 note). Earlier flows split this into a placeholder-writing dispatch followed by a page-rewrite dispatch; that double-write was eliminated.
+
+> **Image Phase 2 is NOT dispatched here.** It was launched earlier in Step 4.5, alongside Phase 3 Components. By the time Step 7 fires, Image Phase 2 has typically been running for ~5–8 minutes and is finished or close to finishing. The Step 8 hard gate still waits for it before invoking `release.sh`.
+
+### Example (ecommerce run — stores pack contributes 4 Phase 4 scopes + cms pack 1)
+
+Five subagents launched concurrently:
+
+1. **product-pages** — `products/index.astro`, `products/[slug].astro`, `ProductCard.astro`
+2. **category-pages** — `category/[slug].astro`, `CategoryRail.astro`, `utils/categories.ts`
+3. **cart-checkout** — `cart.astro`, `thank-you.astro`
+4. **home-and-nav** — patch `index.astro` product grid + `Navigation.astro` (CartBadge mount + Shop submenu insert at `<!-- nav:links -->`)
+5. **cms-pages** — wire About + FAQ to live `@wix/data` queries
+
+`product-pages` and `home-and-nav` import files written by `category-pages` (`CategoryRail.astro`, `utils/categories.ts`) — but the imports resolve at build time (Step 8), not at write time, so the three can dispatch concurrently.
+
+### Phase 4 prompt additions
+
+```
+Scope: <scope name from pack.pages[*].name>
+Files to own (absolute paths): <from pack.pages[*].files>
+Phase 1 Seed data: read from `.wix/site.json.seeded.<vertical>` (path reference — see SKILL.md Step 7)
+Design tokens: .wix/design-tokens.css (read from disk if needed)
+```
+
+Each scope subagent writes its `.astro` files directly with live SDK queries, wires up analytics events, and mounts the React islands written by Phase 3 Components.
+
+Scope subagents MUST NOT:
+- Modify files outside their declared scope
+- Modify CSS (owned by Phase 2 Design System)
+- Modify React islands (owned by Phase 3 Components)
+
+---
+
+## Wait: Phase 4 → Build
+
+> **HARD GATE: Do NOT run `npx @wix/cli build` until `image-phase-2-entity` has completed or timed out (120s).** This gate is non-negotiable even if earlier phases had failures or were written inline. Skipping it after cascading failures has shipped previews with no product images and `run.json` recording `image-phase-2-entity` as `"in_progress"`.
+
+All Step 7 Phase 4 Pages subagents return. Image Phase 2 was dispatched in Step 4.5 (not Step 7), so it has been running through Phase 3 + Phase 4 in parallel — typically ~5–8 minutes by the time Phase 4 Pages finish, which is enough for Image Phase 2 to be done or in its tail. All return JSON is in session context.
+
+If Phase 4 finishes before `image-phase-2-entity`, wait for it before proceeding. Without this wait, the preview shows empty image placeholders on products (images not yet PATCHed). With Image Phase 2 dispatched earlier (in Step 4.5), this wait is usually a no-op.
+
+> **Timeout safety:** if `image-phase-2-entity` has not completed within 120s after all Phase 4 subagents finish, proceed to Build and note `{code: "IMAGE_PHASE_2_TIMEOUT"}` in `run.json`. The timeout is a safety valve — under the Step-4.5-dispatch model it should rarely fire.
+
+Also ensure the background `npm install` (started in Step 2 Setup) has completed. Wait on its handle rather than polling. On non-zero exit, follow the recovery ladder in `SETUP.md` § "npm install recovery".
+
+---
+
+## Subagent rate / credit limits
+
+Some runtimes apply per-session rate or credit limits to subagents. When a subagent return looks truncated, treat it as a rate-limit hit and recover.
+
+### Detection
+
+A subagent has hit a rate / credit limit when its return contains any of:
+- Literal text `"You've hit your limit"`, `"quota exceeded"`, `"rate limit"`
+- Total return under ~100 tokens with no fenced JSON block
+- Return ending mid-sentence without a completion indicator
+
+### Recovery procedure
+
+1. **Check the subagent's declared output files on disk.** Each scope's reference lists the files it owns (e.g., the Phase 4 store-pages scope owns `products/index.astro`, `products/[slug].astro`, `cart.astro`, `thank-you.astro`, `ProductCard.astro`). Read each expected path.
+2. **If all expected files exist on disk and look syntactically valid** (no empty files, no unterminated strings): synthesize a `status: "complete"` entry for `run.json` with `notes: "Sub-agent hit rate limit after writing all files; files on disk are valid."` Proceed with the next dispatch.
+3. **If expected files are missing or empty:** retry the subagent once with an identical prompt. If the retry also hits the limit, mark the phase `status: "partial"` in `run.json` with `errors: [{code: "RATE_LIMIT", message: "Subagent rate-limited; <N> of <M> files produced"}]` and decide per-case — the orchestrator may fall back to inline emission of the missing files if they're trivial (single-file scope), or fail the run.
+4. **Do not loop.** Retrying the same subagent more than once after a rate limit wastes budget — the limit is session-scoped and persists.
+
+Record the rate-limit event in `run.json` `notes[]` regardless of recovery outcome — it's important observability for tuning scope sizes.
+
+## Build & Release
+
+1. `npx @wix/cli build` — if it fails, inspect `.wix/debug.log` for the specific error, fix, retry. Common failure modes are listed in `references/shared/RETURN_CONTRACT.md` § "Common failure modes".
+2. `npx @wix/cli release` — extract the published URL from the `Site published on <url>` line in stdout. This command also populates the **Frontend link** in headless settings natively, so transactional emails link to the deployed frontend without any extra API calls.
+
+---
+
+## Final Message — single concluding turn
+
+Contains (in order):
+
+1. **Release URL** as the very first thing — bold heading or link. The user must see it immediately.
+2. **Write `.wix/run.json`** in the same turn — a single observability record aggregating every subagent return. Format per `references/shared/RETURN_CONTRACT.md` § "Final run.json format".
+
+Why URL-first within one turn: the user perceives the URL instantly, but the turn does not close until the file write completes — so the observability record is guaranteed on disk before the turn ends. Earlier flows composed the final log BEFORE emitting the URL, adding ~70s to the user's wait.
+
+Do NOT re-read anything to compose `run.json`. Use the subagent return data already in session context.
+
+---
+
+## Styling contract coordination
+
+The **design tokens** (`.wix/design-tokens.css` + `.wix/site.d.ts`) are the coordination artifacts between subagents. Read by every downstream phase that touches styled markup.
+
+### Producer: Phase 2 Design System (Step 3, foreground) → orchestrator (Step 4, deterministic)
+
+Phase 2 writes `global.css` and returns `designTokens` JSON. The orchestrator merges the JSON into `.wix/site.json.designTokens` and runs `node <SKILL_ROOT>/scripts/emit-design-tokens.mjs` (Step 4), which deterministically emits `.wix/design-tokens.css` + `.wix/site.d.ts` from the JSON. Both derived files are pure projections — no agent-side template, no LLM. See `<SKILL_ROOT>/scripts/emit-design-tokens.mjs` for the projection rules.
+
+### Consumer: Phase 3 Components (Step 4.5 — launched AFTER Phase 2 completes; no polling)
+
+Phase 3 Components is **not** dispatched in Step 3 alongside Phase 2. The orchestrator waits for Phase 2 to finish (foreground) and then launches Phase 3 in the background in Step 4.5. The contract is passed inline in each Phase 3 prompt.
+
+Why serialized instead of polled: a polling mechanic would only save time if Phase 3 could finish early — but Step 7 (Phase 4) already depends on Phase 2, so Phase 2 is the critical-path gate regardless. Serializing Phase 3 behind Phase 2 adds zero to critical-path `max(Phase 2, Phase 3)` wall time and eliminates one failure mode (a missing-contract timeout).
+
+### Consumers: Phase 4 Pages (Step 7)
+
+Contract already exists when Phase 4 launches. Subagents receive the contract contents inline in their prompt (no polling).
+
+---
+
+## Diagnostic: did the concurrent batch actually run in parallel?
+
+If a build feels slow, check whether dispatches that should have been concurrent actually overlapped in execution. Two failure modes:
+
+1. **Serialized launch:** the orchestrator emitted subagent invocations one at a time across multiple turns instead of as a single batch. Symptom: 12–39s gaps between subagent starts in the run log.
+2. **Serialized execution:** the runtime dispatched the batch but executed it sequentially (rare; most runtimes parallelize properly).
+
+The fix for (1) depends on the runtime — check whether your dispatch primitive supports a single concurrent batch and whether anything between the subagent invocations (status updates, narration, file writes) is splitting the batch into multiple turns. Even when (1) cannot be fixed, **background dispatch alone gives ~2× compression** by overlapping execution. Make every subagent that doesn't block downstream work a background subagent.