destructive-changes

You are building a destructiveChanges.xml file (and the matching package.xml placeholder) to delete metadata from a Salesforce org. Destructive changes are the only safe way to delete components on deploy — manual UI deletes don't propagate.

Read Project Config First

source "${CLAUDE_PLUGIN_ROOT}/hooks/lib/config.sh"
APEX_SRC="$(sf_config_get '.paths.apexSource' "$ENV")"
LWC_SRC="$(sf_config_get '.paths.lwcSource' "$ENV")"
API_VERSION="$(sf_config_get '.platform.apiVersion' "$ENV")"

Input

$ARGUMENTS:

• add <metadataType>:<fullName> — add a component to the destructive set (e.g., ApexClass:OrderHelper, CustomField:Account.Old_Field__c)
• add-from <file> — read components from a file (one per line, same format)
• preview — print the current destructive set
• validate — verify no source still references the listed components
• write [<dir>] — author destructiveChanges.xml + package.xml to <dir> (default manifest/destructive/)
• clear — wipe the in-progress set
• --ci — machine output

State

The in-progress set lives in ${CLAUDE_PLUGIN_DATA}/argo/destructive/<project>/pending.json:

{
  "items": [
    {"type": "ApexClass", "fullName": "OrderHelper"},
    {"type": "CustomField", "fullName": "Account.Old_Field__c"}
  ],
  "lastModified": "2026-04-28T14:45:00Z"
}

Steps

add <Type>:<fullName>

Validate type against the supported list (ApexClass, ApexTrigger, LightningComponentBundle, CustomObject, CustomField, ValidationRule, Layout, FlowDefinition, PermissionSet, etc.).

For CustomField, fullName format is <Object>.<Field> (e.g., Account.Old_Field__c).

Append to the pending set; refuse duplicates.

validate

For each pending item, run the equivalent of /argo:field-impact (for fields) or a grep for the symbol (for classes/components):

• ApexClass: grep references to ClassName. and new ClassName(
• LightningComponentBundle: grep c-<lwc-name> in HTML and from 'c/<lwcName>' in JS
• CustomField: full field-impact across all metadata types
• CustomObject: every reference to <Object>__c in queries, layouts, profiles, perms, flows
• FlowDefinition: every Apex Flow.Interview lookup of the developer name

Report:

• ✅ if no references found in source
• ⚠️ if references exist (list them; refuse to write until cleaned up or user passes --force)

write [<dir>]

Generate two files:

<dir>/destructiveChanges.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>OrderHelper</members>
        <name>ApexClass</name>
    </types>
    <types>
        <members>Account.Old_Field__c</members>
        <name>CustomField</name>
    </types>
    <version>{{platform.apiVersion}}</version>
</Package>

<dir>/package.xml (empty placeholder required by the API):

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <version>{{platform.apiVersion}}</version>
</Package>

Print the deploy command:

sf project deploy start --target-org <ORG> --manifest <dir>/package.xml --post-destructive-changes <dir>/destructiveChanges.xml --wait 30

(Use --pre-destructive-changes if the deletion must happen before the deploy of new components.)

Output

Default Markdown after validate:

# Destructive Changes Validation

Pending items: 3

| Type | Full Name | Source refs | Verdict |
|------|-----------|-------------|---------|
| ApexClass | OrderHelper | 0 | ✅ safe to delete |
| CustomField | Account.Old_Field__c | 2 (in OrderController.cls:42, acmeAccountForm.html:18) | ⚠️ in use |
| FlowDefinition | Old_Auto_Assign | 0 | ✅ safe to delete |

⚠️ Cannot write destructive set — clean up references first or pass `--force`.

Default after write:

# Destructive Changes Written

Files written:
- manifest/destructive/destructiveChanges.xml (3 items)
- manifest/destructive/package.xml (placeholder)

## Deploy command
sf project deploy start \
  --target-org DevVM \
  --manifest manifest/destructive/package.xml \
  --post-destructive-changes manifest/destructive/destructiveChanges.xml \
  --wait 30

## Pre vs Post Destructive
- Use `--post-destructive-changes` (default) when the deletion can happen after new components deploy
- Use `--pre-destructive-changes` when the new components depend on the deletion (e.g., renaming a field requires deleting the old name first)

## Reminder
Run `/argo:diff-deploy --validate` first against prod to catch Salesforce-side dependency errors that source-side validation can't see.

Exit codes

• 0 — operation succeeded
• 1 — validate found references (default refuse to write)
• 2 — invocation error / type unsupported

Rules

• Always validate before writing. Source-side reference checks catch most accidental deletions
• Don't write directly into deploy. This skill produces the manifest; the user (or CI) runs the deploy
• Pre vs post matters. Document both; default to post (the safe default)
• Refuse if references exist unless the user passes --force and accepts responsibility — don't make destruction easy
• Persist state across sessions. The pending file lets the user add over multiple sessions before writing

Consumers

• Release pipeline: build the destructive manifest as part of a release that retires legacy components
• /argo:field-impact is the underlying scanner for validate mode