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
Using site widget/plugin to consume context provider extensions	Only site components (wix-cli-site-component) can consume context provider extensions

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:

1. 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)

2. Who will see it?

   • Admin users only → Dashboard Extensions
   • Site visitors → Site Extensions
   • Server-side only → Backend Extensions

3. Where will it appear?

   • Dashboard sidebar/page → Dashboard Page or Modal
   • Existing Wix app dashboard (widget) → Dashboard Plugin
   • Existing Wix app dashboard (menu item) → Dashboard Menu Plugin
   • Anywhere on site → Site Widget
   • Anywhere on site (with editor manifest) → Site Component
   • 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 with a visual widget? → Dashboard Plugin. Adding a menu item to a Wix app dashboard's more-actions or bulk-actions menu? → Dashboard Menu Plugin. Modal constraint: Dashboard Pages cannot use <Modal />; 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 (standalone)? → Site Widget. React component with editor manifest (styling, content, elements)? → Site Component. 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 to Wix app dashboards	wix-cli-dashboard-menu-plugin
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 Component	Site	Public	React components with editor manifests	wix-cli-site-component
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 constraints:

• Dashboard Page cannot use <Modal />; use a separate Dashboard Modal and dashboard.openModal().
• Only Site Components can consume context provider extensions — NOT site widgets or site plugins. When building consumers for a context provider extension, always use wix-cli-site-component.

Extension Comparison

Site Widget vs Site Component vs Site Plugin	Dashboard Page vs Modal	Service Plugin vs Event
Widget: standalone interactive component. Component: React with editor manifest (CSS/data/elements). Plugin: fixed slot in Wix app page.	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:

1. Go to Wix Dev Center
2. Select your app
3. In the left menu, select Develop > Extensions
4. Click + Create Extension and find the Data Collections extension
5. Click + Create
6. You will be prompted to create an app namespace - follow the prompts to set it up

If you already have an app namespace:

1. Go to Wix Dev Center
2. Open your app dashboard
3. Click the three dots (...) menu button in the top-right corner (next to "Test App" button)
4. Select "View ID & keys" from the dropdown menu
5. In the modal that opens, scroll to the bottom to find the "Namespace" field
6. 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.):

1. Include the wix-stores-versioning skill in implementation sub-agent prompts
2. All Stores operations must check catalog version first using getCatalogVersion()
3. 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:

1. Get the app namespace (see App Namespace Requirement above)
2. Determine the idSuffix for each collection (the wix-cli-data-collection skill documents the full ID format)
3. Pass the full scoped collection ID (<app-namespace>/<idSuffix>) 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.

1. Identify required APIs from user requirements
2. 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
3. Verify the specific method/event exists in references
4. 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

| Name                      | Type   | TypeScript Type                              | Description       |
| ------------------------- | ------ | -------------------------------------------- | ----------------- |
| `moduleName.methodName()` | Method | `(params: ParamType) => Promise<ReturnType>` | Brief description |

**Import:** `import { methodName } from '@wix/sdk-module';`

Include any gotchas or constraints discovered.

## Manual Action Items
List any manual steps the user must perform (e.g., configure dashboard settings, enable permissions). Write "None" if there are no manual steps.

**Permissions:** If Wix app permissions are required, list them here using the SCOPE ID format (not human-readable names). Examples:
- `@wix/data` read operations (query, get) require "SCOPE.DC-DATA.READ"
- `@wix/data` write operations (insert, update, remove) require "SCOPE.DC-DATA.WRITE"
- Embedded scripts require "SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS"
- Check the Wix SDK documentation "Method Permissions Scopes IDs" section for the exact scope ID.
- IMPORTANT: Use scope IDs like "SCOPE.DC-DATA.READ", NOT human-readable names like "Read Data Items".

If discovery is spawned, wait for it to complete before proceeding to Step 4.

Step 4: Spawn Implementation Sub-Agent(s)

⚠️ BLOCKING REQUIREMENT ⚠️

You MUST spawn sub-agent(s) for implementation. Do NOT invoke implementation skills directly. Do NOT write code yourself.

Spawn an implementation sub-agent with the skill context:

The sub-agent prompt should include:

1. The skill to load (e.g., wix-cli-dashboard-page)
2. The user's requirements
3. The SDK context from the discovery sub-agent
4. Instruction to invoke the wds-docs skill only when needed (e.g. when looking up WDS component props or examples)

Implementation sub-agent prompt MUST include:

1. ✅ The skill to load (full path or name)
2. ✅ The user's original requirements (copy verbatim)
3. ✅ SDK methods discovered (with imports and types) — only if discovery was performed
4. ✅ Instruction to invoke wds-docs skill FIRST when using @wix/design-system (critical for correct imports, especially icons)
5. ✅ Any constraints or gotchas discovered
6. ✅ Collection Context with full scoped collection IDs — only if Data Collection is being created
7. ✅ Instruction to return manual action items (see below)

Implementation sub-agent prompt template:

Load and follow the skill: wix-cli-[skill-name]

User Requirements:
[EXACT user request - copy verbatim]

[ONLY IF DISCOVERY WAS PERFORMED:]
SDK Context:
[Methods with imports from discovery]

Constraints:
[Any gotchas or limitations from discovery]

⚠️ MANDATORY when using WDS: Invoke the wds-docs skill FIRST to get correct imports (icons are from @wix/wix-ui-icons-common, NOT @wix/design-system/icons).

⚠️ MANDATORY when using Data Collections: Use EXACT collection ID from `idSuffix` (case-sensitive). Example: If `idSuffix` is "product-recommendations", use "<app-namespace>/product-recommendations" NOT "productRecommendations".

⚠️ MANDATORY: At the END of your response, include a section titled "## Manual Action Items" listing ANY steps the user must perform manually (e.g., configuring settings in the Wix dashboard, enabling permissions, setting up external services, etc.). If there are no manual steps, write "None". This section MUST always be present in your final response.

Implement this extension following the skill guidelines.

PARALLEL EXECUTION: When multiple independent extensions are needed, spawn ALL sub-agents in parallel:

Extension Combination	Parallel?	Reason
Dashboard Page + Site Widget	✅ YES	Independent UI contexts
Dashboard Page + Dashboard Modal	✅ YES	Modal code is independent from page
Dashboard Page + Backend API	✅ YES	Frontend vs backend
Site Widget + Embedded Script	✅ YES	Different rendering contexts
Service Plugin + Event Extension	✅ YES	Independent backend handlers
Data Collection + Dashboard Page	✅ YES	Data schema vs UI
Data Collection + Backend API	✅ YES	Data schema vs HTTP handlers
Data Collection + Site Widget	✅ YES	Data schema vs site UI
Context Provider Extension + Site Component	✅ YES	Provider vs consumer

Pre-spawn coordination required (then parallel is fine):

• When a Data Collection + other extensions reference the same collections: determine the full scoped collection IDs (<app-namespace>/<idSuffix>) BEFORE spawning sub-agents, then pass the IDs to all sub-agents and run them in parallel

Sequential execution required:

• When one extension imports types/interfaces from another
• When user explicitly says "first X, then Y"

Extension Type to Skill Mapping: See Quick Reference Table above.

Wait for sub-agents to complete before proceeding to Step 5.

Step 5: Run Validation

⚠️ BLOCKING REQUIREMENT ⚠️

After ALL implementation sub-agents complete, you MUST run validation by invoking the wix-cli-app-validation skill.

Do NOT report completion to the user until validation passes.

If validation fails:

1. Review the errors
2. Spawn a new implementation sub-agent to fix the issues
3. Run validation again
4. Repeat until validation passes

Step 6: Report Completion

Only after validation passes, provide a concise summary section at the top of your response that includes:

Required format:

## ✅ Implementation Complete

[1-2 sentence description of what was built]

**Extensions Created:**
- [Extension 1 Name] - [Brief purpose]
- [Extension 2 Name] - [Brief purpose]
- [Extension 3 Name] - [Brief purpose]

**Build Status:**
- ✅ Dependencies: [Installed / status message]
- ✅ TypeScript: [No compilation errors / status]
- ✅ Build: [Completed successfully / status]
- ✅/⚠️ Preview: [Running at URL / Failed - reason]

**⚠️ IMPORTANT: [X] manual step(s) required to complete setup** (see "Manual Steps Required" section below)

Critical rules:

• The summary MUST explicitly state how many manual steps are required
• The summary MUST reference where to find the manual steps ("see Manual Steps Required section below")
• If there are NO manual steps, state: "✅ No manual steps required — you're ready to go!"
• Keep the summary concise (under 200 words)
• Present build status clearly with ✅ or ⚠️ indicators

Step 7: Surface Manual Action Items

⚠️ BLOCKING REQUIREMENT ⚠️

Sub-agents often report manual steps the user must take (e.g., configure permissions in the Wix dashboard, enable specific features, etc.). These MUST NOT get lost.

After ALL sub-agents complete, you MUST:

1. Review every sub-agent's output for any "Manual Action Items" section or any mention of steps the user needs to perform manually
2. Aggregate ALL manual action items from every sub-agent into a single, deduplicated list
3. Reference them in the summary section (Step 6) by stating how many manual steps exist
4. Present them prominently at the very end of your final message to the user, under a clear heading

Complete workflow for manual steps:

1. In the summary (Step 6): Include the line **⚠️ IMPORTANT: [X] manual step(s) required to complete setup** (see "Manual Steps Required" section below)
2. At the end of your response: Present the full detailed manual steps section

Format for the manual steps section:

## 🔧 Manual Steps Required

The following actions need to be done manually by you:

### 1. [Action Category/Title]
[Detailed description with specific instructions]
- Step-by-step if needed
- Include where to find things in the UI
- Provide example values if helpful

### 2. [Action Category/Title]
[Detailed description]

### 3. [Action Category/Title]
[Detailed description]

[Continue for all manual steps...]

If no manual steps are needed:

## 🔧 Manual Steps Required

No manual steps required — you're all set! Your implementation is complete and ready to use.

Rules:

• The summary section (Step 6) MUST reference the manual steps
• This detailed manual steps section MUST be the last thing in your final response to the user
• Even if you think the items were mentioned earlier in the conversation, repeat them here — assume the user only reads the final summary
• Include full context for each item (e.g., "In the Wix dashboard, go to Settings > Permissions and enable X" rather than just "enable X")
• Group related steps together under category headings for clarity
• If a sub-agent didn't include a "Manual Action Items" section, review its full output for any implicit manual steps (phrases like "you'll need to", "make sure to", "don't forget to", "manually", "go to the dashboard", etc.)
• Number the main categories/sections (1, 2, 3...) for easy reference

Summary: Discovery = business domain SDK only (Stores, Bookings, etc.) — skip for extension SDK and data collections. Implementation = load extension skill; invoke wds-docs FIRST when using WDS (for correct imports). Validation = wix-cli-app-validation. Manual actions = always aggregated and surfaced at the end.

Cost Optimization

• Check references first — read relevant reference files before spawning discovery
• Skip discovery when all required APIs are in reference files
• maxResults: 5 for all MCP SDK searches
• ReadFullDocsArticle only when search results need more context
• Implementation prompts: include only relevant SDK context from discovery (if performed)
• Parallelize independent sub-agents when possible
• Invoke wds-docs first when using WDS (prevents import errors)
• Targets: discovery output 500-1000 tokens; implementation prompt minimal; each search under 2000-3000 tokens

Documentation

For detailed documentation on all extension types, see references/DOCUMENTATION.md.