@salesforce/afv-skills 1.44.0 → 1.45.0

package/skills/service-itsm-agentic-setup-employee-agent-configure/SKILL.md

@@ -2,10 +2,11 @@
 name: service-itsm-agentic-setup-employee-agent-configure
 description: "Create and activate an IT Service Employee agent as a Next-Gen Authoring (NGA) native agent from an ITSM Employee agent template's Agent Script, via the Salesforce CLI (sf): read the template, check idempotency, create the NGA bundle then publish and activate, verify live. Defaults to the broad IT Service Employee template; when the user names a specialized Employee template (Password Manager Assistance, Certificate Management, Onboarding, Hardware Request, and ~47 others catalogued in references/specialized-templates.md — all under the `svc_emp_intelligence__` namespace), pins that one instead. Idempotent per developer name. TRIGGER when the user asks to create/set up/provision/activate the Employee agent, the IT Service Employee agent, or a specialized Employee agent (password manager, certificate, onboarding, hardware request, etc.). DO NOT TRIGGER: prerequisite checks (service-itsm-agentic-setup-agentforce-studio-validate), CMDB CRUD, Fulfiller setup (service-itsm-agentic-setup-fulfiller-agent-configure)."
 metadata:
-  version: "2.3"
+  version: "2.5"
   domains: ["Service", "Agentforce"]
   minApiVersion: "67.0"
   relatedSkills:
+    - "service-itsm-agentic-setup-agent-runtime-access-assign"
     - "service-itsm-agentic-setup-agentforce-studio-configure"
     - "service-itsm-agentic-setup-agentforce-studio-validate"
     - "service-itsm-agentic-setup-fulfiller-agent-configure"
@@ -60,7 +61,7 @@ If any of these are unmet, `sf` surfaces an auth error or a `401`/`403`/`404`; *
 |---------|---------|-------|
 | Studio access (precondition read) | `sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>` | `hasAccess=false` ⇒ prerequisite hand-off |
 | List agent templates + Agent Script (read) | `sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" --method GET -o <alias>` | `agentType=AgentforceEmployeeAgent` required; confirms resolved `<masterLabel>` template + non-empty `agentScript` |
-| Enumerate existing agent + latest version status (read) | `sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" -o <alias> --json` | Keyed PRIMARILY on the template's `botDefinitionId` (Phase-1 row); the `OR DeveloperName=` clause is both the null-`botDefinitionId` fallback AND the guard for a dangling Id link (deleted target). Classified by `scripts/classify-agent-existence.mjs`; Active latest ⇒ ALREADY-CREATED; Inactive latest ⇒ offer reactivation |
+| Enumerate existing agent + latest version status (read) | `sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" -o <alias> --json` | Keyed PRIMARILY on the template's `botDefinitionId` (Phase-1 row); `OR AgentTemplate=` is the first fallback that catches the pre-provisioned broad `IT_Service_Employee` agent by its OOTB namespaced source template (`svc_emp_intelligence__ItEmployeeAssistance` = Phase-1 `template.id`) regardless of the collected DeveloperName guess; `OR DeveloperName=` is the last fallback for self-created agents (null `AgentTemplate`) and the guard for a dangling Id link (deleted target). Classified by `scripts/classify-agent-existence.mjs`; Active latest ⇒ ALREADY-CREATED; Inactive latest ⇒ offer reactivation |
 | **Create the NGA bundle** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" --method POST --body @<body-file> -o <alias>` | Body built by `scripts/build-create-body.mjs`; response `id` = the bundle **version** Id |
 | **Publish the bundle version** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" --method POST --body '{}' -o <alias>` | Returns `publishedBotId`/`publishedBotVersionId` — creates the underlying `BotDefinition`/`BotVersion` |
 | **Activate the bundle version** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" --method POST --body '{}' -o <alias>` | Empty response on success; agent is now live and NGA-native |
@@ -87,9 +88,9 @@ Collect from the user (ask only what is not already in conversation context):
 | Label | Broad: `IT Service Employee Agent`. Specialized: the picked template's `masterLabel` verbatim (e.g. `Password Manager Assistance`) |
 | Confirm the write | **REQUIRED** — present resolved template + developerName + label, then require "yes" via `AskUserQuestion` |
 
-The collected `<masterLabel>`, `<developerName>`, `<label>` are threaded through every call — `<masterLabel>` selects the row in `agent-templates.data[]` (which also carries the `botDefinitionId` idempotency key); `<developerName>`/`<label>` are used in the `createBundleWithVersion` body (both outer `apiName`/`label` AND the substituted internal `config.developer_name`/`config.agent_label`). The **idempotency + verify reads key PRIMARILY on the template's `botDefinitionId`** (or, after a fresh create, the publish response's `publishedBotId`) and **fall back to the collected `<developerName>`** when that is null. A hardcode/collect mismatch on the create body diverges the bundle's outer identity from the script's internal identity.
+The collected `<masterLabel>`, `<developerName>`, `<label>` are threaded through every call — `<masterLabel>` selects the row in `agent-templates.data[]` (which also carries the `botDefinitionId` idempotency key); `<developerName>`/`<label>` are used in the `createBundleWithVersion` body (both outer `apiName`/`label` AND the substituted internal `config.developer_name`/`config.agent_label`). The **idempotency + verify reads key PRIMARILY on the template's `botDefinitionId`** (or, after a fresh create, the publish response's `publishedBotId`) and **fall back to the BotDefinition's `AgentTemplate`** (the OOTB source template = Phase-1 `template.id`), then to the collected `<developerName>`, when that is null. A hardcode/collect mismatch on the create body diverges the bundle's outer identity from the script's internal identity.
 
-**Idempotency**: keyed PRIMARILY on the **template's `botDefinitionId`** (Phase-1 `agent-templates` row — the platform's authoritative template→`BotDefinition` link) and FALLING BACK to the collected `<developerName>`. The Phase-2 read is `BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'` (the `OR` half is both the null-`botDefinitionId` fallback AND the guard for a **dangling** Id link — one whose target `BotDefinition` was deleted — so a stale link can't slip through to create), + latest `BotVersion.Status`. Outcomes: no match on either key ⇒ create; `Active` ⇒ ALREADY-CREATED (skip write); `Inactive` ⇒ Phase-2b reactivation offer. **Why both keys:** the broad agent ships pre-provisioned as `IT_Service_Employee` ≠ the guess `IT_Service_Employee_Agent`, so `botDefinitionId` catches it — but an agent this skill creates never back-fills `botDefinitionId` (the create path omits `templateName`), so its template row stays null and the `developerName` fallback is what catches a repeat run. The server does reject a duplicate `DeveloperName` at publish (unique-constraint → bundle cleanup), but only this read turns a repeat into a graceful skip instead of a `DUPLICATE_VALUE`.
+**Idempotency**: keyed PRIMARILY on the **template's `botDefinitionId`** (Phase-1 `agent-templates` row — the platform's authoritative template→`BotDefinition` link), FALLING BACK first to the **BotDefinition's `AgentTemplate`** (the OOTB namespaced source template = Phase-1 `template.id`) and then to the collected `<developerName>`. The Phase-2 read is `BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'` (the `OR AgentTemplate=` half catches the broad pre-provisioned agent by its platform-stamped source template regardless of what `DeveloperName` it carries; the `OR DeveloperName=` half is both the last fallback for self-created agents — whose `AgentTemplate` is null — AND the guard for a **dangling** Id link whose target `BotDefinition` was deleted), + latest `BotVersion.Status`. Outcomes: no match on any key ⇒ create; `Active` ⇒ ALREADY-CREATED (skip write); `Inactive` ⇒ Phase-2b reactivation offer. **Why the fallback keys:** the broad agent ships pre-provisioned as `IT_Service_Employee` ≠ the guess `IT_Service_Employee_Agent` (a null-`botDefinitionId` template row too), so neither the primary key nor the `developerName` guess catches it — its `AgentTemplate` (`svc_emp_intelligence__ItEmployeeAssistance`) is the reliable, rename-immune key that matches it; and for an agent this skill creates (which back-fills neither `botDefinitionId` nor `AgentTemplate`), the `developerName` fallback is what catches a repeat run. The server does reject a duplicate `DeveloperName` at publish (unique-constraint → bundle cleanup), but only this read turns a repeat into a graceful skip instead of a `DUPLICATE_VALUE`.
 
 ---
 
@@ -98,8 +99,8 @@ The collected `<masterLabel>`, `<developerName>`, `<label>` are threaded through
 Substitute `<alias>` with the collected target org and `<developerName>` / `<label>` with the collected values. Full command shapes + per-phase verdict-branch handling live in `references/workflow-detail.md` — the phase summary below names each step and its load-bearing rule; the reference file holds the exact `sf` / `node` invocations to copy.
 
 0. **Phase 0 — Establish `${SCRATCH_DIR}`.** Before any phase writes a transient JSON file, invoke the deterministic helper (path is skill-root-qualified so it resolves regardless of the shell's CWD): `SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")"`. The helper picks the base dir (`${TMPDIR}`, else `/tmp`, else the harness `${outputDir}` last-resort — scratch stays OUT of the scored `${outputDir}` tree) and emits the created dir's absolute path on stdout. Every subsequent phase writes its transient JSON under `${SCRATCH_DIR}`; the durable `${outputDir}/report.md` stays under the harness dir.
-1. **Phase 1 — Preflight.** Capture the Studio-access read + `agent-templates` read (with the **required** `agentType=AgentforceEmployeeAgent` query param), then classify via `scripts/classify-preflight.mjs "<masterLabel>"` — pass the resolved `<masterLabel>` (`"IT Service Employee"` for the broad path or the picked specialization's `masterLabel`). The classifier also emits `template.botDefinitionId` from the matched row — **capture it; it is the primary Phase-2 idempotency key (the collected `<developerName>` is the fallback key).** Branch on `verdict`: `READY` ⇒ Phase 2; `NOT-READY` ⇒ prerequisite hand-off via `AskUserQuestion` (delegate to `service-itsm-agentic-setup-agentforce-studio-validate` employee path on "yes"); `ERROR` ⇒ surface + stop; `studio.signal="CANNOT-CONFIRM"` (confirmed 404) does not block.
-2. **Phase 2 — Idempotency (primary key `botDefinitionId`, fallback key `<developerName>`).** Take `template.botDefinitionId` from Phase 1. **Present** ⇒ SOQL `BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'` (+ `BotVersions` subquery — required, else `needsActivation` is permanently false; the `OR` clause makes a **dangling** Id link — deleted target — fall back to the live same-name agent instead of a false `exists:false` → duplicate create). **Empty/null** ⇒ do NOT skip to create; fall back to `WHERE DeveloperName='<developerName>'` (a self-created agent's template row is never back-filled, so its `botDefinitionId` stays null even though the agent exists). Either way classify via `scripts/classify-agent-existence.mjs ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>"`. Branch: `exists:false` ⇒ Phase 3 (create); `exists:true` + `needsActivation:false` ⇒ **ALREADY-CREATED** (skip to Phase 7); `exists:true` + `needsActivation:true` ⇒ Phase 2b. Non-zero exit ⇒ surface CLI error; never assume absent. **Why both keys:** `botDefinitionId` catches the pre-provisioned `IT_Service_Employee` (≠ the guess `IT_Service_Employee_Agent`); the `developerName` fallback catches self-created repeats — a miss on both re-creates and hits `DUPLICATE_VALUE`.
+1. **Phase 1 — Preflight.** Capture the Studio-access read into `${SCRATCH_DIR}/studio-access.json` and the `agent-templates` read (with the **required** `agentType=AgentforceEmployeeAgent` query param) into `${SCRATCH_DIR}/agent-templates.json`, then classify by passing **both file paths, then the label** (that arg order): `node "<skill_dir>/scripts/classify-preflight.mjs" ${SCRATCH_DIR}/studio-access.json ${SCRATCH_DIR}/agent-templates.json "<masterLabel>"` — pass the resolved `<masterLabel>` (`"IT Service Employee"` for the broad path or the picked specialization's `masterLabel`). The classifier emits `template.botDefinitionId`, `template.id`, and `template.masterLabel` from the matched row — **capture all three; `botDefinitionId` is the primary Phase-2 idempotency key, `template.id` (the BotDefinition's `AgentTemplate`) the first fallback, and `<developerName>` the last fallback; `masterLabel` is the report's display label, not a key.** Branch on `verdict`: `READY` ⇒ Phase 2; `NOT-READY` ⇒ prerequisite hand-off via `AskUserQuestion` (delegate to `service-itsm-agentic-setup-agentforce-studio-validate` employee path on "yes"); `ERROR` ⇒ surface + stop; `studio.signal="CANNOT-CONFIRM"` (confirmed 404) does not block.
+2. **Phase 2 — Idempotency (primary key `botDefinitionId`, fallbacks `AgentTemplate` then `<developerName>`).** Take `template.botDefinitionId` and `template.id` from Phase 1. **Present `botDefinitionId`** ⇒ SOQL `BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'` (+ `BotVersions` subquery — required, else `needsActivation` is permanently false; the `OR` clauses make a **dangling** Id link — deleted target — fall back to the live agent instead of a false `exists:false` → duplicate create). **Empty/null `botDefinitionId`** ⇒ do NOT skip to create; read `WHERE AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'` (the broad pre-provisioned agent is recovered by its OOTB source template even when its DeveloperName differs from the guess; a self-created agent carries a null `AgentTemplate`, so `DeveloperName` is its guard). `<agentTemplate>` is Phase-1 `template.id`. Either way classify via `node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>" "<agentTemplate>"`. Branch: `exists:false` ⇒ Phase 3 (create); `exists:true` + `needsActivation:false` ⇒ **ALREADY-CREATED** (skip to Phase 7); `exists:true` + `needsActivation:true` ⇒ Phase 2b. Non-zero exit ⇒ surface CLI error; never assume absent. **Why the fallback keys:** the broad agent ships pre-provisioned as `IT_Service_Employee` with a null template `botDefinitionId`, so neither the primary key nor the `developerName` guess (`IT_Service_Employee_Agent`) catches it — its `AgentTemplate` (`svc_emp_intelligence__ItEmployeeAssistance`) matches it by the platform-stamped source template; the `developerName` fallback catches self-created repeats — a miss on all three re-creates and hits `DUPLICATE_VALUE`.
 3. **Phase 2b — Reactivation offer.** `AskUserQuestion`: _"Employee agent `<developerName>` exists but latest version is Inactive. Activate it?"_. On **Yes**: `POST /connect/bot-versions/<latestVersionId>/activation` with `{"status":"Active"}` — skips Phases 3–6, straight to Phase 7. Aggregate verdict is **ACTIVATED**, not CREATED. On **No**: stop, no writes.
 4. **Phase 3 — Confirm-to-Write (REQUIRED, create path only).** If `${outputDir}` was provided, first render the checkpoint file via `render-report.mjs` with `verdict:"PENDING CONFIRMATION"` (skip for interactive runs). THEN raise the `AskUserQuestion` gate presenting developerName + label + "NGA-native from the Employee template's Agent Script". Proceed **only** on explicit "yes"; on "no" (including "hold off on activation" / "not yet" / any decline of the atomic chain), re-render with `verdict:"DECLINED"` and a one-line `reason`.
 5. **Phase 4 — Create.** `scripts/build-create-body.mjs ${SCRATCH_DIR}/agent-templates.json "<masterLabel>" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json` (helper re-reads Phase-1 templates JSON, HTML-decodes the matched `agentScript`, substitutes internal `config.developer_name`/`config.agent_label`, writes body to file — pass the same `<masterLabel>` used in Phase 1), then `POST /nextgen-authoring/bundles --body @${SCRATCH_DIR}/create-bundle-body.json`. **Capture response `id`** — that is the `bundleVersionId` for Phases 5–6, not `bundleId`. `403 FUNCTIONALITY_NOT_ENABLED`/`404` ⇒ trigger the Phase-1 hand-off; build-script exit 3 ⇒ surface stderr.
@@ -130,7 +131,7 @@ Substitute `<alias>` with the collected target org and `<developerName>` / `<lab
 
 - [ ] Resolved `<masterLabel>` before Phase 1 (broad default or specialization from `references/specialized-templates.md`, `data[]` filtered to `svc_emp_intelligence__`, disambiguated on `id`).
 - [ ] Preflight classified by `classify-preflight.mjs` (PASS or documented CANNOT-CONFIRM); hand-off offered on FAIL; raw error surfaced on ERROR.
-- [ ] Idempotency keyed on the template's `botDefinitionId` (Phase-1 row) with the collected developerName as fallback; `BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'` (the `OR` covers both a null and a dangling `botDefinitionId`) + latest `BotVersion.Status` (subquery present) read + classified before any write.
+- [ ] Idempotency keyed on the template's `botDefinitionId` (Phase-1 row) with the BotDefinition's `AgentTemplate` (Phase-1 `template.id`) as the first fallback and the collected developerName as the last; `BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'` (the `OR`s cover a null/dangling `botDefinitionId`, the pre-provisioned broad agent whose DeveloperName differs from the guess, and self-created agents with a null `AgentTemplate`) + latest `BotVersion.Status` (subquery present) read + classified before any write.
 - [ ] If `needsActivation:true`, Phase-2b reactivation offer presented — no silent skip, no duplicate create.
 - [ ] Explicit user confirmation at Phase 3 (create) or Phase 2b (reactivation) before any write.
 - [ ] Bundle body built by `build-create-body.mjs`, POSTed via `--body @<file>` with the collected `developerName`/`label`; or write correctly skipped.

package/skills/service-itsm-agentic-setup-employee-agent-configure/references/cli-invocation.md

@@ -151,13 +151,13 @@ Classifier output:
 ```json
 {
   "studio":   { "hasAccess": true, "signal": "PASS|FAIL|CANNOT-CONFIRM|ERROR", "reason": "..." },
-  "template": { "present": true, "id": "svc_emp_intelligence__ItEmployeeAssistance", "hasAgentScript": true, "botDefinitionId": "0Xx...", "signal": "PASS|FAIL|CANNOT-CONFIRM", "reason": "..." },
+  "template": { "present": true, "id": "svc_emp_intelligence__ItEmployeeAssistance", "hasAgentScript": true, "botDefinitionId": "0Xx...", "masterLabel": "IT Service Employee", "signal": "PASS|FAIL|CANNOT-CONFIRM", "reason": "..." },
   "verdict": "READY | NOT-READY | CANNOT-CONFIRM | ERROR",
   "reasons": ["..."]
 }
 ```
 
-`template.botDefinitionId` is copied from the matched `agent-templates` row. **`botDefinitionId` is the PRIMARY Phase-2 idempotency key** — a populated value means the template has already been instantiated into a live `BotDefinition` (the broad Employee agent ships pre-provisioned this way); `null` means either it has not been created yet OR it was created by this skill (a self-created agent never back-fills the template row — see Phase 2). Capture `botDefinitionId` for the Phase-2 read below and always carry the collected `<developerName>` as the fallback key. (`isInstalled`/`isActivated` are no longer emitted: they ride the same AgentTemplate join as `botDefinitionId`, so they read false for self-created agents and nothing consumes them.)
+`template.botDefinitionId`, `template.id`, and `template.masterLabel` are copied from the matched `agent-templates` row. **`botDefinitionId` is the PRIMARY Phase-2 idempotency key** — a populated value means the template has already been instantiated into a live `BotDefinition`; `null` means it has not been created yet OR it was created by this skill (a self-created agent never back-fills the template row) OR — as with the broad pre-provisioned Employee agent — the platform instantiated it without joining the template row back (see Phase 2). Capture `botDefinitionId` for the Phase-2 read below and always carry `template.id` (the BotDefinition's `AgentTemplate` — the first fallback) and the collected `<developerName>` (the last fallback) as the fallback keys; `masterLabel` is the report's display label, not an idempotency key. (`isInstalled`/`isActivated` are no longer emitted: they ride the same AgentTemplate join as `botDefinitionId`, so they read false for self-created agents and nothing consumes them.)
 
 `verdict=ERROR` (`studio.signal="ERROR"` — a parseable non-404 Studio-access
 error, e.g. `401`/`403`) ⇒ surface the raw error and stop; takes priority over
@@ -165,53 +165,65 @@ template state so a present template cannot outrun a failed prerequisite read.
 `verdict=NOT-READY` (studio FAIL or template FAIL) ⇒ hand off / stop.
 `verdict=READY` ⇒ proceed to Phase 2. It exits `0` on usable args.
 
-## Enumerate the existing agent — SOQL on `BotDefinition` BY Id (falling back to DeveloperName)
+## Enumerate the existing agent — SOQL on `BotDefinition` BY Id (falling back to AgentTemplate, then DeveloperName)
 
 Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (from the
-Phase-1 row) and **FALLS BACK** to the collected `<developerName>`. The broad
-"IT Service Employee" agent ships pre-provisioned+active under DeveloperName
-`IT_Service_Employee`, which never matches this skill's default guess
-`IT_Service_Employee_Agent`; a name-only read false-negatives on THAT agent
-(`exists:false`) and the create then collides on `apiName` with
-`DUPLICATE_VALUE` — so `botDefinitionId` (the platform's authoritative link from
-the template to the `BotDefinition` it was instantiated into) is the primary key.
-But that link is back-filled onto the template row **only** for pre-provisioned
-agents: an agent THIS skill creates never stamps `templateName`, so its template
-`botDefinitionId` stays `null` on every later read. For that self-created case a
-`DeveloperName`-keyed read is the reliable guard — so use it as the fallback,
-never short-circuit straight to create when `botDefinitionId` is absent.
-
-- **`botDefinitionId` empty/null** (template row never joined — either not
-  created yet, or created by this skill) ⇒ fall back to a DeveloperName-keyed
-  read and let the classifier match on it:
+Phase-1 row), **FALLS BACK** first to the BotDefinition's `AgentTemplate` (the
+OOTB namespaced source template = Phase-1 `template.id`), and then to the
+collected `<developerName>`. The broad "IT Service Employee" agent ships
+pre-provisioned+active under DeveloperName `IT_Service_Employee` **with a `null`
+template `botDefinitionId`** (the platform instantiated it without joining the
+template row back), and `IT_Service_Employee` never matches this skill's default
+guess `IT_Service_Employee_Agent` — so both the primary key AND the
+`DeveloperName` fallback miss on THAT agent, a create is attempted, and it
+collides on `apiName` with `DUPLICATE_VALUE`. The `AgentTemplate`-keyed fallback
+closes that gap far more reliably than a display name would: the live
+pre-provisioned agent carries `AgentTemplate=svc_emp_intelligence__ItEmployeeAssistance`
+(the exact template id this skill installs), the platform-stamped source template,
+immune to any `DeveloperName` rename. `botDefinitionId` remains the
+primary key for a genuinely joined instantiation, and the `DeveloperName`
+fallback is the guard for a self-created repeat (an agent THIS skill creates never
+stamps `templateName`, so BOTH its template `botDefinitionId` AND its
+`AgentTemplate` stay `null`). Never short-circuit straight to create when
+`botDefinitionId` is absent.
+
+- **`botDefinitionId` empty/null** (the broad pre-provisioned agent, and every
+  agent this skill creates) ⇒ fall back to an `AgentTemplate` **`OR` `DeveloperName`**
+  read and let the classifier match on either:
   ```bash
-  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE DeveloperName='<developerName>'" \
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" \
     --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
-  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>"
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>" "<agentTemplate>"
   ```
 - **`botDefinitionId` present** ⇒ read the `BotDefinition` by Id **`OR` by the
-  collected `<developerName>`** in one query, then classify. The `OR DeveloperName=`
-  clause catches a **dangling** link — a `botDefinitionId` whose target row was
-  since deleted: the by-Id half returns nothing, the live same-name agent still
-  surfaces, and the classifier falls back to it (`matchedBy:"developerName"`)
-  rather than concluding `exists:false` and colliding with `DUPLICATE_VALUE`:
+  template's `AgentTemplate` `OR` by the collected `<developerName>`** in one
+  query, then classify. The `OR AgentTemplate=` clause is what catches the
+  pre-provisioned agent by its platform-stamped source template
+  (`matchedBy:"agentTemplate"`) regardless of its DeveloperName. The `OR
+  DeveloperName=` clause catches a **dangling** link — a `botDefinitionId` whose
+  target row was since deleted: the by-Id half returns nothing, the live same-name
+  agent still surfaces, and the classifier falls back to it
+  (`matchedBy:"developerName"`) rather than concluding `exists:false` and
+  colliding with `DUPLICATE_VALUE`:
   ```bash
-  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" \
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" \
     --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
-  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>"
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>" "<agentTemplate>"
   ```
 
-Only when **both** `botDefinitionId` and `<developerName>` are absent does the
-classifier return `exists:false` without reading a query file — in practice the
-collected `<developerName>` is always present, so the fallback read always runs.
+Only when **all** of `botDefinitionId`, `<agentTemplate>`, and `<developerName>`
+are absent does the classifier return `exists:false` without reading a query
+file — in practice the collected `<developerName>` and `template.id` (AgentTemplate)
+are always present, so the fallback read always runs.
 
 The `BotVersions` subquery (child relationship on `BotDefinition`) is what lets
 the classifier see the latest version's `Status` — omit it and
 `latestVersionStatus`/`needsActivation` come back `null`/`false` even when the
 existing agent is actually inactive. The classifier prints
 `{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }`
-(`matchedBy` is `"botDefinitionId"` | `"developerName"` | `null`; `developerName`
-is the ACTUAL live agent's DeveloperName read from the record — surface it in the
+(`matchedBy` is `"botDefinitionId"` | `"agentTemplate"` | `"developerName"` | `null`;
+`developerName` is the ACTUAL live agent's DeveloperName read from the record —
+surface it in the
 report instead of the collected guess):
 - `exists:false` ⇒ proceed to create.
 - `exists:true` and `needsActivation:false` (latest version `Active`) ⇒

package/skills/service-itsm-agentic-setup-employee-agent-configure/references/reactivation.md

@@ -9,13 +9,15 @@ just reactivate what's already there".
 ## When this path fires
 
 `scripts/classify-agent-existence.mjs` (called with the template's
-`botDefinitionId` as the PRIMARY idempotency key and the collected
-`DeveloperName` as the FALLBACK — see `cli-invocation.md` → "Enumerate the
-existing agent") returns
+`botDefinitionId` as the PRIMARY idempotency key, the BotDefinition's
+`AgentTemplate` — the template's OOTB source id — as the first FALLBACK, and the
+collected `DeveloperName` as the last FALLBACK —
+see `cli-invocation.md` → "Enumerate the existing agent") returns
 `{ exists:true, needsActivation:true, latestVersionId, latestVersionStatus:"Inactive" }`.
-That means a `BotDefinition` matching the template (by `botDefinitionId`) or the
-collected `DeveloperName` already exists (created on a prior run, or — for the
-broad Employee agent — by the platform) but its most-recent `BotVersion` is
+That means a `BotDefinition` matching the template (by `botDefinitionId`), its
+`AgentTemplate` source id, or the collected `DeveloperName` already exists (created
+on a prior run, or — for the broad Employee agent, matched by its source template —
+by the platform) but its most-recent `BotVersion` is
 inactive; creating a new bundle would produce a duplicate. Instead, flip the
 existing version to `Active`.
 

package/skills/service-itsm-agentic-setup-employee-agent-configure/references/workflow-detail.md

@@ -28,10 +28,10 @@ node "<skill_dir>/scripts/classify-preflight.mjs" ${SCRATCH_DIR}/studio-access.j
 
 Pass the resolved `<masterLabel>` — `"IT Service Employee"` for the default broad path, or the picked specialized template's `masterLabel` (e.g. `"Password Manager Assistance"`) for a specialized path. The classifier matches `data[]` case-insensitively on `masterLabel` and confirms the matched row has a non-empty `agentScript`.
 
-The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgentScript,botDefinitionId,signal}, verdict, reasons }`:
+The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgentScript,botDefinitionId,masterLabel,signal}, verdict, reasons }`:
 
 - `template.hasAgentScript:true` confirms the template carries the Agent Script content Phase 4 needs; capture the raw `agent-templates.json` file path — Phase 4 re-reads it directly (via `scripts/build-create-body.mjs`) rather than the classifier re-emitting the full script content.
-- **`template.botDefinitionId` is the PRIMARY Phase-2 idempotency key.** A populated value means this template has already been instantiated into a live `BotDefinition` (the broad Employee agent ships pre-provisioned this way); a `null` value means it has not been created yet OR it was created by this skill (self-created agents never back-fill the template row). Capture `botDefinitionId` for Phase 2, and carry the collected `<developerName>` as the fallback key.
+- **`template.botDefinitionId` is the PRIMARY Phase-2 idempotency key.** A populated value means this template has already been instantiated into a live `BotDefinition`; a `null` value means it has not been created yet OR it was created by this skill (self-created agents never back-fill the template row) OR — as with the broad pre-provisioned Employee agent — the platform instantiated it without joining the template row back. Capture `botDefinitionId` for Phase 2, and carry the collected `<developerName>` (first fallback) and `template.masterLabel` (second fallback) as the fallback keys.
 - `verdict:"READY"` ⇒ continue to Phase 2.
 - `verdict:"ERROR"` because `studio.signal="ERROR"` (the Studio-access read returned a parseable but non-404 error body — e.g. `401`/`403`) ⇒ do NOT proceed — surface the raw error and stop. This is a failed prerequisite read, not an unwired gate; do not let a present template push the verdict to READY.
 - `verdict:"NOT-READY"` because `studio.signal="FAIL"` (`hasAccess=false`) ⇒ do NOT proceed — **offer the prerequisite hand-off**:
@@ -44,22 +44,22 @@ The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgen
 
 ## Phase 2 — Idempotency: does the target agent already exist, and is it active?
 
-Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (captured in Phase 1) and **FALLS BACK** to the collected `<developerName>`. The `botDefinitionId` is the platform's authoritative link from the `agent-templates` row to the `BotDefinition` it was instantiated into — it catches the pre-provisioned broad Employee agent (which ships active under DeveloperName `IT_Service_Employee`, never matching the default guess `IT_Service_Employee_Agent`, so a name-only read would false-negative and the create would fail with `DUPLICATE_VALUE`). But that link is back-filled **only** for pre-provisioned agents — an agent this skill creates never stamps `templateName`, so its template `botDefinitionId` stays `null`; for that self-created case the `DeveloperName`-keyed fallback is the guard, so never short-circuit to create when `botDefinitionId` is absent.
+Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (captured in Phase 1), **FALLS BACK** first to the BotDefinition's `AgentTemplate` (the OOTB namespaced source template = Phase-1 `template.id`), and then to the collected `<developerName>`. The `botDefinitionId` is the platform's authoritative link from the `agent-templates` row to the `BotDefinition` it was instantiated into, but that link is populated **only** when the platform joined the row back — which it does NOT do for the broad pre-provisioned Employee agent (it ships active under DeveloperName `IT_Service_Employee` with a `null` template `botDefinitionId`) nor for an agent this skill creates (which never stamps `templateName`). So for the broad agent both the primary key and the `DeveloperName` guess miss (`IT_Service_Employee` ≠ the default `IT_Service_Employee_Agent`), and the `AgentTemplate`-keyed fallback — matching `svc_emp_intelligence__ItEmployeeAssistance`, the platform-stamped source template on the live `BotDefinition`, immune to any rename — is what recovers it; for a self-created repeat (null `AgentTemplate` too) the `DeveloperName` fallback is the guard. Never short-circuit to create when `botDefinitionId` is absent.
 
-- **`template.botDefinitionId` is empty/null** ⇒ fall back to a DeveloperName-keyed read (do **not** short-circuit to create — a self-created agent from a prior run has a null template `botDefinitionId` but still exists). The `BotVersions` subquery is required — omitting it leaves `needsActivation` permanently false and hides the reactivation path:
+- **`template.botDefinitionId` is empty/null** (the broad pre-provisioned agent AND every self-created agent) ⇒ fall back to an `AgentTemplate` **`OR` `DeveloperName`** read (do **not** short-circuit to create — the broad agent is recovered by its OOTB source template, and a self-created agent from a prior run has a null template `botDefinitionId` but still exists). The `BotVersions` subquery is required — omitting it leaves `needsActivation` permanently false and hides the reactivation path:
   ```bash
-  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE DeveloperName='<developerName>'" \
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" \
     --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
-  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>"
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>" "<agentTemplate>"
   ```
-- **`template.botDefinitionId` is present** ⇒ read the `BotDefinition` by Id **`OR` by the collected `<developerName>`** in one query, INCLUDING its latest version's status, then classify. The `OR DeveloperName=` clause is what catches a **dangling** template→BotDefinition link — a `botDefinitionId` whose target row was since deleted: the by-Id half returns nothing, but the live same-name agent still surfaces, so the classifier falls back to it (`matchedBy:"developerName"`) instead of concluding `exists:false` and letting the create collide with `DUPLICATE_VALUE`:
+- **`template.botDefinitionId` is present** ⇒ read the `BotDefinition` by Id **`OR` by the template's `AgentTemplate` `OR` by the collected `<developerName>`** in one query, INCLUDING its latest version's status, then classify. The `OR AgentTemplate=` clause catches the pre-provisioned agent by its platform-stamped source template (`matchedBy:"agentTemplate"`) regardless of its DeveloperName. The `OR DeveloperName=` clause catches a **dangling** template→BotDefinition link — a `botDefinitionId` whose target row was since deleted: the by-Id half returns nothing, but the live same-name agent still surfaces, so the classifier falls back to it (`matchedBy:"developerName"`) instead of concluding `exists:false` and letting the create collide with `DUPLICATE_VALUE`:
   ```bash
-  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" \
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" \
     --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
-  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>"
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>" "<agentTemplate>"
   ```
 
-The classifier prints `{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }` — `matchedBy` is `"botDefinitionId"` | `"developerName"` | `null`, and `developerName` is the ACTUAL live agent's DeveloperName read from the record (e.g. `IT_Service_Employee`), surface it in the report rather than the collected guess:
+The classifier prints `{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }` — `matchedBy` is `"botDefinitionId"` | `"agentTemplate"` | `"developerName"` | `null`, and `developerName` is the ACTUAL live agent's DeveloperName read from the record (e.g. `IT_Service_Employee`), surface it in the report rather than the collected guess:
 
 - `exists:false` ⇒ proceed to Phase 3 (create path).
 - `exists:true` and `needsActivation:false` (latest version `Active`) ⇒ **ALREADY-CREATED** — skip the write, fall through to Phase 7 verification.

package/skills/service-itsm-agentic-setup-employee-agent-configure/scripts/classify-agent-existence.mjs

@@ -3,50 +3,66 @@
 //
 // Idempotency for this flow is keyed PRIMARILY on the TEMPLATE's own
 // `botDefinitionId` — the platform's authoritative link from an `agent-templates`
-// row to the live `BotDefinition` it was instantiated into — and FALLS BACK to a
-// `DeveloperName`-keyed read when that row carries no `botDefinitionId`.
+// row to the live `BotDefinition` it was instantiated into — and FALLS BACK
+// first to the BotDefinition's own `AgentTemplate` field (the OOTB, namespaced
+// source-template API name it was instantiated from, e.g.
+// `svc_emp_intelligence__ItEmployeeAssistance`), then to a `DeveloperName`-keyed
+// read.
 // The broad "IT Service Employee" agent is pre-provisioned+active under
 // DeveloperName `IT_Service_Employee`, which does NOT match this skill's default
-// collected developerName `IT_Service_Employee_Agent`; a DeveloperName-only read
-// false-negatives on THAT agent (exists:false) and the create then collides on
-// `apiName` with `DUPLICATE_VALUE` — hence botDefinitionId is the primary key.
-// But botDefinitionId is back-filled onto the template row ONLY for platform-
-// pre-provisioned agents: the ITSM create path never stamps `templateName`, so
-// agents THIS skill creates keep a null template botDefinitionId forever, and a
-// DeveloperName-keyed read is the reliable guard for them — used as the FALLBACK.
-// (Preflight emits `template.botDefinitionId`; the workflow passes it as the
-// primary key and the collected developerName as the fallback key.)
+// collected developerName `IT_Service_Employee_Agent`, and its template row
+// carries a NULL botDefinitionId — so a read keyed on botDefinitionId + collected
+// DeveloperName false-negatives (exists:false) and the create then collides on
+// `apiName` with `DUPLICATE_VALUE`. `AgentTemplate` is what closes that gap: the
+// live pre-provisioned agent carries `AgentTemplate=svc_emp_intelligence__ItEmployeeAssistance`
+// (the exact template id the skill installs — preflight `template.id`), so matching
+// on it recovers the agent regardless of its DeveloperName. This is far more
+// reliable than a display name (MasterLabel) — AgentTemplate is the platform-
+// stamped source template, immune to renames, and namespaced OOTB. botDefinitionId
+// is back-filled onto the template row ONLY for platform-pre-provisioned agents:
+// the ITSM create path never stamps `templateName`, so agents THIS skill creates
+// keep BOTH a null template botDefinitionId AND a null `AgentTemplate` forever —
+// for those, the DeveloperName-keyed read is the reliable guard, used as the last
+// FALLBACK. (Preflight emits `template.botDefinitionId`, `template.id`, and the
+// collected developerName; the workflow passes the botDefinitionId as the primary
+// key, template.id as the AgentTemplate key, and the developerName as the fallback.)
 //
 // This classifier consumes the raw JSON of a `sf data query ... --json` read of
-// BotDefinition (BY Id primarily, BY DeveloperName on the fallback) and decides
+// BotDefinition (BY Id primarily, BY AgentTemplate then DeveloperName on the
+// fallback) and decides
 // whether the agent already exists — and if so, whether its latest BotVersion is
 // Inactive (so the workflow can offer to activate it instead of creating a
 // duplicate). This is the deterministic decision that gates whether the write is
 // skipped — it MUST NOT be interpreted by the model in prose (authoring standard A9).
 //
 // Usage:
-//   node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName]
+//   node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName] [agentTemplate]
 //
 // When <botDefinitionId> is empty, `-`, or the literal `null`/`undefined` (the
-// matched template carries no botDefinitionId), the classifier FALLS BACK to
-// keying on <developerName>, and <bot-query.json> must be a DeveloperName-keyed
-// BotDefinition read: self-created agents are never back-filled with a
-// botDefinitionId (the ITSM create path doesn't stamp `templateName`, so the
-// platform never joins the agent-templates row to its BotDefinition), so
-// DeveloperName is the only idempotency guard left for them. Only when BOTH
-// <botDefinitionId> and <developerName> are absent is exists:false emitted
-// without reading a query file. Otherwise <bot-query.json> is a FILE PATH to the
-// stdout captured from:
-//   sf data query -q "SELECT Id,DeveloperName,MasterLabel,
+// matched template carries no botDefinitionId — the normal Employee case), the
+// classifier FALLS BACK to keying on <agentTemplate> (the source template API
+// name — this is what catches the pre-provisioned `IT_Service_Employee`), and then
+// to <developerName> when the AgentTemplate misses too. <bot-query.json> must
+// therefore be a read that ORs all three keys together: self-created agents are
+// never back-filled with a botDefinitionId AND carry a null AgentTemplate (the
+// ITSM create path doesn't stamp `templateName`), so DeveloperName is their only
+// idempotency guard; the pre-provisioned broad agent — whose DeveloperName differs
+// from this skill's collected guess — is caught by AgentTemplate. Only when ALL of
+// <botDefinitionId>, <agentTemplate>, and <developerName> are absent is
+// exists:false emitted without reading a query file. Otherwise <bot-query.json> is
+// a FILE PATH to the stdout captured from:
+//   sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,
 //     (SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1)
-//     FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" \
+//     FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>'
+//       OR DeveloperName='<developerName>'" \
 //     --target-org <org> --json > file.json
-// (The present-id read ORs in DeveloperName so a DANGLING template→BotDefinition
-// link — a botDefinitionId whose target BotDefinition was since deleted — still
-// surfaces the live same-name agent: the classifier tries the Id first, then
-// falls back to the name on the SAME records. The pure FALLBACK read, taken when
-// the template row carries no botDefinitionId at all, keys on
-// `DeveloperName='<developerName>'` only; everything else is identical.
+// (The present-id read ORs in AgentTemplate AND DeveloperName so a DANGLING
+// template→BotDefinition link — a botDefinitionId whose target BotDefinition was
+// since deleted — still surfaces the live agent: the classifier tries the Id
+// first, then the AgentTemplate, then the DeveloperName on the SAME records. The
+// pure FALLBACK read, taken when the template row carries no botDefinitionId at
+// all, keys on `AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'`;
+// everything else is identical.
 // `sf data query --json` wraps results in a `.result.records[]` envelope. The
 // BotVersions subquery is required so this classifier can see the latest
 // version's Status — a query without it leaves latestVersionStatus null and
@@ -61,16 +77,17 @@
 // child row was returned), and needsActivation is true only when exists is true
 // AND latestVersionStatus is "Inactive" — the signal to offer activating the
 // existing version instead of creating a new agent. `matchedBy` is
-// "botDefinitionId" | "developerName" | null, recording which key hit. Exit code
+// "botDefinitionId" | "agentTemplate" | "developerName" | null, recording which
+// key hit. Exit code
 // is always 0 on a parseable body (or when neither key is supplied); the verdict
 // is carried in the payload. On an unparseable/failed query it exits 3 so the
 // workflow surfaces the raw error rather than assuming NOT-EXISTS.
 
 import { readFileSync } from 'node:fs';
 
-const [queryPath, rawBotDefinitionId, rawDeveloperName] = process.argv.slice(2);
+const [queryPath, rawBotDefinitionId, rawDeveloperName, rawAgentTemplate] = process.argv.slice(2);
 if (!queryPath) {
-  process.stderr.write('usage: node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName]\n');
+  process.stderr.write('usage: node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName] [agentTemplate]\n');
   process.exit(2);
 }
 
@@ -88,8 +105,10 @@ function notSet(v) {
 
 const botDefinitionId = String(rawBotDefinitionId ?? '').trim();
 const developerName = String(rawDeveloperName ?? '').trim();
+const agentTemplate = String(rawAgentTemplate ?? '').trim();
 const noId = notSet(botDefinitionId);
 const noName = notSet(developerName);
+const noTemplate = notSet(agentTemplate);
 
 const NOT_EXISTS = {
   exists: false,
@@ -103,11 +122,12 @@ const NOT_EXISTS = {
   needsActivation: false,
 };
 
-// Nothing to key on — no botDefinitionId AND no developerName fallback. There is
-// no way to detect an existing agent, so this is the create path. (The workflow
-// should always pass the collected developerName so the fallback below can run;
-// this bare branch only fires when neither key is supplied.)
-if (noId && noName) {
+// Nothing to key on — no botDefinitionId AND no AgentTemplate fallback AND no
+// DeveloperName fallback. There is no way to detect an existing agent, so this is
+// the create path. (The workflow should always pass the collected developerName
+// and the template's id/AgentTemplate so the fallbacks below can run; this bare
+// branch only fires when none of the three keys is supplied.)
+if (noId && noTemplate && noName) {
   process.stdout.write(JSON.stringify(NOT_EXISTS, null, 2) + '\n');
   process.exit(0);
 }
@@ -131,19 +151,26 @@ if (!data || (typeof data.status === 'number' && data.status !== 0) || data.resu
 const records = Array.isArray(data.result?.records) ? data.result.records : [];
 
 // PRIMARY key: the template's `botDefinitionId` (the platform's authoritative
-// template→BotDefinition link) — catches the pre-provisioned broad agent whose
-// live DeveloperName differs from this skill's collected guess.
-// FALLBACK: the collected DeveloperName. Self-created agents are NOT
-// back-filled — the ITSM create path never stamps `templateName`, so the
-// platform never joins the agent-templates row to its BotDefinition and
-// `botDefinitionId` stays null on every later read — so DeveloperName is their
-// only guard. We ALSO fall back to DeveloperName when a PRESENT botDefinitionId
-// matches nothing (a dangling link whose target BotDefinition was deleted): the
-// present-id Phase-2 SOQL reads `WHERE Id=... OR DeveloperName=...`, so a stale
-// link still surfaces the live same-name agent instead of slipping through to the
-// create path and colliding with DUPLICATE_VALUE. Try the Id first, then the
-// name; each filter is self-checking on top of the SOQL WHERE so a wrong-keyed
-// read can't false-positive.
+// template→BotDefinition link) — catches a pre-provisioned agent whose live
+// DeveloperName differs from this skill's collected guess. For the broad Employee
+// agent this is null (see header), so in practice the AgentTemplate fallback below
+// is what fires.
+// FALLBACK: the BotDefinition's own `AgentTemplate`, then the collected
+// DeveloperName. `AgentTemplate` is the OOTB source-template API name the platform
+// stamps on a template-instantiated agent — the reliable "an agent from THIS
+// template already exists" signal for the pre-provisioned broad/specialized
+// agents, independent of any DeveloperName rename (the pre-provisioned
+// `IT_Service_Employee` carries `AgentTemplate=svc_emp_intelligence__ItEmployeeAssistance`
+// even though its DeveloperName differs from this skill's guess). Self-created
+// agents are NOT stamped (the ITSM create path never sets `templateName`), so their
+// `AgentTemplate` is null and DeveloperName is their guard. We ALSO fall back this
+// way when a PRESENT botDefinitionId matches nothing (a dangling link whose target
+// BotDefinition was deleted): the present-id Phase-2 SOQL reads `WHERE Id=... OR
+// AgentTemplate=... OR DeveloperName=...`, so a stale link still surfaces the live
+// agent instead of slipping through to the create path and colliding with
+// DUPLICATE_VALUE. Try the Id first, then the template, then the name; each filter
+// is self-checking on top of the SOQL WHERE so a wrong-keyed read can't
+// false-positive.
 let matches = [];
 let matchedBy = null;
 if (!noId) {
@@ -151,12 +178,40 @@ if (!noId) {
   matches = records.filter((r) => idKey(r?.Id) === wantedIdKey);
   if (matches.length) matchedBy = 'botDefinitionId';
 }
+// FIRST FALLBACK: the BotDefinition's `AgentTemplate` (source template API name).
+// The broad pre-provisioned "IT Service Employee" agent lives under DeveloperName
+// `IT_Service_Employee` — which the DeveloperName filter below misses when this
+// skill collects its default `IT_Service_Employee_Agent` — while its template row
+// carries no botDefinitionId, so the Id and DeveloperName keys both miss and the
+// create then collides with DUPLICATE_VALUE. Its `AgentTemplate` is
+// `svc_emp_intelligence__ItEmployeeAssistance` (the template this skill installs),
+// so matching on it recovers the live agent reliably. SOQL text comparison is
+// case-insensitive, so compare the same way. `AgentTemplate` is NOT unique (a
+// template can be instantiated more than once), so if more than one record shares
+// it we keep them all but surface an Active version first (see below) — the report
+// should treat the already-active one as the real match.
+if (!matches.length && !noTemplate) {
+  const wantedTemplate = agentTemplate.toLowerCase();
+  matches = records.filter((r) => String(r?.AgentTemplate ?? '').trim().toLowerCase() === wantedTemplate);
+  if (matches.length) matchedBy = 'agentTemplate';
+}
+// SECOND FALLBACK: the collected DeveloperName — the guard for self-created agents
+// (null AgentTemplate). DeveloperName uniqueness is case-insensitive; compare
+// accordingly.
 if (!matches.length && !noName) {
-  // DeveloperName uniqueness is case-insensitive; compare accordingly.
   const wantedName = developerName.toLowerCase();
   matches = records.filter((r) => String(r?.DeveloperName ?? '').trim().toLowerCase() === wantedName);
   if (matches.length) matchedBy = 'developerName';
 }
+if (matchedBy === 'agentTemplate' && matches.length > 1) {
+  // Prefer a record whose latest BotVersion is Active so `matches[0]` (used for
+  // latestVersion/agentId below) reflects the live agent rather than a stale draft.
+  matches = [...matches].sort((a, b) => {
+    const aActive = a?.BotVersions?.records?.[0]?.Status === 'Active' ? 0 : 1;
+    const bActive = b?.BotVersions?.records?.[0]?.Status === 'Active' ? 0 : 1;
+    return aActive - bActive;
+  });
+}
 const exists = matches.length > 0;
 
 // The BotVersions child subquery (if present in the SOQL) surfaces the latest
@@ -171,12 +226,15 @@ const needsActivation = exists && latestVersionStatus === 'Inactive';
 process.stdout.write(JSON.stringify({
   exists,
   count: matches.length,
-  // Which key matched — `botDefinitionId` (primary) or `developerName` (the
-  // fallback for self-created agents). null when nothing matched.
+  // Which key matched — `botDefinitionId` (primary), `agentTemplate` (the
+  // reliable catcher for the pre-provisioned broad agent whose DeveloperName
+  // differs from the collected guess), or `developerName` (the fallback for
+  // self-created agents). null when nothing matched.
   matchedBy: exists ? matchedBy : null,
   agentId: exists ? (matches[0].Id ?? null) : null,
-  // On a DeveloperName-fallback hit this surfaces the live BotDefinition Id the
-  // template row was missing; on the Id path it echoes the queried id.
+  // On an AgentTemplate- or DeveloperName-fallback hit this surfaces the live
+  // BotDefinition Id the template row was missing; on the Id path it echoes the
+  // queried id.
   botDefinitionId: exists ? (matches[0].Id ?? null) : (noId ? null : botDefinitionId),
   developerName: exists ? (matches[0].DeveloperName ?? null) : null,
   latestVersionId: latestVersion?.Id ?? null,