/platform-architecture-analyze

name: platform-architecture-analyze
description: "Use when the developer asks to \"review the architecture\", \"run a Well-Architected check\", \"audit this project\", \"is this project well-architected?\", or wants to assess security/governor-limit/risk as a holistic code-and-metadata health report. Grades observable criteria (sharing/FLS, bulkification, SOQL selectivity, packageability) with file:line evidence; emits a governance checklist for what it can't see. Read-only, never edits. DO NOT TRIGGER for single-tool Apex scans (dx-code-analyzer-run)."
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
metadata:
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
  relatedSkills:
    - "dx-code-analyzer-run"
    - "platform-lsp-integrate"
    - "platform-metadata-retrieve"
    - "platform-apex-generate"

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`](references/well-architected-rubric.md) — the full pillar → sub-pillar → criteria tree, each criterion tagged `[observable]` or `[manual]`.
• [`references/observable-checks.md`](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`](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).