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
  • • 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

🛑 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. Ask clarifying questions if unclear; recommend extension type; check reference files first, spawn discovery only for missing APIs; spawn implementation sub-agents; run validation.

❌ ANTI-PATTERNS (DO NOT DO)

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 → 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 <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? → Site Widget. Fixed slot on Wix app page? → Site Plugin. Scripts/analytics only? → Embedded Script.

Quick Reference Table

Key constraint: Dashboard Page cannot use <Modal />; use a separate Dashboard Modal and dashboard.openModal(). Site plugins (CLI) not supported on checkout; use Wix Blocks.

Extension Comparison

Decision & Handoff Workflow

Follow the checklist; steps below add detail.

Step 1: Ask Clarifying Questions (if needed)

If unclear: placement, visibility, configuration, integration. Wait if the answer changes extension type; otherwise proceed and say you can add optional extension later.

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, Wix Bookings, Wix Members, Wix Pricing Plans, third-party integrations

Decision table:

MCP Tools the sub-agent should use:

• •mcp__wix-mcp-remote__SearchWixSDKDocumentation - SDK methods and APIs (Always use maxResults: 5)
• •mcp__wix-mcp-remote__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.

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

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: Before using @wix/design-system components, invoke the wds-docs skill FIRST to get correct imports (icons are from @wix/wix-ui-icons-common, NOT @wix/design-system/icons).
Implement this extension following the skill guidelines.

PARALLEL EXECUTION: When multiple independent extensions are needed, spawn ALL sub-agents 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, report to the user:

• •What was created
• •How to test it (preview commands)
• •Any next steps

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.

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.