@salesforce/afv-skills 1.55.0 → 1.56.0

package/skills/service-helpagent-coordinate/references/channel-voice.md

@@ -2,7 +2,7 @@
 
 > **When to read this file.** Load it only when the user has selected **Voice** at Checkpoint 3 of `assets/help-agent-spec.md`. If they selected Web Chat, read `channel-web-chat.md` instead. If they selected Help Portal, delegate to the sibling skill `service-concierge-portal-generate` — do not inline portal steps here.
 
-Voice wires the Help Agent to an existing `PstnVoice` MessagingChannel via an inbound RoutingFlow. It does **not** provision a new phone number — number acquisition puts the org in a state that isn't cleanly retrievable, so it's out of scope for this skill. If the user has no `PstnVoice` channel yet, tell them to provision the number in Setup → Feature Settings → Service → **Communication Channels** first, then come back.
+Voice wires the Help Agent to a `PstnVoice` MessagingChannel via an inbound RoutingFlow. This skill never calls the Number Management API itself — if no `PstnVoice` channel exists yet, it delegates number procurement to `service-agentforce-contact-center-coordinate`, which owns that end-to-end (fetch → procure → verify live → create the channel).
 
 ---
 
@@ -15,10 +15,20 @@ sf data query --target-org $ORG --json \
   --query "SELECT Id, DeveloperName, MasterLabel, MessagingPlatformKey, IsActive FROM MessagingChannel WHERE MessageType='PstnVoice' ORDER BY MasterLabel"
 ```
 
-If none are returned, stop and tell the user to provision a phone number and `PstnVoice` MessagingChannel in Setup first — this skill does not create one.
-
 If any are returned, present them and let the user choose. Capture the channel's `DeveloperName` as `CHANNEL_DEV_NAME`, then continue to **Step 8 — Wire the channel to the agent**. Fallback queue resolution (including the `SobjectType='VoiceCall'` requirement) is owned by `service-agentforce-channel-configure` — do not resolve or create the queue here.
 
+If none are returned, continue to **No existing number** below.
+
+---
+
+## No existing number — delegate provisioning
+
+Ask the user (`AskUserQuestion`): **provision a new number now** (delegate to `service-agentforce-contact-center-coordinate`), or **provision manually in Setup → Feature Settings → Service → Communication Channels** and come back once a `PstnVoice` channel exists.
+
+If they choose to provision now, delegate to `service-agentforce-contact-center-coordinate`, passing `$ORG`. Instruct it to run its full number-procurement flow through channel creation, but steer the routing-model choice (its Step 7) to **Omni Queue**, not Omni Flow — the Help Agent already exists and owns its own agent authoring; Omni Flow's agent/flow-authoring steps would create a second, redundant agent. `service-agentforce-channel-configure` Branch B (this skill's Step 8, below) rewires the created channel's `SessionHandlerId`/`FallbackQueueId` to the Help Agent regardless of which routing model created it, so Omni Queue is the correct, minimal choice here.
+
+Once `service-agentforce-contact-center-coordinate` reports the created `PstnVoice` MessagingChannel, capture its `DeveloperName` as `CHANNEL_DEV_NAME` and continue to **Step 8 — Wire the channel to the agent**.
+
 ---
 
 ## Step 8 — Wire the channel to the agent
@@ -42,5 +52,6 @@ Return to the Checkpoint 3 loop — offer the user the option to add another cha
 
 | Rule | Rationale |
 |---|---|
-| This skill never acquires a phone number | Provisioning puts the org in a state that isn't cleanly retrievable — must be done in Setup before this skill runs |
+| This skill never calls the Number Management API itself | Delegate provisioning to `service-agentforce-contact-center-coordinate` — do not hand-roll fetch/procure/verify-live here |
+| When delegating provisioning, steer its routing-model choice to Omni Queue | Omni Flow would author a second, redundant Agentforce agent; Branch B rewires the channel's routing to the Help Agent regardless of which model created it |
 | Never resolve or create the fallback queue here | `service-agentforce-channel-configure` owns queue resolution end to end — resolving it twice can double-prompt the user |

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

@@ -2,10 +2,11 @@
 name: service-itsm-agentic-setup-agentforce-coordinate
 description: "Orchestrator for setting up Agentforce in Salesforce Service Cloud ITSM — Agentforce Studio enablement, the IT Service Fulfiller agent, the IT Service Employee agent, specialized employee agents, and human escalation. Use when the user asks to set up Agentforce for ITSM, enable Studio and the Fulfiller/Employee agents together, configure employee-agent escalation, wants a guided Agentforce ITSM walkthrough, or asks what Agentforce features are available for IT Service. Presents available Agentforce capabilities and delegates each selection to a specialized child skill while tracking progress. Triggers on: set up agentforce for itsm, configure agentforce studio and fulfiller, agentforce itsm walkthrough, what agentforce features for it service. DO NOT TRIGGER when: the user asks to enable Agentforce Studio alone, asks to create or activate the Fulfiller or Employee agent alone, asks to configure escalation alone, or asks about CMDB, Incident Management, Teams, or general ITSM setup without Agentforce intent."
 metadata:
-  version: "1.8"
+  version: "2.0"
   domains: ["Service", "Agentforce"]
   relatedSkills:
     - "service-agentforce-human-escalation-configure"
+    - "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-employee-agent-configure"
@@ -65,6 +66,8 @@ undifferentiated list. Only features with a working child skill appear in the me
 
 **Escalation-after-Employee rule (#5 depends on #3).** Employee Agent escalation (#5) configures the Employee agent's hand-off to a human, so it **requires the Employee Agent (#3) to exist and be Active** first. If #5 is selected, ensure #3 has completed successfully in this run (or was already done) before delegating to it; otherwise queue #3 ahead of #5. #5 never runs before Studio (#1) either.
 
+**Runtime-access-after-creation rule (unconditional).** Whenever any Stage 2 agent (#2, #3, #4) returns a live verdict this session (`CREATED`/`ALREADY-CREATED`/`ACTIVATED`), append an automatic **Stage 3 runtime-access** step at the **back** of the queue — the post-requisite mirror of the Studio-first pre-requisite: appended always, never a menu pick — and delegate it **once** after the last Stage 2 agent to `service-itsm-agentic-setup-agent-runtime-access-assign`, covering every newly-live agent (its own target-user + confirm-to-write gates govern the grants; Stage 3 guarantees the *offer*, never a silent grant). It is non-negotiable: a live agent's actions fail on missing user permissions until this sets them up. Do **NOT** append it when only Studio ran or no agent went live (`FAILED`/`PARTIAL`/`PENDING CONFIRMATION`/`DECLINED`, or a Stage 2 verify that stopped the queue). Narration + status mapping: **Runtime access hand-off** in `examples/output-templates.md`.
+
 | # | Feature | Stage | Child Skill |
 |---|---------|-------|-------------|
 | 1 | Agentforce Studio enablement (Foundation for all agents) | 1 | `service-itsm-agentic-setup-agentforce-studio-configure` |
@@ -72,21 +75,22 @@ undifferentiated list. Only features with a working child skill appear in the me
 | 3 | IT Service Employee Agent | 2 | `service-itsm-agentic-setup-employee-agent-configure` |
 | 4 | Specialized Agents for Employee | 2 | `service-itsm-agentic-setup-employee-agent-configure` |
 | 5 | Employee Agent escalation | Post | `service-agentforce-human-escalation-configure` (pass the IT scenario inputs: agent `IT_Service_Employee_Agent`, queue `General_IT_Queue`, `CONTEXT_OBJECT=MessagingSession`) |
-
-**How #3 and #4 relate.** Both #3 and #4 delegate to the same child skill,
-`service-itsm-agentic-setup-employee-agent-configure` — the difference is which template it installs.
-#3 (IT Service Employee Agent) installs the **broad, ready-to-go** employee agent, which is the child
-skill's default whenever no specialization is named. #4 (Specialized Agents for Employee) installs a
-**specialized** employee agent instead — but the child skill only takes the specialized path when it
-is handed the name of a specialized template; handed nothing, it silently falls back to the broad
-agent, which would just re-create #3. So when the user selects #4, **ask which specialized employee
-agent they want before delegating** — offer common examples (Password Manager, Certificate Management,
-Onboarding, Hardware Request) and note that more are available; the child skill holds the full catalog
-and will disambiguate a partial or ambiguous name. Then delegate to the child skill **with that named
-specialization**, and it will pin the matching template (the chosen template names the agent it
-creates). **Never delegate #4 without a named specialization** — that is the one case that produces a
-duplicate broad agent. The specialized templates themselves are turned on in Stage 1 (Agentforce
-Studio enablement); #4 is where an agent is built and activated from one of them.
+| — | Runtime access (auto after any Stage 2 create/activate; never a user pick) | 3 | `service-itsm-agentic-setup-agent-runtime-access-assign` |
+
+**IT Service Employee Agent vs Specialized Agents for Employee.** Both delegate to the same child
+skill, `service-itsm-agentic-setup-employee-agent-configure` — the difference is which template it
+installs. The IT Service Employee Agent installs the **broad, ready-to-go** employee agent (the child
+skill's default when no specialization is named). Specialized Agents for Employee installs a
+**specialized** one instead — but the child skill only takes the specialized path when handed a
+specialized template name; handed nothing it silently falls back to the broad agent, re-creating the
+IT Service Employee Agent. So **before delegating Specialized Agents for Employee, ask which
+specialized employee agent the user wants** — offer common examples (Password Manager, Certificate
+Management, Onboarding, Hardware Request), note more are available, and let the child skill
+disambiguate a partial or ambiguous name; then delegate **with that named specialization** (the chosen
+template names the agent). **Never delegate Specialized Agents for Employee without a named
+specialization** — that is the one case that produces a duplicate broad agent. The specialized
+templates themselves are turned on in Stage 1; this item is where an agent is built and activated from
+one of them.
 
 `service-itsm-agentic-setup-agentforce-studio-configure` performs its own read-and-classify
 preflight (reading live toggle state before writing) rather than delegating to
@@ -99,11 +103,11 @@ to call it as part of the delegation flow above.
 Once a child skill finishes:
 
 1. **Verify** the child skill's own deterministic verdict by running
-   `node "<skill_dir>/scripts/verify-child-verdict.mjs" <studio|fulfiller|employee|escalation> <verdict>` — never
+   `node "<skill_dir>/scripts/verify-child-verdict.mjs" <studio|fulfiller|employee|escalation|runtime> <verdict>` — never
    re-derive the success/failure comparison in prose. Pass Studio's `overall` field from
-   `classify-final-report.mjs`, Fulfiller/Employee Agent's Phase 8 aggregate verdict, or the escalation
-   leaf's `status` (`CONFIGURED`/`ALREADY-CONFIGURED`), as
-   `<verdict>`. Exit code `0` means advance; exit code `1` means **stop and surface the failure in
+   `classify-final-report.mjs`, Fulfiller/Employee Agent's Phase 8 aggregate verdict, the escalation
+   leaf's `status` (`CONFIGURED`/`ALREADY-CONFIGURED`), or the runtime-access skill's Phase-7 aggregate,
+   as `<verdict>`. Exit code `0` means advance; exit code `1` means **stop and surface the failure in
    plain language — do not advance to the next feature in the queue.** A partially-enabled Studio
    (e.g. Einstein GenAI on but the parent umbrella still blocked, `overall: PARTIAL`) will make
    Fulfiller/Employee Agent creation fail too, so the script treats `PARTIAL` the same as `FAILED`
@@ -111,6 +115,10 @@ Once a child skill finishes:
 2. **Update the status** — mark the completed feature as "Done"
 3. **Suggest the next logical step** — if another feature is available, recommend it based on the dependency order
 4. **Re-present the menu** with updated status — use the **Post-feature progress** template in `examples/output-templates.md`
+5. **Stage 3 after the Stage 2 queue drains.** Once no Stage 2 agent remains queued and at least one
+   went live this session, delegate the appended **Stage 3** once (per the rule above) and verify with
+   `verify-child-verdict.mjs runtime <verdict>` — exit `0` ⇒ Stage 3 Done → completion summary; exit
+   `1` ⇒ stop and surface in plain language.
 
 ### 6. Completion summary
 
@@ -133,20 +141,21 @@ Stage 2 — Agent templates: install & activate   (only after Stage 1)
   3. IT Service Employee Agent           (install the broad employee agent from its template and activate it)
   4. Specialized Agents for Employee     (install a specialized employee agent — user picks the template — and activate it)
 
+Stage 3 — Runtime access   (AUTO — after any Stage 2 agent goes live, not a menu pick)
+  •  Grant the live agent(s)' runtime feature permissions + an Agent Access permission set
+
 Post-setup — Human escalation   (only after item 3 is active)
   5. Employee Agent escalation           (configure canEscalate, outbound routing, a staffed General IT queue, and failure-threshold directives)
 ```
 
-Stage 1 (Agentforce Studio enablement) is the **foundation**: it turns on the org-level Agentforce
-and Einstein GenAI feature toggles that all the agents are **built on top of** (including the
-specialized employee templates). Enable it first — attempting to install or activate any agent
-before this foundation is enabled will fail. The three Stage 2 items (Fulfiller, Employee, and
-Specialized Agents for Employee) are independent siblings (none depends on the others) — they can be
-selected together and installed in any order once Stage 1 is done. Specialized Agents for Employee
-is listed right after the IT Service Employee Agent because both build employee agents from the same
-child skill: #3 the broad default, #4 a specialized template the user chooses. Employee Agent
-escalation (#5) is a post-setup action that builds on a live Employee agent, so it runs only after
-item 3 has succeeded.
+Stage 1 (Agentforce Studio enablement) is the **foundation** — it turns on the org-level Agentforce
+and Einstein GenAI toggles every agent (and the specialized employee templates) is built on, so
+enable it first; any agent install/activate attempted before it will fail. The three Stage 2 items
+are independent siblings, orderable freely once Stage 1 is done, and Specialized Agents for Employee
+sits right after the IT Service Employee Agent because both build employee agents from the same child
+skill (the broad default vs. a specialized template the user picks). Employee Agent escalation (a
+post-setup action on a live Employee agent) and **Stage 3 (Runtime access)** (automatic after any
+Stage 2 agent goes live — not a menu pick) are governed by their rules above.
 
 ---
 
@@ -159,7 +168,7 @@ item 3 has succeeded.
 - NEVER show features that do not have a working child skill
 - If the user says "set up everything" or "all", walk through each available feature sequentially in the recommended order, confirming between each step
 - Track progress across the conversation — do not re-present completed features as "Not done"
-- Specialized Agents for Employee (#4) is **re-selectable** — each run builds a *different* specialized employee agent from a template the user picks. Mark the agent just built as `Done`, but keep #4 available to run again for additional specialized agents; do not treat a completed #4 as permanently finished the way #1–#3 are. If the user picks #4 again, ask which specialized template to use next
+- Specialized Agents for Employee (#4) is **re-selectable** — each run builds a *different* specialized employee agent from a template the user picks. Mark the agent just built as `Done`, but keep #4 available to run again for additional specialized agents; do not treat a completed #4 as permanently finished the way the one-and-done items are. If the user picks #4 again, ask which specialized template to use next
 - Employee Agent escalation (#5) is a **post-setup** action that requires the IT Service Employee Agent (#3) to be Active first — never delegate #5 before #3 has succeeded in this run (or was already done)
 - NEVER advance to the next feature in the queue if the current one failed or only partially
   succeeded — stop and surface the failure in plain language instead
@@ -172,6 +181,13 @@ item 3 has succeeded.
   `DUPLICATE_VALUE`, …), internal endpoint/API names, developer names (feature apiNames like
   `sales-cloud-agent-studio`), and CLI/tooling internals. Translate everything to plain, human-readable
   language. Child-skill names shown as next-step pointers are fine.
+- NEVER name a feature by a bare item number in user-facing prose. The `#1`–`#5` labels (and the
+  menu's `#` column) are **internal shorthand** for this skill's ordering/delegation rules and a menu
+  selection handle only (where the user replies `1, 2`) — not feature names. In every message the user
+  reads — opt-out/skip, prerequisite/blocked, progress, next-step, and the completion summary — name
+  each feature in full, never a bare number or range like `#4` or `#1–#3`. This matters most when a
+  Stage 1 toggle is skipped: name the blocked and still-available features, don't say "#4 is blocked,
+  #1–#3 can proceed". See **Naming features in prose** in `examples/output-templates.md`.
 - If the user asks about Agentforce features that are not yet available (e.g., Requester agent, custom topic packs, agent metrics dashboards), tell them those features are not yet available in this orchestrator and will be added as their child skills merge
 
 ---
@@ -192,8 +208,10 @@ Before emitting any menu or summary in this skill, mentally confirm each of the
 - [ ] For a completion summary, the header line and closing line are chosen by the rubric in `examples/output-templates.md` (all `Done` → *Complete*; any `Not done`/`In progress` → *Finished*)
 - [ ] A feature is being configured only because the user explicitly selected it (or is being walked through sequentially with confirmation under an "all" / "everything" request)
 - [ ] Studio enablement is verified done before delegating to any Stage 2 agent (Fulfiller, Employee, or Specialized Agents for Employee)
+- [ ] If any Stage 2 agent went live, Stage 3 runtime access was appended once and delegated to `service-itsm-agentic-setup-agent-runtime-access-assign` (skipped otherwise)
 - [ ] The next action delegates to a child skill, never configures a feature inline
 - [ ] No Salesforce record IDs appear in the output — human-readable names only
+- [ ] No feature is named by a bare item number or range (`#4`, `#1–#3`) in user-facing prose — every feature is named in full; digits appear only as menu selection handles
 
 ---
 

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

@@ -6,6 +6,31 @@ Emit one of these text blocks at the corresponding step in the workflow. Setup i
 only after the Employee agent is active. Only items with a working child skill appear — hide
 placeholder rows.
 
+## Naming features in prose (never use bare item numbers)
+
+The `#1`–`#5` labels and the menu's `#` column are internal shorthand for the ordering/delegation
+rules and a **selection handle** in the menu (the user replies `1, 2`). They are **not** feature
+names. In every message the user reads — opt-out/skip, prerequisite/blocked, progress, next-step, and
+the completion summary — refer to each feature by its full menu name, never by a bare number or range.
+
+This matters most when a user skips a Stage 1 platform toggle and you explain the downstream impact:
+
+```text
+Wrong (internal positional labels leak to the user):
+   You skipped the Specialized Agent Templates toggle — that's the prerequisite for feature #4
+   (Specialized Agents for Employee). Features #1–#3 (Studio, Fulfiller agent, Employee agent) can
+   all proceed, but #4 will be blocked.
+
+Right (features named in full):
+   You skipped the Specialized Agent Templates toggle. That toggle is the prerequisite for building
+   Specialized Agents for Employee, so Agentforce Studio, the IT Service Fulfiller agent, and the IT
+   Service Employee agent can all still be set up — but Specialized Agents for Employee can't be built
+   until that toggle is enabled.
+```
+
+A digit is fine only as a menu selection handle (`reply 1, 2`); it must never stand in for a feature
+name in prose, progress, or the completion summary.
+
 ## Feature menu (Behavior step 3)
 
 ```text
@@ -41,6 +66,8 @@ Stage 2 (install & activate). Employee Agent escalation is available after the E
 
 Reply with the numbers of the features you want to set up (one or more, e.g. `1` or `1, 2`).
 If you pick a Stage 2 template without Stage 1, I'll enable the Stage 1 foundation first.
+After any Stage 2 agent is created and activated, I'll automatically set up its runtime access
+(Stage 3) so it works when opened — that's not a numbered choice.
 ```
 
 Stage 1 (Agentforce Studio enablement) is the **foundation** — it enables the org-level platform
@@ -83,6 +110,8 @@ Agentforce Studio — enabled successfully
 │ 3 │ Stage 2 │ IT Service Employee Agent     │ Not done    │
 │ 4 │ Stage 2 │ Specialized Agents            │ Not done    │
 │   │         │ for Employee                  │             │
+│ R │ Stage 3 │ Runtime access for the        │ Not started │
+│   │ (auto)  │ agent(s)                      │             │
 │ 5 │ Post    │ Employee Agent escalation     │ Not done    │
 │   │ setup   │                               │             │
 └───┴─────────┴───────────────────────────────┴─────────────┘
@@ -93,21 +122,50 @@ employee agent from their templates. The Fulfiller agent gives IT technicians an
 assistant for triage, case summaries, and record automations; the Employee agent
 gives requesters self-service help with their own requests; and Specialized
 Agents for Employee builds a focused employee agent (such as Password Manager or
-Onboarding) from a specialized template you pick.
+Onboarding) from a specialized template you pick. Once an agent is live, I'll set
+up its runtime access (Stage 3) automatically — no need to pick it.
 ```
 
+## Runtime access hand-off (Behavior step 5 — automatic Stage 3)
+
+The `R` (Stage 3) row is not a menu choice. As soon as the Stage 2 queue is drained and at least one
+agent went live this session (`Done`), delegate **once** to
+`service-itsm-agentic-setup-agent-runtime-access-assign`, covering every newly-live agent. That skill
+runs its own target-user selection and confirm-to-write gate — this orchestrator only guarantees the
+hand-off happens, never a silent grant. Narrate it like this before delegating:
+
+```text
+Your agent(s) are live. One required follow-up before anyone can use them: an activated agent's
+actions call platform features the user can't run yet, so it fails the moment it's opened. I'll set
+up runtime access now (Stage 3) — granting the runtime feature permissions the agent's actions use,
+plus an Agent Access permission set, to the user(s) you choose.
+
+Handing off to service-itsm-agentic-setup-agent-runtime-access-assign …
+```
+
+Then mark the `R` row from its Phase-7 verdict: `ASSIGNED`/`ALREADY-ASSIGNED` → `Done`; `NONE-PROVISIONED`
+→ `No-op — nothing to assign`; the user declined the runtime skill's own gate → `Skipped by user`;
+`PARTIAL`/`FAILED` → stop and surface the failure in plain language (do not mark `Done`).
+
 ## Completion summary (Behavior step 6)
 
 The completion summary fires either (a) after every item completes, or (b) when the user says they
 are finished — even if some items are still `Not done`. When rendering:
 
 - Substitute each row's actual tracked status: `Done`, `In progress`, or `Not done`. Do NOT
-  hard-code `Done`.
-- Choose the header line based on whether every item is `Done`:
-  - All items `Done` → `Agentforce for ITSM Setup — Complete`
-  - Any item still `Not done` or `In progress` → `Agentforce for ITSM Setup — Finished`
+  hard-code `Done`. The Stage 3 (Runtime access) row is special — its status is one of `Done`
+  (runtime access set up), `No-op — nothing to assign` (the runtime skill found nothing provisioned
+  to grant), `Skipped by user` (the user declined the runtime skill's own gate), or `Not started`
+  (no Stage 2 agent went live, so Stage 3 never triggered).
+- A row is **settled** when it is `Done`, or — for Stage 3 only — `No-op — nothing to assign`, or a
+  `Not started` that is correct because no agent went live. `Skipped by user` on Stage 3 (an agent
+  went live but runtime access was declined) is **not** settled.
+- Choose the header line based on whether every item is settled:
+  - All items settled → `Agentforce for ITSM Setup — Complete`
+  - Any selected item still `Not done`/`In progress`, or Stage 3 left `Skipped by user` after an
+    agent went live → `Agentforce for ITSM Setup — Finished`
 - Choose the closing line based on state:
-  - All `Done` → `Your Agentforce for ITSM setup is complete.`
+  - Complete → `Your Agentforce for ITSM setup is complete.`
   - Otherwise → `You have finished the items you selected. The remaining items can be resumed later by re-invoking this orchestrator.`
 
 Example — user finished after only enabling Agentforce Studio (the Stage 2 agents stayed `Not done`):
@@ -125,6 +183,8 @@ Agentforce for ITSM Setup — Finished
 │ 3 │ Stage 2 │ IT Service Employee Agent     │ Not done    │
 │ 4 │ Stage 2 │ Specialized Agents            │ Not done    │
 │   │         │ for Employee                  │             │
+│ R │ Stage 3 │ Runtime access for the        │ Not started │
+│   │ (auto)  │ agent(s)                      │             │
 │ 5 │ Post    │ Employee Agent escalation     │ Not done    │
 │   │ setup   │                               │             │
 └───┴─────────┴───────────────────────────────┴─────────────┘
@@ -132,3 +192,8 @@ Agentforce for ITSM Setup — Finished
 You have finished the items you selected. The remaining items can be
 resumed later by re-invoking this orchestrator.
 ```
+
+Here Stage 3 is `Not started` because only Studio was enabled — no agent went live, so the
+runtime-access step correctly never triggered, and its unfinished status does not by itself force
+`Finished` (the unselected Stage 2 items already do). Had a Stage 2 agent gone live, Stage 3 would
+show `Done`, `No-op — nothing to assign`, or `Skipped by user` instead.

package/skills/service-itsm-agentic-setup-agentforce-coordinate/scripts/verify-child-verdict.mjs

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
 // Deterministic queue-advancement gate (authoring standard A9). Each child
 // skill already emits its own machine-readable verdict — Studio's `overall`
-// from classify-final-report.mjs, Fulfiller/Employee's Phase 8 aggregate — so
+// from classify-final-report.mjs, Fulfiller/Employee's Phase 8 aggregate, the
+// escalation leaf's `status`, the runtime-access skill's Phase-7 aggregate — so
 // this script only maps those fixed value sets to an advance/stop decision.
 // It must not be re-derived in prose; the coordinator runs this and reads the
 // exit code.
 //
 // Usage:
-//   node verify-child-verdict.mjs <studio|fulfiller|employee|escalation> <verdict>
+//   node verify-child-verdict.mjs <studio|fulfiller|employee|escalation|runtime> <verdict>
 //
-// Exit 0  -> child succeeded, safe to advance the queue.
+// Exit 0  -> child succeeded (or benign no-op), safe to advance the queue.
 // Exit 1  -> child failed or only partially succeeded, stop the queue.
 // Exit 2  -> usage error (bad args).
 
@@ -21,12 +22,28 @@ const SUCCESS_VALUES = {
   // emits CONFIGURED when every deterministic surface is satisfied; a re-run is an
   // idempotent CONFIGURED. INCOMPLETE/BLOCKED stop the queue.
   escalation: new Set(['CONFIGURED', 'ALREADY-CONFIGURED']),
+  // Runtime-access-assign (service-itsm-agentic-setup-agent-runtime-access-assign),
+  // the automatic Stage 3 after any Stage 2 agent goes live, emits its Phase-7
+  // aggregate: ASSIGNED (a write landed + read back) or ALREADY-ASSIGNED (all
+  // intended state already present). Both advance. PARTIAL / FAILED stop the queue.
+  runtime: new Set(['ASSIGNED', 'ALREADY-ASSIGNED']),
+};
+
+// Benign no-op verdicts: not a success (nothing was assigned) but not a failure
+// either — a legitimate terminal "there is nothing to assign" state that must
+// still ADVANCE (the queue is complete, not broken). Runtime-access emits
+// NONE-PROVISIONED when no feature permset is provisioned AND no agent is
+// activated: correct, expected, and nothing to remediate — so Stage 3 closes
+// cleanly rather than reading as a stop. PARTIAL / FAILED are deliberately NOT
+// here; those fall through to STOP below.
+const NOOP_VALUES = {
+  runtime: new Set(['NONE-PROVISIONED']),
 };
 
 const [child, verdict] = process.argv.slice(2);
 
 if (!child || !verdict || !SUCCESS_VALUES[child]) {
-  process.stderr.write('usage: node verify-child-verdict.mjs <studio|fulfiller|employee|escalation> <verdict>\n');
+  process.stderr.write('usage: node verify-child-verdict.mjs <studio|fulfiller|employee|escalation|runtime> <verdict>\n');
   process.exit(2);
 }
 
@@ -35,5 +52,10 @@ if (SUCCESS_VALUES[child].has(verdict)) {
   process.exit(0);
 }
 
+if (NOOP_VALUES[child]?.has(verdict)) {
+  process.stdout.write(`ADVANCE: ${child} verdict "${verdict}" is a benign no-op — nothing to assign, queue is complete.\n`);
+  process.exit(0);
+}
+
 process.stdout.write(`STOP: ${child} verdict "${verdict}" is not a success value — do not advance the queue.\n`);
 process.exit(1);

package/skills/service-itsm-agentic-setup-cmdb-access-assign/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: service-itsm-agentic-setup-cmdb-access-assign
-description: "Grant a specific user access to CMDB (Configuration Management Database) data in Service Cloud ITSM against a production or sandbox org by assigning the license-backed CMDB permission sets (Configuration Item Reader, Owner, Type Reader, Type Manager) and their permission-set licenses. Use when the user asks to give someone CMDB access, assign CMDB permission sets, grant a user the Configuration Item Reader/Owner role, or fix a CMDB 403 FUNCTIONALITY_NOT_ENABLED that a user still hits after the CMDB feature is already enabled. Triggers on: assign CMDB permission set, grant CMDB access, give user Configuration Item access, CMDB access for user, user still gets CMDB 403 after enable. DO NOT TRIGGER when: the user wants to turn on the CMDB feature or provision the ITOM tenant for the whole org (that is the CMDB feature-enable skill), only install a CMDB content bundle, work with CMDB records directly, or assign general (non-CMDB) permission sets to users (use dx-org-permission-set-assign)."
+description: "Grant a specific user access to CMDB (Configuration Management Database) data in Service Cloud ITSM against a production or sandbox org by assigning the license-backed CMDB permission sets (Configuration Item Reader, Owner, Type Reader, Type Manager) and their permission-set licenses. Use when the user asks to give someone CMDB access, assign CMDB permission sets, grant a user the Configuration Item Reader/Owner role, or fix a CMDB 403 FUNCTIONALITY_NOT_ENABLED that a user still hits after the CMDB feature is already enabled. Triggers on: assign CMDB permission set, grant CMDB access, give user Configuration Item access, CMDB access for user, user still gets CMDB 403 after enable. DO NOT TRIGGER when: the user wants to turn on the CMDB feature or provision the CMDB tenant for the whole org (that is the CMDB feature-enable skill), only install a CMDB content bundle, work with CMDB records directly, or assign general (non-CMDB) permission sets to users (use dx-org-permission-set-assign)."
 metadata:
-  version: "1.0"
+  version: "1.1"
   domains: ["Service"]
   minApiVersion: "67.0"
   relatedSkills:
@@ -13,6 +13,9 @@ metadata:
     headless-360:
       tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
       semver: ">=1.0.0"
+  accessCheck:
+    - type: "orgPerm"
+      value: "ITSrvcsCnfgMgmnt"
 allowed-tools: |
   Read AskUserQuestion
   mcp__headless-360__discover
@@ -71,7 +74,7 @@ not specify a role, ask (see Clarifying questions) — default to **Reader + Typ
 
 - **In scope**: resolving the target user, resolving the requested CMDB permission set(s), checking
   existing assignments, assigning the permission-set license(s) and permission set(s), and verifying.
-- **Out of scope**: enabling the CMDB feature / provisioning the ITOM tenant (Layers 0–2 —
+- **Out of scope**: enabling the CMDB feature / provisioning the CMDB tenant (Layers 0–2 —
   `service-itsm-agentic-setup-cmdb-configure`), installing content bundles, CMDB record CRUD,
   creating custom permission sets, or org-permission/edition changes.
 
@@ -173,17 +176,37 @@ Use the `Name` values from the table above. Capture each `Id` (the permission se
 (the PSL to assign). If a permission set is not found, the org likely is not CMDB-licensed — stop and
 report that CMDB does not appear to be set up on this org.
 
-### Step 4 — Check existing assignments (read — idempotency)
+### Step 4 — Check existing assignments (read — idempotency, permission-set-group–aware)
 
-For each target user + permission set, check whether the assignment already exists:
+A role can be granted **two ways**, and this check must accept **both** — or it falsely reports an
+already-granted role as missing and wrongly asks to assign it:
+
+1. **Directly** — a `PermissionSetAssignment` whose `PermissionSetId` is the role's own permission set.
+2. **Via a permission set group (PSG)** — when the role's permission set is a *member* of a PSG the
+   user is assigned. There the user's `PermissionSetAssignment` row carries a `PermissionSetGroupId` and
+   its `PermissionSetId` is the group's internal *aggregate* set — **not** the member permission set —
+   so a query filtering on `PermissionSetId = '<psId>'` returns **zero** even though the user
+   effectively holds the role.
+
+Run **both** permission-set reads per role; the permission set is present if **either** returns
+`totalSize >= 1` (the second is a top-level semi-join — nesting it inside an `OR` throws `MALFORMED_QUERY`):
 
 ```text
 dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetId = '<psId>'" } })
+dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetGroupId IN (SELECT PermissionSetGroupId FROM PermissionSetGroupComponent WHERE PermissionSetId = '<psId>')" } })
+```
+
+Then check the backing license (a PSG that includes the role also assigns its backing PSL directly, so
+this single read already covers the PSG case):
+
+```text
 dispatch_readonly({ "url": "/services/data/v67.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetLicenseAssign WHERE AssigneeId = '<userId>' AND PermissionSetLicenseId = '<pslId>'" } })
 ```
 
-If both already exist for a role, that role is **already assigned** — skip its writes and record it as
-already-done. Only assign what is missing.
+If the permission set is present by **either** path **and** the license read returns `totalSize >= 1`,
+that role is **already assigned** — skip its writes and record it as already-done. Only assign what is
+genuinely missing, and do **not** re-assign the member permission set directly when the user already
+holds it through a PSG.
 
 ### Step 5 — Assign the permission-set license, then the permission set (write — confirm first)
 
@@ -204,9 +227,10 @@ dispatch({ "url": "/services/data/v67.0/sobjects/PermissionSetAssignment", "meth
 
 ### Step 6 — Verify (read — do NOT trust the POST response alone)
 
-Re-run the Step 4 queries. Confirm each requested role now has **both** a `PermissionSetAssignment`
-and a `PermissionSetLicenseAssign` for the user. Report per-role: assigned / already had it. Only
-roles confirmed present in this read count as done.
+Re-run the Step 4 reads — **both** the direct and the via-PSG permission-set checks, plus the license
+check. A role counts as done only when its permission set is present by **either** path **and** its
+backing license reads back. Report per-role: assigned / already had it. Only roles confirmed present in
+this read count as done.
 
 ---
 
@@ -266,6 +290,7 @@ into what it means ("CMDB isn't turned on for this org yet"), rather than echoin
 | Feature status not `ENABLED` (or `403` on the status read) | Org-level CMDB gate not lifted | CMDB must be turned on for the org first; this is a separate setup step — point to the feature-enable skill |
 | Permission set not found | Org is not CMDB-licensed / not set up | CMDB does not appear to be available on this org; confirm it is licensed and enabled |
 | `403 FUNCTIONALITY_NOT_ENABLED` on a **bundle-management** read (e.g. `bundles/details`, `bundleListView`) after assignment, feature ENABLED | The user holds Reader/Owner/Type Reader but not **Type Manager** — bundle operations require it | Assign **Type Manager** — this role is required for CMDB bundle management; the other CMDB roles do not cover bundle operations |
+| Skill says a CMDB role is missing and asks to assign it, but the user already has it (e.g. through a permission set group) | Idempotency check saw only *directly* assigned permission sets and was blind to group-delivered grants — fixed in Step 4, which now also checks group membership | The user already has that access through a permission set group; treat the role as already granted — no new assignment is needed |
 | `400 DUPLICATE_VALUE` on assign | User already has that access | Not an error — report the role as already assigned |
 | License-limit / no-seats error on assign | CMDB permission-set license seats exhausted | Report seats in use vs available; a seat must free up (or more licenses added) before assigning |
 | `dispatch*` auth error | headless-360 MCP session not authenticated / token expired | Re-authenticate the headless-360 MCP connection and confirm the session points at the intended org |

package/skills/service-itsm-agentic-setup-cmdb-access-assign/references/mcp-invocation.md

@@ -148,8 +148,15 @@ the org is not CMDB-licensed — stop and report.
 
 ---
 
-## Step 4 — Check existing assignments (read — idempotency)
+## Step 4 — Check existing assignments (read — idempotency, permission-set-group–aware)
 
+A role's permission set can be held **directly** or as a **member of a permission set group (PSG)** the
+user is assigned. A PSG-delivered grant produces a `PermissionSetAssignment` whose `PermissionSetGroupId`
+is populated and whose `PermissionSetId` is the group's internal *aggregate* set — **not** the member
+permission set — so filtering on `PermissionSetId = '<psId>'` alone returns `0` for it. Run **both**
+permission-set reads; the permission set is present if **either** returns `totalSize >= 1`.
+
+### Directly assigned
 ```json
 mcp__headless-360__dispatch_readonly({
   "url":    "/services/data/v67.0/query",
@@ -158,6 +165,16 @@ mcp__headless-360__dispatch_readonly({
 })
 ```
 
+### Via a permission set group (top-level semi-join — nesting this inside an `OR` throws `MALFORMED_QUERY`)
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "queryParams": { "q": "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetGroupId IN (SELECT PermissionSetGroupId FROM PermissionSetGroupComponent WHERE PermissionSetId = '<psId>')" }
+})
+```
+
+### Backing license (a PSG that includes the role assigns its PSL directly, so this one read covers the PSG case)
 ```json
 mcp__headless-360__dispatch_readonly({
   "url":    "/services/data/v67.0/query",
@@ -166,8 +183,9 @@ mcp__headless-360__dispatch_readonly({
 })
 ```
 
-`totalSize == 1` on both → that role is already assigned; skip its writes. Otherwise assign what is
-missing (PSL and/or permission set).
+Permission set present by **either** path **and** the license read `totalSize >= 1` → that role is
+already assigned; skip its writes. Otherwise assign what is missing (PSL and/or permission set). Do
+**not** re-assign the member permission set directly when the user already holds it through a PSG.
 
 ---
 
@@ -204,8 +222,9 @@ Response on success: `{ "id": "0Pa...", "success": true }` (`201`). On `400`, re
 
 ## Step 6 — Verify (read)
 
-Re-run the Step 4 queries. A role counts as assigned only when **both** the `PermissionSetAssignment`
-and the `PermissionSetLicenseAssign` return `totalSize == 1` for the user. Report per role.
+Re-run the Step 4 reads — **both** the direct and the via-PSG permission-set checks, plus the license
+check. A role counts as assigned only when its permission set is present by **either** path **and** the
+`PermissionSetLicenseAssign` returns `totalSize >= 1` for the user. Report per role.
 
 ---
 
@@ -257,4 +276,5 @@ before the assignment can succeed.
 | `PermissionSet` query `totalSize == 0` | Org not CMDB-licensed / not set up | CMDB is not available on this org; confirm it is licensed and enabled |
 | `User` query `totalSize == 0` / `> 1` | User not found / ambiguous | Ask the user to confirm the username, or pick from the listed candidates |
 | `403 FUNCTIONALITY_NOT_ENABLED` on a bundle-management read (`bundles/details`, `bundleListView`) after assign | User lacks **Type Manager** — bundle operations require it, Reader/Owner/Type Reader do not clear it | Assign the **Type Manager** role (PS `ItSrvcCnfgItmTypManagerPermissionSet` + its own PSL `ItSrvcCnfgItmTypMgrPsl`), then re-verify via Step 6 |
+| Step 4 reports a role missing (skill asks to assign it) but the user already has it via a **permission set group** | Direct-only `PermissionSetId` filter is blind to PSG-delivered grants — the PSA row carries `PermissionSetGroupId` and the group's aggregate `PermissionSetId`, not the member set | Use the via-PSG semi-join in Step 4; a role present by **either** path is already assigned — do not re-assign it |
 | `dispatch*` auth error | headless-360 MCP session not authenticated / token expired | Re-authenticate the headless-360 MCP connection; confirm the session points at the intended org |

package/skills/service-itsm-agentic-setup-cmdb-bundle-deploy/SKILL.md

@@ -39,7 +39,7 @@ identically against **production** and sandbox with no per-user MCP install.
 
 - **In scope**: confirming CMDB is enabled, reading the live bundle catalog, resolving the exact
   version of the base bundle, installing the **base** (`CMDB Foundation`) bundle, and verifying.
-- **Out of scope**: enabling the CMDB feature / provisioning the ITOM tenant (Layers 0–2 —
+- **Out of scope**: enabling the CMDB feature / provisioning the CMDB tenant (Layers 0–2 —
   `service-itsm-agentic-setup-cmdb-configure`), assigning permission sets (Layer 3 —
   `service-itsm-agentic-setup-cmdb-access-assign`), installing **optional add-on** bundles (e.g.
   Component Identification Rules), CMDB record CRUD, or Discovery.

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

@@ -1,6 +1,6 @@
 ---
 name: service-itsm-agentic-setup-cmdb-configure
-description: "Enable the CMDB (Configuration Management Database) feature in Service Cloud ITSM against a production or sandbox org: verify the CMDB org SKU, provision the ITOM tenant, and enable the service-cloud-itsm-cmdb-integration feature that lifts the CMDB access gate. Use when the user asks to enable CMDB, turn on the Configuration Management Database, provision the ITOM tenant, enable the CMDB feature, or fix a CMDB 403 FUNCTIONALITY_NOT_ENABLED error. Triggers on: enable CMDB feature, provision ITOM tenant, turn on CMDB, CMDB not enabled, CMDB 403 error, service-cloud-itsm-cmdb-integration. DO NOT TRIGGER when: the user only wants to assign CMDB permission sets to users, only install a CMDB content bundle, or work with CMDB records directly."
+description: "Enable the CMDB (Configuration Management Database) feature in Service Cloud ITSM against a production or sandbox org: verify the CMDB org SKU, provision the CMDB tenant, and enable the service-cloud-itsm-cmdb-integration feature that lifts the CMDB access gate. Use when the user asks to enable CMDB, turn on the Configuration Management Database, provision the CMDB tenant, enable the CMDB feature, or fix a CMDB 403 FUNCTIONALITY_NOT_ENABLED error. Triggers on: enable CMDB feature, provision CMDB tenant, turn on CMDB, CMDB not enabled, CMDB 403 error, service-cloud-itsm-cmdb-integration. DO NOT TRIGGER when: the user only wants to assign CMDB permission sets to users, only install a CMDB content bundle, or work with CMDB records directly."
 metadata:
   version: "1.0"
   domains: ["Service"]
@@ -57,7 +57,7 @@ Layer 2. This skill's job is to make that gate return true.
 
 ## Scope
 
-- **In scope**: verifying the CMDB org permission (Layer 0), triggering + polling ITOM tenant
+- **In scope**: verifying the CMDB org permission (Layer 0), triggering + polling CMDB tenant
   provisioning (Layer 1), pre-checking + enabling + verifying the CMDB feature (Layer 2).
 - **Out of scope**: permission-set assignment (Layer 3 — `service-itsm-agentic-setup-cmdb-access-assign`),
   bundle installation (Layer 4 — `service-itsm-agentic-setup-cmdb-bundle-deploy`), CMDB record CRUD,
@@ -126,9 +126,9 @@ The core Connect API `GET /services/data/v63.0/setup/org/permissions/ITSrvcsCnfg
 `references/mcp-invocation.md` for the details. If no probe resolves, report that the org perm could
 not be verified and ask the user to confirm the org has CMDB licensed before continuing.
 
-### Layer 1 — Provision the ITOM tenant
+### Layer 1 — Provision the CMDB tenant
 
-CMDB runs on an ITOM tenant that must reach status `PROVISIONED` (asynchronous).
+CMDB runs on a dedicated tenant (the CMDB tenant) that must reach status `PROVISIONED` (asynchronous).
 
 1. **Check current status** (read):
    ```text
@@ -261,7 +261,7 @@ CMDB Feature Enable — Complete (via service-itsm-agentic-setup-cmdb-configure)
 Target org: <org>
 
   CMDB license .................. Present
-  ITOM tenant ................... Provisioned
+  CMDB tenant ................... Provisioned
   CMDB feature .................. Enabled
 
 CMDB is now enabled on this org. Next steps:

package/skills/service-itsm-agentic-setup-cmdb-configure/references/mcp-invocation.md

@@ -75,7 +75,7 @@ user to confirm CMDB is licensed before proceeding.
 
 ---
 
-## Layer 1 — Provision the ITOM tenant
+## Layer 1 — Provision the CMDB tenant
 
 ### Check current provisioning status (read)