@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/service-email-to-case-configure/scripts/validate-casesettings.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Validate a CaseSettings source file for headless Email-to-Case configuration.
+
+This file is the input to apply-casesettings.py, which supplies the routing
+emails (via --routing-email) and resolves the default case owner at apply time.
+So the source file must NOT carry emailAddress, and the owner fields are optional.
+
+Checks structural rules that must hold before applying:
+  - Well-formed XML with the CaseSettings root and correct namespace.
+  - defaultCaseOwnerType, if present, is User or Queue.
+  - useSystemUserAsDefaultCaseUser, if present, is boolean, and is not combined
+    with a named defaultCaseUser (mutually exclusive at the platform layer).
+  - emailToCase enables both enableEmailToCase and enableOnDemandEmailToCase.
+  - Each routingAddresses has addressType, routingName, caseOrigin, casePriority.
+  - If a routingAddresses sets caseOwner, it also sets caseOwnerType (User or
+    Queue) — the platform rejects caseOwner without it — and neither is left as
+    an unfilled {PLACEHOLDER}.
+  - emailAddress is NOT set in the file (it is supplied via --routing-email).
+  - addressType is not E2cEasy (must use the Service Easy Setup wizard).
+  - Read-only fields (emailServicesAddress, isVerified) are not set.
+  - Enum values for overEmailLimitAction / unauthorizedSenderAction are valid.
+
+Usage: python3 validate-casesettings.py <path-to-file>   (--help for this text)
+Exits non-zero and prints ERROR lines to stderr if any check fails.
+"""
+import sys
+import xml.etree.ElementTree as ET
+
+NS = "http://soap.sforce.com/2006/04/metadata"
+Q = f"{{{NS}}}"
+
+VALID_ADDRESS_TYPES = {"EmailToCase", "Outlook", "GmailOAuth"}
+VALID_OWNER_TYPES = {"User", "Queue"}
+OVER_LIMIT_ACTIONS = {"Bounce", "Discard", "Requeue"}
+UNAUTHORIZED_ACTIONS = {"Bounce", "Discard"}
+READONLY_FIELDS = {"emailServicesAddress", "isVerified"}
+
+# Boolean toggles that must be "true"/"false" when present. Split by container
+# so a field placed in the wrong section is flagged.
+TOP_LEVEL_BOOL_TOGGLES = {"enableDraftEmails"}
+EMAIL_TO_CASE_BOOL_TOGGLES = {
+    "enableEmailToCase", "enableOnDemandEmailToCase", "enableHtmlEmail",
+    "notifyOwnerOnNewCaseEmail", "enableE2CDeduplicateAttachments",
+    "showWordCountInComposer",
+}
+
+
+def local(tag):
+    return tag.split("}", 1)[-1]
+
+
+def child_text(parent, name):
+    el = parent.find(f"{Q}{name}")
+    return el.text.strip() if el is not None and el.text else None
+
+
+def is_placeholder(value):
+    """A value left as an unfilled template token, e.g. {CASE_OWNER_...}."""
+    return bool(value) and value.startswith("{") and value.endswith("}")
+
+
+def validate(path):
+    errors = []
+    try:
+        tree = ET.parse(path)
+    except ET.ParseError as exc:
+        return [f"XML is not well-formed: {exc}"]
+    except OSError as exc:
+        return [f"Cannot read file: {exc}"]
+
+    root = tree.getroot()
+    if local(root.tag) != "CaseSettings":
+        errors.append(f"Root element must be CaseSettings, found '{local(root.tag)}'.")
+    if not root.tag.startswith(Q):
+        errors.append(f"Root must use namespace '{NS}'.")
+
+    # CaseSettings-level Support-Settings owner / automated-user fields are
+    # OPTIONAL in the source file — apply-casesettings.py preserves existing org
+    # settings, or takes explicit values (validated against the org) when they
+    # are not configured. Here we only enforce the structural rules that hold
+    # regardless of the org.
+    owner_type = child_text(root, "defaultCaseOwnerType")
+    if owner_type and owner_type not in {"User", "Queue"}:
+        errors.append(f"defaultCaseOwnerType must be 'User' or 'Queue', found '{owner_type}'.")
+
+    # Default Case Owner is a paired field: the platform rejects defaultCaseOwner
+    # without defaultCaseOwnerType, and defaultCaseOwnerType without a value is a
+    # half-filled owner. Enforce both directions (mirrors the per-address rule).
+    owner_value = child_text(root, "defaultCaseOwner")
+    if owner_value is not None and owner_type is None:
+        errors.append(
+            "defaultCaseOwner is set without defaultCaseOwnerType — the platform "
+            "requires defaultCaseOwnerType ('User' or 'Queue') whenever "
+            "defaultCaseOwner is set. Add defaultCaseOwnerType, or remove "
+            "defaultCaseOwner to use the org Default Case Owner.")
+    if owner_type is not None and owner_value is None:
+        errors.append(
+            "defaultCaseOwnerType is set without defaultCaseOwner — either add a "
+            "defaultCaseOwner value (active Username or Queue DeveloperName) or "
+            "remove defaultCaseOwnerType.")
+
+    # Automated Case User: 'System' (useSystemUserAsDefaultCaseUser=true) and a
+    # named defaultCaseUser are mutually exclusive at the platform layer.
+    use_system = child_text(root, "useSystemUserAsDefaultCaseUser")
+    if use_system is not None and use_system not in {"true", "false"}:
+        errors.append(
+            f"useSystemUserAsDefaultCaseUser must be 'true' or 'false', "
+            f"found '{use_system}'.")
+    if use_system == "true" and child_text(root, "defaultCaseUser") is not None:
+        errors.append(
+            "useSystemUserAsDefaultCaseUser is 'true' but defaultCaseUser is "
+            "also set — they are mutually exclusive. For a System automated "
+            "case user, omit defaultCaseUser (optionally set systemUserEmail).")
+
+    # Top-level Support-Settings boolean toggles (e.g. enableDraftEmails).
+    for field in TOP_LEVEL_BOOL_TOGGLES:
+        val = child_text(root, field)
+        if val is not None and val not in {"true", "false"}:
+            errors.append(f"{field} must be 'true' or 'false', found '{val}'.")
+
+    e2c = root.find(f"{Q}emailToCase")
+    if e2c is None:
+        errors.append("Missing <emailToCase> block.")
+        return errors
+
+    if child_text(e2c, "enableEmailToCase") != "true":
+        errors.append("emailToCase.enableEmailToCase must be 'true'.")
+    if child_text(e2c, "enableOnDemandEmailToCase") != "true":
+        errors.append(
+            "emailToCase.enableOnDemandEmailToCase must be 'true' "
+            "before routing addresses can be created."
+        )
+
+    # emailToCase section boolean toggles (enableHtmlEmail, etc.).
+    for field in EMAIL_TO_CASE_BOOL_TOGGLES:
+        val = child_text(e2c, field)
+        if val is not None and val not in {"true", "false"}:
+            errors.append(f"emailToCase.{field} must be 'true' or 'false', found '{val}'.")
+
+    over = child_text(e2c, "overEmailLimitAction")
+    if over and over not in OVER_LIMIT_ACTIONS:
+        errors.append(f"overEmailLimitAction must be one of {sorted(OVER_LIMIT_ACTIONS)}, found '{over}'.")
+    unauth = child_text(e2c, "unauthorizedSenderAction")
+    if unauth and unauth not in UNAUTHORIZED_ACTIONS:
+        errors.append(f"unauthorizedSenderAction must be one of {sorted(UNAUTHORIZED_ACTIONS)}, found '{unauth}'.")
+
+    addresses = e2c.findall(f"{Q}routingAddresses")
+    if not addresses:
+        errors.append("No <routingAddresses> found — at least one is expected.")
+    seen_names = set()
+    for i, addr in enumerate(addresses, 1):
+        label = f"routingAddresses[{i}]"
+        for field in ("addressType", "routingName", "caseOrigin", "casePriority"):
+            if not child_text(addr, field):
+                errors.append(f"{label} missing required field '{field}'.")
+        atype = child_text(addr, "addressType")
+        if atype == "E2cEasy":
+            errors.append(
+                f"{label} uses addressType 'E2cEasy', which is not supported via Metadata API — "
+                "use the Service Easy Setup wizard."
+            )
+        elif atype and atype not in VALID_ADDRESS_TYPES:
+            errors.append(f"{label} addressType '{atype}' invalid; expected one of {sorted(VALID_ADDRESS_TYPES)}.")
+        name = child_text(addr, "routingName")
+        if name:
+            if name in seen_names:
+                errors.append(f"{label} duplicate routingName '{name}'.")
+            seen_names.add(name)
+        if child_text(addr, "emailAddress") is not None:
+            errors.append(
+                f"{label} sets 'emailAddress' — remove it; the customer-facing "
+                "email is supplied at apply time via --routing-email, never in "
+                "the source file.")
+        for field in READONLY_FIELDS:
+            if child_text(addr, field) is not None:
+                errors.append(f"{label} sets read-only field '{field}' — remove it; the platform manages it.")
+
+        # Optional per-address Default Case Owner. If caseOwner is set, it must
+        # be a real value (not an unfilled placeholder) AND be paired with a
+        # valid caseOwnerType — the platform rejects caseOwner without a type.
+        case_owner = child_text(addr, "caseOwner")
+        case_owner_type = child_text(addr, "caseOwnerType")
+        if case_owner is not None:
+            if is_placeholder(case_owner):
+                errors.append(
+                    f"{label} caseOwner is still the placeholder '{case_owner}' "
+                    "— set a real active Username or Queue DeveloperName, or "
+                    "remove caseOwner (and caseOwnerType) to use the org "
+                    "Default Case Owner.")
+            if case_owner_type is None:
+                errors.append(
+                    f"{label} sets caseOwner without caseOwnerType — the "
+                    "platform requires caseOwnerType ('User' or 'Queue') "
+                    "whenever caseOwner is set. Add caseOwnerType, or remove "
+                    "caseOwner to use the org Default Case Owner.")
+        if case_owner_type is not None:
+            if is_placeholder(case_owner_type):
+                errors.append(
+                    f"{label} caseOwnerType is still the placeholder "
+                    f"'{case_owner_type}' — set 'User' or 'Queue'.")
+            elif case_owner_type not in VALID_OWNER_TYPES:
+                errors.append(
+                    f"{label} caseOwnerType must be 'User' or 'Queue', found "
+                    f"'{case_owner_type}'.")
+            if case_owner is None:
+                errors.append(
+                    f"{label} sets caseOwnerType without caseOwner — either add "
+                    "a caseOwner value or remove caseOwnerType.")
+
+    return errors
+
+
+def main():
+    args = [a for a in sys.argv[1:] if a not in ("--help", "-h")]
+    if len(sys.argv) == 1 or "--help" in sys.argv or "-h" in sys.argv:
+        print(__doc__)
+        return 0 if "--help" in sys.argv or "-h" in sys.argv else 2
+    path = args[0]
+    errors = validate(path)
+    if errors:
+        for e in errors:
+            print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+    print(f"OK: {path} passed CaseSettings Email-to-Case validation.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/service-itsm-agentic-setup-agentforce-coordinate/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: service-itsm-agentic-setup-agentforce-coordinate
-description: "Orchestrator for setting up Agentforce in Salesforce Service Cloud ITSM — Agentforce Studio enablement, the IT Service Fulfiller agent lifecycle, and the IT Service Employee agent lifecycle. Use when the user asks to set up Agentforce for ITSM, enable Studio and the Fulfiller/Employee agents together, wants a guided Agentforce ITSM walkthrough, or asks what Agentforce features are available for IT Service. Presents available Agentforce capabilities and delegates each selection to a specialized child skill while tracking progress. Triggers on: set up agentforce for itsm, configure agentforce studio and fulfiller, agentforce itsm walkthrough, what agentforce features for it service. DO NOT TRIGGER when: the user asks to enable Agentforce Studio alone, asks to create or activate the Fulfiller or Employee agent alone, or asks about CMDB, Incident Management, Teams, or general ITSM setup without Agentforce intent."
+description: "Orchestrator for setting up Agentforce in Salesforce Service Cloud ITSM — Agentforce Studio enablement, the IT Service Fulfiller agent, and the IT Service Employee agent. Use when the user asks to set up Agentforce for ITSM, enable Studio and the Fulfiller/Employee agents together, wants a guided Agentforce ITSM walkthrough, or asks what Agentforce features are available for IT Service. Presents available Agentforce capabilities and delegates each selection to a specialized child skill while tracking progress. Triggers on: set up agentforce for itsm, configure agentforce studio and fulfiller, agentforce itsm walkthrough, what agentforce features for it service. DO NOT TRIGGER when: the user asks to enable Agentforce Studio alone, asks to create or activate the Fulfiller or Employee agent alone, or asks about CMDB, Incident Management, Teams, or general ITSM setup without Agentforce intent."
 metadata:
-  version: "1.2"
+  version: "1.6"
   domains: ["Service", "Agentforce"]
   relatedSkills:
     - "service-itsm-agentic-setup-agentforce-studio-configure"
@@ -46,21 +46,27 @@ explicit confirmation of the org.
 
 ### 3. Present the Agentforce feature menu as a multi-select
 
-Show the user what's available and what's done. Only features with a working child skill appear in the menu — use the **Feature menu** template in `examples/output-templates.md`. Collect the user's selections through a single multi-select prompt (use `AskUserQuestion` with `multiSelect: true` when tooling permits, otherwise ask the user to reply with a list of numbers such as `1, 2`). Do NOT show placeholder features that cannot be executed.
+Show the user what's available and what's done, organized into the **two sequential setup stages** —
+**Stage 1: enable platform features** (Agentforce Studio enablement) and **Stage 2: install &
+activate agent templates** (the Fulfiller and Employee agents). This separation is load-bearing:
+Stage 1 *enables* org-level platform toggles/preferences, while Stage 2 *installs and activates*
+agents from a template — they are distinct kinds of action and must read as distinct stages, not one
+undifferentiated list. Only features with a working child skill appear in the menu — use the
+**Feature menu** template in `examples/output-templates.md`. Collect the user's selections through a single multi-select prompt (use `AskUserQuestion` with `multiSelect: true` when tooling permits, otherwise ask the user to reply with a list of numbers such as `1, 2`). Use the **exact Item names from the Feature menu table** as the multi-select option labels — verbatim, including each item's parenthetical note and the word "Agent" and its capitalization (`Agentforce Studio enablement (Foundation for both agents)`, `IT Service Fulfiller Agent`, `IT Service Employee Agent`) — so the picker options and the table never diverge. Each item's **Description column matches the wording on the Salesforce Setup → Agentforce for IT Service page** (the Fulfiller and Employee agent-template descriptions are used verbatim) so a user evaluating which template to install reads the same purpose/scope here as they would in Setup — do not paraphrase or shorten that product copy. For the two Stage 2 agent templates, follow the verbatim product copy with one short trailing `Setup:` line stating what installing does (`Setup: creates the agent from this template and activates a version.`) so a single row carries purpose, scope, and the install action together. When raising `AskUserQuestion`, put that same Description text (product copy + the `Setup:` line) in each option's `description` field so the picker carries the detail too. Do NOT show placeholder features that cannot be executed.
 
 **Report file (harness / non-interactive runs).** If a `${outputDir}` is provided (via the harness's generated-file location directive), write the menu emission (attribution header + feature table with status + delegation targets + dependency signal + the multi-select prompt itself) to `${outputDir}/report.md` **before** raising `AskUserQuestion` — so the report file always exists even when the harness parks at the confirmation gate. Overwrite the same file after each feature completes with the updated status table. Skip these writes when running interactively for a user in a chat surface — write only when `${outputDir}` was passed as an explicit destination.
 
 ### 4. Delegate to child skills in dependency order
 
-**Studio-first rule (unconditional).** If Agentforce Studio enablement (#1) is in the user's selection and not already done, run it **first**, always — regardless of the order the user listed their numbers in. Both the Fulfiller Agent (#2) and Employee Agent (#3) lifecycles depend on Studio being enabled and will fail if attempted first. Reorder the queue silently so Studio runs before either agent lifecycle. This rule is non-negotiable and applies whether the user selected two features (Studio + one agent) or all three.
+**Studio-first rule (unconditional).** If Agentforce Studio enablement (#1) is in the user's selection and not already done, run it **first**, always — regardless of the order the user listed their numbers in. Both the Fulfiller Agent (#2) and Employee Agent (#3) depend on Studio being enabled and will fail if attempted first. Reorder the queue silently so Studio runs before either agent. This rule is non-negotiable and applies whether the user selected two features (Studio + one agent) or all three.
 
 **User-order rule (between #2 and #3 only).** Fulfiller Agent (#2) and Employee Agent (#3) are independent of each other — neither depends on the other. If **both** are selected, run them in the order the user listed them (default 2 → 3 when unspecified). This rule applies **only** to the ordering between #2 and #3; it never overrides the Studio-first rule above.
 
 | # | Feature | Child Skill |
 |---|---------|-------------|
-| 1 | Agentforce Studio enablement | `service-itsm-agentic-setup-agentforce-studio-configure` |
-| 2 | Fulfiller Agent lifecycle | `service-itsm-agentic-setup-fulfiller-agent-configure` |
-| 3 | Employee Agent lifecycle (broad or specialized template) | `service-itsm-agentic-setup-employee-agent-configure` |
+| 1 | Agentforce Studio enablement (Foundation for both agents) | `service-itsm-agentic-setup-agentforce-studio-configure` |
+| 2 | IT Service Fulfiller Agent | `service-itsm-agentic-setup-fulfiller-agent-configure` |
+| 3 | IT Service Employee Agent | `service-itsm-agentic-setup-employee-agent-configure` |
 
 `service-itsm-agentic-setup-agentforce-studio-configure` performs its own read-and-classify
 preflight (reading live toggle state before writing) rather than delegating to
@@ -91,15 +97,26 @@ When the user says they're done (or all available features are configured), pres
 
 ---
 
-## Feature Dependencies & Recommended Order
+## Setup Stages & Recommended Order
+
+Setup runs in **two sequential stages**. Stage 1 (enable platform features) must complete before
+Stage 2 (install & activate agent templates).
 
 ```text
-1. Agentforce Studio enablement   (foundation — org-level Agentforce and Einstein GenAI toggles)
-2. Fulfiller Agent lifecycle      (create, commit, activate the IT Service Fulfiller agent)
-3. Employee Agent lifecycle       (create, commit, activate the IT Service Employee agent)
+Stage 1 — Foundation: enable platform features
+  1. Agentforce Studio enablement (Foundation for both agents)   (turn ON org-level Agentforce + Einstein GenAI feature toggles)
+
+Stage 2 — Agent templates: install & activate   (only after Stage 1)
+  2. IT Service Fulfiller Agent     (install from template, commit, and activate the agent)
+  3. IT Service Employee Agent      (install from template, commit, and activate the agent)
 ```
 
-Agentforce Studio enablement is the foundation: it turns on the org-level Agentforce and Einstein GenAI features that both the Fulfiller and Employee agents depend on. Configure Studio first — attempting to create or activate either agent before Studio is enabled will fail. Fulfiller and Employee are independent siblings (neither depends on the other) — both can be selected together and run in either order after Studio.
+Stage 1 (Agentforce Studio enablement) is the **foundation**: it turns on the org-level Agentforce
+and Einstein GenAI feature toggles that both the Fulfiller and Employee agents are **built on top
+of**. Enable it first — attempting to install or activate either agent before this foundation is
+enabled will fail. The two Stage 2 items (Fulfiller and Employee) are independent siblings (neither
+depends on the other) — both can be selected together and installed in either order once Stage 1 is
+done.
 
 ---
 
@@ -115,8 +132,8 @@ Agentforce Studio enablement is the foundation: it turns on the org-level Agentf
 - NEVER advance to the next feature in the queue if the current one failed or only partially
   succeeded — stop and surface the failure in plain language instead
 - If Agentforce Studio enablement reports the org lacks the Agentforce license (`accessCheck`), STOP
-  the whole flow — this is a license/edition prerequisite no API can grant, and neither the
-  Fulfiller nor the Employee Agent lifecycle can succeed without it
+  the whole flow — this is a license/edition requirement no API can grant, and neither the
+  Fulfiller nor the Employee Agent can succeed without it
 - ALWAYS confirm the target org before delegating to any child skill, and state that the org will be modified
 - Do NOT expose internal technical jargon in user-facing output. This includes Salesforce record
   IDs and org IDs, raw HTTP status codes (403, 500, …), API error codes (`FUNCTIONALITY_NOT_ENABLED`,
@@ -137,6 +154,7 @@ Before emitting any menu or summary in this skill, mentally confirm each of the
 - [ ] Only features with a working child skill are shown; placeholder features are hidden
 - [ ] The feature menu is presented as a multi-select (single-select only if the user has already named a specific feature)
 - [ ] Each feature row's `Status` column reflects the actual tracked state from the conversation (`Not done`, `In progress`, or `Done`) — not a hard-coded default
+- [ ] Each feature row's `Description` matches the Salesforce Setup → Agentforce for IT Service page wording (Fulfiller and Employee agent-template descriptions verbatim, not paraphrased), the two Stage 2 rows end with the short `Setup:` install line, and the `AskUserQuestion` option descriptions carry the same text
 - [ ] For a completion summary, the header line and closing line are chosen by the rubric in `examples/output-templates.md` (all `Done` → *Complete*; any `Not done`/`In progress` → *Finished*)
 - [ ] A feature is being configured only because the user explicitly selected it (or is being walked through sequentially with confirmation under an "all" / "everything" request)
 - [ ] Studio enablement is verified done before delegating to the Fulfiller Agent or Employee Agent child skill
@@ -149,5 +167,5 @@ Before emitting any menu or summary in this skill, mentally confirm each of the
 
 | File | When to read |
 |------|--------------|
-| `examples/output-templates.md` | Behavior steps 2, 4, and 5 — feature menu (multi-select), post-feature progress, and completion summary text blocks |
+| `examples/output-templates.md` | Behavior steps 3, 5, and 6 — feature menu (two-stage, multi-select), post-feature progress, and completion summary text blocks |
 | `scripts/verify-child-verdict.mjs` | Behavior step 5 — run via `Bash` (`node`) to check a child skill's verdict deterministically before advancing the queue |

package/skills/service-itsm-agentic-setup-agentforce-coordinate/examples/output-templates.md

@@ -1,79 +1,95 @@
 # Output Templates — service-itsm-agentic-setup-agentforce-coordinate
 
-Emit one of these text blocks at the corresponding step in the workflow. Only features with a
-working child skill appear — hide placeholder rows.
+Emit one of these text blocks at the corresponding step in the workflow. Setup is presented as
+**two sequential stages** — Stage 1 (enable platform features) must finish before Stage 2 (install
+& activate agent templates). Only items with a working child skill appear — hide placeholder rows.
 
-## Feature menu (Behavior step 2)
+## Feature menu (Behavior step 3)
 
 ```text
 Agentforce for ITSM Setup (via service-itsm-agentic-setup-agentforce-coordinate)
 
-Here are the features available for Agentforce ITSM. Select one or more to configure:
-
-┌───┬───────────────────────────────┬──────────────────────────────────────────────────┬──────────┐
-│ # │ Feature                       │ Description                                      │ Status   │
-├───┼───────────────────────────────┼──────────────────────────────────────────────────┼──────────┤
-│ 1 │ Agentforce Studio enablement  │ Turn on org-level Agentforce, Einstein GenAI,    │ Not done │
-│   │                               │ and IT Service agent features                    │          │
-│ 2 │ Fulfiller Agent lifecycle     │ Create the IT Service Fulfiller agent from       │ Not done │
-│   │                               │ template, commit, and activate a version         │          │
-│ 3 │ Employee Agent lifecycle      │ Create the IT Service Employee agent from        │ Not done │
-│   │                               │ template, commit, and activate a version         │          │
-└───┴───────────────────────────────┴──────────────────────────────────────────────────┴──────────┘
+Here are the features available for Agentforce ITSM. Set them up in two stages —
+Stage 1 (enable) must finish before Stage 2 (install & activate):
+
+┌───┬─────────┬──────────────────────────────┬────────────────────────────────────────────────────────┬──────────┐
+│ # │ Stage   │ Item                         │ Description                                            │ Status   │
+├───┼─────────┼──────────────────────────────┼────────────────────────────────────────────────────────┼──────────┤
+│ 1 │ Stage 1 │ Agentforce Studio enablement │ Turn on org-level Agentforce, Einstein GenAI, and IT   │ Not done │
+│   │         │ (Foundation for both agents) │ Service agent features                                 │          │
+│ 2 │ Stage 2 │ IT Service Fulfiller Agent   │ Automate actions and simplify critical asks for IT     │ Not done │
+│   │         │                              │ service fulfillers who work with incidents, problems,  │          │
+│   │         │                              │ change requests and more to resolve issues and         │          │
+│   │         │                              │ requests.                                              │          │
+│   │         │                              │ Setup: creates the agent from this template and        │          │
+│   │         │                              │ activates a version.                                   │          │
+│ 3 │ Stage 2 │ IT Service Employee Agent    │ Help employees quickly troubleshoot IT issues, raise   │ Not done │
+│   │         │                              │ service requests, and track their incidents with ease. │          │
+│   │         │                              │ Setup: creates the agent from this template and        │          │
+│   │         │                              │ activates a version.                                   │          │
+└───┴─────────┴──────────────────────────────┴────────────────────────────────────────────────────────┴──────────┘
 
 Reply with the numbers of the features you want to set up (one or more, e.g. `1` or `1, 2`).
+If you pick a Stage 2 template without Stage 1, I'll enable the Stage 1 foundation first.
 ```
 
-## Post-feature progress (Behavior step 4)
+Stage 1 (Agentforce Studio enablement) is the **foundation** — it enables the org-level platform
+features both agents are built on. Stage 2 items (the Fulfiller and Employee agents) are **installed
+from a template and activated**; they can be set up in either order once Stage 1 is done.
+
+## Post-feature progress (Behavior step 5)
 
-Example after Agentforce Studio enablement completes:
+Example after Stage 1 (Agentforce Studio enablement) completes:
 
 ```text
 Agentforce Studio — enabled successfully
 (via service-itsm-agentic-setup-agentforce-studio-configure)
 
-┌───┬───────────────────────────────┬──────────┐
-│ # │ Feature                       │ Status   │
-├───┼───────────────────────────────┼──────────┤
-│ 1 │ Agentforce Studio enablement  │ Done     │
-│ 2 │ Fulfiller Agent lifecycle     │ Not done │
-│ 3 │ Employee Agent lifecycle      │ Not done │
-└───┴───────────────────────────────┴──────────┘
-
-Agentforce Studio is enabled. Next up: create and activate the IT Service
-Fulfiller and Employee agents — the Fulfiller agent gives IT technicians an
-assistant for triage, case summaries, and record automations, while the
-Employee agent gives requesters self-service help with their own requests.
+┌───┬─────────┬──────────────────────────────┬─────────────┐
+│ # │ Stage   │ Item                         │ Status      │
+├───┼─────────┼──────────────────────────────┼─────────────┤
+│ 1 │ Stage 1 │ Agentforce Studio enablement │ Done        │
+│   │         │ (Foundation for both agents) │             │
+│ 2 │ Stage 2 │ IT Service Fulfiller Agent   │ Not done    │
+│ 3 │ Stage 2 │ IT Service Employee Agent    │ Not done    │
+└───┴─────────┴──────────────────────────────┴─────────────┘
+
+Stage 1 (foundation) is enabled. On to Stage 2 — install and activate the IT
+Service Fulfiller and/or Employee agents from their templates. The Fulfiller
+agent gives IT technicians an assistant for triage, case summaries, and record
+automations; the Employee agent gives requesters self-service help with their
+own requests.
 ```
 
-## Completion summary (Behavior step 5)
+## Completion summary (Behavior step 6)
 
-The completion summary fires either (a) after every feature completes, or (b) when the user says
-they are finished — even if some features are still `Not done`. When rendering:
+The completion summary fires either (a) after every item completes, or (b) when the user says they
+are finished — even if some items are still `Not done`. When rendering:
 
-- Substitute each feature's row with its actual tracked status: `Done`, `In progress`, or `Not done`.
-  Do NOT hard-code `Done`.
-- Choose the header line based on whether every feature is `Done`:
-  - All features `Done` → `Agentforce for ITSM Setup — Complete`
-  - Any feature still `Not done` or `In progress` → `Agentforce for ITSM Setup — Finished`
+- Substitute each row's actual tracked status: `Done`, `In progress`, or `Not done`. Do NOT
+  hard-code `Done`.
+- Choose the header line based on whether every item is `Done`:
+  - All items `Done` → `Agentforce for ITSM Setup — Complete`
+  - Any item still `Not done` or `In progress` → `Agentforce for ITSM Setup — Finished`
 - Choose the closing line based on state:
   - All `Done` → `Your Agentforce for ITSM setup is complete.`
-  - Otherwise → `You have finished the features you selected. The remaining features can be resumed later by re-invoking this orchestrator.`
+  - Otherwise → `You have finished the items you selected. The remaining items can be resumed later by re-invoking this orchestrator.`
 
-Example — user finished after only enabling Agentforce Studio (Fulfiller and Employee Agent lifecycles stayed `Not done`):
+Example — user finished after only enabling Agentforce Studio (the Stage 2 agents stayed `Not done`):
 
 ```text
 Agentforce for ITSM Setup — Finished
 (via service-itsm-agentic-setup-agentforce-coordinate)
 
-┌───────────────────────────────┬──────────┐
-│ Feature                       │ Status   │
-├───────────────────────────────┼──────────┤
-│ Agentforce Studio enablement  │ Done     │
-│ Fulfiller Agent lifecycle     │ Not done │
-│ Employee Agent lifecycle      │ Not done │
-└───────────────────────────────┴──────────┘
+┌───┬─────────┬──────────────────────────────┬─────────────┐
+│ # │ Stage   │ Item                         │ Status      │
+├───┼─────────┼──────────────────────────────┼─────────────┤
+│ 1 │ Stage 1 │ Agentforce Studio enablement │ Done        │
+│   │         │ (Foundation for both agents) │             │
+│ 2 │ Stage 2 │ IT Service Fulfiller Agent   │ Not done    │
+│ 3 │ Stage 2 │ IT Service Employee Agent    │ Not done    │
+└───┴─────────┴──────────────────────────────┴─────────────┘
 
-You have finished the features you selected. The remaining features can be
+You have finished the items you selected. The remaining items can be
 resumed later by re-invoking this orchestrator.
 ```

package/skills/service-itsm-agentic-setup-agentforce-studio-configure/SKILL.md

@@ -2,7 +2,7 @@
 name: service-itsm-agentic-setup-agentforce-studio-configure
 description: "Enable the Agentforce for IT Service Salesforce Go feature toggles (Agentforce Studio, Einstein Generative AI, the parent umbrella, and the Fulfiller/Employee agent templates) using the Salesforce CLI (sf). Turns ON org prefs via the Setup Discovery feature/{apiName}/enable Connect API route. Write-capable, idempotent, dependency-ordered, confirm-to-write required. Use when asked to enable Agentforce Studio, turn on Agentforce for IT Service, enable Einstein generative AI, or configure the org-level Agentforce for IT Service prerequisites. Triggers: enable agentforce studio, turn on agentforce for it service, enable einstein generative ai, configure agentforce org prefs. DO NOT TRIGGER: read-only prerequisite check (service-itsm-agentic-setup-agentforce-studio-validate), create/activate an agent (service-itsm-agentic-setup-fulfiller-agent-configure), or assigning permission sets."
 metadata:
-  version: "1.0"
+  version: "1.3"
   domains: ["Service", "Agentforce"]
   minApiVersion: "67.0"
   relatedSkills:
@@ -25,7 +25,7 @@ allowed-tools: |
 
 # Enable Agentforce for IT Service Prerequisites
 
-Enable the **Agentforce for IT Service** Salesforce Go feature toggles — **Einstein Generative AI**, **Agentforce Studio**, the **parent umbrella**, and the path-specific agent template (**Fulfiller** or **Employee**) — entirely through the **Salesforce CLI (`sf`)**. This is the **write-capable** step in a three-skill flow; every write goes through the Setup Discovery `POST /connect/setup/discovery/feature/{apiName}/enable` Connect API route — the only correct write path for these toggles. Each toggle is enabled **idempotently** (skipped if already `ENABLED`), dependencies are enabled first, and explicit confirmation is required before any write.
+Enable the **Agentforce for IT Service** Salesforce Go feature toggles — **Einstein Generative AI**, **Agentforce Studio**, the **parent umbrella**, and the path-specific agent template (**Fulfiller** or **Employee**) — entirely through the **Salesforce CLI (`sf`)**. These toggles are the **prerequisites for creating the Fulfiller/Employee agent**; this **write-capable** step turns them on via the Setup Discovery `POST /connect/setup/discovery/feature/{apiName}/enable` Connect API route. Each toggle is enabled **idempotently** (skipped if already `ENABLED`), dependencies are enabled first, and explicit confirmation is required before any write.
 
 | Step | Skill | What it does |
 |------|-------|--------------|
@@ -218,7 +218,6 @@ Substitute `<alias>` with the target org alias. `<agentType>` is `fulfiller` or
 | `updateOrgPref` → 500 `Invalid prefName` for an agent pref | Wrong write path — use the Setup Discovery `feature/{apiName}/enable` endpoint instead |
 | Auth error from `sf api request rest` | The target org's session needs re-authentication (`sf org login web`) |
 | Treating an auth/permission/empty-body read failure as "not wired" | Pass the captured `$?` as the classifier's 3rd arg — only a confirmed 404 is CANNOT-CONFIRM; anything else is ERROR (surface `rawError`, stop) |
-| Trusting the Phase-2 `blocked` list for the entire Phase-4 loop | It is a snapshot before any write — re-read + reclassify before each toggle attempt instead, or a dependency-blocked child gets reported FAILED even after its blocker was just cleared |
 | Reporting `ALL-ENABLED` because `pending` is empty | Also check `unconfirmed` — a required toggle missing from the response or with an unrecognized status is neither confirmed ENABLED nor NOT_ENABLED |
 | Re-deriving the per-feature / overall verdict in prose from the before/after JSON | Run `scripts/classify-final-report.mjs` — the aggregation is fixed comparison logic (authoring standard A9), not a judgment call |
 | Setting the feature-status request body in a shell variable in Phase 1 and expecting it in Phase 4/5 | Each `Bash` invocation may run in a fresh shell where the variable is unset, silently sending an empty body — persist it to `/tmp/feature-status-body.json` once and read it back with `--body "$(cat /tmp/feature-status-body.json)"` in every phase |
@@ -240,27 +239,33 @@ Substitute `<alias>` with the target org alias. `<agentType>` is `fulfiller` or
 
 ## Output Format
 
-Present the enablement report as:
+Present the enablement report as a **table** — this is **Stage 1 (Foundation)**, the platform
+enablement that Stage 2 (install & activate the agent) is built on. Each Status is one of
+ENABLED / ALREADY-ENABLED / FAILED / CANNOT-CONFIRM:
 
 ```text
-Agentforce for IT Service — Enable Prerequisites (via service-itsm-agentic-setup-agentforce-studio-configure)
+Agentforce for IT Service — Stage 1: Enable Platform Features (via service-itsm-agentic-setup-agentforce-studio-configure)
 
 Org:          <org-alias> (API v67.0)
 Agent path:   fulfiller | employee
 
-  [1] Einstein Generative AI ................. ENABLED | ALREADY-ENABLED | FAILED | CANNOT-CONFIRM
-  [2] Agentforce Studio ...................... ENABLED | ALREADY-ENABLED | FAILED | CANNOT-CONFIRM
-  [3] Agentforce for IT Service (parent) ..... ENABLED | ALREADY-ENABLED | FAILED | CANNOT-CONFIRM
-  [4] <path-specific template(s)> ............ ENABLED | ALREADY-ENABLED | FAILED | CANNOT-CONFIRM
+| # | Platform feature | Status |
+| --- | --- | --- |
+| 1 | Einstein Generative AI | <status> |
+| 2 | Agentforce Studio | <status> |
+| 3 | Agentforce for IT Service | <status> |
+| 4 | <path-specific toggle(s)> | <status> |
 
-Verdict: SUCCESS  |  PARTIAL  |  FAILED  |  CANNOT-CONFIRM  |  ERROR
+Verdict: SUCCESS | PARTIAL | FAILED | CANNOT-CONFIRM | ERROR
 
 Next steps:
-  - <If SUCCESS: "Org satisfies the prerequisites for the <path> agent. Create it via service-itsm-agentic-setup-fulfiller-agent-configure (fulfiller) / the employee-agent skill.">
+  - <If SUCCESS: "Stage 1 (foundation) complete — proceed to Stage 2: install + activate the <path> agent via service-itsm-agentic-setup-fulfiller-agent-configure (fulfiller) / the employee-agent skill.">
   - <If PARTIAL/FAILED/CANNOT-CONFIRM/ERROR: list the affected toggle(s) + reason (enableBlockedReasons, unconfirmed status, or read error) + remediation steps>
 ```
 
-Render `overall` and each feature's `finalStatus` from `scripts/classify-final-report.mjs` verbatim — do not recompute them. No files are produced beyond the temporary response captures used by the classifiers.
+Render `overall` and each feature's `finalStatus` from `scripts/classify-final-report.mjs` verbatim (substitute into each `<status>` cell) — do not recompute them. No files are produced beyond the temporary response captures used by the classifiers.
+
+Label rows exactly as the classifier emits them — never add `Requestor`, `Specialized`, or `parent`.
 
 ---
 

package/skills/service-itsm-agentic-setup-agentforce-studio-configure/references/cli-invocation.md

@@ -31,11 +31,13 @@ Every call this skill makes — read and write — is a plain
 |-----------|----------------|------------|
 | Einstein Generative AI | `sales-cloud-einstein-generative-ai` | none |
 | Turn on Agentforce Studio | `sales-cloud-agent-studio` | Einstein GenAI |
-| Agentforce for IT Service (parent umbrella) | `service-cloud-agentforce-for-itsm` | Studio, Einstein GenAI |
-| IT Service Fulfiller (template) | `service-cloud-it-fulfiller-agent` | parent umbrella |
-| IT Service Employee (template) | `service-cloud-requestor-agent` | parent umbrella |
+| Agentforce for IT Service | `service-cloud-agentforce-for-itsm` | Studio, Einstein GenAI |
+| IT Service Fulfiller Template | `service-cloud-it-fulfiller-agent` | parent umbrella |
+| IT Service Employee Template | `service-cloud-requestor-agent` | parent umbrella |
 | Specialized Agent Templates for Employee | `service-cloud-it-service-employee-agent` | parent umbrella |
 
+**Label rule (report output).** Render every toggle by its report label — `Einstein Generative AI`, `Agentforce Studio`, `Agentforce for IT Service`, `IT Service Fulfiller Template`, `IT Service Employee Template`, `Specialized Agent Templates for Employee` — verbatim, and identical across every report and both toggling skills (`-configure` and `-validate`). These match the first-column labels above, except the Studio row: its Go-page toggle reads "Turn on Agentforce Studio", but the rendered report label is simply `Agentforce Studio`. The `Template` suffix on the two agent-template toggles is the authoritative, deliberate report label — it intentionally differs from the shorter setup-page toggle caption (`IT Service Fulfiller` / `IT Service Employee`), the same way the Studio row's caption `Turn on Agentforce Studio` renders simply as `Agentforce Studio`. It marks these as the agent templates enabled at this stage, distinct from the installed agent that the agent-configure skills name `IT Service Fulfiller Agent` / `IT Service Employee Agent` (no `Template`) — do not simplify the report label to the bare caption. Never add an invented role qualifier such as "Requestor", "Specialized", or "parent" to a label. The fulfiller path shows one path-specific row (`IT Service Fulfiller Template`); the employee path shows two (`IT Service Employee Template` **and** `Specialized Agent Templates for Employee`) — never collapse them to a single row or disambiguate them with any other suffix.
+
 Enable order: Einstein GenAI → Studio → parent umbrella → path-specific
 template(s). The read response echoes unmet dependencies in
 `dependencyStatuses[]`; the classifier encodes this same order in `ORDER` so

package/skills/service-itsm-agentic-setup-agentforce-studio-configure/scripts/classify-enable-plan.mjs

@@ -64,12 +64,20 @@ const ORDER = {
   employee: [EINSTEIN, STUDIO, PARENT, REQUESTOR, SPECIALIZED],
 };
 
+// Report labels — the authoritative strings these reports render. The two
+// agent-template rows intentionally differ from their shorter Salesforce Go
+// setup-page toggle caption, the same way the Studio caption "Turn on
+// Agentforce Studio" renders as "Agentforce Studio": these toggles enable agent
+// *templates*, so their report label carries a deliberate "Template" suffix. By
+// design — do not simplify it to the bare caption. It is also distinct from the
+// installed agent the agent-configure skills create ("IT Service Fulfiller
+// Agent" / "IT Service Employee Agent", no "Template").
 const LABEL = {
   [EINSTEIN]: 'Einstein Generative AI',
   [STUDIO]: 'Agentforce Studio',
-  [PARENT]: 'Agentforce for IT Service (parent)',
-  [FULFILLER]: 'IT Service Fulfiller template',
-  [REQUESTOR]: 'IT Service Employee template',
+  [PARENT]: 'Agentforce for IT Service',
+  [FULFILLER]: 'IT Service Fulfiller Template',
+  [REQUESTOR]: 'IT Service Employee Template',
   [SPECIALIZED]: 'Specialized Agent Templates for Employee',
 };