@salesforce/afv-skills 1.44.0 → 1.45.0

package/skills/service-itsm-channels-coordinate/SKILL.md

@@ -1,16 +1,12 @@
 ---
 name: service-itsm-channels-coordinate
-description: "Top-level interactive coordinator for Employee Service (ITSM) channel setup. Presents menu of channel setup options (Teams, Slack, Swarming, Notifications, Portal) and delegates to the corresponding skill. Use this for: 'setup ITSM channels', 'configure employee service channels', 'set up service cloud communication channels', 'I want to configure ITSM integrations', or any general request for ITSM channel/integration setup where the user hasn't specified exactly which channel they want. DO NOT TRIGGER for requests that already name a specific channel or child skill (e.g. 'configure Teams', 'set up Slack', 'enable Swarming', 'configure ITSM notifications', 'create an employee portal') — route directly to the matching child skill instead."
+description: "Top-level interactive coordinator for Employee Service (ITSM) channel setup. Presents menu of channel setup options (Portal, Teams, Slack) and delegates to the corresponding skill. Use this for: 'setup ITSM channels', 'configure employee service channels', 'set up service cloud communication channels', 'I want to configure ITSM integrations', or any general request for ITSM channel/integration setup where the user hasn't specified exactly which channel they want. DO NOT TRIGGER for requests that already name a specific channel or child skill (e.g. 'configure Teams', 'set up Slack', 'create an employee portal', 'configure ITSM notifications') — route directly to the matching child skill instead."
 metadata:
   version: "1.0"
   domains: ["Service"]
-  mcpTools:
-    headless-360:
-      tools: ["dispatch"]
-      semver: ">=1.0.0"
+  minApiVersion: "66.0"
   relatedSkills:
     - "experience-portal-create"
-    - "service-itsm-swarming-configure"
     - "service-itsm-teams-configure"
     - "service-itsm-teams-debug"
     - "service-itsm-teams-employee-agent-configure"
@@ -24,16 +20,30 @@ Interactive coordinator that presents a menu of ITSM channel setup options and d
 
 ## Scope
 
-- **In scope**: Presenting the channel setup menu to the user. Delegating to child skills based on selection (Teams, Swarming, Portal). Validating prerequisites before delegation. Providing clear descriptions of each channel capability. **Notifications is the one exception** — no dedicated notifications child skill exists yet, so this coordinator enables the notification-channel org preferences inline for that choice (see Choice 4); those are the only setup-API writes it performs itself.
-- **Out of scope**: Directly calling setup APIs for any channel that has a dedicated child skill (Teams, Swarming, Portal — always delegate). Channel-specific configuration details beyond the initial enablement. User permission assignment. Post-setup testing.
+- **In scope**: Presenting the channel setup menu to the user. Delegating to child skills based on selection (Portal, Teams, Slack). Validating prerequisites before delegation. Providing clear descriptions of each channel capability.
+- **Out of scope**: Directly calling setup APIs for any channel — always delegate to the dedicated child skill. Channel-specific configuration details beyond the initial enablement. User permission assignment. Post-setup testing. ITSM notification preferences (a separate concern — handle those with the dedicated notification-preferences skill, not through this menu).
 
 ---
 
 ## Available Channel Setup Skills
 
-This coordinator can invoke five distinct channel setup skills:
+This coordinator can invoke three distinct channel setup skills:
 
-### 1. Microsoft Teams Setup
+### 1. Portal Setup
+**Skill:** `experience-portal-create`
+
+**What it does:**
+- Creates a Digital Experience portal for employee self-service
+- Supports Employee Service, Partner, and Customer portals
+
+**Prerequisites:**
+- Vary by portal type
+
+**Use when:** User wants to create a portal for employee self-service.
+
+---
+
+### 2. Microsoft Teams Setup
 **Skill:** `service-itsm-teams-configure`
 
 **What it does:**
@@ -54,12 +64,14 @@ a specific half): `service-itsm-teams-itdesk-configure` (fulfiller/IT Desk check
 `service-itsm-teams-itservice-configure` (employee/IT Service checklist),
 `service-itsm-teams-employee-agent-configure` (embedded "Ask AI Agent"), and
 `service-itsm-teams-debug` (diagnose a failing Teams setup — login, tab loading, agent, swarming, SSO).
+Swarming (collaborative problem-solving) is configured **inside** the Teams setup flow, not as a
+separate top-level channel option.
 
 ---
 
-### 2. Slack Setup
+### 3. Slack Setup
 **Skill:** the installed Slack ITSM setup skill — resolve it from the skills catalog at delegation
-time by name pattern (see Choice 2 in the workflow); do not hardcode a single skill name.
+time by name pattern (see Choice 3 in the workflow); do not hardcode a single skill name.
 
 **What it does:**
 - Enables Slack integration for ITSM (Employee Service / IT Service on Slack)
@@ -73,54 +85,6 @@ time by name pattern (see Choice 2 in the workflow); do not hardcode a single sk
 
 ---
 
-### 3. Swarming Setup
-**Skill:** `service-itsm-swarming-configure`
-
-**What it does:**
-- Enables the `service-cloud-swarming` Salesforce Go feature via headless-360's feature-enablement
-  Connect API
-- Sets the "Select a Collaboration Tool" picklist to `Teams` via
-  `PATCH /services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL` — fully automated, no
-  manual click required
-
-**Prerequisites:**
-- Microsoft Teams integration (Swarming requires Teams — run `service-itsm-teams-configure` first)
-
-**Use when:** User wants collaborative problem-solving for ITSM.
-
----
-
-### 4. Notifications Setup
-**Skill:** none yet — handled inline by this coordinator (see Choice 4)
-
-**What it does:**
-- Enables the master Notifications feature
-- Configures notification channels: Email, In-App, Slack, Teams
-
-**Prerequisites:**
-- Multi-channel Notifications feature enabled
-- View Setup + Customize Application permissions
-
-**Use when:** User wants to enable multi-channel notifications for ITSM events.
-
-**Note:** For demo, execute inline until dedicated skill is created.
-
----
-
-### 5. Portal Setup
-**Skill:** `experience-portal-create`
-
-**What it does:**
-- Creates a Digital Experience portal for employee self-service
-- Supports Employee Service, Partner, and Customer portals
-
-**Prerequisites:**
-- Vary by portal type
-
-**Use when:** User wants to create a portal for employee self-service.
-
----
-
 ## Workflow
 
 ### Step 1: Present Menu to User
@@ -132,32 +96,22 @@ I can help you set up ITSM channels. Which channel would you like to configure?
 
 **Choose one:**
 
-1. **Microsoft Teams Setup**
+1. **Portal Setup**
+   - Create Digital Experience portal for employee self-service
+   - Choose portal type during setup
+   - Prerequisites: Vary by portal type
+
+2. **Microsoft Teams Setup**
    - Enable Teams integration master toggle
    - Provision authentication infrastructure
    - Prerequisites: Teams ITSM licenses required
 
-2. **Slack Setup**
+3. **Slack Setup**
    - Enable Slack integration for ITSM
    - Configure Slack workspace connection
    - Prerequisites: Slack workspace with admin access
 
-3. **Swarming Setup**
-   - Enable Swarming for collaborative problem-solving
-   - Configure Swarming channels (requires Teams)
-   - Prerequisites: Teams integration + Swarming feature
-
-4. **Notifications Setup**
-   - Enable multi-channel notifications (Email, In-App, Slack, Teams)
-   - Configure notification delivery channels
-   - Prerequisites: Multi-channel Notifications feature
-
-5. **Portal Setup**
-   - Create Digital Experience portal for employee self-service
-   - Choose portal type during setup
-   - Prerequisites: Vary by portal type
-
-Please respond with the number (1, 2, 3, 4, or 5) of your choice.
+Please respond with the number (1, 2, or 3) of your choice.
 ```
 
 **Do NOT proceed** until the user provides a choice.
@@ -168,25 +122,35 @@ Please respond with the number (1, 2, 3, 4, or 5) of your choice.
 
 Based on user's choice, check prerequisites **before** delegating to child skills:
 
-#### For Choice 1 or 3 (Teams Integration):
+#### For Choice 2 (Teams Integration):
 1. Check if Teams master toggle API is accessible
 2. Attempt to query current toggle state
 3. If prerequisites fail, inform user about missing Teams ITSM licenses
 
-#### For Choice 2 or 4 (Notifications):
-1. Check if Notifications preference APIs are accessible
-2. Verify Multi-channel Notifications feature is available
-
 **If prerequisites fail:**
 - Explain what's missing (licenses, features, permissions)
-- Offer alternative choices (e.g., suggest #4 if Teams licenses missing)
+- Offer alternative choices (e.g., suggest Slack if Teams licenses missing)
 - Do NOT attempt to execute the chosen configuration
 
 ---
 
 ### Step 3: Delegate to Child Skill
 
-#### Choice 1: Microsoft Teams Setup
+#### Choice 1: Portal Setup
+
+**Delegation:**
+```text
+Invoke the experience-portal-create skill.
+```
+
+The portal creation skill will handle all clarifying questions (portal type, name, URL prefix, etc.).
+
+**After delegation:**
+"Success: Portal setup delegated to experience-portal-create skill. Follow the prompts to complete portal creation."
+
+---
+
+#### Choice 2: Microsoft Teams Setup
 
 **Delegation:**
 ```text
@@ -205,11 +169,11 @@ Next steps:
 
 Resolution:
 - Verify org has Teams ITSM licenses
-- Try option #4 (Notifications) instead"
+- Try option #3 (Slack) instead"
 
 ---
 
-#### Choice 2: Slack Setup
+#### Choice 3: Slack Setup
 
 **Resolve the delegation target deterministically from the skills catalog, then invoke the result.**
 Do not decide by prose guesswork — look the skill up:
@@ -230,105 +194,20 @@ Do not decide by prose guesswork — look the skill up:
 
 ---
 
-#### Choice 3: Swarming Setup
-
-**Delegation:**
-```text
-Invoke the service-itsm-swarming-configure skill.
-```
-
-**On success:**
-"Success: Swarming feature enabled, and the Collaboration Tool is now set to Teams — 'Set Teams as
-Collaboration Tool for Swarming' is fully complete, no manual click needed."
-
-**On failure:**
-"Failed: Swarming setup failed: [error details]
-
-Resolution:
-- Ensure Microsoft Teams integration is enabled first (use option #1)
-- Verify org has the Swarming feature entitlement"
-
----
-
-#### Choice 4: Notifications Setup
-
-**Inline enablement (in-scope exception — no dedicated notifications child skill exists yet).**
-Unlike the other choices, this branch enables the notification-channel org preferences itself. Issue
-the writes with `mcp__headless-360__dispatch` (`PATCH`, full `/services/data/vXX.0/...` path). When a
-dedicated `setup-itsm-notifications-*` child skill lands, delegate to it and drop this inline block.
-
-**Step 4.1: Enable Master Notifications Preference**
-```text
-PATCH /services/data/v66.0/setup/org/preferences/Notifications
-Body: {"desiredState": true}
-```
-
-**Step 4.2: Enable Individual Channels**
-```text
-PATCH /services/data/v66.0/setup/org/preferences/EmailNotifications
-Body: {"desiredState": true}
-
-PATCH /services/data/v66.0/setup/org/preferences/InAppNotifications
-Body: {"desiredState": true}
-
-PATCH /services/data/v66.0/setup/org/preferences/SlackNotifications
-Body: {"desiredState": true}
-
-PATCH /services/data/v66.0/setup/org/preferences/TeamsNotifications
-Body: {"desiredState": true}
-```
-
-**On success:**
-"Success: All notification channels enabled:
-- Email Notifications
-- In-App Notifications
-- Slack Notifications
-- Teams Notifications
-
-Next steps:
-- Create notification definitions at: Setup → Service → Notifications
-- Configure ITSM event triggers
-- Customize message templates"
-
-**On failure:**
-"Failed: Notification channels setup failed: [error details]
-
-Resolution:
-- Verify org has Multi-channel Notifications feature
-- Confirm you have Customize Application permission"
-
----
-
-#### Choice 5: Portal Setup
-
-**Delegation:**
-```text
-Invoke the experience-portal-create skill.
-```
-
-The portal creation skill will handle all clarifying questions (portal type, name, URL prefix, etc.).
-
-**After delegation:**
-"Success: Portal setup delegated to experience-portal-create skill. Follow the prompts to complete portal creation."
-
----
-
 ## Decision Tree
 
 ```text
 User requests ITSM channel setup
   ↓
-Present menu (5 options)
+Present menu (3 options)
   ↓
-User selects option (1-5)
+User selects option (1-3)
   ↓
 Validate prerequisites (optional)
   ↓
-  ├─ Choice 1: Invoke service-itsm-teams-configure
-  ├─ Choice 2: Resolve the Slack skill from the catalog, then invoke it (or manual instructions)
-  ├─ Choice 3: Invoke service-itsm-swarming-configure
-  ├─ Choice 4: Execute notifications setup inline (demo mode)
-  └─ Choice 5: Invoke experience-portal-create
+  ├─ Choice 1: Invoke experience-portal-create
+  ├─ Choice 2: Invoke service-itsm-teams-configure
+  └─ Choice 3: Resolve the Slack skill from the catalog, then invoke it (or manual instructions)
   ↓
 Report outcome to user
   ↓
@@ -343,38 +222,32 @@ Suggest next steps
 |---|---|
 | Always present options before proceeding | User may not know what's possible or what their org supports |
 | Validate prerequisites before delegating | Catch licensing/feature gaps early before invoking child skills |
-| Choice 4 uses manual API calls, not a child skill | No existing skill for "notifications without specific channels" |
+| Notifications are not a menu option | ITSM notification preferences are a separate concern; route those requests to the dedicated notification-preferences skill, not through this coordinator |
+| Swarming is configured inside Teams, not a top-level channel | Swarming requires Teams; it is handled within the Teams setup flow (`service-itsm-teams-configure`), so it is not offered as a separate menu option |
 | Do not retry failed delegations | Child skills handle their own retries; surfacing error to user for decision |
-| Partial success is acceptable | If Teams succeeds but Notifications fails, user can retry Notifications separately |
+| Partial success is acceptable | If Teams succeeds but Slack fails, user can retry Slack separately |
 
 ---
 
 ## Prerequisites by Choice
 
-### Choice 1: Teams Setup
+### Choice 1: Portal Setup
+- Vary by portal type (see experience-portal-create skill)
+
+### Choice 2: Teams Setup
 - Teams ITSM licenses
 - Setup admin permissions
 
-### Choice 2: Slack Setup
+### Choice 3: Slack Setup
 - Slack workspace with admin access
 - Org has Slack integration enabled
 
-### Choice 3: Swarming Setup
-- Microsoft Teams integration (required for Swarming — run Choice 1 first)
-
-### Choice 4: Notifications Setup
-- Multi-channel Notifications feature enabled
-- View Setup + Customize Application permissions
-
-### Choice 5: Portal Setup
-- Vary by portal type (see experience-portal-create skill)
-
 ---
 
 ## Error Handling
 
 ### If user provides invalid choice:
-"Please choose a valid option: 1, 2, 3, 4, or 5."
+"Please choose a valid option: 1, 2, or 3."
 
 ### If prerequisites check fails:
 "I've detected that your org is missing [specific requirement]. 
@@ -389,19 +262,13 @@ I recommend choosing [alternative option] instead, which works with your current
 ### If user is unsure which to choose:
 "Let me help you decide:
 
-- **Do you want to enable communication channels?**
-  - Microsoft Teams → Choose #1
-  - Slack → Choose #2
-  - Both → Run #1, then #2
-
-- **Do you want collaborative problem-solving?**
-  - Swarming (requires Teams) → Choose #1 first, then #3
-
-- **Do you want notifications for ITSM events?**
-  - Multi-channel notifications → Choose #4
-
 - **Do you want a portal for employee self-service?**
-  - Digital Experience portal → Choose #5"
+  - Digital Experience portal → Choose #1
+
+- **Do you want to enable a communication channel?**
+  - Microsoft Teams → Choose #2
+  - Slack → Choose #3
+  - Both → Run #2, then #3"
 
 ---
 
@@ -410,8 +277,8 @@ I recommend choosing [alternative option] instead, which works with your current
 After completing channel setup via this coordinator:
 
 - **Configure channel-specific settings** — customize each channel's behavior
-- **Create notification definitions** — configure ITSM event triggers (if Notifications selected)
 - **Set up Azure AD** — required for Teams (if Teams selected)
+- **Configure ITSM notifications** — use the dedicated notification-preferences skill (separate from this coordinator)
 - **Test channels** — verify each channel is working
 
 To modify later:
@@ -442,16 +309,14 @@ then leaves without replying" has two fixable causes — auth mode left ON (→
 ## API Type Classification
 
 This coordinator:
-- **Does NOT call APIs directly** (except for Choice 4 demo mode) — it delegates to child skills
+- **Does NOT call APIs directly** — it delegates to child skills
 - **Uses interactive menu** for user selection
 - **Child skills handle all API calls**
 
 Child skills used:
+- `experience-portal-create` — Connect API
 - `service-itsm-teams-configure` — headless-360 (Salesforce Go feature-enablement Connect API)
 - Slack ITSM setup skill (resolved from catalog by name pattern) — child skill handles its own API calls
-- `service-itsm-swarming-configure` — headless-360 (Salesforce Go feature-enablement Connect API)
-- Notifications — no dedicated child skill yet; handled inline via Connect API (see Choice 4)
-- `experience-portal-create` — Connect API
 
 ---
 
@@ -463,10 +328,12 @@ Child skills used:
 
 3. **Some skills may not exist yet** — if a skill is not found, provide manual setup instructions so the user isn't blocked.
 
-4. **Choice 4 (Notifications) executes inline** — no dedicated notifications child skill exists yet, so this coordinator enables the notification-channel preferences directly (see Choice 4). When such a skill lands, delegate to it and drop the inline block.
+4. **Notifications are handled elsewhere** — ITSM notification preferences are not a channel-menu option; route those requests to the dedicated notification-preferences skill.
+
+5. **Swarming lives inside Teams** — Swarming is not a standalone menu option; it is configured within the Teams setup flow (`service-itsm-teams-configure`), since it requires Teams.
 
-5. **Prerequisites vary by channel** — each channel has different licensing and feature requirements.
+6. **Prerequisites vary by channel** — each channel has different licensing and feature requirements.
 
-6. **No retry logic** — this coordinator doesn't retry failed operations. Surface the error and let user decide next steps.
+7. **No retry logic** — this coordinator doesn't retry failed operations. Surface the error and let user decide next steps.
 
-7. **Educational role** — help users understand what each channel does and which prerequisites they need.
+8. **Educational role** — help users understand what each channel does and which prerequisites they need.