dx-org-analyze

Tool Restrictions

Use ONLY the Bash tool to execute all sf CLI commands and Python scripts. Always include --json for sf commands. Do NOT use mcp__salesforce_dx__* tools.

Output artifacts for eval/testing: When an output directory is available, write results there. After executing the skill: (1) if the user specified an output path, write there immediately; (2) otherwise run [ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' to detect the eval directory; (3) write the full JSON result to <output-dir>/dx-org-analyze-result.json and the markdown report to <output-dir>/dx-org-analyze-result.md.

---

Data Access Hierarchy

When querying org data, always follow this priority order:

1. SF CLI commands — Preferred. Use sf org list metadata-types, sf org list metadata, sf org display, sf data query, sf limits api display, etc.
2. Direct REST/Tooling API calls — Last resort, only when SF CLI cannot provide the data.

Never bypass this hierarchy. If an SF CLI command exists for the operation, use it even if a direct API call would be simpler.

---

Authentication Rules

• All authentication MUST go through SF CLI (sf org login web, sf org login jwt, sf org login access-token).
• Never accept raw credentials (username + password), session IDs, or access tokens directly from the user.
• The collection script obtains its access token exclusively via sf org display --json.

---

Workflow

Step 0: List Authenticated Orgs

Run this command to discover all authenticated orgs:

sf org list --json --skip-connection-status

Parse the JSON output. Collect orgs from all buckets (devHubs, nonScratchOrgs, scratchOrgs, sandboxes, other). Present authenticated orgs in a readable table:

| # | Alias | Username | Instance URL | Org ID | Type |

|---|-------|----------|--------------|--------|------|

If fewer than 2 orgs are authenticated but at least 1 is available, offer the single-org introspect mode (see Introspect Workflow below). If no orgs are authenticated, STOP and advise:

> You need at least 1 authenticated org. Run sf org login web --alias <name> to authenticate.

If the user explicitly requests a single-org introspection or inventory, use the Introspect Workflow regardless of how many orgs are available.

Step 1: User Selects Two Orgs

Ask the user to select two orgs from the list. Both must be explicitly named — do NOT allow implicit/default orgs.

> Select two orgs to compare. Which is the source (reference/expected state)? Which is the target (to compare against)?

Accept: alias, username, or number from the list. Resolve each selection to a concrete username. If an org lacks an alias, prompt the user to assign one. Confirm:

> Comparing:

> - Source: <alias> (<username>)

> - Target: <alias> (<username>)

Step 2: Validate Connectivity

For each org, confirm reachability with a lightweight query that does not expose secrets:

sf data query --target-org <alias-or-username> --query "SELECT Id FROM Organization LIMIT 1" --json

If the query succeeds (exit 0 and a record is returned), the org is connected. If it fails with INVALID_SESSION_ID or auth errors:

sf org login web --alias <alias>

Step 3: Collect Data (per org)

Generate a unique run ID and run the collection script for each org:

RUN_ID=$(date +%Y%m%d-%H%M%S)

python3 ./scripts/collect_org_data.py \
  --org-alias "$SOURCE_ORG" \
  --output /tmp/dx-org-comparison-${RUN_ID}-source

python3 ./scripts/collect_org_data.py \
  --org-alias "$TARGET_ORG" \
  --output /tmp/dx-org-comparison-${RUN_ID}-target

Exit codes: 0 = success, 1 = fatal error (report stderr to user), 2 = session expired (re-authenticate Step 2 and retry).

For details on what the collection script gathers, see references/collection-details.md.

Step 4: Compute Diff and Report

python3 ./scripts/compute_diff.py \
  --org-a /tmp/dx-org-comparison-${RUN_ID}-source \
  --org-b /tmp/dx-org-comparison-${RUN_ID}-target \
  --output /tmp/dx-org-comparison-${RUN_ID} \
  --format both \
  --org-a-label "Source" \
  --org-b-label "Target"

Use --show-shared if the user wants shared components listed in detail.

Step 5: Present Results

Read /tmp/dx-org-comparison-${RUN_ID}.md and present to the user. If the user asks follow-up questions, use /tmp/dx-org-comparison-${RUN_ID}.json for data lookups. Then resolve the output directory and copy both files there:

OUTPUT_DIR=""
if [ -n "$USER_OUTPUT_PATH" ]; then
  OUTPUT_DIR="$USER_OUTPUT_PATH"
elif [ -d "force-app/main/adk-eval-output" ]; then
  OUTPUT_DIR="force-app/main/adk-eval-output"
fi

if [ -n "$OUTPUT_DIR" ]; then
  cp /tmp/dx-org-comparison-${RUN_ID}.json "$OUTPUT_DIR/dx-org-analyze-result.json"
  cp /tmp/dx-org-comparison-${RUN_ID}.md "$OUTPUT_DIR/dx-org-analyze-result.md"
fi

---

Introspect Workflow (Single-Org Mode)

Use this workflow when the user wants to inspect a single org's configuration, or when only one org is authenticated.

Introspect Step 1: Validate Connectivity

sf data query --target-org <alias-or-username> --query "SELECT Id FROM Organization LIMIT 1" --json

Introspect Step 2: Collect Data

RUN_ID=$(date +%Y%m%d-%H%M%S)

python3 ./scripts/collect_org_data.py \
  --org-alias "$ORG" \
  --output /tmp/dx-org-analysis-${RUN_ID}

Introspect Step 3: Generate Report

python3 ./scripts/introspect_org.py \
  --org /tmp/dx-org-analysis-${RUN_ID} \
  --output /tmp/dx-org-analysis-${RUN_ID} \
  --format both \
  --label "OrgName"

Introspect Step 4: Present Results

Read /tmp/dx-org-analysis-${RUN_ID}.md and present to the user. The report covers: metadata inventory, org settings, org limits, installed packages, licenses, system permissions, and deep data records. Then resolve the output directory and copy both files there:

OUTPUT_DIR=""
if [ -n "$USER_OUTPUT_PATH" ]; then
  OUTPUT_DIR="$USER_OUTPUT_PATH"
elif [ -d "force-app/main/adk-eval-output" ]; then
  OUTPUT_DIR="force-app/main/adk-eval-output"
fi

if [ -n "$OUTPUT_DIR" ]; then
  cp /tmp/dx-org-analysis-${RUN_ID}.json "$OUTPUT_DIR/dx-org-analyze-result.json"
  cp /tmp/dx-org-analysis-${RUN_ID}.md "$OUTPUT_DIR/dx-org-analyze-result.md"
fi

---

Report Structure

The generated report includes:

1. Drift Score — Weighted overall score (60% metadata, 30% permissions, 10% profiles) with severity level (LOW/MODERATE/HIGH/CRITICAL)
2. Summary Statistics — Counts per metadata type with Identical/Different columns from deep data
3. Metadata Components by Type — Only-in-Source, only-in-Target, shared per type
4. Profiles — Shared, source-only, target-only
5. Installed Packages — Version comparison, only-in-Source, only-in-Target
6. Package Components — Namespaced components grouped by namespace
7. Org Permissions — Boolean enabled/disabled diffs by category, plus value diffs
8. System Permissions — PermissionsXxx fields on PermissionSet, per-set diffs
9. Org Values & Limits — Grouped by Identity, Storage, API, Feature Limits
10. Licenses — User, Permission Set, Package license quantity diffs
11. Deep Data — Content-level diffs for Apex, Flows, Validation Rules, Custom Fields, etc.

---

Rules / Constraints

| Constraint | Rationale |

|-----------|-----------|

| Always use --json with sf commands | Structured output for reliable parsing |

| Resolve orgs to usernames, not aliases | Aliases can be ambiguous; usernames are unique |

| Skip expired and disconnected orgs | Cannot query metadata from inaccessible orgs |

| Read-only — never deploy or modify | This skill compares only, never mutates either org |

| SF CLI auth only | All authentication through SF CLI credential store |

| Both orgs must be explicit | Never compare unnamed or implicit/default orgs |

---

Troubleshooting

| Issue | Resolution |

|-------|------------|

| "No org found for \<alias\>" | Org not authenticated — run sf org login web --alias <name> |

| Fewer than 2 authenticated orgs | Authenticate additional orgs before comparing |

| "INVALID_SESSION_ID" or auth errors | Session expired — re-run sf org login web --alias <name> |

| Collection script exits with code 2 | Session expired — re-authenticate and retry |

| API limit errors during metadata listing | Use --skip-deep-data for a faster pass with less detail |

| Edition differences (DE vs EE) | Many differences are edition-inherent, not configuration drift |

| Large orgs timeout on deep data | Use --skip-deep-data flag; run full deep data on targeted follow-ups |

---

Cross-Skill Integration

| Need | Delegate to |

|------|-------------|

| Retrieve specific metadata from an org | platform-metadata-retrieve |

| Deploy metadata to an org | platform-metadata-deploy |

| Create a scratch org for comparison | dx-org-manage |

| Switch default org after comparison | dx-org-switch |

---

Reference File Index

| File | When to read |

|------|-------------|

| references/collection-details.md | For details on what the collection script gathers and how |

| references/report-format.md | For drift score formula and report section details |

| scripts/collect_org_data.py | Data collection script (per org) |

| scripts/compute_diff.py | Diff computation and report generation script |

| scripts/introspect_org.py | Single-org introspection report script |