@salesforce/afv-skills 1.21.0 → 1.23.0

package/skills/integration-eventing-cdc-configure/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: integration-eventing-cdc-configure
+description: "Use to enable Salesforce Change Data Capture (CDC) on a standard or custom object, configure a custom event channel, set a filter expression, or add enrichment fields. TRIGGER broadly on any of: 'enable CDC', 'enable Change Data Capture', 'turn on CDC', 'subscribe X to change events', 'only emit events for', 'filter change events', 'enrich change events', 'create a custom event channel'; or any mention of CDC, change events, PlatformEventChannel, PlatformEventChannelMember, EnrichedField, ChangeEvents channel, enrichment fields, change event filter; or when the user wants a downstream system to receive Salesforce data changes; or when the user touches .platformEventChannelMember-meta.xml / .platformEventChannel-meta.xml files. SKIP when publishing platform events, Pub/Sub API or REST/SOAP (use integration-connectivity-generate), or ManagedEventSubscription (out of scope for CDC). Always use this skill for CDC channel-membership metadata."
+metadata:
+  version: "1.0"
+---
+
+# Managing Change Data Capture Enablement
+
+Generate the metadata that subscribes Salesforce objects to Change Data Capture: `PlatformEventChannelMember` files for the default `ChangeEvents` channel or a custom channel, and `PlatformEventChannel` files for new custom channels. Covers enrichment fields, filter expressions, and the canonical naming and value formats that the Metadata API actually accepts (which differ from values that appear in many internal test fixtures and code-search hits).
+
+## Scope
+
+- **In scope**: Generating `PlatformEventChannelMember` and `PlatformEventChannel` metadata for CDC. Subscribing standard objects, custom objects, or both. Configuring enrichment fields. Configuring filter expressions. Defining custom data channels.
+- **Out of scope**: Publishing custom platform events (PE) — that's a different metadata type (`PlatformEvent`). Pub/Sub API or external Kafka/Bayeux configuration. Pricing/limits guidance — refer the user to the [CDC Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/). Programmatic event-bus subscribers in Apex.
+
+---
+
+## Clarifying Questions
+
+Before generating, confirm with the user if not already clear:
+
+- Which entity (or entities) need CDC enablement? Standard, custom, or both?
+- Default channel (`ChangeEvents`) or a custom channel? If custom, what's the channel label?
+- Any enrichment fields needed? (Lookup IDs that the consumer needs even when they didn't change.)
+- Any filter expression needed? (A SOQL-WHERE-clause body that gates which change events emit.)
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Source entity API name(s)** — e.g. `Account`, `Lead`, `Order__c`. The skill internally translates this to the **ChangeEvent entity name** (see Workflow step 2).
+- **Channel** — either `ChangeEvents` (default) or the developer name of a custom channel ending in `__chn`.
+- **Enrichment fields (optional)** — list of field API names on the source object whose values should be included in every change event.
+- **Filter expression (optional)** — a predicate over fields on the change event payload (e.g. `Status__c != null`).
+
+Defaults unless specified:
+- Channel: `ChangeEvents` (the default CDC channel — no path prefix).
+- Enrichment fields: none.
+- Filter expression: none.
+
+If the user provides a clear, complete request, generate immediately without unnecessary back-and-forth.
+
+---
+
+## Workflow
+
+All steps are sequential. Do not skip or reorder.
+
+**Before generating anything, know the only valid CDC metadata types:** CDC is expressed entirely through `PlatformEventChannelMember` (one per subscribed entity) and `PlatformEventChannel` (only for custom channels). Do NOT use `<ChangeDataCapture>`, `.changeDataCapture-meta.xml`, `changeDataCapture/` directories, `EnableChangeDataCapture`, or `ManagedEventSubscription` — these are not in scope for CDC. If you find yourself writing any of them, stop and use a `PlatformEventChannelMember` file instead.
+
+1. **Identify the channel** — if the user names a custom channel, you'll generate a `PlatformEventChannel` file (see step 4). Otherwise use the literal value `ChangeEvents` for the default channel.
+
+2. **Translate source entity to ChangeEvent entity name** — `<selectedEntity>` is the **ChangeEvent** type, NOT the source object:
+
+   | Source object | `<selectedEntity>` value |
+   |---|---|
+   | `Account` | `AccountChangeEvent` |
+   | `Lead` | `LeadChangeEvent` |
+   | `Contact` | `ContactChangeEvent` |
+   | `Order__c` (custom) | `Order__ChangeEvent` |
+   | `MyThing__c` (custom) | `MyThing__ChangeEvent` |
+
+   For standard objects: append `ChangeEvent`. For custom objects: replace the trailing `__c` with `__ChangeEvent` (the double-underscore is preserved).
+
+3. **Generate the channel-member file** — one file per `(entity, channel)` pair. **The filename and fullName always use a SINGLE underscore between the entity stem and `ChangeEvent`** — this is independent of how `selectedEntity` is formatted in the XML body. For custom objects, drop the `__c` from the source name when forming the filename:
+
+   | Source object | Filename (and fullName) | `<selectedEntity>` (in XML) |
+   |---|---|---|
+   | `Account` | `Account_ChangeEvent.platformEventChannelMember-meta.xml` | `AccountChangeEvent` |
+   | `Lead` | `Lead_ChangeEvent.platformEventChannelMember-meta.xml` | `LeadChangeEvent` |
+   | `Order__c` | `Order_ChangeEvent.platformEventChannelMember-meta.xml` (NOT `Order__ChangeEvent`) | `Order__ChangeEvent` |
+   | `MyThing__c` | `MyThing_ChangeEvent.platformEventChannelMember-meta.xml` (NOT `MyThing__ChangeEvent`) | `MyThing__ChangeEvent` |
+
+   The custom-object case is the easiest place to slip — the filename uses single underscore, the `selectedEntity` keeps its double underscore. Read `assets/PlatformEventChannelMember-template.xml` as the structural template.
+
+4. **For a custom channel**, generate a `PlatformEventChannel` file — required if any member references a non-default channel. Derive a DeveloperName from the user's label: strip spaces and non-alphanumeric characters, convert to CamelCase, then **always** append the literal suffix `__chn`. The filename and the channel's `<eventChannel>` reference must use this exact form, otherwise the deploy fails with `Invalid channel name`:
+
+   | User says | DeveloperName | Filename |
+   |---|---|---|
+   | `Partner Sync` | `PartnerSync__chn` | `PartnerSync__chn.platformEventChannel-meta.xml` (NOT `Partner_Sync...` or `PartnerSync...`) |
+   | `Order Updates` | `OrderUpdates__chn` | `OrderUpdates__chn.platformEventChannel-meta.xml` |
+   | `data sync` | `DataSync__chn` | `DataSync__chn.platformEventChannel-meta.xml` |
+
+   Members on this channel reference it by the same DeveloperName: `<eventChannel>PartnerSync__chn</eventChannel>`. Read `assets/PlatformEventChannel-template.xml`.
+
+5. **Add enrichment fields** if requested — repeat the `<enrichedFields><name>FIELD_API_NAME</name></enrichedFields>` block for each field. The name must be a **single-hop API name on the source entity** — verified working with: standard lookup IDs (`OwnerId`, `ParentId`), custom lookup fields (`MyLookup__c`), and custom non-relationship fields (`Region__c`, `Status__c`). Relationship traversals like `Owner.Name` or `Parent.Account.Industry` are rejected by deploy with "The selected field, X.Y, isn't valid".
+
+6. **Add a filter expression** if requested — wrap the predicate in `<filterExpression>...</filterExpression>`. The body is a WHERE-clause body without the `WHERE` keyword (e.g. `Status__c != null`, not `WHERE Status__c != null`). For supported operators, field types, and pitfalls, read `references/filter-expressions.md`.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|---|---|
+| `<selectedEntity>` is the ChangeEvent type name, not the source object name | The Metadata API binds the member to a ChangeEvent entity — passing `Account` directly fails with "invalid event in selectedEntity". |
+| Member fullName uses **single** underscore: `Account_ChangeEvent` | The double-underscore form (`Account__ChangeEvent`) is parsed as `<namespace>__<name>` and rejected: "Cannot create a new component with the namespace: Account". |
+| Default channel value is exactly `ChangeEvents` — no path prefix | Older fixtures and some docs show `data/ChangeEvents`; the deploy returns "Unable to find the specified channel" for that value. |
+| Enrichment field names are single-hop API names on the source entity | Standard (`OwnerId`), custom lookup (`MyLookup__c`), and custom non-relationship (`Region__c`) all validate. Traversals like `Owner.Name` are rejected: "The selected field, X.Y, isn't valid". |
+| `<filterExpression>` body has no `WHERE` keyword | Deploy returns "filter expression has syntax errors: unexpected token: 'WHERE'". |
+| Filter cannot reference `IsDeleted` or do relationship traversal (`Owner.Username`) | Deploy rejects with "field is invalid". |
+| DateTime fields support **only equality** in filters (`=`, `!=`) — not `<` / `>` | Deploy returns "Only equality operators are supported for this field type or value". Use a named date literal: `LastModifiedDate = TODAY`. |
+| Filter RHS must be a literal — no field-to-field comparison | `BillingCity = ShippingCity` returns "unexpected token: 'ShippingCity'". |
+| Compound fields (e.g. `BillingAddress`) require dotted component access in filter | `BillingAddress.City = 'X'` deploys; flat `BillingCity` is rejected as "field is invalid"; raw `BillingAddress` is rejected as "has to be used with a component field". Note this is the OPPOSITE of `<enrichedFields>`, which uses flat names. |
+| Custom channel filename ends with `__chn` before the meta-xml suffix | Salesforce's MDAPI naming convention; mismatch causes deploy ambiguity. |
+| Custom channel XML must include `<channelType>data</channelType>` | Without `data`, the channel is rejected for CDC (other types exist for streaming/event channels). |
+| Source custom objects must already exist (or be deployed in the same transaction) | The ChangeEvent entity for `Foo__c` doesn't exist until `Foo__c` does; member deploy fails otherwise. |
+| Never generate a `PlatformEventChannel` file for the default `ChangeEvents` channel | The default channel is system-provided. Reference it via `<eventChannel>ChangeEvents</eventChannel>` on members, but only custom (`__chn`) channels need a channel-meta file. |
+| `PlatformEventChannelMember` accepts ONLY four elements: `<enrichedFields>`, `<eventChannel>`, `<filterExpression>`, `<selectedEntity>` | Adding `<description>`, `<isActive>`, `<masterLabel>`, or any other element fails XML schema validation: "Element {...} invalid at this location". Stick to the four documented elements. |
+| `PlatformEventChannel` accepts ONLY two elements: `<channelType>` and `<label>` | Adding `<masterLabel>`, `<description>`, etc. produces "Element {...}masterLabel invalid at this location in type PlatformEventChannel". Use `<label>`, not `<masterLabel>`. |
+| Generated metadata files only — never run `sf project deploy start` from this skill | This skill produces artifacts; deployment is a separate lifecycle concern. |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| `Unable to find the specified channel` | Set `<eventChannel>ChangeEvents</eventChannel>` (no `data/` prefix). |
+| `The PlatformEventChannelMember can't be created because it references an invalid event in the "selectedEntity" field` | Use the ChangeEvent name, not the source object: `AccountChangeEvent`, not `Account`. |
+| `Cannot create a new component with the namespace: <Object>` | Rename the file to use a single underscore: `Account_ChangeEvent...`, not `Account__ChangeEvent...`. |
+| `The selected field, X.Y, isn't valid` (in `<enrichedFields>`) | Replace `Owner.Name` with `OwnerId`. CDC enriches the lookup automatically; only single-hop field API names validate. |
+| `filter expression has syntax errors: unexpected token: 'WHERE'` | Remove the `WHERE` keyword. The body is the predicate only. |
+| `The BillingCity field in the filter expression is invalid` (or any flat Address component) | Use the compound dotted form: `BillingAddress.City`, not `BillingCity`. See `references/filter-expressions.md` for the full compound-field matrix. |
+| Custom-object member fails with "ChangeEvent doesn't exist" | The source object isn't deployed yet. Ensure the `Foo__c` object metadata is in the same deploy or already in the org. |
+| `DUPLICATE_VALUE` on second deploy | The member is already subscribed. Either delete first or skip — CDC doesn't support upsert on members directly. |
+| `sf infra error (TypeInferenceError, DeployMetadata): Could not infer a metadata type` for a `.changeDataCapture-meta.xml` file | That file extension and metadata type don't exist. Replace the `changeDataCapture/<Entity>.changeDataCapture-meta.xml` file with a `platformEventChannelMembers/<Entity>_ChangeEvent.platformEventChannelMember-meta.xml` file. |
+| User says "subscribe Order__c" but means standard `Order` | Confirm — `OrderChangeEvent` (standard) and `Order__ChangeEvent` (custom) are different entities. |
+
+---
+
+## Output Expectations
+
+Deliverables:
+- One `force-app/.../platformEventChannelMembers/<Entity>_ChangeEvent.platformEventChannelMember-meta.xml` per subscribed entity.
+- One `force-app/.../platformEventChannels/<DevName>__chn.platformEventChannel-meta.xml` per custom channel (if any).
+
+File structure follows the templates in `assets/`.
+
+After receiving the generated files, the user can verify them with `sf project deploy start --dry-run -d <path> --target-org <alias>` before deploying. If a dry-run surfaces an unfamiliar error, `references/deploy-troubleshooting.md` maps the common deploy errors to their metadata-side fixes.
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|---|---|
+| Generate the source custom object | `platform-custom-object-generate` skill |
+| Generate custom fields referenced by enrichment or filter | `platform-custom-field-generate` skill |
+| Build a permission set for users who consume change events | `platform-permission-set-generate` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `assets/PlatformEventChannelMember-template.xml` | Step 3 — starting structure for a channel member |
+| `assets/PlatformEventChannel-template.xml` | Step 4 — starting structure for a custom channel |
+| `references/filter-expressions.md` | Step 6 — for the supported operators and field-type matrix when writing a filter expression |
+| `references/deploy-troubleshooting.md` | When a user reports a dry-run deploy error and asks for help diagnosing it |

package/skills/integration-eventing-subscription-configure/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: integration-eventing-subscription-configure
+description: "Create, read, update, and delete ManagedEventSubscription metadata in Salesforce. Use this skill for any work involving managed event subscriptions, platform event subscriptions, event channel subscribers, or .managedEventSubscription-meta.xml files. TRIGGER when: user asks to subscribe to a platform event, create a managed subscription, set up event replay, configure an event channel subscriber, update replay preset, activate or deactivate a subscription, delete a subscription, or manage ManagedEventSubscription metadata. SKIP when: user needs to create the platform event channel itself (use platform-custom-object-generate skill) or needs Flow-based event subscriptions (use automation-flow-generate skill)."
+metadata:
+  version: "1.0"
+---
+
+# Managing ManagedEventSubscription
+
+Create, read, update, and delete `ManagedEventSubscription` metadata — the Salesforce construct for durably subscribing to platform event channels with managed replay tracking.
+
+## Scope
+
+- **In scope**: Generating and modifying `.managedEventSubscription-meta.xml` files for create, read, update, and delete operations
+- **Out of scope**: Creating the underlying platform event (`__e`) channel itself; Flow-based or Apex-based event subscriptions; deploying metadata to an org
+- **Only generate one file** — the `.managedEventSubscription-meta.xml` file. Do NOT generate the referenced platform event object or any other metadata type.
+
+---
+
+## Clarifying Questions
+
+Before generating, confirm if not already clear:
+
+- What is the **topic name**? (see format table in `references/topic-name-formats.md`)
+- What is the **developer name**? (required for Create — alphanumeric and underscores only, no spaces; optional for Read/Update/Delete if `Id` is known)
+- What is the **label** (human-readable name)?
+- What **default replay** preset — `LATEST` (default) or `EARLIEST`?
+- What **error recovery replay** preset — `LATEST` (default) or `EARLIEST`?
+- What should the initial **state** be — `RUN` (active) or `STOP` (inactive)? (default: `RUN`)
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Operation**: create, read, update, or delete
+- **DeveloperName**: required for Create (becomes the filename); optional for Read/Update/Delete if `Id` is provided instead
+- **Id**: Tooling API record Id — can be used to identify the subscription for Read/Update/Delete instead of DeveloperName
+- **label**: human-readable label (can include spaces)
+- **topicName**: event channel path — read `references/topic-name-formats.md` for valid formats (platform events, change events, custom channels)
+- **defaultReplay**: `LATEST` or `EARLIEST` (default: `LATEST`)
+- **errorRecoveryReplay**: `LATEST` or `EARLIEST` (default: `LATEST`)
+- **state**: `RUN` or `STOP` (default: `RUN`) — `PAUSE` is reserved for internal platform use and will be rejected with `INVALID_INPUT`
+- **version**: Metadata API version (default: match org API version, e.g. `67.0`)
+
+---
+
+## Workflow
+
+### Create
+
+1. **Gather inputs** — confirm DeveloperName, label, topicName, defaultReplay, errorRecoveryReplay, state, version. Apply defaults for any omitted fields. If DeveloperName is not provided, ask the user — do not derive it from the label.
+2. **Confirm the topic exists** — ask the user to confirm the event channel already exists in the org before proceeding. Do NOT generate the platform event object yourself — that is out of scope for this skill. If the user says it doesn't exist yet, stop and direct them to create it first using the `platform-custom-object-generate` skill, then return here.
+3. **Read the template** — load `assets/managed-event-subscription-template.xml` as the starting structure.
+4. **Generate the file** — produce `managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml` filled with user-provided values.
+5. **Verify** — run the checklist below before presenting output.
+6. **Guide the user on subscribing** — after deployment, the subscription can be identified for Pub/Sub API `ManagedSubscribe` RPC calls using either the `DeveloperName` or the record `Id`. To retrieve the `Id`, run: `SELECT Id, DeveloperName FROM ManagedEventSubscription WHERE DeveloperName='<DeveloperName>'` via the Tooling API.
+
+### Read
+
+1. **Identify the subscription** — accept either `Id` or `DeveloperName`; prefer `Id` if provided.
+2. **Show the file path** — `managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml` (if DeveloperName known).
+3. **Retrieve and display** — read and present the current XML content.
+
+### Update
+
+1. **Identify the subscription** — accept either `Id` or `DeveloperName`; prefer `Id` if provided.
+2. **Read the existing file** — load current content before modifying.
+3. **Apply changes** — update only the specified fields; preserve all others.
+4. **Read `references/update-constraints.md`** for fields that cannot be changed after creation.
+5. **Verify** — run the checklist below before presenting output.
+
+### Delete
+
+1. **Identify the subscription** — accept either `Id` or `DeveloperName`; confirm with the user before proceeding.
+2. **Warn** — deleting a ManagedEventSubscription permanently removes replay tracking state.
+3. **Produce deletion instructions** — explain how to remove the file and deploy the destructive change using `destructiveChanges.xml`.
+4. **Read `references/delete-guide.md`** for the destructive deployment procedure.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| `<topicName>` must use a valid path prefix | Platform events use `/event/Name__e`; change events use `/data/Name`; see `references/topic-name-formats.md` for all formats |
+| `<defaultReplay>` and `<errorRecoveryReplay>` must be `LATEST` or `EARLIEST` | These are the only valid enum values; any other value fails metadata validation |
+| `<state>` must be `RUN` or `STOP` | `PAUSE` is reserved for internal platform use — the API rejects it with `INVALID_INPUT: You can create a managed event subscription state field only to RUN or STOP` |
+| All six required elements must be present | `topicName`, `defaultReplay`, `errorRecoveryReplay`, `label`, `state`, `version` are all required; omitting any causes a deploy error |
+| DeveloperName must be unique within the org | Duplicate names cause `DUPLICATE_DEVELOPER_NAME` errors |
+| Do not include `<namespacePrefix>`, `<id>`, or `<createdDate>` | Read-only platform fields; including them causes deployment failures in unpackaged orgs |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| `The topicName field is invalid` on deploy | Wrong format or the event doesn't exist in the org — read `references/topic-name-formats.md` for correct path |
+| Replay state lost after delete + recreate | Deleting discards stored replay position; recreating starts from `defaultReplay` — avoid reusing the same DeveloperName after delete |
+| `INVALID_TYPE` on SOQL query | ManagedEventSubscription is only queryable via Tooling API, not standard SOQL |
+| `EARLIEST` replay on high-volume channels | Can trigger up to 72 hours of backlog replay on activation; always confirm with the user |
+| Metadata not supported in older orgs | ManagedEventSubscription requires API v60.0+; check org API version |
+| `eventChannel` or `isActive` in generated XML | These are wrong field names — use `topicName` and `state` (`RUN`/`STOP`) instead |
+| `PAUSE` state in generated XML | `PAUSE` is reserved for internal platform use and will be rejected with `INVALID_INPUT` — only use `RUN` or `STOP` |
+| User unsure how to identify subscription for Pub/Sub API | Both `DeveloperName` and record `Id` can be used with `ManagedSubscribe` RPC — retrieve the `Id` via Tooling API if needed: `SELECT Id FROM ManagedEventSubscription WHERE DeveloperName='<name>'` |
+| Changes not reflected immediately in Pub/Sub API | After create/update/delete, the Pub/Sub API can take up to ~2 minutes to reflect the new config; if ManagedSubscribe returns NOT_FOUND, wait and retry |
+
+---
+
+## Verification Checklist
+
+Before presenting any generated XML:
+
+- [ ] Does `<topicName>` follow a valid path format per `references/topic-name-formats.md`? (`/event/Name__e`, `/data/NameChangeEvent`, `/data/ChangeEvents`, `/event/Name__chn`, `/data/Name__chn`)
+- [ ] Is `<defaultReplay>` exactly `LATEST` or `EARLIEST`?
+- [ ] Is `<errorRecoveryReplay>` exactly `LATEST` or `EARLIEST`?
+- [ ] Is `<state>` exactly `RUN` or `STOP`? (`PAUSE` is invalid for user-created subscriptions)
+- [ ] Is `<label>` populated?
+- [ ] Is `<version>` present (e.g. `67.0`)?
+- [ ] Are read-only fields (`<id>`, `<createdDate>`, `<namespacePrefix>`) absent?
+- [ ] Does the filename match the DeveloperName exactly?
+
+---
+
+## Output Expectations
+
+- **Create / Update**: `managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml` — this is the only file to generate
+- **Delete**: instructions to remove the file and deploy via `destructiveChanges.xml`
+- **Read**: display of existing file contents
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|------|-------------|
+| Create the platform event channel (`__e`) being subscribed to | `platform-custom-object-generate` skill |
+| Subscribe via Flow (Process Automation) | `automation-flow-generate` skill |
+| Deploy metadata to org | `platform-metadata-deploy` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `assets/managed-event-subscription-template.xml` | Before generating any new subscription — use as starting structure |
+| `references/topic-name-formats.md` | When setting `<topicName>` — covers platform events, change events, and custom channels |
+| `references/update-constraints.md` | During Update workflow — to check which fields are immutable post-creation |
+| `references/delete-guide.md` | During Delete workflow — for destructive change deployment procedure |

package/skills/managing-suite-assignments/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: managing-suite-assignments
-description: "Manages all forms of test suite assignment for DevOps Center pipeline stages via the Connect API testSuiteStages endpoint. Covers three modes: (A) attaching a single suite to a stage as a one-off add, (B) bulk-mapping multiple suites to a stage as a testing strategy with a mandatory impact-preview table before any changes, and (C) adding or removing individual test classes within a suite assignment with governance rules that exclude rejected tests and re-present the final list before committing. TRIGGER when: a suite is found unlinked from a pipeline stage and the user wants to assign it; the user wants to configure suite-to-stage mappings across a pipeline or assign multiple suites to stages as part of a testing strategy; the user wants to add or remove tests in a suite, sync reviewed tests into a suite, or promote tests to a suite. DO NOT TRIGGER when: authoring new test classes (use generating-apex-test) or running tests directly (use running-apex-tests)."
+description: "Manages all forms of test suite assignment for DevOps Center pipeline stages via the Connect API testSuiteStages endpoint. Covers three modes: (A) attaching a single suite to a stage as a one-off add, (B) bulk-mapping multiple suites to a stage as a testing strategy with a mandatory impact-preview table before any changes, and (C) adding or removing individual test classes within a suite assignment with governance rules that exclude rejected tests and re-present the final list before committing. TRIGGER when: a suite is found unlinked from a pipeline stage and the user wants to assign it; the user wants to configure suite-to-stage mappings across a pipeline or assign multiple suites to stages as part of a testing strategy; the user wants to add or remove tests in a suite, sync reviewed tests into a suite, or promote tests to a suite. DO NOT TRIGGER when: authoring new test classes (use platform-apex-test-generate) or running tests directly (use platform-apex-test-run)."
 metadata:
   version: "1.0"
   minApiVersion: "67.0"

package/skills/mobile-apps-create/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mobile-apps-create
+description: "The entry point for building any Salesforce native mobile app on iOS or Android. TRIGGER when the user says: \"build a Salesforce iOS app\", \"add Salesforce login to my Android app\", \"set up Mobile SDK\", \"add MobileSync / SmartStore offline storage\", \"embed an Agentforce agent in my mobile app\", \"add Agentforce chat to iOS/Android\", or otherwise asks to create, extend, or integrate a Salesforce mobile experience in Swift or Kotlin (MSDK, Agentforce SDK, or both). SKIP when the user is building a non-Salesforce mobile app, using React Native / Flutter / Ionic without Salesforce integration, asking about generic mobile UI design, or working on a Salesforce-adjacent web/desktop surface (LWC, Experience Cloud, Mobile Publisher branding-only)."
+metadata:
+  version: "1.0"
+---
+
+# Salesforce Mobile
+
+Route the user to the right SDK-family skill for building Salesforce-connected mobile apps. Do not implement features here; child skills own scenario detection and step-by-step instructions.
+
+## Before routing
+
+Disambiguate on two dimensions: **SDK family** (Mobile SDK vs. Agentforce SDK) and **platform** (iOS vs. Android). They are not mutually exclusive — an app can use both SDKs.
+
+If the user's intent could plausibly map to either SDK, ask before routing. Guessing wrong wastes the user's time because the child skills are platform- and SDK-specific.
+
+## Routing — which SDK family?
+
+| User's situation | SDK |
+|---|---|
+| Authenticating end users to Salesforce, syncing records (MobileSync), storing data offline (SmartStore), biometric login, push notifications, REST integration | **Mobile SDK** |
+| Embedding an Agentforce agent — chat UI, agent conversations, conversational features as the primary surface | **Agentforce SDK** |
+| Both (data-driven app with an embedded agent) | **Mobile SDK first**, then **Agentforce SDK** layered on top |
+
+### Tiebreakers when both seem to apply
+
+- Is the agent the *primary surface* (chat-first app), or a *feature inside* an otherwise data-driven app?
+  - Primary → Agentforce SDK
+  - Feature → Mobile SDK; embed the agent via Agentforce SDK alongside it
+- Are end users authenticating into Salesforce data?
+  - Yes → Mobile SDK is required (Agentforce SDK can be added on top).
+  - No → Agentforce SDK alone is likely sufficient (it uses guest auth).
+- Asking about offline storage, sync, REST, push, or biometrics? → Mobile SDK.
+- Asking about agent conversations, chat UI, or streaming responses? → Agentforce SDK.
+
+When still unclear, ask the user directly.
+
+## Routing — which platform?
+
+| Platform | Mobile SDK skill | Agentforce SDK skill |
+|---|---|---|
+| iOS (Swift) | `ios-mobile-sdk` | `integrate-agentforce-ios` |
+| Android (Kotlin) | `android-mobile-sdk` | `integrate-agentforce-android` |
+
+If the user wants both platforms, route to each child skill separately — they are independent.
+
+## Combined workflows (Mobile SDK + Agentforce SDK)
+
+When an app needs both:
+
+1. Route to the Mobile SDK platform skill first to scaffold and authenticate.
+2. Route to the Agentforce SDK platform skill to layer the agent surface.
+3. Treat each child skill's instructions as authoritative for its SDK; do not merge their steps. Each SDK owns its own auth setup, dependency installation order, and initialization sequence — interleaving them produces conflicting config and broken init order.
+
+This sequencing is the only multi-skill logic this skill owns. Everything else lives inside the child skills.
+
+## Loading a child skill
+
+Invoke the child skill by name through the harness. If it is not available locally, prompt the user to install it with `npx skills add <repo>`. If the user confirms (or has pre-authorized installs), run the command and load the child skill — do not make the user go figure out how to continue the workflow. If the user declines, stop and explain that the child skill owns the SDK's setup steps and the workflow cannot continue without it. Each child skill is published from a public repo:
+
+| Skill | Repo | Install command |
+|---|---|---|
+| `ios-mobile-sdk` | [`forcedotcom/SalesforceMobileSDK-Templates`](https://github.com/forcedotcom/SalesforceMobileSDK-Templates) → `skills/ios-mobile-sdk/` | `npx --yes skills add forcedotcom/SalesforceMobileSDK-Templates --skill ios-mobile-sdk --yes` |
+| `android-mobile-sdk` | [`forcedotcom/SalesforceMobileSDK-Templates`](https://github.com/forcedotcom/SalesforceMobileSDK-Templates) → `skills/android-mobile-sdk/` | `npx --yes skills add forcedotcom/SalesforceMobileSDK-Templates --skill android-mobile-sdk --yes` |
+| `integrate-agentforce-ios` | [`salesforce/AgentforceMobileSDK-iOS`](https://github.com/salesforce/AgentforceMobileSDK-iOS) → `skills/integrate-agentforce-ios/` | `npx --yes skills add salesforce/AgentforceMobileSDK-iOS --skill integrate-agentforce-ios --yes` |
+| `integrate-agentforce-android` | [`salesforce/AgentforceMobileSDK-Android`](https://github.com/salesforce/AgentforceMobileSDK-Android) → `skills/integrate-agentforce-android/` | `npx --yes skills add salesforce/AgentforceMobileSDK-Android --skill integrate-agentforce-android --yes` |
+
+After install, load the child skill and let it take over. Do not inline the child skill's content — the child skill owns scenario detection, prerequisites, and step-by-step instructions.

package/skills/mobile-platform-native-capabilities-integrate/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: mobile-platform-native-capabilities-integrate
+description: "Build a Salesforce LWC that uses native mobile device capabilities — barcode scanner, biometrics, location, NFC, calendar, contacts, document scanner, geofencing, AR space capture, app review, and payments. Use this skill when the user asks for an LWC that scans a barcode, captures a photo of a document, reads location or geofences, prompts for biometrics, reads/writes the device calendar or contacts, taps NFC, takes a payment, prompts for an app review, or scans an AR space. Also triggers on \"lightning/mobileCapabilities\", \"mobile capability\", \"Nimbus\", \"device capability\". Do not use for mobile offline / Komaci priming reviews (use `mobile-platform-offline-validate`) or for picking generic Lightning base components (use a generic Lightning base components skill)."
+metadata:
+  version: "1.0"
+---
+
+# Using Mobile Native Capabilities
+
+The `lightning/mobileCapabilities` module exposes a set of factory functions
+that return service objects for native device features (barcode scanning,
+biometrics, location, etc.). Each service extends a common
+[BaseCapability](references/base-capability.md) with an `isAvailable()`
+method, so an LWC can degrade gracefully on surfaces where the capability is
+not present (desktop, mobile web).
+
+This skill routes an agent through (1) picking the right capability, (2)
+loading the authoritative type definitions, and (3) wiring the service into
+an LWC with the correct availability gating, error handling, and
+deprecation-aware API choice.
+
+## When to Use This Skill
+
+- User asks for an LWC that uses a device capability listed in the index
+  below.
+- User mentions `lightning/mobileCapabilities`, "mobile capability", or
+  "Nimbus" by name.
+- User wants to know which mobile native APIs are available, or which one
+  fits their feature.
+
+Do NOT use this skill for:
+
+- Mobile-offline review of an LWC (lwc:if, inline GraphQL, Komaci-priming
+  violations) — use `mobile-platform-offline-validate`.
+- Picking generic Lightning Base Components — use
+  `using-lightning-base-components`.
+
+## Prerequisites
+
+- Knowledge that the LWC will run inside a supported mobile container
+  (Salesforce Mobile App, Field Service Mobile App). These capabilities are
+  unavailable on desktop and mobile web; gate every call behind
+  `isAvailable()`.
+- Familiarity with the `lightning/mobileCapabilities` module declaration
+  (see [mobile-capabilities](references/mobile-capabilities.md)).
+
+## Capability Index
+
+| Capability | Reference | One-line use |
+| --- | --- | --- |
+| App Review | [App Review](references/app-review.md) | Prompt the user for a native in-app review. |
+| AR Space Capture | [AR Space Capture](references/ar-space-capture.md) | Capture a 3D scan of a physical space using AR. |
+| Barcode Scanner | [Barcode Scanner](references/barcode-scanner.md) | Read QR / UPC / EAN / Code-128 / etc. from the camera. |
+| Biometrics | [Biometrics](references/biometrics.md) | Authenticate via Face ID / fingerprint. |
+| Calendar | [Calendar](references/calendar.md) | Read or create events on the device calendar. |
+| Contacts | [Contacts](references/contacts.md) | Read or create entries in the device address book. |
+| Document Scanner | [Document Scanner](references/document-scanner.md) | Scan paper documents using the camera with edge detection. |
+| Geofencing | [Geofencing](references/geofencing.md) | Trigger logic when the device crosses a geographic boundary. |
+| Location | [Location](references/location.md) | Read GPS coordinates and watch for updates. |
+| NFC | [NFC](references/nfc.md) | Read or write NFC tags. |
+| Payments | [Payments](references/payments.md) | Take an Apple Pay / Google Pay payment. |
+
+## Workflow
+
+### Step 1 — Identify the capability
+
+Map the user's feature ask to one row of the capability index. If the ask
+spans multiple capabilities (e.g. "scan a barcode and store it on a
+contact"), plan for **each** capability separately — there is one factory
+function per capability.
+
+### Step 2 — Load the shared and capability-specific references
+
+Read these two shared references **once** per session — they apply to every
+capability and are not duplicated in the per-capability files:
+
+- [BaseCapability](references/base-capability.md) — the common interface
+  with `isAvailable()` that every service extends.
+- [mobile-capabilities](references/mobile-capabilities.md) — the
+  `lightning/mobileCapabilities` module declaration showing every
+  re-exported service.
+
+Then open the capability's reference file from the table above. Each
+per-capability reference contains the service-specific TypeScript API
+(factory function, service interface, options types, result types, error
+types) and assumes the two shared references above are already in context.
+
+Do not infer the API from memory — read it. The services evolve and some
+methods are explicitly `@deprecated` in favor of newer alternatives.
+
+### Step 3 — Wire the service into the LWC
+
+For each capability:
+
+1. Import the factory from `lightning/mobileCapabilities`:
+   ```js
+   import { getBarcodeScanner } from 'lightning/mobileCapabilities';
+   ```
+2. Get an instance: `const scanner = getBarcodeScanner();`
+3. Gate the call behind `isAvailable()`:
+   ```js
+   if (!scanner.isAvailable()) {
+     // graceful fallback or user message
+     return;
+   }
+   ```
+4. Call the **non-deprecated** entry point. Several services keep older
+   methods marked `@deprecated` alongside the recommended one — always
+   prefer the recommended method in the reference.
+5. Wrap the promise in `try/catch` and handle the typed failure codes the
+   service exposes (e.g. `BarcodeScannerFailureCode`,
+   `LocationServiceFailureCode`). User-cancelled vs. permission-denied vs.
+   service-unavailable are distinct UX states.
+
+### Step 4 — Surface failure modes to the user
+
+Each service defines its own failure-code enum. Translate codes into
+user-actionable messages: a `USER_DENIED_PERMISSION` should ask the user to
+grant permission; a `USER_DISABLED_PERMISSION` must direct them to the OS
+settings; a `SERVICE_NOT_ENABLED` should be a developer-visible error, not
+shown to the user.
+
+### Step 5 — Stay inside the supported surface
+
+Mobile capabilities are available **only** when the LWC runs inside a
+supported Salesforce mobile app. If the same component is rendered on
+desktop or mobile web, the factory will still return an object but
+`isAvailable()` will return `false`. Never assume availability — gate every
+call.
+
+
+## Examples
+
+### Example — "Scan a barcode and write it into a field"
+
+1. Map to: Barcode Scanner.
+2. Read [Barcode Scanner](references/barcode-scanner.md).
+3. Use `scan(options)` (not the deprecated `beginCapture` / `resumeCapture`
+   / `endCapture` triple).
+4. In options, set the `barcodeTypes` to the symbologies needed (default is
+   all supported types) and `enableMultiScan: false` for a single read.
+5. On resolve, write `result[0].value` to the bound field. On reject,
+   inspect `error.code` against `BarcodeScannerFailureCode`.
+
+### Example — "Take an Apple Pay payment for an order total"
+
+1. Map to: Payments.
+2. Read [Payments](references/payments.md).
+3. Gate on `isAvailable()`.
+4. Build the payment request object per the reference.
+5. On resolve, surface the transaction id to the calling flow. On reject,
+   handle user-cancelled and payment-failed paths separately.
+
+
+## Verification Checklist
+
+- [ ] Every capability call is preceded by `isAvailable()`.
+- [ ] The non-deprecated entry point is used (no `beginCapture` /
+      `resumeCapture` / `endCapture` for barcode, etc.).
+- [ ] Each rejection path is mapped to the typed failure code enum.
+- [ ] Imports come from `lightning/mobileCapabilities`, not from a private
+      path.
+- [ ] No assumption that the capability runs on desktop or mobile web.
+
+
+## Troubleshooting
+
+- **`isAvailable()` returns `false` on a real device** — the device is
+  running an unsupported app surface (not Salesforce Mobile or Field
+  Service Mobile), or the service is gated by an org-level setting. The
+  fix is org configuration, not code.
+- **TypeScript can't find the import** — confirm the LWC has access to
+  `lightning/mobileCapabilities`. The module is declared globally inside
+  Salesforce mobile containers; outside that, the types must be installed
+  separately.
+- **Deprecated barcode methods still work** — yes, but new code must use
+  `scan()` and `dismiss()`. Refactor any sample code the agent received
+  before returning it.
+- **Multiple capabilities in one component** — get separate instances per
+  capability (they are independent service objects); do not try to share
+  state between them.