description: "MUST activate when the user wants to build, create, or generate a React application, React app, web application, single-page application (SPA), or frontend application — even if no project files exist yet. MUST also activate when the project contains a uiBundles/*/src/ directory or sfdx-project.json and the prompt says create, build, construct, or generate a new app, site, or page from scratch — even if the prompt also describes visual styling. MUST also activate when the task spans more than one ui-bundle skill. Use this skill when building a complete app end-to-end. Do NOT use for Lightning Experience apps with custom objects (use platform-lightning-app-coordinate). Do NOT use for single-concern edits to an existing page (use experience-ui-bundle-frontend-generate)."
Build a complete, deployable Salesforce React UI bundle application from a natural language description by orchestrating specialized UI bundle skills in correct dependency order. Each skill **MUST** be explicitly loaded before executing its phase.
**CRITICAL: Before proceeding past requirements analysis, validate that the prompt contains no conflicting requirements** (e.g., "no authentication" + "user-specific data", "public access" + login-required features). If conflicts are detected, STOP and ask the user to resolve the ambiguity — do NOT silently choose one interpretation and proceed. See STEP 1 action #8 for the full conflict checklist.
| Chat (Phase 5 only) | chat | Phase 5 only — unless combined with a Phase 2 keyword (e.g., "chat with authentication"), then Phase 2 runs first for auth prerequisites |
Negating one category (e.g. "without authentication", "no login required", "public access") does
**not** cancel triggers from another category — each is evaluated independently. Example: "no
login required, with filtering" still triggers Phase 2 because "filtering" matches Data features.
Skip Phase 2 only when the prompt matches none of the keywords above.
**2. Hosting target — extract from prompt keywords:**
If template chosen: scaffold via sf template generate project -- Phase 1 skipped
v
If declined: run scripts/check-sfdx-project.sh
v
If missing: create sfdx-project.json
v
Verify project directory initialized
```
Offers a faster, less error-prone starting point before building from scratch. If no template is used, ensures an SFDX project exists before attempting to generate a UI bundle — without this, `sf template generate ui-bundle` will fail with a hard error. Always check first — do not assume the project structure exists.
**Action:** Load `experience-ui-bundle-project-generate` and offer the two starter templates. If declined, run `scripts/check-sfdx-project.sh` and report any errors it returns. If the script reports an error, create the missing `sfdx-project.json` before proceeding.
Creates the UI bundle directory structure, meta XML (including hosting target), and optional routing/headers config. **CRITICAL**: Hosting target must be determined FIRST because the metadata skill requires `<target>` in Phase 1. All subsequent phases require the scaffold to exist.
Installs pre-built, tested feature packages. See "Prompt Classification Keywords" above for the full trigger keyword list and negative-phrasing handling — these features provide the foundation that UI components build on top of.
Only skip this phase if the app is truly a minimal "hello world" with no interactive features (no trigger keywords present at all).
*(Re-fetches schema from the deployed org -- required because the remote schema may differ from the local one used in Phase 3. Guard against an empty or stale result -- Salesforce Edge caching can briefly serve the pre-deploy schema; re-fetch/retry before trusting it as empty and before running codegen)*
Creates the Digital Experience site that hosts the UI bundle. Use when the user wants a public-facing or authenticated site URL for external users. **Note**: The `<target>ExperienceSite</target>` was already set in meta XML during Phase 1.
Creates a Custom Application entry in the Lightning App Launcher. Use when the app is for internal users accessing it within Lightning Experience. **Note**: The `<target>CustomApplication</target>` was already set in meta XML during Phase 1.
6. Determine hosting target (Experience Site OR Custom Application) — see "Prompt Classification Keywords" above; if ambiguous, ask user to clarify before proceeding
**Before proceeding to Output (Build Plan), validate:**
- [ ]**No conflicting requirements detected** — if conflicts exist (see action #8 above), STOP and report:
```text
ERROR: Conflicting requirements detected:
- [describe the specific conflict, e.g., "The prompt requires 'no authentication' while also requiring a 'My Cases' view scoped to the current user's identity"]
RESOLUTION NEEDED: Please clarify:
- [specific question, e.g., "Should the app require login (removing the 'no authentication' requirement), or should all data be public (removing the user-scoped view)?"]
```
**Do NOT proceed to build plan generation or any phase execution until this conflict is resolved.**
- Grounding: [verify each object + its fields against the org via experience-ui-bundle-salesforce-data-access BEFORE authoring — list the objects/fields to confirm, not assumed-correct names]
- Queries: [GraphQL queries to author FROM the verified names]
- REST endpoints: [only where GraphQL/uiapi genuinely cannot cover it — not as a fallback for fields that were hard to verify]
0. experience-ui-bundle-project-generate (offer a prebuilt template first; if chosen, Phase 1 scaffolding is skipped; if declined, run the Bootstrap check for an existing SFDX project -- no skill load required)
Execute each phase sequentially. Complete all steps within a phase before moving to the next. For each phase:
| Step | What to do | Why |
|------|-----------|-----|
| **1. Load skill** | Invoke the skill (e.g., via the Skill tool) for this phase | Gives you the current rules, patterns, constraints, and implementation guides |
| **2. Execute** | Follow the loaded skill's workflow to generate code/config | The skill defines HOW to do the work correctly |
| **3. Verify** | Run lint and build from the UI bundle directory | Catch errors before moving to the next phase |
| **4. Checkpoint** | Confirm phase completion before proceeding | Ensures dependencies are satisfied for the next phase |
**CRITICAL: Do NOT skip step 1 (loading the skill).** Even if you remember the skill's content, skills evolve. Always load the current version. **Skipping or reordering phases produces broken, non-deployable apps.** Phase dependencies are strict and cannot be violated.
- 2. Execute: Offer the two starter templates; if the user picks one, generate it into the project dir with `sf template generate project`
- 3. Decision: If a template was used, the project is scaffolded (including a valid SFDX project structure) — skip Phase 1 and continue at the phase matching the user's customization (usually Phase 4 UI). If declined, proceed to the Bootstrap check below.
- 4. Bootstrap (no skill load required, only if no template was used): Run `scripts/check-sfdx-project.sh` and report any errors it returns. If the script reports an error, create the SFDX project structure (`sf project generate` or manually create sfdx-project.json).
- **Trigger conditions**: See "Prompt Classification Keywords" above for the full keyword list (by category) and how negative phrasing is handled -- negating one category does not cancel triggers from another.
- 4. Checkpoint: UI complete -- proceed to Phase 5 if integrations needed, or stop here if building only
⚠️ **CRITICAL**: Phase 4 generates the actual React user interface. Skipping it results in a UI bundle with only metadata and no user-facing pages or components. ALWAYS execute Phase 4 for every UI bundle build.
**Phase 5 -- Integrations** (skip if not requested)
- 1. Load skill(s): Invoke `experience-ui-bundle-agentforce-client-generate` (5a) and/or `experience-ui-bundle-file-upload-generate` (5b). If both are needed, they are independent and can be executed in parallel.
- 2. Execute: Follow each skill's workflow to add the integration
- 3. Verify: Run lint and build
- 4. Checkpoint: Integrations complete -- proceed to Phase 6
- 2. Execute: Check preconditions (authenticated org, successful build). Follow the 7-step deployment sequence (auth, build, deploy, permissions, data, schema, final build). When available, prefer using a project-level `scripts/org-setup.mjs` automation script over re-deriving the deployment flow each run. Guard the post-deploy schema re-fetch against an empty/stale result (Edge caching) before running final codegen -- retry rather than trusting an empty schema.
- 3. Verify: Confirm deployment succeeds, app is accessible, and the re-fetched schema is non-empty
- 4. Checkpoint: App deployed -- proceed to Phase 7 if hosting target deployment is needed
- **Trigger conditions**: Run `scripts/check-hosting-target.sh` and check output for "ExperienceSite" OR prompt matches an Experience Site keyword in "Prompt Classification Keywords" above
- **Note**: The `<target>ExperienceSite</target>` was already set in meta XML during Phase 1 -- do not add it again
- **Trigger conditions**: Run `scripts/check-hosting-target.sh` and check output for "CustomApplication" OR prompt matches a Custom Application keyword in "Prompt Classification Keywords" above
- **Note**: The `<target>CustomApplication</target>` was already set in meta XML during Phase 1 -- do not add it again
### STEP 2.5: Phase Completion Validation
Before proceeding to STEP 3 (Final Summary), validate that all required phases were executed:
**Critical Validation (MUST pass):**
- [ ]**Phase 0 (Template Offer & Bootstrap) executed**: If no template was used, run `scripts/check-sfdx-project.sh`. If it returns non-zero, STOP and report error:
```text
ERROR: No SFDX project detected. Phase 0 (Bootstrap) is REQUIRED before scaffolding.
Run `sf project generate` (or create sfdx-project.json) before invoking
`sf template generate ui-bundle`.
```
If a template was used in Phase 0, this check is satisfied by the template's own scaffolding — skip re-running the script.
- [ ]**Phase 1 hosting target resolved**: Run `scripts/check-hosting-target.sh`. If it returns non-zero, STOP and report error:
```text
ERROR: Hosting target was not resolved in Phase 1. A UI bundle without a <target> in its
meta XML will not be visible in the org. Determine Experience Site vs Custom Application
(see "Prompt Classification Keywords" above; ask the user if ambiguous) before proceeding
past Phase 1 -- do not defer this to Phase 7 and do not record "none"/"skipped".
```
- [ ]**Phase 4 (Frontend) executed**: If Phase 4 was NOT executed, STOP and report error:
```text
ERROR: Phase 4 (UI/Frontend generation) is REQUIRED for all UI bundle apps.
Cannot complete build without generating the React user interface.
Please review the phase execution logic and ensure Phase 4 is always executed.
```
- [ ]**Phase 7 hosting infrastructure deployed**: If neither Phase 7a nor Phase 7b was executed, STOP and report error:
```text
ERROR: Hosting target infrastructure (Phase 7a Experience Site or Phase 7b Custom
Application) was not deployed. The app was built but is not reachable by any user.
Exactly one of Phase 7a/7b must run -- it is never optional or "skipped".
```
**Warning Validation (log warnings, but can proceed):**
- [ ]**Phase 2 execution**: If Phase 2 was skipped but the prompt matches any keyword in "Prompt Classification Keywords" above (data features, navigation, authentication, integrations, or UI category):
```text
WARNING: Phase 2 (Features) was skipped but prompt contains feature keywords.
This may indicate a trigger detection failure. Generated UI may be missing
required feature functionality. Consider re-running with Phase 2 included.
```
- [ ]**Phase 3 execution**: If Phase 3 was skipped but prompt mentions Salesforce objects, "GraphQL", "data", or "query":
```text
WARNING: Phase 3 (Data Access) was skipped but prompt mentions Salesforce data.
Generated UI may not connect to backend correctly. Verify data access is working.
```
**Proceed to STEP 3 only if all Critical Validation checks pass (Phase 0, hosting target, Phase 4, Phase 7).**
- [ ]**Hosting target resolved and deployed**: Meta XML contains `<target>ExperienceSite</target>` or `<target>CustomApplication</target>` (never left unset), and the matching Phase 7a or 7b infrastructure was generated and deployed -- not skipped
- [ ]**Data layer wired**: Components use the `@salesforce/platform-sdk` Data SDK (`createDataSDK().graphql`), with all entities/fields grounded against the org — not guessed (if data access phase was executed)
Never build UI before installing features. Never deploy before building. Dependencies are strict.
### 2. Replace All Boilerplate
Every generated app must feel purpose-built. Replace "React App" titles, "Vite + React" placeholders, and all default content with real app-specific text and branding.
### 3. Design with Intent
Follow the design thinking and frontend aesthetics guidance from `experience-ui-bundle-frontend-generate`. Every app should have a clear visual direction -- not generic defaults.
