@salesforce/afv-skills 1.57.0 → 1.59.0

package/skills/agentforce-persona-generate/references/workshop-question-policy.md

@@ -0,0 +1,90 @@
+---
+version: "1.0.0"
+date: 2026-05-15
+---
+
+# Workshop Question Policy
+
+Rules for generating stakeholder-facing questions in the WORKSHOP spoke. The skill produces these questions for a customer's internal stakeholders to answer **asynchronously** — not in a live workshop with the skill running. So the questions need to be open-ended, thought-provoking, scoped to what's actually unresolved, and respectful of stakeholder time.
+
+## Guiding principle
+
+**Quality over coverage. Better to ask 4 great questions than 12 generic ones.**
+
+There is an infinite possible question set the framework could generate. Most of those questions are noise for any specific persona. The job here is identifying *what's actually unresolved or high-leverage* for *this* persona, given everything the skill already knows.
+
+## Skip what you already know
+
+The skill must NOT generate questions for things it already knows from the brand input, persona draft, or context. Stakeholder attention is the scarce resource.
+
+**Examples of what to skip:**
+
+- The brand input clearly says "always formal" → don't ask about Formality.
+- The customer is a serious law firm → don't ask "How much humor?" (the answer is probably None and asking burns attention on a non-question).
+- Channel is locked to telephony → don't ask "Should the agent use emoji?" (no formatting in audio).
+- Personification is locked to Talking System → don't ask about character names.
+- Identity is filled with strong-signal traits → don't ask the stakeholders to re-validate every adjective; pick one or two with productive tension.
+
+This is harder than it sounds. The framework has 14 dimensions × 5+ persona artifacts × business context. Most could generate plausible questions. The skill must actively prune.
+
+## What to ask about
+
+In priority order:
+
+1. **High up the dimensions ladder** — Identity, Personification, Register. These have the most leverage; getting them wrong cascades.
+2. **Where confidence is low** — when a draft dimension was filled with a default rather than a strong signal, that's a candidate question.
+3. **Where productive tension exists** — Tension Pairs in the framework (Cool Warmth + Bold Personality, Blunt Coloring + Playful Humor, etc.) are inherently questions stakeholders should weigh in on.
+4. **Where the brand input is silent or contradictory** — e.g., the brand guide says "approachable" but doesn't say how much humor; that's worth asking.
+5. **Where channel forces a tradeoff** — voice agents handling frustrated callers; humor in escalation flows.
+6. **Where the use case raises a tone-flex question** — the framework's tone-flex triggers (system errors, content sensitivity, escalation) are stakeholder-relevant moments.
+
+## What never to ask about
+
+- Things the input or context already answers definitively.
+- Things downstream of a higher decision already made (don't ask about emoji if Formal Register is locked — Formal pulls Emoji to None).
+- Internal mechanics the stakeholders shouldn't be making decisions about (e.g., dimension constraint notes, tension-pair resolution rules).
+- Anything that produces a "neutral default" answer — those questions waste stakeholder attention without changing the persona.
+
+## Question styles
+
+Three styles, picked per question based on what's needed:
+
+### 1. Validate
+
+Use when the skill has a strong-signal draft and wants stakeholder confirmation.
+
+> "We assumed [X] from your brand guide. Confirm or push back."
+> "The agent will speak in Coach register — instructive, takes a position. That fits the 'sales coach' framing in the brief. Right call?"
+
+### 2. Choose between
+
+Use when there are two genuinely different positions on a spectrum, with consequences spelled out.
+
+> "When a customer expresses frustration, would you rather the agent (A) acknowledge the frustration before solving, or (B) skip to the solve? A reads as more empathetic; B reads as more efficient. Pick one."
+
+The two options must be **meaningfully different**. Don't write false binaries where both options are the same with cosmetic differences. If you can't articulate the consequence of each choice, drop the question.
+
+### 3. Open spectrum
+
+Use when it's a blank slate — no signal in the input, and the stakeholders genuinely need to make the call.
+
+> "Place the agent on this line: [Brisk] ⟷ [Languid]"
+> "How much character should come through? [Talking System] ⟷ [Familiar Thing] ⟷ [Personal Assistant]"
+
+These are dimension-card-shaped — print on a page, dot-vote, or place stickies on a FigJam board. Especially good for high-leverage dimensions (Identity, Personification, Register, Warmth) where the stakeholder team needs to converge.
+
+## Output format constraints
+
+The workshop outline is meant to be **lightweight and printable** — a FigJam board, a whiteboard, a Google Doc with sticky notes. Not a slide deck. Not a long-form persona document. The skill's job is to produce the outline; the customer's job is to run the workshop with it.
+
+- Aim for 4-8 total questions per workshop outline. Fewer if the persona is well-grounded.
+- Group questions by Activity (Identity calibration, Tone in difficult moments, Spectrum check) so the workshop has a clear arc.
+- Pre-read materials section: link to or attach the brand-grounded persona draft and sample dialog so stakeholders walk in informed.
+- Include a brief "Background" paragraph for the facilitator (≤1 paragraph) summarizing where the persona stands and what input is needed.
+
+## Anti-patterns to refuse
+
+- A 20-question workshop outline. If you're hitting 20, you haven't pruned.
+- A workshop outline for a Talking System that asks "What kind of humor?" Skip. You know the answer.
+- A workshop outline that asks every dimension "where on the spectrum?" — that's a coverage approach, not a leverage approach.
+- A workshop outline where every option in a "choose between" pair reads as neutral or compromised. The job is to surface real tradeoffs, not to write safe choices.

package/skills/agentforce-persona-generate/references/workshop-scenario-seeds.md

@@ -0,0 +1,119 @@
+---
+version: "1.0.0"
+date: 2026-05-15
+---
+
+# Workshop Scenario Seeds
+
+A library of common stakeholder-relevant scenarios the WORKSHOP spoke uses as starting material for would-you-rather question pairs. These are conversational moments where persona-level decisions have visible consequences.
+
+The skill picks scenarios from this library that align with the captured Use cases and the dimensions where stakeholder input is wanted. It customizes the response options A and B to the persona under design. **Do not use these seeds verbatim** — the skill should rewrite the user utterance and the response pair so they fit the customer's actual context (their language, their typical issues, their brand voice).
+
+## How to use this library
+
+For each seed:
+- The **user utterance** is a representative kind of moment, not a literal quote. Adapt the wording.
+- The **A / B contrast** sketches the two persona directions that produce different responses. The skill rewrites both A and B in the persona's voice (or two persona voices, if asking the stakeholders to pick).
+- The **dimensions exercised** field identifies which dimensions the choice surfaces. This helps the skill pick the right seed for the gap it's trying to fill.
+
+---
+
+## Seeds
+
+### Frustration
+
+**User utterance:** the user expresses frustration with a problem (a billing issue, a delayed order, a feature that doesn't work).
+
+- **A — acknowledge first, then solve.** "That's frustrating, and I'm sorry you're dealing with it. Let me look into it."
+- **B — skip to the solve.** "Let me check that for you. One moment."
+
+**Dimensions exercised:** Empathy Level, Emotional Coloring, Brevity. A reads as more empathetic; B reads as more efficient. Different audiences (and different brands) have different right answers.
+
+### Escalation
+
+**User utterance:** the user requests a human agent or escalation.
+
+- **A — acknowledge the request, hand off warmly.** "I hear you — let me get a teammate on this who can help directly. One moment."
+- **B — execute the handoff cleanly, no flourish.** "Connecting you to a specialist now."
+
+**Dimensions exercised:** Warmth, Brevity, Phrase Book (handoff category). A invests in the relationship at the moment of handoff; B prioritizes speed and clarity.
+
+### Ambiguity
+
+**User utterance:** the user gives an ambiguous request that could mean two things ("can you check on that order").
+
+- **A — ask for clarification before acting.** "Got it — which order? You've got [N] in flight. Order number or recent activity?"
+- **B — make the most likely guess and surface it.** "Pulling up your most recent order — is that the one?"
+
+**Dimensions exercised:** Brevity, Personality Intensity, Empathy Level. A is conservative and accurate; B is proactive and faster. Choice often signals whether the agent is meant to feel like a careful clerk or a quick assistant.
+
+### Success
+
+**User utterance:** the user confirms something worked or expresses satisfaction.
+
+- **A — match the energy.** "Great. Glad we got it sorted."
+- **B — acknowledge minimally and move on.** "Done."
+
+**Dimensions exercised:** Warmth, Personality Intensity, Brevity, Emotional Coloring. A invests in the moment; B treats success as the default state. Different brands handle success differently — luxury hospitality tends toward A, transactional efficiency toward B.
+
+### Error (system)
+
+**User utterance:** something the agent tried to do failed (an API call timed out, a record wasn't found).
+
+- **A — apologize, then recover.** "Sorry — that didn't go through. Let me try again."
+- **B — state the issue, recover.** "That didn't go through. Trying again."
+
+**Dimensions exercised:** Formality, Warmth, Empathy Level, Brevity. A apologizes for the system; B treats the error as a fact. Stakeholders sometimes care more than designers expect.
+
+### Off-topic
+
+**User utterance:** the user asks something the agent isn't designed to handle ("what do you think of the latest movie?").
+
+- **A — engage briefly, then redirect.** "Ha — not really my thing. What I can help with: [scope]."
+- **B — redirect cleanly without engagement.** "I can help with [scope]. What's on your mind?"
+
+**Dimensions exercised:** Personality Intensity, Humor, Brevity, Phrase Book (off-topic redirect category). A acknowledges the human moment; B keeps the conversation on rails.
+
+### Bad news
+
+**User utterance:** the user is about to receive news they won't like (their order is delayed; the feature isn't available; the policy doesn't allow it).
+
+- **A — soften the delivery.** "Here's what I'm seeing — and it's not the news either of us wanted: [bad news]."
+- **B — deliver directly.** "Your order is delayed by 3 days."
+
+**Dimensions exercised:** Empathy Level, Emotional Coloring, Personality Intensity, Tone Flex. A leans into Encouraging coloring; B leans into Blunt or Neutral. Strong stakeholder-leverage question — the answer reveals brand stance on hard truths.
+
+### Repeat customer
+
+**User utterance:** the user is a returning customer the agent has context on.
+
+- **A — personalize the greeting.** "Welcome back, [name]. Last time we were sorting out [thing]."
+- **B — start fresh, treat each session as new.** "Hi — what can I help with today?"
+
+**Dimensions exercised:** Warmth, Personality Intensity, Personification. A treats the relationship as continuous; B treats each session discretely. Often a privacy / brand-stance question.
+
+### Compliment / kudos
+
+**User utterance:** the user thanks the agent or compliments its help.
+
+- **A — accept the thanks warmly.** "Glad it helped. Anything else?"
+- **B — deflect to the user's effort.** "You did the work — I just pulled the data. Anything else?"
+
+**Dimensions exercised:** Personality Intensity, Warmth, Humor. A is straightforward; B is humble and frames the interaction as collaborative. The choice signals whether the agent has its own agency or is a tool.
+
+### Disagreement
+
+**User utterance:** the user pushes back on the agent's recommendation or information.
+
+- **A — yield gracefully.** "Fair enough — let's go with your call. What can I do next?"
+- **B — hold the line with reasoning.** "Hear you on that. The reason I went there: [reason]. Want to walk through together?"
+
+**Dimensions exercised:** Register, Personality Intensity, Empathy Level. A is more Subordinate / accommodating; B is more Coach / Advisor with conviction. Reveals whether the agent has a point of view.
+
+---
+
+## Coverage
+
+The library covers the situations a typical Agentforce agent will encounter — happy path, uncertainty, hard moments, and edge cases. The skill doesn't need to use all of these in any one workshop. **Pick 2-4 that align with the persona's use cases and the gaps in dimension coverage.**
+
+If the agent's use cases include heavy escalation work, prioritize Frustration + Escalation + Bad news. If the agent is consultative (sales coach, advisor), prioritize Disagreement + Ambiguity + Compliment. If the agent is transactional, Frustration + Success + Off-topic may cover it.

package/skills/agentforce-persona-generate/scripts/parse_agent_yaml.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""Parse an Agent Script .agent file and return a normalized dict.
+
+READ-ONLY. This script never writes back to the source file. It opens the
+file, walks the structure, and returns a normalized Python dict that the
+SKILL.md flow can iterate over without caring about the file's exact YAML
+nesting.
+
+Usage:
+    python3 parse_agent_yaml.py <path-to-.agent-file>
+
+Output (stdout): JSON-formatted normalized structure.
+
+Normalized shape:
+    {
+        "system": {
+            "instructions": str,
+            "welcome": str,
+            "error": str,
+        },
+        "config": {
+            "developer_name": str,
+            "agent_label": str,
+            "agent_type": str,
+            ...
+        },
+        "subagents": [
+            {
+                "name": str,
+                "description": str,
+                "instructions": str | None,
+                "reasoning_instructions": str | None,
+                "system_override": str | None,
+                "actions": [{"name": str, "progress_indicator_message": str | None}, ...]
+            },
+            ...
+        ],
+        "actions_global": [{"name": str, "progress_indicator_message": str | None}, ...],
+    }
+
+The skill uses this structure to:
+- SCORE: traverse subagents and actions, score per layer
+- ENCODE (brownfield): produce a proposed-new-file with only persona-bearing
+  fields modified, preserving everything else exactly as the source had it.
+
+Note on Agent Script syntax: .agent files are YAML-LIKE but use directive
+syntax (`->`, `|`, `system:`, `subagent name:`) that isn't strict YAML. This
+parser does best-effort regex-based extraction targeted at the persona-bearing
+fields the skill needs. For full Agent Script parsing, refer to the
+developing-agentforce skill in forcedotcom/sf-skills.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def parse_agent_file(path: Path) -> dict:
+    """Parse an .agent file and return normalized structure. Read-only."""
+    text = path.read_text()
+
+    return {
+        "system": _extract_system(text),
+        "config": _extract_config(text),
+        "subagents": _extract_subagents(text),
+        "actions_global": [],  # Global actions are rare; usually nested under subagents.
+    }
+
+
+def _extract_block(text: str, header: str) -> str | None:
+    """Extract a top-level block (system, config, etc.) by indent boundary.
+
+    Returns the block content (lines after the header, dedented) or None if
+    the header isn't present.
+    """
+    lines = text.splitlines()
+    in_block = False
+    block_indent: int | None = None
+    block_lines: list[str] = []
+
+    for line in lines:
+        if not in_block:
+            stripped = line.strip()
+            if stripped == header or stripped == f"{header}:":
+                in_block = True
+                continue
+        else:
+            if not line.strip():
+                block_lines.append(line)
+                continue
+            indent = len(line) - len(line.lstrip())
+            if block_indent is None:
+                block_indent = indent
+            if indent < block_indent and line.strip():
+                # Dedent below the block — we're out.
+                break
+            block_lines.append(line[block_indent:] if len(line) >= block_indent else line)
+
+    return "\n".join(block_lines).rstrip() if block_lines else None
+
+
+def _extract_field(block: str | None, key: str) -> str | None:
+    """Extract a `key: value` or `key: |` literal-block field from a block."""
+    if not block:
+        return None
+
+    # Try literal block scalar first: key: |\n    text...
+    pattern_literal = rf"^{re.escape(key)}:\s*\|\s*\n((?:[ \t]+.*\n?)*)"
+    m = re.search(pattern_literal, block, flags=re.MULTILINE)
+    if m:
+        return _dedent(m.group(1)).rstrip()
+
+    # Try inline string: key: "value" or key: value
+    pattern_inline = rf'^{re.escape(key)}:\s*"?([^"\n]*?)"?\s*$'
+    m = re.search(pattern_inline, block, flags=re.MULTILINE)
+    if m:
+        val = m.group(1).strip()
+        return val if val else None
+
+    return None
+
+
+def _dedent(text: str) -> str:
+    """Strip the common leading whitespace from every line."""
+    lines = text.splitlines()
+    indents = [len(l) - len(l.lstrip()) for l in lines if l.strip()]
+    if not indents:
+        return text
+    common = min(indents)
+    return "\n".join(l[common:] if len(l) >= common else l for l in lines)
+
+
+def _extract_system(text: str) -> dict:
+    block = _extract_block(text, "system")
+    if not block:
+        return {"instructions": None, "welcome": None, "error": None}
+
+    # messages is a sub-block
+    messages_block = _extract_block(block, "messages")
+
+    return {
+        "instructions": _extract_field(block, "instructions"),
+        "welcome": _extract_field(messages_block, "welcome"),
+        "error": _extract_field(messages_block, "error"),
+    }
+
+
+def _extract_config(text: str) -> dict:
+    block = _extract_block(text, "config")
+    if not block:
+        return {}
+
+    return {
+        "developer_name": _extract_field(block, "developer_name"),
+        "agent_label": _extract_field(block, "agent_label"),
+        "description": _extract_field(block, "description"),
+        "agent_type": _extract_field(block, "agent_type"),
+        "default_agent_user": _extract_field(block, "default_agent_user"),
+    }
+
+
+def _extract_subagents(text: str) -> list[dict]:
+    """Find each `subagent NAME:` block and extract its persona-bearing fields."""
+    # Match subagent declarations and capture name + body
+    pattern = r"^subagent\s+(\w+):\s*\n((?:[ \t]+.*\n?)*)"
+    subagents: list[dict] = []
+
+    for match in re.finditer(pattern, text, flags=re.MULTILINE):
+        name = match.group(1)
+        body = _dedent(match.group(2))
+
+        system_override_block = _extract_block(body, "system")
+        reasoning_block = _extract_block(body, "reasoning")
+
+        subagents.append({
+            "name": name,
+            "description": _extract_field(body, "description"),
+            "system_override": _extract_field(system_override_block, "instructions"),
+            "reasoning_instructions": _extract_field(reasoning_block, "instructions"),
+            "actions": _extract_subagent_actions(body),
+        })
+
+    return subagents
+
+
+def _extract_subagent_actions(subagent_body: str) -> list[dict]:
+    """Extract per-action progress_indicator_message from a subagent's actions: block."""
+    actions_block = _extract_block(subagent_body, "actions")
+    if not actions_block:
+        return []
+
+    actions: list[dict] = []
+    # Action declarations are like: `action_name:` followed by indented properties
+    pattern = r"^(\w+):\s*\n((?:[ \t]+.*\n?)*)"
+    for match in re.finditer(pattern, actions_block, flags=re.MULTILINE):
+        name = match.group(1)
+        body = _dedent(match.group(2))
+        actions.append({
+            "name": name,
+            "progress_indicator_message": _extract_field(body, "progress_indicator_message"),
+        })
+
+    return actions
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: parse_agent_yaml.py <path-to-.agent-file>", file=sys.stderr)
+        return 1
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"File not found: {path}", file=sys.stderr)
+        return 1
+
+    parsed = parse_agent_file(path)
+    print(json.dumps(parsed, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/dx-app-analytics-query/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: dx-app-analytics-query
-description: "ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings. Use this skill when the user asks about retrieving managed package usage data, configuring App Analytics simulation mode, querying subscriber snapshots, or understanding the AppAnalyticsQueryRequest lifecycle (New → Pending → Complete → Expired). TRIGGER when: user mentions App Analytics, AppAnalyticsQueryRequest, AppAnalyticsSettings, package usage data, subscriber analytics, ISV analytics, or simulation mode for app analytics. DO NOT TRIGGER when: the task is about standard Salesforce reports/dashboards (use reporting skills), custom SOQL on Account/Contact (use platform-soql-query)."
+description: "ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings. Use this skill when the user asks about retrieving managed package usage data, configuring App Analytics simulation mode, querying subscriber snapshots, or understanding the AppAnalyticsQueryRequest lifecycle (New → Pending → Complete → Expired). TRIGGER when: user mentions App Analytics, AppAnalyticsQueryRequest, AppAnalyticsSettings, package usage data, subscriber analytics, ISV analytics, or simulation mode for app analytics. DO NOT TRIGGER when: the task is about standard Salesforce reports/dashboards (use reporting skills), custom SOQL on Account/Contact (use querying-soql), or Data Cloud query/search (use retrieving-datacloud)."
 metadata:
-  cliTools:
-    - tool: ["sf"]
-      semver: ">=2.0.0"
-  relatedSkills:
-    - "platform-metadata-deploy"
-    - "platform-soql-query"
   version: "1.0"
   domains: ["Developer Experience"]
   minApiVersion: "56.0"
+  relatedSkills:
+    - "platform-soql-query"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 # App Analytics
@@ -28,8 +27,9 @@ Use `dx-app-analytics-query` when the work involves:
 
 Delegate elsewhere when the user is:
 - Running standard CRM SOQL queries → platform-soql-query
+- Working with Data Cloud SQL or DMOs → retrieving-datacloud
 - Building reports/dashboards on standard objects → reporting skills
-- Deploying or retrieving generic metadata XML → platform-metadata-deploy / retrieving-metadata
+- Deploying or retrieving generic metadata XML → deploying-metadata / retrieving-metadata
 
 ---
 

package/skills/experience-ui-bundle-app-coordinate/SKILL.md

@@ -42,7 +42,7 @@ Before starting any phase, verify these preconditions are met:
 
 1. **Authenticated Salesforce org**: Run `sf org display` to confirm a default org is set and authenticated. If not, prompt the user to authenticate: `sf org login web`
 2. **Required CLI tools**: Verify `sf`, `npm`, and `npx` are available (declared in metadata.cliTools)
-3. **Node.js version**: Run `scripts/check-prerequisites.sh` and report any errors it returns
+3. **Node.js version**: Run `node scripts/check-prerequisites.mjs` and report any errors
 4. **Org features** (if deploying): Experience Cloud enabled, appropriate licenses, and Sites enabled
 
 If any precondition fails, stop and report the specific missing requirement before attempting any phase execution.
@@ -114,7 +114,7 @@ Offer prebuilt starter template (experience-ui-bundle-project-generate)
     v
 If template chosen: scaffold via sf template generate project -- Phase 1 skipped
     v
-If declined: run scripts/check-sfdx-project.sh
+If declined: run node scripts/check-sfdx-project.mjs
     v
 If missing: create sfdx-project.json
     v
@@ -123,7 +123,7 @@ 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.
+**Action:** Load `experience-ui-bundle-project-generate` and offer the two starter templates. If declined, run `node scripts/check-sfdx-project.mjs`; on error, create the missing `sfdx-project.json` before proceeding.
 
 ### Phase 1: Scaffolding (Foundation)
 
@@ -154,7 +154,7 @@ Creates the UI bundle directory structure, meta XML (including hosting target),
 - `package.json` — remove now-unused dependencies (`vite-plugin-graphql-codegen`, `@graphql-codegen/*`, `playwright`, `vitest`, etc.) and their npm scripts, not just the config files.
 - Any component/page that imports a deleted hook, client, or shadcn component (e.g. `useAsyncData`, `graphqlClient`) must have that import and its usage removed or replaced — never leave an import pointing at a file that no longer exists.
 - Do NOT re-add a file you just deleted elsewhere in the same pass (e.g. deleting `codegen.yml` while still emitting `.graphqlrc.yml`) — decide scope once per concern and apply it consistently across every file that touches that concern.
-- Before finishing Phase 4, run `scripts/check-dangling-refs.sh <deleted-basename>` for each deleted file and report any errors it returns.
+- Before finishing Phase 4, run `node scripts/check-dangling-refs.mjs <deleted-basename>` for each deleted file and report any errors.
 
 ### Phase 2: Features (Required if prompt mentions feature keywords — see "Prompt Classification Keywords" above)
 
@@ -378,12 +378,12 @@ Execute each phase sequentially following the standard pattern in `references/ph
 ---
 
 **Phase 0 -- Template Offer & Bootstrap**
-- Load `experience-ui-bundle-project-generate`, offer templates. If chosen: skip Phase 1, continue at Phase 2. If declined: run `scripts/check-sfdx-project.sh`, create project if missing.
+- Load `experience-ui-bundle-project-generate`, offer templates. If chosen: skip Phase 1, continue at Phase 2. If declined: run `node scripts/check-sfdx-project.mjs`, create project if missing.
 
 **Phase 1 -- Scaffolding** (skip if template used in Phase 0)
-- **Precondition**: `scripts/check-sfdx-project.sh` passes
+- **Precondition**: `node scripts/check-sfdx-project.mjs` passes
 - Load `experience-ui-bundle-metadata-generate`. Determine hosting target FIRST. Run `sf template generate ui-bundle --template reactbasic`, configure meta XML with `<target>`.
-- **Post-verification**: `scripts/check-phase-1-complete.sh` passes
+- **Post-verification**: `node scripts/check-phase-1-complete.mjs` passes
 
 **Phase 2 -- Features** (run on any feature keyword, even if pre-installed — see "Prompt Classification Keywords")
 - Load `experience-ui-bundle-features-generate`. Install features, integrate examples. Verify with `npm run build`.
@@ -395,25 +395,25 @@ Execute each phase sequentially following the standard pattern in `references/ph
 - Load `experience-ui-bundle-salesforce-data-access`. Fetch schema, ground entities, generate queries/mutations. Verify with `npx eslint`.
 
 **Phase 4 -- UI** (ALWAYS REQUIRED)
-- **Precondition**: `scripts/check-phase-1-complete.sh` passes
+- **Precondition**: `node scripts/check-phase-1-complete.mjs` passes
 - Load `experience-ui-bundle-frontend-generate`. Build layout, pages, components. Replace all boilerplate.
-- **Post-verification**: `scripts/check-phase-4-complete.sh` passes
+- **Post-verification**: `node scripts/check-phase-4-complete.mjs` passes
 - **CRITICAL**: Phase 4 generates the actual React UI. Never skip.
 
 **Phase 5 -- Integrations** (skip if not requested)
 - Load `experience-ui-bundle-agentforce-client-generate` (5a) and/or `experience-ui-bundle-file-upload-generate` (5b) as needed.
 
 **Phase 6 -- Deployment**
-- **Precondition**: `scripts/check-phase-6-ready.sh` passes
+- **Precondition**: `node scripts/check-phase-6-ready.mjs` passes
 - Load `experience-ui-bundle-deploy`. Follow 7-step sequence. Prefer `scripts/org-setup.mjs` if available.
 - **CRITICAL**: Guard against empty schema — retry fetch 3x before codegen.
 
 **Phase 7a -- Experience Site** (external users)
-- **Trigger**: `scripts/check-hosting-target.sh` outputs "ExperienceSite"
+- **Trigger**: `node scripts/check-hosting-target.mjs` outputs "ExperienceSite"
 - Load `experience-ui-bundle-site-generate`. Deploy site infrastructure.
 
 **Phase 7b -- Custom Application** (internal users)
-- **Trigger**: `scripts/check-hosting-target.sh` outputs "CustomApplication"
+- **Trigger**: `node scripts/check-hosting-target.mjs` outputs "CustomApplication"
 - Load `experience-ui-bundle-custom-app-generate`. Deploy app metadata.
 
 ### STEP 2.5: Phase Completion Validation

package/skills/experience-ui-bundle-app-coordinate/references/phase-completion-validation.md

@@ -3,7 +3,7 @@
 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:
+- [ ] **Phase 0 (Template Offer & Bootstrap) executed**: If no template was used, run `node scripts/check-sfdx-project.mjs`. 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
@@ -11,7 +11,7 @@ Before proceeding to STEP 3 (Final Summary), validate that all required phases w
   ```
   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:
+- [ ] **Phase 1 hosting target resolved**: Run `node scripts/check-hosting-target.mjs`. 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
@@ -33,7 +33,7 @@ Before proceeding to STEP 3 (Final Summary), validate that all required phases w
   Exactly one of Phase 7a/7b must run -- it is never optional or "skipped".
   ```
 
-- [ ] **No dangling references after scaffold pruning**: If any file was deleted during Phase 1 scaffold pruning (see "Prune unused scaffold" in SKILL.md), run `scripts/check-dangling-refs.sh <deleted-basename>` for each deleted file. If it returns non-zero (e.g. `vite.config.ts` still imports `vite-plugin-graphql-codegen` after `codegen.yml` was deleted, or a page still imports a deleted hook/component), STOP and report error:
+- [ ] **No dangling references after scaffold pruning**: If any file was deleted during Phase 1 scaffold pruning (see "Prune unused scaffold" in SKILL.md), run `node scripts/check-dangling-refs.mjs <deleted-basename>` for each deleted file. If it returns non-zero (e.g. `vite.config.ts` still imports `vite-plugin-graphql-codegen` after `codegen.yml` was deleted, or a page still imports a deleted hook/component), STOP and report error:
   ```text
   ERROR: Scaffold pruning left a dangling reference -- <file> was deleted but <other-file>
   still imports/references it. Remove the reference (or restore the file) before completing

package/skills/experience-ui-bundle-app-coordinate/references/phase-execution-pattern.md

@@ -4,21 +4,23 @@ Each phase follows this standard pattern:
 
 | Step | What to do | Why |
 |------|-----------|-----|
-| **0. Precondition Check** | Run `scripts/check-phase-N-*.sh` script | Verifies prerequisites are met before proceeding |
+| **0. Precondition Check** | Run the matching `node scripts/check-phase-N-*.mjs` script | Verifies prerequisites are met before proceeding |
 | **1. Load skill** | Invoke the skill for this phase | Gives you current rules, patterns, constraints |
 | **2. Execute** | Follow the loaded skill's workflow | The skill defines HOW to do the work correctly |
 | **3. Verify** | Run lint and build | Catch errors before moving to next phase |
-| **4. Post-verification** | Run `scripts/check-phase-N-complete.sh` (if available) | Machine-checkable validation of phase completion |
+| **4. Post-verification** | Run the matching `node scripts/check-phase-N-complete.mjs` (if available) | Machine-checkable validation of phase completion |
 | **5. Checkpoint** | Confirm phase completion | Ensures dependencies satisfied for next phase |
 
 **CRITICAL: Do NOT skip step 1 (loading the skill).** Skills evolve — always load the current version.
 
+**Always invoke every script via `node` (never as a bare executable)** so it works on Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+
 ## Available Verification Scripts
 
-- `scripts/check-sfdx-project.sh` - Validates SFDX project exists (Phase 0/1 prerequisite)
-- `scripts/check-phase-1-complete.sh` - Verifies scaffold complete (Phase 4/6 prerequisite)
-- `scripts/check-phase-4-complete.sh` - Verifies UI build complete (Phase 6 prerequisite)
-- `scripts/check-phase-6-ready.sh` - Verifies deployment prerequisites met
-- `scripts/check-hosting-target.sh` - Determines which hosting target is configured
+- `node scripts/check-sfdx-project.mjs` - Validates SFDX project exists (Phase 0/1 prerequisite)
+- `node scripts/check-phase-1-complete.mjs` - Verifies scaffold complete (Phase 4/6 prerequisite)
+- `node scripts/check-phase-4-complete.mjs` - Verifies UI build complete (Phase 6 prerequisite)
+- `node scripts/check-phase-6-ready.mjs` - Verifies deployment prerequisites met
+- `node scripts/check-hosting-target.mjs` - Determines which hosting target is configured
 
 All scripts exit 0 on success, exit 1 on failure with an error message.