/platform-sharing-owd-configure

name: platform-sharing-owd-configure
description: "Use when the user wants to retrieve or update Organization-Wide Default (OWD) sharing settings for Salesforce objects. TRIGGER when: user asks to check current OWD settings, view sharing defaults, change default access levels (Private, Public Read Only, Public Read/Write, Controlled by Parent), configure internal or external access for standard or custom objects, mentions org-wide defaults, wants to make records private or restrict who can see records, wants to control default record visibility for an object, or references .settings-meta.xml sharing fields or sharingModel in .object-meta.xml files. DO NOT TRIGGER when: user asks about sharing rules, criteria-based sharing, role hierarchy, or manual sharing — delegate to platform-sharing-rules-generate."
metadata:
  version: "1.2"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"

Managing Org-Wide Defaults

Retrieve and update Organization-Wide Default (OWD) sharing settings for standard and custom objects in a Salesforce org. OWDs define the baseline level of access users have to records they do not own.

Scope

• **In scope**: Retrieving current OWD settings, updating internal/external access levels for standard and custom objects
• **Out of scope**: Sharing rules, role hierarchy configuration, manual sharing, permission sets, criteria-based sharing — delegate to appropriate skills

---

Clarifying Questions

Before proceeding, confirm with the user if not already clear:

• Which object(s) do you want to get or update OWD settings for?
• What access level do you want to set? (Private, Public Read Only, Public Read/Write, Controlled by Parent)
• Do you need to change both internal and external access, or just one?

---

Required Inputs

Gather or infer before proceeding:

• **Target org**: The org alias or username to query/update (use default org if not specified)
• **Object name(s)**: Standard object API name (e.g., `Account`, `Contact`) or custom object API name (e.g., `Invoice__c`)
• **Operation**: Get (retrieve current settings) or Update (change access levels)
• **Access levels** (for update): Internal access and/or external access values

Defaults unless specified:

• Use the default connected org
• If only one access level is provided, assume it applies to internal access

---

Workflow

All steps are sequential. Do not skip or reorder.

Phase 1 — Retrieve Current Settings

1. **Query current OWD settings** using the Salesforce CLI Tooling API: `sf data query --query "SELECT QualifiedApiName, InternalSharingModel, ExternalSharingModel FROM EntityDefinition WHERE QualifiedApiName = '<ObjectName>'" --use-tooling-api --target-org <org>`

2. **For retrieving all OWD settings at once:** `sf data query --query "SELECT QualifiedApiName, InternalSharingModel, ExternalSharingModel FROM EntityDefinition WHERE IsCustomizable = true ORDER BY QualifiedApiName" --use-tooling-api --target-org <org>`

3. **Present results clearly** — read `references/access_levels.md` for valid values and display a formatted table to the user.

Phase 2 — Update Settings (if requested)

4. **Check for immutable/fixed OWD** — read `references/access_levels.md` "Immutable / Fixed OWD Objects" section. If the requested change targets a fixed value (e.g., Price Book external OWD), **stop immediately** and explain to the user that this value is platform-fixed and cannot be changed by any means. Do not attempt a deploy.

5. **Validate the requested access level** — read `references/access_levels.md` to confirm the value is valid for the target object. If the value is not in the allowed set for that object, explain what values are valid and ask the user to choose one. Do not guess alternative values.

6. **Retrieve the object metadata** using the Metadata API (same command for both standard and custom objects): `sf project retrieve start --metadata CustomObject:<ObjectName> --target-org <org>`. This retrieves `<ObjectName>.object-meta.xml` containing `<sharingModel>` and `<externalSharingModel>`. See `references/metadata_api_approach.md` for the full procedure.

7. **Modify the sharing settings** — update the `<sharingModel>` (internal access) and/or `<externalSharingModel>` (external access) in the object's `.object-meta.xml`. Read `references/metadata_api_approach.md` for details.

8. **Pre-deploy verification** — before deploying, confirm:

• [ ] External access is not more permissive than internal access
• [ ] Objects with Master-Detail relationships use `ControlledByParent`
• [ ] The requested access level is valid for the target object (see `references/access_levels.md`)
• [ ] Cross-object constraints are satisfied (see "Cross-Object Constraints" in `references/access_levels.md`)
• [ ] The target field is not listed as immutable/fixed in `references/access_levels.md`

9. **Deploy the updated settings:** `sf project deploy start --metadata CustomObject:<ObjectName> --target-org <org>`.

10. **Handle deploy failure (max 2 attempts):** If the deploy fails:

• Read the error message and identify the root cause.
• If the error indicates the value is invalid or unsupported for the object, **stop** — report the failure to the user with the exact error message and explain what is and isn't possible. Do not try alternative values unless the user explicitly requests a different valid value.
• If the error is transient (network timeout, auth expired), retry **once**.
• **Never attempt more than 2 total deploys for the same change.** After 2 failures, report the error, discard local edits (`sf project retrieve start --metadata CustomObject:<ObjectName> --target-org <org>`), and ask the user how to proceed.

11. **Verify the change** by re-running the query from Phase 1, Step 1.

---

Rules / Constraints

| Constraint | Rationale | |-----------|-----------| | Objects with Master-Detail relationships must use `ControlledByParent` | Platform enforces this —