/platform-environment-validate

name: platform-environment-validate
description: "Validate and configure the local Salesforce development environment. Runs a prerequisite scan across required tools with per-tool status and offers to install or update missing items. Use when the user asks to 'check my setup', 'validate tools', 'verify prerequisites', 'am I set up correctly', or reports a tool is missing or not working. DO NOT TRIGGER for org auth (/salesforce-development:login), deployment problems (platform-metadata-deploy), or status checks (/salesforce-development:status)."
metadata:
  domains: ["Platform"]
  relatedSkills: ["platform-metadata-deploy"]
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
    - tool: ["npm"]
      semver: "*"
    - tool: ["node"]
      semver: "*"
    - tool: ["git"]
      semver: "*"
allowed-tools:
  - Bash
  - Read

Validating: Salesforce Development Environment

Validate all required prerequisites and surface a clear, actionable status report. This skill is on-demand — it does not run automatically on session start. Run it explicitly to check or repair your local setup.

Phase 1: Prerequisite Scan

Run the tool check:

${CLAUDE_PLUGIN_ROOT}/scripts/sf-context check-tools

The output is a JSON object with a `tools` array (plus a `diagnostic` block on any critical failure).

**The banner is painted for you — do not reproduce it.** When `check-tools` runs, the plugin paints the framed **"Ready to build on Salesforce?"** banner deterministically on the visible channel — one status row per tool, the footer verdict, and the wayfinding footer — exactly like the SessionStart banner. It is a **Tier-1 surface**: read the JSON for your own understanding, but do **NOT** reproduce, redraw, or re-render the banner. Add only a short read of what the result means for the user, then go to **Phase 2**.

The painted banner looks like this (illustrative — the version/message text in each row comes straight from the JSON: `version` for READY, `message` + fix hint for WARN/CRITICAL, the note for INFO; the values below show the style, not fixed strings):

──────────────────────────────────────────────────────────────
 Ready to build on Salesforce?   checking your toolchain…
──────────────────────────────────────────────────────────────
 READY Salesforce CLI             v2.144.6
 READY Code Analyzer              v5.14.0 · JIT, auto-installs on first use
 READY Node.js                    v22.11.0 LTS
 READY NPM                        v10.9.0
 READY Git                        v2.50.1
 READY Salesforce MCP (config)    .mcp.json + proxy present
 READY Salesforce MCP (metadata-experts) Server active and reachable
 READY Salesforce MCP (metadata-grounding) Optional; endpoint reachable
 INFO  Salesforce MCP (headless-360) Optional; local opt-in unknown. Recommended for live Setup settings…
 INFO  Salesforce MCP (process)   confirm with /mcp or /doctor
 READY Source Tracking            enabled
──────────────────────────────────────────────────────────────
 PASS toolchain ready                                (skill: platform-environment-validate)

Each row's status label carries the state — CRITICAL `critical` (missing or below minimum — Salesforce development cannot proceed), WARN `warn` (installed but outdated, non-LTS, or misconfigured), READY `ok`, INFO `info` (a contextual note that can't be auto-verified, e.g. MCP process health) — and the framed footer gives the verdict plus the single most relevant `Next:` step. The JSON `status` field is the source of truth per tool; use these states when you write your short read.

**If the banner did not paint** (an older Claude Code build, or a paint fallback), do **not** hand-render it from the JSON. Print it with the deterministic renderer instead:

${CLAUDE_PLUGIN_ROOT}/scripts/sf-context readiness-banner

This reads the same scan result `check-tools` just recorded and prints the identical framed banner — rows in fixed order, the footer verdict, and the "you don't memorize commands here" wayfinding footer with its `Next:` step — so ordering, padding, counts, and next-step selection are decided once in the script, never re-derived by hand. The `check-tools` JSON stays the authoritative, machine-readable result.

**Deterministic results — do NOT override a failure:** the JSON report is the authoritative, machine-readable result. If a tool reports CRITICAL/WARN, report it as-is. Do **not** re-run the tool a different way (PowerShell, a raw shell probe, a different command) and then present the result as READY — a fallback that happens to find the tool does **not** mean the deterministic check passed. A failed check must stay failed until that **same** `check-tools` check passes. When the report includes a `diagnostic` block (attached on any critical failure), surface it: it carries the platform, active shell, working directory, plugin root, and the **resolved executable paths** — the fastest way to see why a tool didn't resolve (e.g. a Windows `sf.cmd` not on `PATH`). The diagnostic is secret-free by design; never add tokens or org auth to it.

**MCP reports configuration, required-server probes, and process visibility separately:** `Salesforce MCP (config)` (are `.mcp.json` and the required proxy bundle present?), the individually probed required servers, and `Salesforce MCP (process)` (is the MCP process actually healthy?). Headless 360 has a separate optional row: a missing launcher warns; otherwise it reports local opt-in and endpoint evidence. Known-enabled opt-in allows an on-demand probe outside hook deadlines. Disabled/unknown opt-in never probes. Cached health is labeled **Last observed** and must match the selected org. Reachable endpoints do not prove host tool exposure. Claude commands may not receive the plugin option; report unknown and point to `/plugin` in that case. Codex reads its saved local preference. Recommend H360 for better answers about live Setup settings and org-specific caps. If a probe reports