salesforce-metadata-fetcher-skill

salesforce-metadata-fetcher-skill

Fetches Salesforce metadata live from a connected org under T1 least-privilege scope, sanitizes output, and routes sanitized payloads to the appropriate downstream review skill. This skill eliminates the hand-paste requirement across the entire Vanguard Salesforce review portfolio — admins no longer need to manually export XML and paste it into review skills.

When This Skill Owns the Task

This skill owns the task when the user wants live metadata from a connected org rather than supplying a pre-exported file.

Explicit ownership signals

• "Fetch the Account object schema from my org"
• "List all flows in production"
• "Show me the PermissionSet called Sales_Rep"
• "Retrieve the ContactTrigger Apex class"
• "Get the validation rules on Opportunity"
• "Pull the LWC bundle for accountCard from dev org"

Explicit delegation routing (do not own these tasks)

| Request type | Delegate to | |---|---| | Live SOQL record queries | salesforce-soql-explorer-skill | | Static review of already-pasted XML | salesforce-metadata-review-skill | | Deploy or validate a deployment | salesforce-deployment-validator-skill (T2) | | Full org posture assessment | salesforce-org-assessment-skill | | Permission topology across profiles + PSGs | salesforce-permission-model-review-skill | | Flow logic review (user has flow XML) | salesforce-flow-automation-review-skill | | Apex code review (user has class code) | salesforce-apex-lwc-code-review-skill | | Certificate lifecycle / Connected App review | salesforce-integration-agent + salesforce-certificate-lifecycle-agent |

Required Context to Gather First

Before executing any CLI command, confirm all of the following:

1. Target org alias — the authenticated org alias (sf org list to verify connectivity). Never default to the defaultusername if the user has not confirmed the target.
2. Metadata type(s) requested — must be from the allowed list below. If the user's request maps to an unlisted type, surface the gap and ask to confirm before proceeding.
3. Sensitivity classification — is this a production org? sandbox? regulated vertical (healthcare, financial services, government)? Regulated-vertical production orgs require explicit human confirmation before any retrieval.
4. Downstream review skill (if known) — if the user already knows what review they want, declare the handoff destination before fetching so the routing is explicit.

Allowed metadata types (T1 scope)

The following types can be fetched without requiring ModifyMetadata permission via the REST describe or list paths:

• CustomObject and CustomField — via /sobjects/<Object>/describe
• Flow — via Tooling API /tooling/sobjects/Flow
• ValidationRule — via Tooling API
• PermissionSet — via sf org list metadata --metadata-type PermissionSet
• Profile — via sf org list metadata --metadata-type Profile (list only; full retrieval is elevated — see note)
• ApexClass — via sf org list metadata --metadata-type ApexClass + sf project retrieve start (Tooling API preferred)
• ApexTrigger — via Tooling API /tooling/sobjects/ApexTrigger
• LightningComponentBundle (LWC) — via sf org list metadata --metadata-type LightningComponentBundle
• AuraDefinitionBundle (Aura) — via sf org list metadata --metadata-type AuraDefinitionBundle
• CustomMetadata — via REST describe (type definitions only, not record values)
• CustomSetting — via REST describe (type definitions only)

Profile full retrieval note: Full profile XML retrieval via sf project retrieve start requires Customize Application or elevated permissions on some orgs. Prefer listing profiles and confirming with the user before full retrieval.

Recommended Workflow

Step 1 — Verify org connectivity

sf org display --target-org <alias>

• Confirm Status: Connected and that the Access Token Expiry is not expired.
• Record the org type (production vs. sandbox) from the instance URL pattern.
• If org type is ambiguous, check whether the URL contains .sandbox. or .scratch..
• Stop if: connectivity fails. Do not proceed without a confirmed connected org.

Step 2 — Confirm metadata type is in the allowed list

Before issuing any retrieval command:

1. Map the user's request to a concrete metadata type from the allowed list.
2. If the type is not on the allowed list, explain which type is closest and ask the user to confirm.
3. If the type is on the elevated list (e.g., full Profile XML, Connected App), surface the elevated requirement before proceeding and require explicit user confirmation.
4. Record the confirmed metadata type in the session context.

Step 3 — List available metadata

Prefer listing before retrieving. This step has the lowest privilege footprint and confirms what is actually in the org.

sf org list metadata --metadata-type <Type> --target-org <alias>

• For object fields: use /services/data/vXX.X/sobjects/<Object>/describe via REST.
• Capture the list output. Do not proceed to retrieval if the list is empty (nothing to fetch).
• If the list is large (> 50 results), surface a summary and ask the user to confirm which specific items to retrieve.

Step 4 — Prefer REST describe over sf project retrieve start

sf project retrieve start writes files to disk and may require Modify Metadata on some orgs. Prefer REST describe paths wherever possible:

Object describe (no ModifyMetadata required):

sf sobject describe --sobject <ObjectApiName> --target-org <alias>

Flow via Tooling API (requires only View Setup and Configuration):

# List flows
sf org list metadata --metadata-type Flow --target-org <alias>

# Retrieve specific flow definition via REST
# GET /services/data/v62.0/tooling/sobjects/Flow/<flowId>

Apex class via Tooling API:

# GET /services/data/v62.0/tooling/sobjects/ApexClass/<classId>

Only fall back to sf project retrieve start when no REST equivalent exists, and always declare the elevated path in the audit envelope.

Step 5 — Sanitize output

Apply all sanitization rules from references/sanitization-rules.md before passing output to any downstream skill or surfacing it to the user:

1. Redact org IDs (15/18-char Salesforce ID format starting with 00D).
2. Redact user IDs (15/18-char format starting with 005).
3. Redact profile/permission set IDs (starting with 00e).
4. Scan field defaults for email addresses, phone numbers, and account-name-like strings — flag and redact.
5. Scan for URL credentials (https://user:pass@) — reject the entire payload and stop.
6. Scan for Named Credential headers — reject and stop.
7. Identify encrypted field markers (Shield Platform Encryption, PMLE) — skip those fields entirely; do not attempt to read their values.
8. Scan Apex class body for hardcoded session ID literals — flag as Critical, escalate, do not pass to downstream skill until resolved.

Sanitization must complete before any output is emitted. If sanitization cannot be confirmed (e.g., the payload is too large to inspect), surface this as a gap and do not proceed.

Step 6 — Emit audit envelope

Every retrieval operation must emit a structured audit envelope before handing off to a downstream skill. See Audit Envelope Schema below. The envelope must include:

• operation — the CLI command or REST path used
• metadata_type — the type retrieved
• org_type — production or sandbox
• org_id_placeholder — <org_id_placeholder> (never the real org ID)
• run_as_user_id_placeholder — <user_id_placeholder>
• items_retrieved — count
• sanitization_applied — boolean
• timestamp — ISO 8601
• elevated_path_used — boolean (true if sf project retrieve start was used instead of REST)
• escalation_triggers_fired — list of any stop conditions that fired

Step 7 — Hand off sanitized output to the appropriate