Terminal
Terminal/Skill
Reviews a Salesforce DX project against the Well-Architected framework and reports sharing, bulkification and SOQL selectivity findings with file and line evidence, without editing anything.
By Salesforce
Works with
npx skills add forcedotcom/sf-skills --skill platform-architecture-analyzeGrade 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.
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.# Package directories + API version
cat sfdx-project.json
Establish:
packageDirectories[].path) — where the source lives.find <pkgdir> -name '*.cls' | wc -l
find <pkgdir> -name '*.trigger' | wc -l
find <pkgdir> -name '*.js-meta.xml' | wc -l # LWC bundles
*Test.cls, __tests__/), CI (.github/workflows/), linting (.eslintrc*, .prettierrc*), a package.xml vs source/package strategy?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.
Work through references/observable-checks.md. For the heavy lifting, delegate:
dx-code-analyzer-run. It runs sf code-analyzer and classifies findings by severity. Map its rules onto the rubric:
ApexSOQLInjection, ApexCRUDViolation, ApexInsecureEndpoint, ApexBadCrypto → SecureApexSharingViolations → Secure (sharing) / Composable (separation)OperationWithLimitsInLoop, OperationWithHighCostInLoop → Reliable / AutomatedAvoidDebugStatements → Automatedplatform-lsp-integrate (apex_diagnostics, lwc_diagnostics, check_soql_selectivity) when lsp_health is green → Reliable / Automated.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.
Assign ✅ / ⚠️ / ❌ per sub-pillar using the thresholds in references/observable-checks.md:
Then roll the sub-pillar verdicts up to a pillar verdict (worst-of, with a note).
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.
Produce one report using the format below. Lead with pillar verdicts, then observable findings (Trusted/Secure first — never bury security under style), then the manual checklist, then recommended next steps that name the skill which would apply each fix.
Well-Architected Review — <project name>
Scope: <pkg dirs>, <N classes / M triggers / K LWC>, tests: <y/n>, CI: <y/n>, org: <connected alias / none>
PILLAR VERDICTS
🛡️ Trusted <✅|⚠️|❌> (Secure …, Compliant …, Reliable …)
⚡ Easy <✅|⚠️|❌> (Intentional …, Automated …, Engaging …)
🔁 Adaptable <✅|⚠️|❌> (Resilient …, Composable …)
OBSERVABLE FINDINGS (graded from code + metadata)
Sub-pillar | Verdict | Finding | Evidence (file:line / tool)
MANUAL REVIEW (not auto-graded — assess with your team)
[ ] <item> …
RECOMMENDED NEXT STEPS
- <highest-signal fix> → via `<skill>`
Scope the project, run all observable checks (delegating Apex analysis to dx-code-analyzer-run), score all three pillars, emit the full manual checklist, and report. This is the default full review.
Narrow to the Secure and Reliable/Automated sub-pillars: run dx-code-analyzer-run with a security + performance selector, use platform-lsp-integrate check_soql_selectivity for selectivity, grep for missing sharing keywords. Score those sub-pillars; still emit the Secure/Compliant manual items (security matrix, encryption strategy). Skip the Adaptable deep-dive unless asked.
Full review, weighting Composable (packageability — CMT vs custom settings, loose coupling, LATEST aliasing, no package.xml-driven deploys) and Resilient (source-tracked, CI, no failed deploys). Lead the report with the packageability readiness verdict.
| Symptom | Cause | Recovery |
|---|---|---|
dx-code-analyzer-run reports the analyzer isn't installed | Code Analyzer v5 missing | Note it in the report; fall back to grep-based structural checks for Apex and mark PMD-only criteria "not observable". |
sf org display fails | No org connected | Mark OWD / permission-set / org-metadata criteria as manual; grade only file-based criteria. |
LSP tools return lsp_disabled / no_apex_workspace | LSP off or no workspace | Skip the LSP-grounded checks; rely on dx-code-analyzer-run + grep. Note the gap. |
No sfdx-project.json | Not an SFDX project | Stop — this skill reviews SFDX projects. Tell the developer. |
| Huge repo, scan is slow | Project-wide PMD + graph build | Scope dx-code-analyzer-run to the package dir; note that cross-file (sfge) findings may be partial. |
references/*.md files before scoring — the rubric is the source of truth.file:line (or tool-result) evidence. No evidence → manual checklist, not the scored table.[manual] governance criterion from inference — list it for human review.platform-apex-generate for Apex authoring / trigger refactoring); never edit, deploy, or delete.