AGENTS.md

Tool-neutral entry point for AI coding assistants working in this repository. The canonical code conventions live in docs/Code Conventions - Guide.md; they apply to every contributor — human or automated — and supersede generic language/style heuristics that an assistant might apply by default.

Output grading

Generated code must pass the two rulesets that ship in this repo under scanner/:

• PMD (Apex): scanner/kerndx-pmd-ruleset.xml — KernDX Apex conventions (no inline SOQL/DML, no System.debug, no fflib_ patterns, ApexDoc required, explicit sharing, coverage-theatre detection, etc.).
• ESLint (LWC + JS): scanner/eslint-plugin-kerndx/ — KernDX LWC conventions (no direct LightningElement, ComponentBuilder extension, etc.).

Run them locally before opening a PR:

# PMD via Salesforce Code Analyzer (uses scanner/code-analyzer.yml config)
sf code-analyzer run --config-file code-analyzer.yml --target force-app/

# ESLint via the bundled plugin (extend it from your repo's flat config)
npx eslint --config eslint.config.mjs <files>

If either fails, fix the violation in source — do not suppress the rule without justification documented in code review.

Read first

Document	Purpose
docs/Code Conventions - Guide.md	Critical Apex/LWC/JS rules, naming, formatting, ApexDoc requirements.
docs/Installation.md	How adopters install or repackage KernDX. Path 1 (managed package) vs Path 2 (namespace repackage).
docs/README.md	Learning paths into Fast Starts + Strategic Guides + the auto-generated Apex reference.
scanner/README.md	How to wire the PMD ruleset + ESLint plugin into a subscriber's CI.

Operating rules for AI assistants

• Match repository style. Allman braces in Apex + JavaScript, tabs for indentation, 180-char Apex line cap, single-quoted JS strings, K&R-style if(condition) (no space before paren).
• No inline SOQL / DML. Use SEL_* selectors and DML_Builder — see docs/Selectors - Guide.md and docs/DML - Guide.md.
• No System.debug. Use LOG_Builder — see docs/Logging - Guide.md.
• No LightningElement directly. Use ComponentBuilder — see docs/LWC - Guide.md.
• Declare sharing. Every Apex class declares one of with sharing / inherited sharing / without sharing. Default to with sharing; use inherited sharing for selectors + stateless utilities.
• 100% test coverage on Apex + LWC. Tests must assert behaviour — empty try { ... } catch { } blocks and unconditional Assert.isNotNull(record) after TST_Builder.build() are coverage theatre and rejected by the scanner.
• No hardcoded namespaces. Use SObjectClass.class.getName() in Apex, @salesforce/schema/* and standard__objectPage in LWC. Never embed kern. as a literal in production code.
• Use Assert.* in tests, not System.Assert.*. Prefer Foobar__c over standard objects unless the test specifically validates a standard-object integration.

Subscriber context

KernDX ships as a managed package under the kern namespace. Subscribers may have their own namespace and prefix conventions (e.g., ACME_SEL_*). When generating code for a subscriber repo, apply that repo's stated prefix conventions and refer to KernDX classes as kern.ClassName from subscriber Apex.

Building subscriber code that consumes KernDX? This file (AGENTS.md) governs work inside this repo. For AI-generation context to drop into your own subscriber repository's AI assistant, use docs/AI Agent Instructions.md — it's the comprehensive KernDX framework reference (namespace rules, class patterns, common idioms) designed for that purpose.

Configuration

The release-testing runners read two environment variables:

• SF_SUBSCRIBER_ORG_ALIAS — your subscriber test scratch-org alias.
• KERN_DEV_ORG — your dev scratch-org alias.

Both are required (no defaults). Export them before invoking npm run release:phase2, npm run release:all, or any script under scripts/ that resolves an org alias.

When this document doesn't apply

• Pure documentation edits.
• Build-script changes that touch only scripts/ and do not alter Apex or LWC contracts.
• Configuration / metadata edits in force-app/main/default/customMetadata/.

For everything else: docs/Code Conventions - Guide.md is the rule set.