@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-incident-mgmt-configure/references/mcp-invocation.md

@@ -0,0 +1,225 @@
+# MCP invocation reference — service-itsm-incident-mgmt-configure
+
+This skill toggles the **master ITSM Incident Management** org preference through the Salesforce-hosted **Headless-360 MCP server** (server key `headless-360`). The master pref reads and writes via the **Setup Discovery Connect API** (`/services/data/v67.0/connect/setup/discovery/*`, `apiName = service-cloud-itsm-incident`); enabling it cascades the sub-preferences on server-side, so the common enablement flow is a single POST.
+
+Every read and every write dispatches through the four meta-tools that Headless-360 exposes: `discover`, `describe`, `dispatch`, `dispatch_readonly`. URLs are addressed by `url` + `method` on the dispatch tools — **not** by `operation_id`.
+
+Public reference: `https://developer.salesforce.com/docs/platform/hosted-mcp-servers/references/reference/headless-360-mcp.html`
+
+## Tool argument shape (IMPORTANT)
+
+Both `mcp__headless-360__dispatch` and `mcp__headless-360__dispatch_readonly` take:
+
+```json
+{
+  "url": "/services/data/v67.0/...",
+  "method": "GET|POST|PATCH|...",
+  "body": { /* optional; POST/PATCH only */ },
+  "query_params": { /* optional; alternative to inline querystring */ }
+}
+```
+
+They do **not** take `{operation_id, arguments}` — that shape returns `INVALID_ARGUMENT: 'url' and 'method' are required`. Every example in this file uses the `{url, method, body?, query_params?}` shape.
+
+`mcp__headless-360__describe` takes `{id: "<sor_id>"}` — a different arg name from the dispatch tools.
+
+## MCP client registration
+
+The MCP client (adk-eval, Claude Code session, Postman, Cursor, etc.) needs an `additionalServers.headless-360` entry pointing at the correct env URL. Working example (from `packages/adk-eval/mcp-config.json`):
+
+```json
+{
+  "enabled": true,
+  "toolsets": ["data", "orgs", "metadata", "testing", "users"],
+  "additionalServers": {
+    "headless-360": {
+      "disabled": false,
+      "timeout": 900000,
+      "type": "streamableHttp",
+      "url": "<pick from Server URLs table below>",
+      "autoApprove": ["discover", "describe", "dispatch_readonly"]
+    }
+  }
+}
+```
+
+Server URLs by environment:
+
+| Environment | URL |
+|-------------|-----|
+| Production | `https://api.salesforce.com/platform/mcp/v1/platform/headless-360` |
+| Sandbox / Scratch | `https://api.salesforce.com/platform/mcp/v1/sandbox/platform/headless-360` |
+| Login-restricted org (`/d/` form) | `https://api.salesforce.com/platform/mcp/v1/d/{mydomain}/{develop\|scratch}/platform/headless-360` |
+
+The `/d/` variant is required for orgs that have disabled login through `login.salesforce.com` / `test.salesforce.com`. `{mydomain}` is the org's My Domain prefix — the value before `.my.salesforce.com` in the org's login host.
+
+Notes:
+
+- **`timeout` is milliseconds** in the Vibes SDK contract, not seconds. `900000` = 15 minutes; a smaller value will kill `discover` / `dispatch` calls prematurely.
+- `dispatch` is intentionally omitted from `autoApprove` — mutations should be user-approved per invocation. `dispatch_readonly` is auto-approved because it cannot change state.
+- The URL's env segment (`platform` / `sandbox` / `develop` / `scratch`) must match the target org's tier and the tier of the ECA used for OAuth. A prod URL with a sandbox-tier ECA (or vice versa) will cause `OAUTH_AUTHORIZATION_BLOCKED` errors.
+
+## External Client App setup (one-time, org-admin task)
+
+`headless-360` requires an **External Client App** (ECA) with:
+
+- OAuth Scopes (Salesforce scope names): `MCP`, `RefreshToken`
+- OIDC `.well-known` names for the same scopes: `mcp_api`, `refresh_token`
+- **Issue JSON Web Token (JWT)-based access tokens for named users**: on
+- All other security options: off unless the org requires them
+- PKCE required (Authorization Code + PKCE grant only)
+- Callback URL: one per MCP client (see below)
+
+Callback URLs by client:
+
+| Client | Callback URL |
+|--------|--------------|
+| Claude.ai (web app) | `https://claude.ai/api/mcp/auth_callback` |
+| Claude Code CLI | `http://localhost:<port>/callback` — port matches the `oauth.callbackPort` set on the `mcpServers.<name>` entry in the Claude Code MCP client configuration. Register the same port on the ECA. Default port when unset is dynamic (a random high port each session), which will fail against a pre-registered ECA — always set `callbackPort` explicitly. |
+| Postman (HTTP) | `https://oauth.pstmn.io/v1/callback` |
+| Postman (browser) | `https://oauth.pstmn.io/v1/browser-callback` |
+| Cursor (recent) | `http://localhost:8787/callback` |
+| Cursor (legacy) | `cursor://anysphere.cursor-mcp/oauth/callback` |
+
+Propagation: an ECA can take up to **30 minutes** to become operational after Create. Server activation (Setup → MCP Servers → `headless-360` → Activate) can take up to **2 minutes**.
+
+Auth URLs (used by the MCP client at OAuth time):
+
+| Env | Auth URL | Token URL |
+|-----|----------|-----------|
+| Production | `https://login.salesforce.com/services/oauth2/authorize` | `https://login.salesforce.com/services/oauth2/token` |
+| Sandbox / Scratch | `https://test.salesforce.com/services/oauth2/authorize` | `https://test.salesforce.com/services/oauth2/token` |
+| Login-restricted org (`/d/` form) | `https://{mydomain}.my.salesforce.com/services/oauth2/authorize` | `https://{mydomain}.my.salesforce.com/services/oauth2/token` |
+
+For the `/d/` variant, the Auth/Token URLs point at the org's My Domain host directly — not at `login.salesforce.com` / `test.salesforce.com`. This is why the `/d/` server URL exists in the first place: those orgs have login through the shared hosts disabled.
+
+Header prefix on tool calls: `Bearer <access_token>`. The org against which each tool call runs is derived from the JWT issuer — callers do not pass an orgId in the body.
+
+## API contract — master ITSM Incident Management toggle
+
+**User-visible label**: Enable Incident Management. **Backing**: **Setup Discovery Connect API** at `/services/data/v67.0/connect/setup/discovery/*`. **Identifier on the wire**: `apiName = service-cloud-itsm-incident`.
+
+**Access guard**: requires View Setup + Setup Admin (`UserPermissions.CustomizeApplication`). Org must have `IncidentMgmt.orgHasITSMOrgPermission`. Does not require the Headless-360 Aura dispatcher — this pref routes entirely through the Connect API.
+
+Always call `describe` at runtime to confirm the exact schema — the examples here are working expectations, not contracts.
+
+### Read endpoint
+
+`GET /services/data/v67.0/connect/setup/discovery/features`
+
+This is the Setup Discovery **collection endpoint** — it returns the full feature catalog (~763 entries, ~1.1 MB on a well-loaded org) and does not honor an `?apiName=` filter server-side. Filter the returned array client-side to the element where `apiName == "service-cloud-itsm-incident"` and read its `status` field (`ENABLED` / `NOT_ENABLED` / …).
+
+```json
+{
+  "url": "/services/data/v67.0/connect/setup/discovery/features",
+  "method": "GET"
+}
+```
+
+Trimmed element after client-side filtering:
+
+```json
+{
+  "apiName": "service-cloud-itsm-incident",
+  "title": "Incident Management",
+  "tag": "ITSM_CLOUD",
+  "status": "ENABLED",
+  "completedConfigStepCount": 2,
+  "totalConfigStepCount": 17
+}
+```
+
+### Write endpoints
+
+`POST /services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-incident/enable` and `POST .../disable`
+
+Both endpoints take an empty body. The enable path flips the master to `ENABLED`; the disable path flips it to `NOT_ENABLED`. Verified: `GET` on either path returns `HTTP 405 METHOD_NOT_ALLOWED. Allowed are POST` — confirming both routes are registered as POST-only writers.
+
+Enable:
+
+```json
+{
+  "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-incident/enable",
+  "method": "POST",
+  "body": {}
+}
+```
+
+Disable:
+
+```json
+{
+  "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-incident/disable",
+  "method": "POST",
+  "body": {}
+}
+```
+
+Response: `201 {"success": true}` on both routes (some builds may return `200`/`204` with an echoed feature summary or empty body — call `describe` at runtime to confirm the exact response schema).
+
+Disabling then re-enabling on the same org preserves `completedConfigStepCount` — the server restores prior progress instead of resetting it.
+
+### Idempotency contract
+
+Read the feature via the collection GET; filter to `apiName == "service-cloud-itsm-incident"`; compare `status` against the requested state; skip the POST when they already match (`status == "ENABLED"` for an enable request, or `status != "ENABLED"` for a disable request); verify by re-reading the feature after writing.
+
+## Confirm-to-write checkpoint (REQUIRED)
+
+Before dispatching any POST, present the target payload via `AskUserQuestion` as `(Master Incident Management: <current> → <requested>)` and require an explicit "yes" before proceeding. Proceed to write ONLY on explicit "yes". On "no", stop and report the current state without writing.
+
+## Error taxonomy
+
+Errors observed on Headless-360 for this surface:
+
+- **`OAUTH_AUTHORIZATION_BLOCKED: Cross-org OAuth flows are not supported for this external client app`** during the OAuth handshake (before any `tools/call`) — the ECA the MCP client is using lives in a different org than the JWT-issuing target org, and that ECA has cross-org OAuth disabled (the default). Fixes, in order of preference:
+    1. Create/activate the ECA **inside the target org** (Setup → External Client Apps in that org). Self-contained; no cross-org allowance needed.
+    2. Confirm the target org's My Domain matches the `{mydomain}` segment in the server URL exactly, and matches the host in the Auth/Token URLs the ECA is registered against — an ECA registered against `login.salesforce.com` cannot mint tokens for a My-Domain host, and vice versa.
+    3. Only if (1) is not possible: reconfigure the source-org ECA to permit cross-org OAuth.
+- **`401 Unauthorized`** on `initialize` or any `tools/call` — ECA not propagated yet (takes up to 30 minutes), wrong scopes on the ECA (must be `mcp_api` + `refresh_token`), or the access token has expired. Surface verbatim.
+- **`404 Not Found`** on `initialize` — the `headless-360` server is not activated on the org (Setup → MCP Servers → Activate — takes up to 2 minutes), or the server URL's env segment (`platform` / `sandbox` / `develop` / `scratch`) doesn't match the target org's tier.
+- **`403 Forbidden`** on `discover` / `describe` — corpus gate closed (`enableHeadless360CorpusAccess` off for the org). The corpus gate is required for semantic search; if the org hasn't opened it, `dispatch*` will still work if you already know the URL directly.
+- **`403 Forbidden`** on `dispatch_readonly` / `dispatch` — the calling user lacks View Setup + Setup Admin, or the org lacks `IncidentMgmt.orgHasITSMOrgPermission`.
+- **`ROUTE_NOT_FOUND`** on `/services/data/*` — the exact URL isn't registered — usually a typo, wrong path segment, or a wrong `vXX.0` API version. Re-check the URL and API version.
+- **`HTTP 405 METHOD_NOT_ALLOWED. Allowed are POST`** on a write URL — the caller used `GET` instead of `POST` against `.../enable` or `.../disable`. Both write routes are POST-only.
+
+## Worked example — Toggle master Incident Management
+
+Step 1: Read current state via `dispatch_readonly`.
+
+```json
+{
+  "url": "/services/data/v67.0/connect/setup/discovery/features",
+  "method": "GET"
+}
+```
+
+Response (after client-side filtering on `apiName == "service-cloud-itsm-incident"`):
+
+```json
+{
+  "apiName": "service-cloud-itsm-incident",
+  "title": "Incident Management",
+  "tag": "ITSM_CLOUD",
+  "status": "NOT_ENABLED",
+  "completedConfigStepCount": 0,
+  "totalConfigStepCount": 17
+}
+```
+
+Step 2: Confirm-to-write — present `(Master Incident Management: NOT_ENABLED → ENABLED)` and require "yes".
+
+Step 3: Write via `dispatch`.
+
+```json
+{
+  "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-incident/enable",
+  "method": "POST",
+  "body": {}
+}
+```
+
+Response: `201 {"success": true}`.
+
+Step 4: Verify via `dispatch_readonly` — re-read the collection endpoint, filter to `apiName == "service-cloud-itsm-incident"`, and confirm `status == "ENABLED"`.
+
+**Disable direction**: substitute `.../disable` for `.../enable` in step 3; substitute `NOT_ENABLED` for `ENABLED` in the verify step and in the confirm-to-write tuple.

package/skills/service-itsm-incident-priority-configure/SKILL.md

@@ -2,7 +2,7 @@
 name: service-itsm-incident-priority-configure
 description: "Configures the Incident Priority Matrix for Salesforce ITSM through the sf CLI — enabling or disabling the matrix, shaping the Impact x Urgency grid that derives Priority on Incident records, toggling the manual-override preference, and reading or setting the default fallback priority. Reads every value before writing, is idempotent, and requires explicit user confirmation before any mutation. Use when the user wants to view, enable, disable, set up, seed, add to, change, or remove priority matrix configuration for Incident records, change the default incident priority, or asks about incident priority setup, impact/urgency mapping, override, or the ITSM incident priority matrix. DO NOT TRIGGER for Problem or ChangeRequest priority matrices, Case priority fields, standard Priority picklists outside ITSM, SLA or milestone configuration, or enabling Incident Management itself (use the service-itsm-incident-mgmt-configure skill)."
 metadata:
-  version: "1.0"
+  version: "1.3"
   domains: ["Service"]
   minApiVersion: "67.0"
   cliTools:
@@ -11,8 +11,6 @@ metadata:
   accessCheck:
     - type: "userPerm"
       value: "CustomizeApplication"
-    - type: "orgPref"
-      value: "ITSMIncidentMgmtEnabled"
 allowed-tools: |
   Read AskUserQuestion Bash
 ---
@@ -39,9 +37,14 @@ Writes are **idempotent** (skipped when the current state already matches the ta
 
 1. `sf` CLI ≥ 2.60 (verify with `sf --version`).
 2. The target org is authenticated with `sf` — one of `sf org list` should show it as `Connected`.
-3. Incident Management is enabled on the org (`ITSMIncidentMgmtEnabled` org pref). Confirmed at
-   preflight time via the Incident `describe`; if it 404s, direct the user to enable Incident
-   Management first (use the `service-itsm-incident-mgmt-configure` skill).
+3. Incident Management is enabled on the org — the master pref for the Service Cloud ITSM
+   Incident feature (Setup Discovery `apiName = service-cloud-itsm-incident`). Read directly
+   at preflight time via `GET /services/data/v67.0/connect/setup/discovery/features` and
+   filter to `apiName == "service-cloud-itsm-incident"` (the setup-org-preferences endpoint
+   for the master is not exposed on this surface — `IncidentMgmtEnabled` /
+   `ITSMIncidentMgmtEnabled` both 404). If `status != "ENABLED"`, delegate to
+   `service-itsm-incident-mgmt-configure` inline to enable it (that skill runs its own
+   read-before-write + confirm-to-write against the same route), then resume Phase 1.
 4. The calling user has `CustomizeApplication` (View Setup + Setup Admin).
 
 If any precondition is unmet, the CLI surfaces the raw error verbatim — **do not fabricate state,
@@ -56,6 +59,7 @@ details, the picklist extraction recipe, and gotchas live in `references/sf-cli-
 
 | Concern | Transport | HTTP status |
 |---------|-----------|-------------|
+| Master Incident Mgmt pref (read) | `sf api request rest` GET on `/services/data/v67.0/connect/setup/discovery/features`, filter `apiName == "service-cloud-itsm-incident"` for `status` | 200 |
 | Matrix enable flag (read/write) | `sf api request rest` on `/services/data/v67.0/setup/org/preferences/IncPriorityMatrixEnabled` | 200 |
 | Manual override (read/write) | `sf api request rest` on `/services/data/v67.0/setup/org/preferences/IncPriorityOverrideEnabled` | 200 |
 | Matrix rows (read) | `sf data query --use-tooling-api` on `ServiceOpPriorityConfig` | 200 |
@@ -86,19 +90,56 @@ Ask only what you cannot infer:
 
 All steps are sequential. **Always read before you write.** All calls go through `sf` CLI.
 
+### Phase 0 — Reuse what the session already knows
+
+Each Phase 1 / Phase 2 read below carries a **skip-if-already-known** clause. Before
+calling any `sf` command, check whether an earlier turn in this session already produced
+the same fact **from a successful `sf` invocation tied to the current `--target-org`**
+(a prior run of this skill, or an earlier `sf` call in the same conversation). Session
+context here is per `--target-org <alias>`, so a different alias is a different session.
+**An explicit user statement is NOT cache-eligible** — the picklist values, pref
+booleans, matrix rows, and fallback priority all drive client-side validation and
+duplicate prevention on Phase-4 mutations, so a mistaken or stale user assertion can
+bypass those safeguards and create invalid or duplicate rows. When the only source is
+a user statement (or you cannot identify a specific prior `sf` response), re-read.
+
+- **`sf --version`** — if the CLI version was already reported this session, skip step 1.
+- **Incident `describe` (active `Impact` / `Urgency` / `Priority` picklists)** — if the
+  Incident describe was already read for the current `--target-org` this session and the
+  three picklists are in context, skip step 2 and reuse them.
+- **`IncPriorityMatrixEnabled` / `IncPriorityOverrideEnabled` pref values** — if either
+  was already read this session AND has not been PATCHed since, skip its Phase-2 read.
+- **`ServiceOpPriorityConfig` rows** — if the current-org Incident rows were already
+  read this session AND no `POST` / `PATCH` / `delete` on `ServiceOpPriorityConfig` has
+  been dispatched since, skip step 5 and reuse the row list.
+- **`StandardValueSet:IncidentPriority` default** — if the fallback priority was already
+  read this session AND no `StandardValueSet:IncidentPriority` deploy has run since,
+  skip step 6.
+
+**When in doubt, re-check.** Skip only when the earlier fact is unambiguously in context
+AND the target-org alias has not changed AND no write elsewhere in the session could
+have invalidated it (Phase-4 writes in this skill are the primary invalidators — a
+PATCH on a pref, a POST/PATCH/delete on a `ServiceOpPriorityConfig` row, or a
+`StandardValueSet:IncidentPriority` deploy all bust the cache for the matching read).
+If the user hints at a different org (or a different alias), re-run the read. A wrong
+skip on a live org write is worse than a duplicated read.
+
 ### Phase 1 — Preflight
 
-1. `sf --version` to confirm the CLI is available.
-2. `sf api request rest "/services/data/v67.0/sobjects/Incident/describe" --method GET --target-org <alias>`. A **200** with `Impact` / `Urgency` / `Priority` picklist fields confirms Incident Management is enabled. Extract active picklist values for later validation. If the describe response is large, dispatch a subagent (haiku tier) to extract just the three picklists.
+1. *(Skip if `sf --version` was already reported this session — see Phase 0.)* `sf --version` to confirm the CLI is available.
+2. **Master Incident Management pref — direct read** *(Skip only if the master pref was
+   already read this session for the current `--target-org` AND the value was `ENABLED`
+   AND no write elsewhere in this session could have flipped it — see Phase 0.)* `sf api request rest "/services/data/v67.0/connect/setup/discovery/features" --method GET --target-org <alias>`. Parse the response and filter the `features[]` array to the element where `apiName == "service-cloud-itsm-incident"`; read its `status` field. If `status == "ENABLED"`, proceed to step 3. **If `status != "ENABLED"`, delegate to `service-itsm-incident-mgmt-configure` inline to enable the master pref** (that skill runs its own confirm-to-write against the same route), then re-read this step to verify `status == "ENABLED"` before continuing. If the delegation is declined by the user, halt — Priority Matrix cannot function while the master is off. This is a **direct read of the master pref**, not a proxy — the Incident describe check that follows is a secondary sanity check, not the master-state signal.
+3. *(Skip if the Incident describe for the current `--target-org` — including active `Impact` / `Urgency` / `Priority` picklists — is already in context this session — see Phase 0.)* `sf api request rest "/services/data/v67.0/sobjects/Incident/describe" --method GET --target-org <alias>`. A **200** with `Impact` / `Urgency` / `Priority` picklist fields is a secondary sanity check. Extract active picklist values for later validation. If the describe response is large, dispatch a subagent (haiku tier) to extract just the three picklists.
 
 ### Phase 2 — Show current state (read-only)
 
 Dispatch these reads (all expected to return 200):
 
-3. `sf api request rest "/services/data/v67.0/setup/org/preferences/IncPriorityMatrixEnabled" --method GET --target-org <alias>` — matrix enable flag. Body: `{"isPreferenceEnabled": <bool>}`.
-4. `sf api request rest "/services/data/v67.0/setup/org/preferences/IncPriorityOverrideEnabled" --method GET --target-org <alias>` — manual-override flag. Same body shape.
-5. Matrix rows — `sf data query --use-tooling-api --target-org <alias> --query "SELECT Id, DeveloperName, ReferenceObject, Urgency, Impact, Priority FROM ServiceOpPriorityConfig WHERE ReferenceObject = 'Incident'"`. Returns zero or more rows. `DeveloperName` is required so the add step can derive a fresh unique suffix.
-6. Default fallback priority — `sf api request rest "/services/data/v67.0/tooling/query/?q=SELECT+Id,MasterLabel,Metadata+FROM+StandardValueSet+WHERE+MasterLabel='IncidentPriority'" --method GET --target-org <alias>`. Read `records[0].Metadata.standardValue`, find the entry with `default: true`, take its `valueName` — that is the fallback priority.
+3. *(Skip if `IncPriorityMatrixEnabled` for the current `--target-org` was already read this session AND has not been PATCHed since — see Phase 0.)* `sf api request rest "/services/data/v67.0/setup/org/preferences/IncPriorityMatrixEnabled" --method GET --target-org <alias>` — matrix enable flag. Body: `{"isPreferenceEnabled": <bool>}`.
+4. *(Skip if `IncPriorityOverrideEnabled` for the current `--target-org` was already read this session AND has not been PATCHed since — see Phase 0.)* `sf api request rest "/services/data/v67.0/setup/org/preferences/IncPriorityOverrideEnabled" --method GET --target-org <alias>` — manual-override flag. Same body shape.
+5. *(Skip if the Incident `ServiceOpPriorityConfig` rows for the current `--target-org` were already read this session AND no POST / PATCH / delete on this SObject has been dispatched since — see Phase 0.)* Matrix rows — `sf data query --use-tooling-api --target-org <alias> --query "SELECT Id, DeveloperName, ReferenceObject, Urgency, Impact, Priority FROM ServiceOpPriorityConfig WHERE ReferenceObject = 'Incident'"`. Returns zero or more rows. `DeveloperName` is required so the add step can derive a fresh unique suffix.
+6. *(Skip if the `StandardValueSet:IncidentPriority` default was already read this session AND no `StandardValueSet:IncidentPriority` deploy has run since — see Phase 0.)* Default fallback priority — `sf api request rest "/services/data/v67.0/tooling/query/?q=SELECT+Id,MasterLabel,Metadata+FROM+StandardValueSet+WHERE+MasterLabel='IncidentPriority'" --method GET --target-org <alias>`. Read `records[0].Metadata.standardValue`, find the entry with `default: true`, take its `valueName` — that is the fallback priority.
 
 Format the rows as an Impact × Urgency grid (see `examples/render-matrix.md`). Steps 3–6 together are the "view" operation and the before-snapshot.
 

package/skills/service-itsm-swarming-configure/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: service-itsm-swarming-configure
+description: "Enable Swarming for Employee Service (ITSM) in Salesforce — the Salesforce Go feature service-cloud-swarming that lets IT Desk agents pull in subject-matter experts to collaboratively resolve incidents in real time. Use this for: 'turn on swarming', 'enable service-cloud-swarming', 'set up swarming for IT Desk', 'set Teams as collaboration tool for swarming', 'enable collaborative incident resolution', or any request to enable/verify this Salesforce Go feature. DO NOT TRIGGER for the base Microsoft Teams ITSM integration toggle (service-itsm-teams-configure) or for configuring notification-channel preferences."
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "experience-portal-create"
+    - "service-itsm-channels-coordinate"
+    - "service-itsm-teams-configure"
+  mcpTools:
+    headless-360:
+      tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
+      semver: ">=1.0.0"
+  accessCheck:
+    - type: "orgPref"
+      value: "ITSMTeamsEnabled"
+allowed-tools: |
+  Read AskUserQuestion
+  mcp__headless-360__discover
+  mcp__headless-360__describe
+  mcp__headless-360__dispatch
+  mcp__headless-360__dispatch_readonly
+---
+
+# Enable Swarming for Employee Service (ITSM)
+
+Enable the Salesforce Go feature **"Swarming"** (`service-cloud-swarming`) — the feature that
+helps service reps pull in the right collaborators and subject-matter experts to resolve
+incidents in real time. Every operation dispatches through **headless-360**.
+
+> **Execute one step at a time.** These steps make real, state-changing API calls. Run a single
+> operation, show its result, confirm it succeeded, then proceed — do not batch multiple setup
+> calls into one parallel block.
+
+## Scope
+
+- **In scope**: Enabling the `service-cloud-swarming` Go feature via its feature-enablement
+  Connect API; verifying feature state afterward; setting the "Select a Collaboration Tool"
+  picklist (the API-level target of the "Set Teams as Collaboration Tool for Swarming" checklist
+  item) to `Teams` via the org-values Connect API.
+- **Out of scope**: The base Microsoft Teams ITSM Salesforce Go page toggle (`ITSMTeamsEnabled`) and Azure/Entra
+  app registration — use `service-itsm-teams-configure` (Swarming requires Teams to already be set
+  up as a prerequisite, per the Go page). Notification-channel preferences
+  (`Notifications` / `TeamsNotifications`) — a separate concern from this feature. Portal/site
+  creation — use `experience-portal-create`.
+
+---
+
+## The problem this skill solves
+
+"Set Teams as Collaboration Tool for Swarming" is one item in the "Set Up Salesforce IT Desk"
+checklist on the Teams ITSM Go page (`service-cloud-itsm-teams-integration`'s feature page) — but
+it is gated behind a *separate* Go feature, `service-cloud-swarming`, which must be turned on
+first. This skill is the dedicated place to turn Swarming on, so `service-itsm-teams-configure`
+can delegate to it instead of duplicating feature-enablement logic.
+
+---
+
+## Workflow
+
+### Step 1 — Check current feature status
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/connect/setup/discovery/features/status",
+  body:   { "featureApiNames": ["service-cloud-swarming"] }
+)
+```
+
+Response shape:
+```json
+{
+  "items": [
+    {
+      "apiName": "service-cloud-swarming",
+      "status": "ENABLED",          // or "NOT_ENABLED" / "DISABLED"
+      "blockedByApexLock": false,
+      "dependencyStatuses": [],
+      "enableBlockedReasons": [],
+      "disableBlockedReasons": []
+    }
+  ]
+}
+```
+
+**Note:** this endpoint is POST-only despite being a status read — a `GET` with `queryParams`
+returns `405 METHOD_NOT_ALLOWED "Allowed are POST"`.
+
+If `status` is already `"ENABLED"`, skip to Step 3 (verification) — do not re-enable.
+If `enableBlockedReasons` is non-empty, surface those reasons to the user before attempting Step 2.
+
+### Step 2 — Enable the feature
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-swarming/enable",
+  body:   {}
+)
+```
+
+Verified live: returns `201 {"success":true}` cleanly (unlike the Teams feature-enable, this call
+did not exhibit the "500 that still succeeds" gotcha in testing — but re-check status afterward
+regardless, since Go feature-enable calls can be flaky in general).
+
+### Step 3 — Verify
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/connect/setup/discovery/features/status",
+  body:   { "featureApiNames": ["service-cloud-swarming"] }
+)
+```
+
+Expect `status: "ENABLED"`.
+
+### Step 4 — Check current collaboration tool value
+
+```text
+mcp__headless-360__dispatch_readonly(
+  method: "GET",
+  url:    "/services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL"
+)
+```
+
+Response shape — exactly one of the four value fields is populated:
+```json
+{ "booleanValue": false, "dateValue": null, "numberValue": null, "stringValue": "None" }
+```
+
+`stringValue` holds the current picklist selection: `"None"`, `"Slack"`, or `"Teams"`. This is
+the same Java enum-gated org-value endpoint family described in `setup-connect-api`'s
+`get-org-value`/`update-org-value`/`verify-org-value-update` steps — `valueName` must be the
+literal Java enum constant name (`SWARM_COLLABORATION_TOOL`, SCREAMING_SNAKE_CASE), not a
+camelCase guess like `SwarmCollaborationTool`.
+
+If already `"Teams"`, skip to Step 6 (report) — do not re-issue the write.
+
+### Step 5 — Set the collaboration tool to Teams
+
+```text
+mcp__headless-360__dispatch(
+  method: "PATCH",
+  url:    "/services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL",
+  body:   { "orgValue": "Teams" }
+)
+```
+
+Verified live: returns `200 { "stringValue": "Teams", ... }`. This is the API-level write behind
+the Swarming Go feature page's "Select a Collaboration Tool" dropdown — the same control the
+Teams ITSM Go page's "Set Teams as Collaboration Tool for Swarming" checklist item deep-links to
+via its "Go to Feature Page" button. Valid `orgValue` strings are `"None"`, `"Slack"`, `"Teams"`.
+
+Re-run Step 4's GET afterward to confirm `stringValue == "Teams"`.
+
+### Step 6 — Report to the user
+
+Report both the `service-cloud-swarming` feature status and the `SWARM_COLLABORATION_TOOL`
+value, confirming "Set Teams as Collaboration Tool for Swarming" is now fully automated —
+enabling the feature is the prerequisite, and the org-value PATCH is the actual checklist-item
+write.
+
+---
+
+## Disabling (if requested)
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-swarming/disable",
+  body:   {}
+)
+```
+
+Re-run Step 1 afterward to confirm.
+
+To also reset the collaboration tool selection (optional — disabling the feature does not reset
+it automatically):
+```text
+mcp__headless-360__dispatch(
+  method: "PATCH",
+  url:    "/services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL",
+  body:   { "orgValue": "None" }
+)
+```
+
+---
+
+## Gotchas
+
+| Issue | Detail |
+|-------|--------|
+| "Set Teams as Collaboration Tool for Swarming" writes via `SWARM_COLLABORATION_TOOL`, not a Teams-side endpoint | This checklist item lives on the **Swarming** Go feature page itself (`/lightning/setup/page/feature/service-cloud-swarming/home`, "Select a Collaboration Tool" dropdown) — the Teams ITSM Go page's checklist item is just a deep link to it via "Go to Feature Page." The write API is `PATCH /services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL` with body `{"orgValue": "Teams"}` — part of `setup-connect-api`'s `get-org-value`/`update-org-value` steps. Verified live: `GET` returned `{"stringValue":"None"}` before, `{"stringValue":"Teams"}` after `PATCH`. |
+| `valueName` must be the exact Java enum constant, not camelCase | The `/setup/org/values/{valueName}` endpoint calls `OrgValues.valueOf(valueName)` directly (`Enum.valueOf`), so it requires the literal SCREAMING_SNAKE_CASE constant name declared in `ui.services.utils.OrgValueUtil.OrgValues` — e.g. `SWARM_COLLABORATION_TOOL`. CamelCase guesses like `SwarmCollaborationTool` or `SwarmingCollaborationTool` return `400 ILLEGAL_QUERY_PARAMETER_VALUE "No enum constant ui.services.utils.OrgValueUtil.OrgValues.<guess>"` — that specific error confirms the endpoint/mechanism is right but the casing/name is wrong. The read-only `get-service-itsm-teams-collaboration-app-settings` endpoint (`GET /connect/it-service/collaboration-app-settings/{targetApplication}`) is unrelated to this setting — it's read-only (`POST`/`PATCH`/`PUT` return `405`) and returns empty `settings: []` regardless of feature state. |
+| `features/status` is POST-only | A `GET` with `queryParams` on `/connect/setup/discovery/features/status` returns `405 METHOD_NOT_ALLOWED "Allowed are POST"` — always POST a JSON body with `featureApiNames`. |
+| `swarming-connect-api` SOR is unrelated | headless-360's `swarming-connect-api` SOR is about **Slack messaging within swarming conversations** (post/patch/delete Slack messages, reactions, file uploads, channel/user search) — it does not configure which collaboration tool (Teams vs. Slack vs. Chatter) swarming uses. Do not confuse it with this skill's scope. |
+| Swarming requires Teams first | The Go page frames "Set Teams as Collaboration Tool for Swarming" as a step *within* Teams ITSM setup — enable `service-cloud-itsm-teams-integration` (via `service-itsm-teams-configure`) before or alongside this skill. |
+| Version prefix required | headless-360 `dispatch`/`dispatch_readonly` do not resolve API versions — always pass the full `/services/data/vXX.0/...` prefix. |
+
+---
+
+## Related Skills
+
+| Skill | When to use instead / alongside |
+|-------|---------------------------------|
+| `service-itsm-teams-configure` | Enabling the base Microsoft Teams ITSM integration and Azure/Entra setup — a prerequisite for Swarming; delegates to this skill for the "Set Teams as Collaboration Tool for Swarming" checklist item |
+| Notification-channel preferences | Enabling the `Notifications`/`TeamsNotifications` preferences is a distinct concern from this feature (no dedicated child skill exists yet) |
+| `service-itsm-channels-coordinate` | Top-level menu across Teams, Slack, Swarming, Notifications, Portal |