@salesforce/afv-skills 1.24.0 → 1.26.0

package/skills/platform-sharing-rules-generate/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: platform-sharing-rules-generate
+description: "Use this skill when users need to create, generate, or modify Salesforce Sharing Rules metadata. TRIGGER when: users mention sharing rules, record sharing, criteria-based sharing, role-based sharing, guest user sharing, portal user sharing, sharingRules, sharingCriteriaRules, sharingGuestRules, sharingOwnerRules, .sharingRules-meta.xml files, or ask to share records with specific roles or groups. Also trigger when users want to configure record-level access beyond org-wide defaults (OWD), share object records with roles, groups, or guest users, or set up Experience Site guest user record visibility. SKIP when: user needs permission sets or profiles (use platform-permission-set-generate), or needs object-level security rather than record-level sharing (use platform-permission-set-generate)."
+metadata:
+  version: "1.0"
+---
+
+# Sharing Rules Generator
+
+Generate Salesforce Sharing Rules metadata to control record-level access beyond org-wide defaults. Supports criteria-based rules, role/group-based owner rules, and guest user rules for Experience Sites.
+
+## Scope
+
+- **In scope**: Generating `sharingCriteriaRules`, `sharingOwnerRules`, and `sharingGuestRules` metadata; retrieving existing sharing rules from an org; appending new rules to existing files; configuring rules for Guest and Portal profiles.
+- **Out of scope**: Changing org-wide defaults (OWD/sharing model), creating Experience Sites, configuring permission sets or profiles (use `platform-permission-set-generate`), territory-based sharing rules.
+
+---
+
+## Clarifying Questions
+
+Before generating, confirm with the user if not already clear:
+
+- Which object should the sharing rule apply to? (standard or custom object API name)
+- What type of rule? (criteria-based, role/group-based owner rule, or guest user rule)
+- Who should records be shared with? (role name, group, portal role, or guest user nickname)
+- What access level? (Read or Read/Write)
+- For criteria-based rules: what field conditions should match?
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Object API name**: The sObject the rule targets (e.g., `Account`, `Property__c`)
+- **Rule type**: One of `sharingCriteriaRules`, `sharingOwnerRules`, or `sharingGuestRules`
+- **Shared-to target**: Role, group, portal role, or guest user community nickname
+- **Access level**: `Read` or `Edit` (maps to Read-Only or Read/Write)
+- **Criteria** (for criteria/guest rules): Field name, operation, and value for each filter item
+
+Defaults unless specified:
+- Access level: `Read`
+- `includeRecordsOwnedByAll`: `true` for criteria rules
+- `includeHVUOwnedRecords`: `false` for guest rules
+- Account sharing rules include `accountSettings` with all sub-access levels set to `None`
+
+---
+
+## Workflow
+
+All steps are sequential. Do not skip or reorder.
+
+### Phase 1 — Discover
+
+1. **Resolve the SFDX project path** — find the project's `sfdx-project.json` and identify the package directory for `sharingRules/`.
+
+2. **Check for existing sharing rules** — look for `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml`. If found, read it to understand existing rules and avoid duplicates.
+
+3. **If no local file exists**, retrieve from the org:
+   ```sh
+   sf project retrieve start --metadata "SharingRules:<ObjectName>" --target-org <org>
+   ```
+
+### Phase 2 — Determine Rule Type
+
+4. **Select the rule type** based on user intent. Read `references/rule-types.md` for the complete schema of each type and its required elements.
+
+5. **For Account sharing rules**: the `accountSettings` element is required. Default sub-access levels to `None` unless the user specifies otherwise.
+
+6. **For Guest rules**: the `sharedTo` must use `<guestUser>` with the site guest user's community nickname. Never use `<role>` or `<group>` for guest rules.
+
+### Phase 3 — Generate
+
+7. **Construct the XML** following the schema in `references/rule-types.md`. Key structure:
+   - One `.sharingRules-meta.xml` file per object
+   - All rules for the same object go in the same file
+   - If appending to an existing file, add the new rule element inside the existing `<SharingRules>` root
+
+8. **Name the rule** — derive `<fullName>` from the intent (PascalCase, no spaces, descriptive). Generate a matching `<label>` in Title Case with spaces.
+
+9. **Write the file** to `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml`.
+
+### Phase 4 — Verify
+
+10. **Run the verification checklist** below before presenting output.
+
+---
+
+## Verification Checklist
+
+### Universal Checks
+- [ ] Does the file have the XML declaration and `<SharingRules xmlns="http://soap.sforce.com/2006/04/metadata">` root?
+- [ ] Is there exactly one file per object with all rules inside it?
+- [ ] Does `<fullName>` use PascalCase with no spaces?
+- [ ] Is `<label>` present and human-readable?
+- [ ] Is `<accessLevel>` one of `Read` or `Edit`?
+
+### Criteria Rule Checks
+- [ ] Is `<includeRecordsOwnedByAll>` present (required boolean)?
+- [ ] Does each `<criteriaItems>` have `<field>`, `<operation>`, and `<value>`?
+- [ ] Are picklist values valid for the target org?
+
+### Guest Rule Checks   CRITICAL
+- [ ] Does `<sharedTo>` use `<guestUser>` (NOT `<role>` or `<group>`)?
+- [ ] Is `<includeHVUOwnedRecords>` present (required boolean)?
+- [ ] Is `<includeRecordsOwnedByAll>` ABSENT (only for criteria rules, not guest rules)?
+
+### Owner Rule Checks
+- [ ] Does the rule have both `<sharedFrom>` and `<sharedTo>` elements?
+- [ ] Do both use valid `<role>`, `<roleAndSubordinates>`, or `<group>` targets?
+
+### Account-Specific Checks   CRITICAL
+- [ ] If object is Account, is `<accountSettings>` present with all three sub-elements?
+- [ ] Are `<caseAccessLevel>`, `<contactAccessLevel>`, `<opportunityAccessLevel>` all set?
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| One `.sharingRules-meta.xml` file per object | Platform requirement — multiple files cause deployment errors |
+| Guest rules must use `<guestUser>` in `sharedTo` | Using `<role>` or `<group>` causes: "Specify a guest user's nickname for the guestUser field" |
+| Account rules require `<accountSettings>` | Without it: "AccountSettings is required for account sharing rules" |
+| `includeRecordsOwnedByAll` is required on criteria rules | Missing it causes: "Required field is missing: sharingCriteriaRules" |
+| `includeHVUOwnedRecords` is required on guest rules | Missing it causes deployment failure |
+| Criteria field values must exist as picklist values on the org | Invalid values cause: "Picklist value does not exist" |
+| Never hardcode file paths — resolve from `sfdx-project.json` | Customer projects use custom package directories |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Guest rule uses `<role>` instead of `<guestUser>` | Replace with `<guestUser>CommunityNickname</guestUser>` |
+| Account rule missing `accountSettings` | Add `<accountSettings>` with all three access level sub-elements set to `None` |
+| Criteria rule missing `includeRecordsOwnedByAll` | Add `<includeRecordsOwnedByAll>true</includeRecordsOwnedByAll>` |
+| Picklist value mismatch | Query the org for valid values before generating criteria |
+| Appending duplicates existing rule name | Check existing `<fullName>` values before writing |
+| Guest user nickname not found | Query: `SELECT CommunityNickname FROM User WHERE UserType='Guest' AND IsActive=true` |
+
+---
+
+## Output Expectations
+
+Deliverables:
+- `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml` — complete sharing rules file for the target object
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|------|-------------|
+| Permission set configuration | `platform-permission-set-generate` skill |
+| Custom object creation (if target object doesn't exist) | `platform-custom-object-generate` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/rule-types.md` | Phase 2 — before generating any rule, to get the complete XML schema for each rule type |

package/skills/platform-sharing-rules-generate/references/rule-types.md

@@ -0,0 +1,199 @@
+# Sharing Rule Types — Complete XML Schema
+
+Reference for all supported sharing rule types. Read this before generating any rule.
+
+---
+
+## File Structure
+
+All sharing rules for a single object live in one file:
+
+```xml
+<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml
+```
+
+The root element wraps all rule types:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<SharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- One or more rule elements of any type -->
+</SharingRules>
+```
+
+---
+
+## Criteria-Based Rules (`sharingCriteriaRules`)
+
+Share records that match specific field conditions with a target role, group, or portal role.
+
+```xml
+<sharingCriteriaRules>
+    <fullName>RuleApiName</fullName>
+    <accessLevel>Read</accessLevel>
+    <includeRecordsOwnedByAll>true</includeRecordsOwnedByAll>
+    <label>Human Readable Rule Name</label>
+    <sharedTo>
+        <role>RoleDeveloperName</role>
+    </sharedTo>
+    <criteriaItems>
+        <field>FieldApiName</field>
+        <operation>equals</operation>
+        <value>FieldValue</value>
+    </criteriaItems>
+</sharingCriteriaRules>
+```
+
+### Required Elements
+
+| Element | Type | Notes |
+|---------|------|-------|
+| `fullName` | string | PascalCase API name, unique within the object's sharing rules |
+| `accessLevel` | enum | `Read` or `Edit` |
+| `includeRecordsOwnedByAll` | boolean | `true` = all records matching criteria; `false` = only records not owned by the sharedTo target |
+| `label` | string | Human-readable name displayed in Setup |
+| `sharedTo` | SharedTo | Target users/roles/groups (see SharedTo section below) |
+| `criteriaItems` | FilterItem[] | One or more field criteria (see FilterItem section below) |
+
+### Optional Elements
+
+| Element | Type | Notes |
+|---------|------|-------|
+| `booleanFilter` | string | Custom logic for multiple criteria (e.g., `"1 AND (2 OR 3)"`) |
+| `description` | string | Optional description |
+| `accountSettings` | AccountSettings | **Required if object is Account** |
+
+---
+
+## Guest Rules (`sharingGuestRules`)
+
+Share records with Experience Site guest (unauthenticated) users. The `sharedTo` MUST use `<guestUser>` — never `<role>` or `<group>`.
+
+```xml
+<sharingGuestRules>
+    <fullName>ShareRecordsWithSiteGuest</fullName>
+    <accessLevel>Read</accessLevel>
+    <includeHVUOwnedRecords>false</includeHVUOwnedRecords>
+    <label>Share Records With Site Guest</label>
+    <sharedTo>
+        <guestUser>Site Guest User CommunityNickname</guestUser>
+    </sharedTo>
+    <criteriaItems>
+        <field>Status__c</field>
+        <operation>equals</operation>
+        <value>Published</value>
+    </criteriaItems>
+</sharingGuestRules>
+```
+
+### Required Elements
+
+| Element | Type | Notes |
+|---------|------|-------|
+| `fullName` | string | PascalCase API name |
+| `accessLevel` | enum | `Read` or `Edit` |
+| `includeHVUOwnedRecords` | boolean | Whether to include records owned by high-volume users |
+| `label` | string | Human-readable name |
+| `sharedTo` | SharedTo | Must contain `<guestUser>` with the CommunityNickname |
+| `criteriaItems` | FilterItem[] | One or more field criteria |
+
+### Finding the Guest User Nickname
+
+Query the org to find the correct community nickname:
+
+```sql
+SELECT CommunityNickname, Name FROM User WHERE UserType = 'Guest' AND IsActive = true
+```
+
+The `CommunityNickname` value goes in the `<guestUser>` element.
+
+---
+
+## Owner Rules (`sharingOwnerRules`)
+
+Share records based on record ownership — records owned by users in one role/group are shared with users in another role/group.
+
+```xml
+<sharingOwnerRules>
+    <fullName>ShareManagerRecordsWithTeam</fullName>
+    <accessLevel>Read</accessLevel>
+    <label>Share Manager Records With Team</label>
+    <sharedFrom>
+        <role>Manager</role>
+    </sharedFrom>
+    <sharedTo>
+        <roleAndSubordinates>TeamLead</roleAndSubordinates>
+    </sharedTo>
+</sharingOwnerRules>
+```
+
+### Required Elements
+
+| Element | Type | Notes |
+|---------|------|-------|
+| `fullName` | string | PascalCase API name |
+| `accessLevel` | enum | `Read` or `Edit` |
+| `label` | string | Human-readable name |
+| `sharedFrom` | SharedTo | Source — whose records are being shared |
+| `sharedTo` | SharedTo | Target — who gets access |
+
+---
+
+## SharedTo Element
+
+The `<sharedTo>` (and `<sharedFrom>` for owner rules) element specifies the target. Use exactly ONE of these child elements:
+
+| Element | Use for |
+|---------|---------|
+| `<role>RoleDeveloperName</role>` | A specific role |
+| `<roleAndSubordinates>RoleName</roleAndSubordinates>` | A role and all subordinates in the hierarchy |
+| `<group>GroupDeveloperName</group>` | A public group |
+| `<guestUser>CommunityNickname</guestUser>` | Experience Site guest user (guest rules only) |
+| `<portalRole>PortalRoleName</portalRole>` | Portal user role |
+| `<portalRoleAndSubordinates>PortalRoleName</portalRoleAndSubordinates>` | Portal role + subordinates |
+| `<allInternalUsers>AllInternalUsers</allInternalUsers>` | All internal users |
+| `<allCustomerPortalUsers>AllCustomerPortalUsers</allCustomerPortalUsers>` | All customer portal users |
+
+---
+
+## FilterItem (criteriaItems)
+
+Each `<criteriaItems>` element specifies one condition:
+
+```xml
+<criteriaItems>
+    <field>FieldApiName</field>
+    <operation>equals</operation>
+    <value>MatchValue</value>
+</criteriaItems>
+```
+
+| Element | Required | Notes |
+|---------|----------|-------|
+| `field` | Yes | API name of the field (no object prefix) |
+| `operation` | Yes | One of: `equals`, `notEqual`, `lessThan`, `greaterThan`, `lessOrEqual`, `greaterOrEqual`, `contains`, `notContain`, `startsWith` |
+| `value` | Conditional | Required unless operation is a null check |
+
+Multiple `<criteriaItems>` are ANDed by default. Use `<booleanFilter>` for custom logic.
+
+---
+
+## AccountSettings (Account object only)
+
+When creating sharing rules for the Account object, you MUST include `<accountSettings>`:
+
+```xml
+<accountSettings>
+    <caseAccessLevel>None</caseAccessLevel>
+    <contactAccessLevel>None</contactAccessLevel>
+    <opportunityAccessLevel>None</opportunityAccessLevel>
+</accountSettings>
+```
+
+| Element | Valid Values | Notes |
+|---------|-------------|-------|
+| `caseAccessLevel` | `None`, `Read`, `Edit` | Access to related Cases |
+| `contactAccessLevel` | `None`, `Read`, `Edit` | Access to related Contacts |
+| `opportunityAccessLevel` | `None`, `Read`, `Edit` | Access to related Opportunities |
+
+Place `<accountSettings>` inside the rule element, after `<accessLevel>`.

package/skills/platform-tracing-agentforce-configure/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: platform-tracing-agentforce-configure
+description: "Generate AgentforcePlatformTracingSettings metadata to enable or disable Agentforce agent execution trace spans flowing to Data Cloud. Use this skill for any AgentforcePlatformTracingSettings metadata work. TRIGGER when: user mentions Agentforce tracing, agent trace spans, Data Cloud tracing, AgentforcePlatformTracingSettings, platform observability tracing, enable agent tracing, wants agent execution spans in Data Cloud, mentions .settings-meta.xml for AgentforcePlatformTracing, or asks about enabling observability for Agentforce agents. DO NOT TRIGGER when: user wants Platform Tracing for TraceSpanEvent (use platform-tracing-configure), wants to query or analyze existing agent trace data in Data Cloud (use agentforce-observe), wants Event Log Files or ELF configuration, wants Change Data Capture (use integration-eventing-cdc-configure), or wants ManagedEventSubscription (use integration-eventing-subscription-configure)."
+metadata:
+  version: "1.0"
+  minApiVersion: "68.0"
+  relatedSkills: platform-tracing-configure
+---
+
+# Platform Tracing — Agentforce Configure
+
+Generate AgentforcePlatformTracingSettings metadata to enable or disable forwarding of Agentforce agent execution trace spans to Data Cloud's ingestion pipeline. This is a singleton Settings type with one boolean field introduced in API v68.0 (Spring '25).
+
+## Scope
+
+- **In scope**: Generating `AgentforcePlatformTracing.settings-meta.xml` to enable or disable Agentforce agent tracing.
+- **Out of scope**: Platform Tracing for TraceSpanEvent (use `platform-tracing-configure`). Event Log Files. Change Data Capture. Org permission provisioning. Data Cloud provisioning.
+
+---
+
+## Prerequisites
+
+Before generating, inform the user of these requirements. The skill cannot check org state, but deploying without these prerequisites means the setting has no effect:
+
+1. **Data Cloud must be provisioned** in the org — trace spans are forwarded to Data Cloud's ingestion pipeline. Without Data Cloud, there is no destination for the spans.
+2. **`PlatformObservability` org permission** must be active — this permission gates the feature. It is provisioned (not settable via metadata).
+3. **API version 68.0+** — the `AgentforcePlatformTracingSettings` type was introduced in Spring '25. Orgs on older API versions will not recognize it.
+
+If the user reports the setting isn't working after deploy, the most likely cause is a missing prerequisite above.
+
+---
+
+## Clarifying Questions
+
+Before generating, confirm with the user if not already clear:
+
+- Enable or disable? (Which state do you want for Agentforce agent tracing?)
+
+No other clarification needed — this is a singleton type with one boolean field.
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Desired state**: `true` (enable) or `false` (disable)
+
+Defaults unless specified:
+- If user says "enable" or "turn on": set to `true`
+- If user says "disable" or "turn off": set to `false`
+
+If the user provides a clear request, generate immediately without unnecessary back-and-forth.
+
+---
+
+## Workflow
+
+1. **Warn about prerequisites** — inform the user that this feature requires Data Cloud and the `PlatformObservability` org permission.
+
+2. **Read the template** — load `assets/AgentforcePlatformTracing-template.xml`.
+
+3. **Generate the settings file** — replace `{ENABLED}` with `true` or `false` based on the user's desired state.
+
+4. **Place the file** — output to `settings/AgentforcePlatformTracing.settings-meta.xml` in the project's source directory.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|---|---|
+| Singleton — only one file per org, one boolean field | The metadata type has exactly one instance. Deploying the file sets the org-wide preference. |
+| XML namespace must be `http://soap.sforce.com/2006/04/metadata` | Any other namespace causes deploy failure. |
+| File must be named `AgentforcePlatformTracing.settings-meta.xml` | SFDX source format convention for this Settings type. |
+| Only include `enableAgentforcePlatformTracing` field | No other fields exist on this type. |
+| Requires API v68.0+ | Older orgs reject the metadata type entirely. |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| Deploy succeeds but tracing doesn't activate | Org lacks `PlatformObservability` permission or Data Cloud is not provisioned. These are provisioned, not settable via metadata. |
+| `AgentforcePlatformTracingSettings` type not recognized | Org or tooling is on API version < 68.0. Update `sfdx-project.json` sourceApiVersion. |
+| User confuses this with Platform Tracing (TraceSpanEvent) | Clarify: this sends Agentforce agent execution spans to Data Cloud. For TraceSpanEvent publishing, use the `platform-tracing-configure` skill. |
+
+---
+
+## Output Expectations
+
+Deliverables:
+- `settings/AgentforcePlatformTracing.settings-meta.xml`
+
+Before delivering, verify:
+- [ ] XML namespace is exactly `http://soap.sforce.com/2006/04/metadata`
+- [ ] File is named `AgentforcePlatformTracing.settings-meta.xml`
+- [ ] Only `enableAgentforcePlatformTracing` is present (no extra fields)
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|---|---|
+| Enable TraceSpanEvent publishing (Platform Tracing) | `platform-tracing-configure` skill |
+| Query or analyze existing Agentforce agent trace data in Data Cloud | `agentforce-observe` skill |
+| Set up Change Data Capture | `integration-eventing-cdc-configure` skill |
+| Configure ManagedEventSubscription | `integration-eventing-subscription-configure` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `assets/AgentforcePlatformTracing-template.xml` | Step 2 — template for generating the settings file |

package/skills/platform-tracing-agentforce-configure/assets/AgentforcePlatformTracing-template.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<AgentforcePlatformTracingSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableAgentforcePlatformTracing>{ENABLED}</enableAgentforcePlatformTracing>
+</AgentforcePlatformTracingSettings>

package/skills/platform-tracing-configure/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: platform-tracing-configure
+description: "Generate EventSettings metadata to enable or disable Platform Tracing (TraceSpanEvent publishing) in Event Monitoring. Use this skill for any EventSettings enablePlatformTracing metadata work. TRIGGER when: user mentions Platform Tracing, TraceSpanEvent, enable tracing in Event Monitoring Settings, event monitoring tracing toggle, enablePlatformTracing, .settings-meta.xml for Event settings tracing, turn on trace span events, or stop publishing trace spans. DO NOT TRIGGER when: user wants Agentforce agent tracing to Data Cloud (use platform-tracing-agentforce-configure), wants Event Log Files or ELF generation, wants Change Data Capture (use integration-eventing-cdc-configure), or wants ManagedEventSubscription (use integration-eventing-subscription-configure)."
+metadata:
+  version: "1.0"
+  minApiVersion: "68.0"
+  relatedSkills: platform-tracing-agentforce-configure
+---
+
+# Platform Tracing — Configure
+
+Generate EventSettings metadata to enable or disable the Platform Tracing toggle, which controls whether TraceSpanEvent is published at a sample rate. This modifies a single field (`enablePlatformTracing`) within the existing EventSettings metadata type.
+
+## Scope
+
+- **In scope**: Generating `Event.settings-meta.xml` with the `enablePlatformTracing` field to enable or disable TraceSpanEvent publishing.
+- **Out of scope**: Agentforce agent tracing to Data Cloud (use `platform-tracing-agentforce-configure`). Other EventSettings fields (`enableDeleteMonitoringData`, `enableLoginForensics`, etc.) owned by other teams. Event Log Files. Change Data Capture.
+
+---
+
+## Prerequisites
+
+Before generating, inform the user of these requirements:
+
+1. **`PlatformTracing` org permission** must be active — this permission gates the feature. It is provisioned (not settable via metadata). Without it, the setting deploys but TraceSpanEvent is not published.
+2. **API version 68.0+** — `enablePlatformTracing` on EventSettings was introduced in Spring '25. Orgs or tooling on older API versions will not recognize the field. Update `sfdx-project.json` `sourceApiVersion` to `68.0` or higher if on an older tooling version.
+
+If the user reports the setting isn't working after deploy, the most likely cause is a missing prerequisite above.
+
+---
+
+## Clarifying Questions
+
+Before generating, confirm with the user if not already clear:
+
+- Enable or disable? (Which state do you want for Platform Tracing / TraceSpanEvent?)
+
+No other clarification needed — this controls a single boolean field.
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Desired state**: `true` (enable) or `false` (disable)
+
+Defaults unless specified:
+- If user says "enable" or "turn on": set to `true`
+- If user says "disable" or "turn off": set to `false`
+
+If the user provides a clear request, generate immediately without unnecessary back-and-forth.
+
+---
+
+## Workflow
+
+1. **Warn about prerequisites** — inform the user that this feature requires the `PlatformTracing` org permission and API version 68.0+.
+
+2. **Read the template** — load `assets/EventSettings-template.xml`.
+
+3. **Generate the settings file** — replace `{ENABLED}` with `true` or `false` based on the user's desired state.
+
+4. **Place the file** — output to `settings/Event.settings-meta.xml` in the project's source directory.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|---|---|
+| Only include `enablePlatformTracing` in generated metadata | Other fields in EventSettings are owned by other teams. Including them risks overwriting unrelated settings during deploy. |
+| XML namespace must be `http://soap.sforce.com/2006/04/metadata` | Any other namespace causes deploy failure. |
+| File must be named `Event.settings-meta.xml` | SFDX source format convention — the type name prefix for EventSettings is `Event`. |
+| Requires `PlatformTracing` org permission | Without this permission, the setting deploys but has no effect on TraceSpanEvent publishing. |
+| Requires API v68.0+ | Older orgs/tooling reject the field entirely. |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| Deploy succeeds but TraceSpanEvent not published | Org lacks the `PlatformTracing` permission. This is provisioned, not settable via metadata. |
+| `enablePlatformTracing` field not recognized by org/tooling | Tooling is on API version < 68.0. Update `sfdx-project.json` `sourceApiVersion` to `68.0` or higher. |
+| User confuses this with Agentforce tracing | Clarify: this publishes TraceSpanEvent for platform operations. For Agentforce agent spans to Data Cloud, use the `platform-tracing-agentforce-configure` skill. |
+| User wants to configure all Event Monitoring settings | Only `enablePlatformTracing` is in scope. Other EventSettings fields are owned by other teams and not managed by this skill. |
+
+---
+
+## Output Expectations
+
+Deliverables:
+- `settings/Event.settings-meta.xml`
+
+Before delivering, verify:
+- [ ] XML namespace is exactly `http://soap.sforce.com/2006/04/metadata`
+- [ ] File is named `Event.settings-meta.xml`
+- [ ] Only `enablePlatformTracing` is present (no other EventSettings fields)
+- [ ] Project `sourceApiVersion` in `sfdx-project.json` is `68.0` or higher
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|---|---|
+| Enable Agentforce agent tracing to Data Cloud | `platform-tracing-agentforce-configure` skill |
+| Set up Change Data Capture | `integration-eventing-cdc-configure` skill |
+| Configure ManagedEventSubscription | `integration-eventing-subscription-configure` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `assets/EventSettings-template.xml` | Step 2 — template for generating the settings file |

package/skills/platform-tracing-configure/assets/EventSettings-template.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<EventSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enablePlatformTracing>{ENABLED}</enablePlatformTracing>
+</EventSettings>