Platform Architecture Analyze

Analyzing Architecture (Well-Architected Review)

Grade a Salesforce DX project against the Salesforce Well-Architected framework and produce an honest, evidence-backed report: a pillar-scored table for what's observable in code and metadata, plus a human checklist for the governance/process concerns a local repo can't reveal.

This skill is an orchestrator. It does not re-implement static analysis — it drives the analysis skills the plugin already ships and maps their output onto the Well-Architected pillars. It is read-only: it grades and recommends; it never edits, deploys, or deletes.

It also backs the architecture-review agent, which runs this exact workflow as a dedicated read-only reviewer. Invoke the agent for an end-to-end review; use this skill directly when you want the workflow inline in the current session.

Capability resolution

1. Skill-orchestrated review (this skill) — runs the observable checks by delegating to existing skills/MCP tools, scores each sub-pillar, and emits the manual checklist.
2. Direct CLI / grep — used only for the lightweight structural signals the rubric names (sharing keywords, legacy-tech file types, deploy strategy). Fine standalone, but skips the pillar scoring and the governance checklist this skill provides.
3. API — not applicable.

The rubric (read these first)

Before scoring, read the three reference files — they are the source of truth:

• references/well-architected-rubric.md — the full pillar → sub-pillar → criteria tree, each criterion tagged [observable] or [manual].
• references/observable-checks.md — each [observable] criterion mapped to its detection (skill / MCP tool / grep pattern) and the anti-pattern it flags.
• references/manual-review-checklist.md — the [manual] criteria as a copy-pasteable governance checklist.

Workflow

Step 1 — Scope the project

# Package directories + API version
cat sfdx-project.json

Establish:

• Package dirs (from packageDirectories[].path) — where the source lives.
• Inventory — count Apex classes, triggers, LWC bundles, Aura, Flows, objects:

  find <pkgdir> -name '*.cls' | wc -l
  find <pkgdir> -name '*.trigger' | wc -l
  find <pkgdir> -name '*.js-meta.xml' | wc -l   # LWC bundles

• Tooling signals — does the repo have tests (*Test.cls, __tests__/), CI (.github/workflows/), linting (.eslintrc*, .prettierrc*), a package.xml vs source/package strategy?
• Org connection — sf org display --json succeeds → org-dependent checks (OWD, permission sets) are in play; otherwise mark them manual.

Record the scope line for the report header.

Step 2 — Run the observable checks (delegate; don't re-scan)

Work through references/observable-checks.md. For the heavy lifting, delegate:

• Apex security + performance → dx-code-analyzer-run. It runs sf code-analyzer and classifies findings by severity. Map its rules onto the rubric:
  • ApexSOQLInjection, ApexCRUDViolation, ApexInsecureEndpoint, ApexBadCrypto → Secure
  • ApexSharingViolations → Secure (sharing) / Composable (separation)
  • OperationWithLimitsInLoop, OperationWithHighCostInLoop → Reliable / Automated
  • AvoidDebugStatements → Automated
• Inline SOQL parse + selectivity, compile-level diagnostics → platform-lsp-integrate (apex_diagnostics, lwc_diagnostics, check_soql_selectivity) when lsp_health is green → Reliable / Automated.
• OWD / sharing model / permission sets → platform-metadata-retrieve + sf org inspection, only if an org is connected → Secure.

For the lightweight structural signals, grep directly (patterns in references/observable-checks.md), e.g.:

# Secure — classes missing a sharing keyword
grep -rLE 'with(out)? sharing|inherited sharing' --include='*.cls' <pkgdir>

# Intentional — legacy tech still present
find <pkgdir> -name '*.workflow-meta.xml' -o -name '*.flowDefinition-meta.xml'
grep -rl '@future' --include='*.cls' <pkgdir>

# Composable — deploy strategy
ls manifest/package.xml 2>/dev/null            # package.xml-driven (anti-pattern past PoC)
grep -l '"path"' sfdx-project.json             # source/package strategy

# Composable — runtime config in custom settings vs CMT
find <pkgdir> -path '*objects*' -name '*.object-meta.xml' | xargs grep -l 'CustomSetting' 2>/dev/null

Collect every finding with file:line evidence. A check with no evidence is not a pass and not a fail — it's "not observable" and moves to the manual checklist.

Step 3 — Score each observable sub-pillar

Assign ✅ / ⚠️ / ❌ per sub-pillar using the thresholds in references/observable-checks.md:

• ✅ no anti-patterns found in the observable checks for that sub-pillar.
• ⚠️ low/moderate findings, or only some criteria observable.
• ❌ critical/high findings (e.g. SOQL injection, FLS bypass, SOQL-in-loop at scale).

Then roll the sub-pillar verdicts up to a pillar verdict (worst-of, with a note).

Step 4 — Emit the manual checklist

Copy the [manual] criteria from references/manual-review-checklist.md into the report as unchecked items, grouped by pillar. Label the section clearly: "not auto-graded — assess with your team." Do not guess at these; the point is to hand the developer a structured governance checklist, not to fake a score.