/platform-sharing-rules-generate

name: platform-sharing-rules-generate
description: "Use when users get, create, edit, delete, or retrieve Salesforce Sharing Rules metadata for record-level access. TRIGGER on sharing rules, record/criteria-based/role-based/guest-user sharing, sharingCriteriaRules/sharingOwnerRules/sharingGuestRules, .sharingRules-meta.xml files, or sharing records with roles or groups, including viewing or modifying existing rules. DO NOT TRIGGER for permission sets/profiles or object-level (not record-level) security (use platform-permission-set-generate)."
metadata:
  version: "1.3"
  domains: ["Platform"]
  minApiVersion: "60.0"
  relatedSkills:
    - "platform-custom-object-generate"
    - "platform-permission-set-generate"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"

Sharing Rules Generator

Get, create, edit, and delete 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**: Creating, editing, deleting, and retrieving (getting) `sharingCriteriaRules`, `sharingOwnerRules`, and `sharingGuestRules` metadata; retrieving existing sharing rules from an org using the Metadata API Retrieve pattern; appending new rules to existing files; modifying rule criteria or access levels; removing rules from metadata 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 proceeding, confirm with the user if not already clear:

For Get operations:

• Which object's sharing rules should be retrieved? (standard or custom object API name, or all objects)
• Which target org should the rules be retrieved from? (org alias or default)

For Create operations:

• 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?

For Edit operations:

• Which existing rule should be modified? (rule fullName or label)
• What should change? (access level, criteria, label — note: `sharedTo` and `sharedFrom` cannot be edited in place)

For Delete operations:

• Which rule(s) should be removed? (rule fullName or label)
• Confirm the object the rule belongs to

---

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

Steps are sequential within each phase. Phase 3 branches by operation type — execute only the matching branch. Phase 4 applies to create, edit, and delete only (get operations end at Phase 3).

Phase 1 — Discover

1. **Resolve the SFDX project path** — find the project's `sfdx-project.json` and identify the package directory for `sharingRules/`.

2. **Always retrieve the latest sharing rules from the org** using the Metadata API Retrieve pattern:

   sf project retrieve start --metadata "SharingRules:<ObjectName>" --target-org <org>

This ensures the local file reflects the current org state. Never trust a local file that may be stale — edits or deletes against a stale file can recreate rules that were already removed in the org or overwrite changes made by other users.

3. **Read the retrieved file** — parse `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml` to understand existing rules and avoid duplicates.

Phase 2 — Determine Operation and Rule Type

4. **Identify the operation** — determine whether the user wants to **get**, **create**, **edit**, or **delete** a sharing rule.

5. **Select the rule type** based on user intent. Read `references/rule-types.md` for the complete schema of each type and its required elements.

6. **For Account sharing rules**: the `accountSettings` element is required. Default sub-access levels to `None` unless the user specifies otherwise.

7. **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 — Execute Operation

For Get:

8a. **Use the file already retrieved in Phase 1** — the retrieve in step 2 already pulled the latest `<ObjectName>.sharingRules-meta.xml` from the org. No additional retrieve is needed.

8b. **Read and present the retrieved rules** — parse the `.sharingRules-meta.xml` file and present the rules to the user in a readable format showing:

• Rule name (`fullName`) and label
• Rule type (criteria-based, owner-based, or guest)
• Access level
• Shared-to target
• Criteria (if applicable)

For get operations, skip Phase 4 (no write needed). The retrieve itself writes the metadata file to the local project.

For Create:

8a. **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 ne