bmad-dept-code-audit-agent

name: bmad-dept-code-audit-agent description: "Two-tier code auditor (part of BMAD DEPT Code Agent suite). Tier 1: deterministic TypeScript/Node.js static analysis (42+ categories, Excel report). Tier 2: LLM-driven deep semantic analysis for Commerce, AEMaaCS, EDS, Adobe App Builder (API Mesh, Commerce UI Extensibility, AEM UI Extensibility), and hybrid projects."

BMAD DEPT Code Agent — Audit Skill

Purpose

Two-tier code audit system for enterprise projects including AEM as a Cloud Service (AEMaaCS), Adobe Commerce (Magento), Edge Delivery Services (EDS), EDS+Commerce hybrid implementations, and Adobe App Builder (API Mesh, Commerce Admin UI Extensibility, AEM UI Extensibility, Experience Cloud Shell, Asset Compute).

Tier 1 — Deterministic Static Analysis (TypeScript/Node.js)

Fast, reproducible scan using scripts/run.ts. Produces an enterprise Excel report with:

• 42-category code audit (security, performance, deprecated APIs, etc.)
• Database dump analysis (schema, indexes, integrity)
• BRD impact analysis (new requirements, feature enhancements)
• Bug cascade & severity analysis (from Excel bug reports)
• Patch/upgrade breaking change analysis

Invocation: npx ts-node scripts/run.ts --path <PROJECT_ROOT>

Tier 2 — LLM Deep Semantic Analysis

AI-driven analysis using rule packs and detection strategy. Catches what scripts cannot:

• Architectural anti-patterns and design violations
• Cross-file data flow issues (unsanitized input propagation)
• Business logic correctness problems
• Contextual performance issues (N+1 across multiple endpoints)
• Configuration consistency (code expects config that doesn't exist)

Invocation: Activated via BMAD skill workflow (rule packs + detection strategy)

Activation

This skill activates when the user asks to:

• Audit project code
• Scan a project (code scan, quick scan)
• Review code quality for AEM/Commerce/EDS projects
• Analyze architecture compliance
• Check for anti-patterns or violations
• Generate a code audit report
• Audit an App Builder application or extension
• Review API Mesh configuration
• Audit Commerce Admin UI extension
• Audit AEM UI extension
• Run a static analysis scan
• Analyze with DB dump / database schema
• Run BRD impact analysis
• Analyze bug reports / bug cascade
• Analyze patch upgrade impact
• Export audit findings

Pre-flight: Auto-install Dependencies

Before running any audit, check if Node dependencies are installed. If not, install them automatically:

# Check and install (works on macOS, Linux, Windows WSL)
cd .claude/skills/bmad-dept-code-audit-agent/scripts && [ -d node_modules ] || npm install --silent

Do NOT ask the user for permission to install these — they are required for the scanner to function. Just install silently if missing.

Consent: Ask Audit Mode

Direct-intent triggers (skip the question, go straight to that mode):

• "scan my project" / "run scanner" / "quick scan" / "scan with DB" / "scan with BRD" / "scan with bugs" / "analyze patch" → Tier 1 (Scanner)
• "deep audit" / "LLM analysis" / "semantic audit" → Tier 2 (LLM)
• "full audit" / "complete audit" → Tier 1 + Tier 2

Ambiguous triggers (ask which mode):

• "audit my project" / "run code review" / "check my code" / "review code quality"

When the intent is ambiguous, ask using the interactive question picker (options UI). Use the vscode_askQuestions tool with these options:

question: "How would you like to audit this project?"
options:
  - label: "Scanner"
    description: "Fast deterministic scan. Produces Excel report in seconds. Minimal token usage (~1.5K)."
    recommended: true
  - label: "LLM Analysis"
    description: "AI-driven semantic analysis. Catches architectural flaws, cross-file issues. Uses ~15K tokens."
  - label: "Full Audit (Scanner + LLM)"
    description: "Run both for comprehensive coverage. Uses ~25K tokens."

Important: Always recommend "Scanner" as default. It produces the same structured report with near-zero token cost. Only suggest LLM when the user needs semantic/architectural insights that rules can't catch.

Proceed with the user's chosen mode.

Prompt → CLI Resolution (Tier 1)

When the user triggers a Tier 1 scan, build the CLI command by extracting parameters from their natural language prompt. The base command is:

npx ts-node {this_skill_path}/scripts/run.ts [flags]

Flag Resolution Rules

Compound Resolution

When a single prompt mentions multiple inputs, combine all matched flags into one command:

• "full audit named Client X with DB at /db.sql and BRD at /spec.docx" → --name "Client X" --db /db.sql --brd /spec.docx
• "scan Checkout module, include bugs from /bugs.xlsx, output JSON" → --module Checkout --bugs /bugs.xlsx --json
• "audit Payment namespace with database from /prod.sql" → --namespace Payment --db /prod.sql

Missing Required Info — Ask (don't guess)

Patch Analysis (Config-Based)

Patch analysis is configured via config.json, not CLI flags. When the user says "analyze patch upgrade from X to Y":

1. Read {this_skill_path}/scripts/engines/commerce/config.json
2. Set analysis.patch.enabled = true, analysis.patch.from_version = "X", analysis.patch.to_version = "Y"
3. Write config back
4. Run the CLI command normally (patch will be included in the scan automatically)

Example prompt: "analyze patch upgrade impact from 2.4.7-p7 to 2.4.7-p9" → Update config.json patch section, then run: npx ts-node {this_skill_path}/scripts/run.ts --path {cwd} --engine commerce

Engine Auto-Detection (do not ask unless ambiguous)

Examples of Full Resolution

User: "scan my project"

npx ts-node {this_skill_path}/scripts/run.ts --path {cwd} --engine commerce

User: "scan my project and name it Acme, include DB dump at ./db/prod.sql"

npx ts-node {this_skill_path}/scripts/run.ts --path {cwd} --engine commerce --name "Acme" --db ./db/prod.sql

User: "run full scanner with everything — DB at /tmp/dump.sql, BRD at /docs/brd.docx, bugs at /reports/bugs.xlsx"

npx ts-node {this_skill_path}/scripts/run.ts --path {cwd} --engine commerce --db /tmp/dump.sql --brd /docs/brd.docx --bugs /reports/bugs.xlsx

User: "just run BRD analysis from /spec/requirements.docx, skip the code scan"

npx ts-node {this_skill_path}/scripts/run.ts --path {cwd} --engine commerce --no-code-audit --brd /spec/requirements.docx

User: "what engines are available?"

npx ts-node {this_skill_path}/scripts/run.ts --list-engines

Workflow

Mode A: Script-Only (Tier 1)

Use when the user wants a quick deterministic report. Build the command using the Prompt → CLI Resolution rules above and execute it.

Output: Excel report in engine's output/ directory.

Mode B: Deep Analysis (Tier 2)

Use when the user wants semantic/architectural analysis:

Mode C: Full Audit (Tier 1 + Tier 2)

Recommended for comprehensive audits:

1. Run Tier 1 → produces Excel with deterministic findings
2. Load resources/shared/scanner-llm-crossref.md to determine LLM action per category
3. For SKIP categories → keep scanner findings as-is (no LLM re-analysis)
4. For DEEPEN categories → feed high-severity scanner findings to LLM with rule context for root-cause and cross-file enrichment
5. For VERIFY categories → LLM confirms true positives, dismisses false positives
6. For EXPAND categories → LLM runs full semantic analysis (business logic, cross-module flow) independent of scanner
7. Deduplicate: same file+line from both tiers → merge into single finding using LLM rule ID
8. Combined output: Excel report + AI-driven narrative report

Step 1: Detect Project Type

Scan the workspace to determine which Adobe platform(s) are in use:

Step 2: Load Applicable Rule Pack(s)

Based on detected platform, load rules from resources/rule-packs/<platform>/.

For hybrid projects (e.g., EDS+Commerce, or App Builder with multiple extension types), load multiple rule packs and apply intersection logic.

Step 3: Deep Analysis

Use the multi-pass analysis strategy defined in resources/shared/detection-strategy.md:

Pass 1 — Structural Scan

• Map project topology: packages, modules, configs, deployment artifacts
• Identify dependency graph and module boundaries
• Flag structural violations (misplaced files, missing manifests, circular deps)

Pass 2 — Pattern Matching

For each file in scope, apply platform-specific rules from the loaded rule pack:

• Match bad code examples against actual source (regex + semantic)
• Compare against good code examples to confirm it's truly violating
• Check false positive conditions to avoid noise
• Note related rules that should also be checked in the same context

Pass 3 — Cross-File & Contextual Analysis

• Trace data flow across files (e.g., unsanitized input flowing to output)
• Check configuration consistency (code expects config that doesn't exist)
• Validate inter-module contracts (declared dependencies vs actual usage)
• Assess cumulative patterns (e.g., N+1 query across multiple endpoints)

Pass 4 — Scoring & Correlation

1. Score severity using resources/shared/severity-model.md
2. Calculate confidence using resources/shared/confidence-scoring.md
3. Assess impact using resources/shared/impact-analysis.md
4. Correlate related findings (group root causes, deduplicate symptoms)
5. Identify systemic patterns (same mistake repeated = architectural issue)

Step 4: Generate Report

Use templates from templates/ to produce the final audit report in the requested format (markdown or JSON).

Step 5: Actionable Recommendations

Beyond findings, generate:

• Prioritized remediation roadmap (fix order considering dependencies between findings)
• Quick wins list (high-impact, low-effort fixes)
• Architecture improvement suggestions (when systemic patterns detected)
• Upgrade path warnings (deprecated APIs with timeline)

Configuration

The skill reads configuration from environment variables when available:

Tools Required

• claude-code — For code analysis and pattern matching

Output

The skill produces a structured audit report containing:

• Executive summary with risk score
• Findings grouped by severity (critical, high, medium, low)
• Each finding includes: location, rule violated, explanation, remediation suggestion, confidence score
• Platform-specific recommendations
• Summary statistics

Post-Audit Actions

After an audit has been run (Excel or markdown report exists), the user may ask follow-up questions. Handle these by reading the generated report and responding:

Report location: Look for the latest .xlsx or .md file in {this_skill_path}/scripts/engines/{engine}/output/