platform-sharing-rules-generate

Summary

---
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:
   ```bash
   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 new rule element inside the existing `<SharingRules>` root

8b. **Name the rule** — derive `<fullName>` from the intent (PascalCase, no spaces, descriptive). Generate a matching `<label>` in Title Case with spaces.

#### For Edit:

8a. **Locate the target rule** — find the rule by `<fullName>` or `<label>` in the existing `.sharingRules-meta.xml` file.

8b. **Gate unsupported edits** — the platform does NOT support in-place modification of `<sharedTo>` or `<sharedFrom>` elements. If the user requests a change to the sharing target or source, refuse the edit and instruct them to delete the existing rule and create a new one with the desired target. This is the same pattern used for rule-type changes (see TC-16).

8c. **Determine modifications based on rule type**:
    - **Owner-based rules (`sharingOwnerRules`)**: only `<accessLevel>` can be edited. The platform does not support modifying any other element (`sharedTo`, `sharedFrom`, `label`) on owner rules. If the user requests changes beyond access level, refuse and instruct them to delete + create.
    - **Criteria-based rules (`sharingCriteriaRules`)**: supported editable elements are `<accessLevel>`, `<criteriaItems>`, `<label>`, and `<booleanFilter>`.
    - **Guest rules (`sharingGuestRules`)**: supported editable elements are `<accessLevel>`, `<criteriaItems>`, `<label>`, and `<includeHVUOwnedRecords>`.

#### For Delete:

8a. **Locate the target rule** — find the rule by `<fullName>` or `<label>` in the existing `.sharingRules-meta.xml` file.

8b. **Count remaining rules** — run `scripts/count-remaining-rules.sh <file>` to get the total rule count. If the count is 1 (only the rule being deleted), the file must be removed entirely in Phase 4.

8c. **Delegate destructive deployment to `platform-destructive-deploy`** — a normal `sf project deploy start` is additive and will NOT remove a rule from the org. Delegate to the `platform-destructive-deploy` skill with the following context:
    - Metadata type: `SharingCriteriaRule`, `SharingOwnerRule`, or `SharingGuestRule` (depending on the rule type)
    - Member: `<ObjectName>.<RuleFullName>`
    - Target org: the user's specified org

### Phase 4 — Write and Verify

9. **Apply the change**:
    - **Create**: Write the file to `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml`.
    - **Edit**: Update only the elements identified in step 8b; preserve all other elements exactly as they were.
    - **Delete (rules remain)**: Write the updated file with the target rule removed.
    - **Delete (last rule)**: Remove the file `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml` entirely.

10. **Run the verification checklist** below and consult the examples files (`examples/create-cases.md`, `examples/edit-cases.md`, `examples/delete-cases.md`) for scenario-specific expected behaviors 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?

### Edit Operation Checks
- [ ] Was the edit against a freshly retrieved file (not a stale local copy)?
- [ ] Is the edit limited to supported fields for the rule type?
  - Owner rules: only `accessLevel`
  - Criteria rules: `accessLevel`, `criteriaItems`, `label`, `booleanFilter`
  - Guest rules: `accessLevel`, `criteriaItems`, `label`, `includeHVUOwnedRecords`
- [ ] Was `sharedTo`/`sharedFrom` left unchanged? (if user requested that change, refuse and advise delete + create)
- [ ] Was only the intended element modified?
- [ ] Are all required elements still present after the edit?
- [ ] Does the modified rule still pass the universal checks above?

### Delete Operation Checks
- [ ] Was the correct rule removed (matched by `<fullName>`)?
- [ ] Is the remaining XML well-formed with proper `<SharingRules>` root?
- [ ] If no rules remain, was the file removed entirely?
- [ ] Was `platform-destructive-deploy` delegated to with the correct metadata type (`SharingCriteriaRule`, `SharingOwnerRule`, or `SharingGuestRule`)?

### 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 |
| For managed package custom objects, use the full API name including namespace prefix (e.g., `ns__Object__c`) | Namespace-prefixed objects store sharing rules under the prefixed name |
| `sharedTo` and `sharedFrom` cannot be edited in place | Platform does not support modifying sharing targets — deploy will fail. Delete the rule and create a new one instead |
| Owner-based rules only support editing `accessLevel` | No other field (`label`, `sharedTo`, `sharedFrom`) can be modified on owner rules — delete and recreate instead |
| Always retrieve from the org before edit or delete | Local files may be stale; editing a stale file can recreate deleted rules or overwrite concurrent changes |
| Deleting a rule requires a destructive deployment | A normal deploy is additive — it will not remove rules from the org. Delegate to `platform-destructive-deploy` |
| Edit must preserve unmodified elements | Changing only `accessLevel` must not alter `criteriaItems` or other fields |
| Delete must remove the entire rule block | Partial deletion leaves invalid XML and causes deployment failures |
| Delete last rule removes the file | An empty `<SharingRules>` root with no children is invalid metadata |

---

## 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` |
| User requests edit to `sharedTo` or `sharedFrom` | Not supported — refuse the edit and instruct user to delete + create a new rule |
| User requests edit to owner rule beyond `accessLevel` | Not supported — owner rules only allow `accessLevel` edits. Refuse and instruct user to delete + create |
| Editing changes rule type (e.g., criteria → owner) | Not supported — delete the old rule and create a new one instead |
| Local file is stale (rule deleted/changed in org) | Always retrieve fresh from org before edit or delete to avoid recreating removed rules |
| Delete deployed with normal deploy (no destructive manifest) | Rule remains in the org — delegate to `platform-destructive-deploy` for proper removal |
| Deleting a rule referenced by other automation | Warn the user about potential downstream impact |
| Delete leaves malformed XML | Ensure proper XML structure after removal; validate the file is well-formed |

---

## Output Expectations

Deliverables:
- **For get operations**: `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml` — retrieved sharing rules file from the org, plus a formatted summary of all rules found
- **For create/edit/delete operations**: `<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 |
| Destructive deployment (rule deletion from org) | `platform-destructive-deploy` 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 |
| `scripts/count-remaining-rules.sh` | Phase 3, step 8b (Delete) — count sharing rule elements to determine if file should be removed |
| `examples/create-cases.md` | Phase 4, step 10 — expected behavior for create and append scenarios |
| `examples/edit-cases.md` | Phase 4, step 10 — expected behavior for edit scenarios |
| `examples/delete-cases.md` | Phase 4, step 10 — expected behavior for delete scenarios |

Security audits