wix-cli-orchestrator

Wix CLI Orchestrator Helps select the appropriate Wix CLI extension type based on use case and requirements. ⚠️ MANDATORY WORKFLOW CHECKLIST ⚠️ Before reporting completion to the user, ALL boxes MUST be checked: Step 1: Determined extension type(s) needed Asked clarifying questions if requirements were unclear Checked for implicit Data Collection need — unless user provided a collection ID directly (see Data Collection Inference ) Obtained app namespace if Data Collection extension is being created Determined full scoped collection IDs if Data Collection extension is being created (see Collection ID Coordination ) Explained recommendation with reasoning Step 2: Checked references, spawned discovery if needed Checked relevant reference files for required APIs Spawned discovery only if API not found in references Skip if all APIs are in reference files or no external APIs needed Step 3: Waited for discovery sub-agent to complete (if spawned) Received SDK methods with imports Step 4: Spawned implementation sub-agent(s) with skill context Included user requirements in prompt Included SDK context from discovery (if any) Instructed sub-agent to invoke wds-docs skill FIRST when using @wix/design-system (for correct imports, especially icons) Step 5: Waited for implementation sub-agent(s) to complete All files created Extension registered in extensions.ts Step 6: Invoked wix-cli-app-validation skill Step 7: Validation passed Dependencies installed TypeScript compiled Build succeeded Preview deployed Step 8: Collected and presented ALL manual action items to user Reviewed output from every sub-agent for manual steps Aggregated into a single actionable list at the end of the conversation 🛑 STOP: If any box is unchecked, do NOT proceed to the next step. Your Role You are a decision-maker and orchestrator , not an implementer. Decide → Check References → Discovery (if needed) → Implementation Sub-Agent(s) → Validation → Surface Manual Actions. Ask clarifying questions if unclear; recommend extension type; check reference files first, spawn discovery only for missing SDK methods; spawn implementation sub-agents; run validation; aggregate and present all manual action items at the end. ❌ ANTI-PATTERNS (DO NOT DO) ❌ WRONG ✅ CORRECT Writing implementation code yourself Spawning a sub-agent to implement Invoking implementation skills directly Spawning sub-agent with skill context Discovering extension SDK (dashboard, etc.) Extension SDK is in skill reference files Spawning discovery without checking refs Check skill refs first Reporting done without validation Always run wix-cli-app-validation at the end Reading/writing files after invoking skills Let sub-agents handle ALL file operations Letting manual action items get buried Aggregate all manual steps at the very end CRITICAL: After this planner skill loads, you should ONLY: Spawn sub-agents (for discovery and implementation) Invoke wix-cli-app-validation skill at the end You should NEVER: Read, Write, Edit files for implementation yourself Quick Decision Helper Answer these questions to find the right extension: What are you trying to build? Admin interface → Dashboard Extensions Backend logic → Backend Extensions Data storage / CMS collections → Data Collection Site component → Site Extensions (app projects only) Who will see it? Admin users only → Dashboard Extensions Site visitors → Site Extensions Server-side only → Backend Extensions Where will it appear? Dashboard sidebar/page → Dashboard Page or Modal Existing Wix app dashboard → Dashboard Plugin Anywhere on site → Site Widget Wix business solution page → Site Plugin During business flow → Service Plugin After event occurs → Event Extension Decision Flow (Not sure?) Admin: Need full-page UI? → Dashboard Page. Need popup/form? → Dashboard Modal. Extending Wix app dashboard? → Dashboard Plugin. Modal constraint: Dashboard Pages cannot use ; use a separate Dashboard Modal extension and dashboard.openModal() . Backend: During business flow (checkout/shipping/tax)? → Service Plugin. After event (webhooks/sync)? → Event Extension. Custom HTTP endpoints? → Backend Endpoints. Need CMS collections for app data? → Data Collection. Site: User places anywhere? → Site Widget. Fixed slot on Wix app page? → Site Plugin. Scripts/analytics only? → Embedded Script. Data Collection Inference CRITICAL: Data collections are often needed implicitly — don't wait for the user to explicitly say "create a CMS collection." Infer the need automatically. Skip this section if the user provides a collection ID directly (e.g., an existing site-level collection). In that case, use the provided ID as-is — no Data Collection extension or namespace scoping needed. Always include a Data Collection extension when ANY of these are true: Indicator Example User mentions saving/storing/persisting app-specific data "save the fee amount", "store product recommendations" A dashboard page will manage (CRUD) domain entities "dashboard to manage fees", "admin page to edit rules" A service plugin reads app-configured data at runtime "fetch fee rules at checkout", "look up shipping rates" User mentions "dedicated database/collection" "save in a dedicated database collection" Multiple extensions reference the same custom data Dashboard manages fees + service plugin reads fees Why this matters: Without the Data Collection extension, the collection won't be created when the app is installed, the Wix Data APIs may not work (code editor not enabled), and collection IDs won't be properly scoped to the app namespace. If data collection is inferred, follow the App Namespace Requirement to obtain the namespace before proceeding. Quick Reference Table Extension Type Category Visibility Use When Skill Dashboard Page Dashboard Admin only Full admin pages wix-cli-dashboard-page Dashboard Modal Dashboard Admin only Popup dialogs wix-cli-dashboard-modal Dashboard Plugin Dashboard Admin only Extend Wix app dashboards wix-cli-dashboard-plugin Dashboard Menu Plugin Dashboard Admin only Add menu items (none yet) Service Plugin Backend Server-side Customize business flows wix-cli-service-plugin Event Extension Backend Server-side React to events wix-cli-backend-event Backend Endpoints Backend API Custom HTTP handlers wix-cli-backend-api Data Collection Backend Data CMS collections for app data wix-cli-data-collection Site Widget Site Public Standalone widgets wix-cli-site-widget Site Plugin Site Public Extend Wix business solutions wix-cli-site-plugin Embedded Script Site Public Inject scripts/analytics wix-cli-embedded-script Key constraint: Dashboard Page cannot use ; use a separate Dashboard Modal and dashboard.openModal() . Extension Comparison Site Widget vs Site Plugin Dashboard Page vs Modal Service Plugin vs Event Widget: user places anywhere. Plugin: fixed slot in Wix app. Page: full page. Modal: overlay; use for popups. Service: during flow. Event: after event. Decision & Handoff Workflow Follow the checklist; steps below add detail. Step 1: Ask Clarifying Questions (if needed) Only ask for configuration values when absolutely necessary for the implementation to proceed — i.e., the sub-agent literally cannot generate working code without it. If a value can be configured later or added as a manual step, don't block on it. App Namespace Requirement: When creating a Data Collection, you MUST ask the user for their app namespace from Wix Dev Center. This is a required parameter that must be obtained from the user's Dev Center dashboard and cannot be recommended or guessed. Instructions to give the user: If you don't have an app namespace yet: Go to Wix Dev Center Select your app In the left menu, select Develop > Extensions Click + Create Extension and find the Data Collections extension Click + Create You will be prompted to create an app namespace - follow the prompts to set it up If you already have an app namespace: Go to Wix Dev Center Open your app dashboard Click the three dots (...) menu button in the top-right corner (next to "Test App" button) Select "View ID & keys" from the dropdown menu In the modal that opens, scroll to the bottom to find the "Namespace" field Copy the Namespace value If unclear on approach (placement, visibility, configuration, integration), ask clarifying questions. If the answer could change the extension type, wait for the response before proceeding. Otherwise, proceed with the best-fit extension type. Wix Stores Versioning Requirement Applies when ANY Wix Stores API is used (products, inventory, orders, etc.): Include the wix-stores-versioning skill in implementation sub-agent prompts All Stores operations must check catalog version first using getCatalogVersion() Use the correct module based on version: productsV3 (V3) vs products (V1) This is non-negotiable — V1 and V3 are NOT backwards compatible. Collection ID Coordination Applies ONLY when a Data Collection extension is being created. If the user provides a collection ID directly, use it as-is — no namespace scoping, no Data Collection extension needed. When a Data Collection is created alongside other extensions that reference the same collections: Get the app namespace (see App Namespace Requirement above) Determine the idSuffix for each collection (the wix-cli-data-collection skill documents the full ID format) Pass the full scoped collection ID ( / ) to every other sub-agent (dashboard page, service plugin, etc.) so they use it in all Wix Data API calls Step 2: Make Your Recommendation Use Quick Reference Table and decision content above. State extension type and brief reasoning (placement, functionality, integration). Step 3: Check References, Then Discover (if needed) Workflow: References first, search only for gaps. Identify required APIs from user requirements Check relevant reference files: Backend events → wix-cli-backend-event/references/COMMON-EVENTS.md Wix Data → wix-cli-dashboard-page/references/WIX_DATA.md Dashboard SDK → wix-cli-dashboard-page/references/DASHBOARD_API.md Service Plugin SPIs → wix-cli-service-plugin/references/*.md Verify the specific method/event exists in references ONLY spawn discovery if NOT found in reference files Platform APIs (never discover - in references): Wix Data, Dashboard SDK, Event SDK (common events), Service Plugin SPIs Vertical APIs (discover if needed): Wix Stores ( ⚠️ MUST use wix-stores-versioning skill - V1/V3 catalog check required), Wix Bookings, Wix Members, Wix Pricing Plans, third-party integrations Decision table: User Requirement Check References / Discovery Needed? Reason / Reference File "Display store products" ✅ YES (Spawn discovery) Wix Stores API — include wix-stores-versioning skill "Show booking calendar" ✅ YES (Spawn discovery) Wix Bookings API not in reference files "Send emails to users" ✅ YES (Spawn discovery) Wix Triggered Emails not in reference files "Get member info" ✅ YES (Spawn discovery) Wix Members API not in reference files "Listen for cart events" Check COMMON-EVENTS.md Spawn discovery only if event missing in reference "Store data in collection" WIX_DATA.md ✅ Found ❌ Skip discovery (covered by WIX_DATA.md ) "Create CMS collections for my app" Reference: wix-cli-data-collection ❌ Skip discovery (covered by dedicated skill) "Show dashboard toast" DASHBOARD_API.md ✅ Found ❌ Skip discovery "Show toast / navigate" DASHBOARD_API.md ✅ Found ❌ Skip discovery "UI only (forms, inputs)" N/A (no external API) ❌ Skip discovery "Settings page with form inputs" N/A (UI only, no external API) ❌ Skip discovery "Dashboard page with local state" N/A (no external API) ❌ Skip discovery MCP Tools the sub-agent should use: SearchWixSDKDocumentation - SDK methods and APIs ( Always use maxResults: 5 ) ReadFullDocsArticle - Full documentation when needed (only if search results need more detail) Discovery sub-agent prompt template: Discover SDK methods for [SPECIFIC API/EVENT NOT IN REFERENCE FILES]. Search MCP documentation (use maxResults: 5): - Search SDK documentation for [SPECIFIC API] with maxResults: 5 - Only use ReadFullDocsArticle if search results need more context Return ONLY a concise summary in this format:

SDK Methods & Interfaces