/platform-apex-generate

name: platform-apex-generate
description: "Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex."
metadata:
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
  relatedSkills:
    - "platform-apex-test-generate"
  version: "1.0"
  minApiVersion: "66.0"

Generating Apex

Use this skill for production-grade Apex: new classes, selectors, services, async jobs, invocable methods, and triggers; and for evidence-based review of existing `.cls` OR `.trigger`.

Required Inputs

Gather or infer before authoring:

• Class type (service, selector, domain, batch, queueable, schedulable, invocable, trigger, trigger action, DTO, utility, interface, abstract, exception, REST resource)
• Target object(s) and business goal
• Class name (derive using the naming table below)
• Net-new vs refactor/fix; any org/API constraints
• Deployment targets (default to runSpecifiedTests and use generated tests where applicable)

Defaults unless specified:

• Sharing: `with sharing` (see sharing rules per type below)
• Access: `public` (use `global` only when required by managed packages or `@RestResource`)
• API version: `66.0` (minimum version)
• ApexDoc comments: yes

If the user provides a clear, complete request, generate immediately without unnecessary back-and-forth.

---

Workflow

All steps are sequential. Do not skip, merge, or reorder. If blocked, stop and ask for missing context. If not applicable, mark `N/A` with a one-line justification in the report.

Phase 1 — Author

1. **Discover project conventions**

• Service-Selector-Domain layering, logging utilities
• Existing classes/triggers and current trigger framework or handler pattern
• Whether Trigger Actions Framework (TAF) is already in use

2. **Choose the smallest correct pattern** (see Type-Specific Guidance below)

3. **Review templates and assets**

• Read the matching template from `assets/` before authoring (see Type-Specific Guidance for the file mapping)
• When a `references/` example exists for the type, read it as a concrete style guide
• For any test class work, always read and use `platform-apex-test-generate` skill

4. **Author with guardrails** -- apply every rule in the Rules section below

• Generate `{ClassName}.cls` with ApexDoc
• Generate `{ClassName}.cls-meta.xml`

5. **Generate test classes** -- Load the skill `platform-apex-test-generate` to create `{ClassName}Test.cls` and `{ClassName}Test.cls-meta.xml`. Apex tests are always required to be generated to deploy. No test file creation or edits can occur without loading the `platform-apex-test-generate` skill to generate tests.

Phase 2 — Validate (required before reporting)

Writing files is the midpoint, not the finish line. Steps 6 and 7 each require a tool invocation and produce output that must appear in the Step 8 report. Do not summarize or present the report until both steps have run and their output is captured.

6. **Run code analyzer**

• Invoke MCP `run_code_analyzer` on all generated/updated `.cls` files.
• Remediate all `sev0`, `sev1`, and `sev2` violations; re-run until clean.
• Capture the final tool output verbatim for the report.
• Fallback: `sf code-analyzer run --target <target>`. If both are unavailable, record `run_code_analyzer=unavailable: <error>` in the report.

7. **Execute Apex tests**

• Run org tests including `{ClassName}Test` via `sf apex run test` or MCP.
• Delegate all test generation/fixes/coverage work to `platform-apex-test-generate`; iterate until the tests pass.
• Capture pass/fail counts and coverage percentage for the report.
• If unavailable, record `test_execution=unavailable: <error>` in the report.

Phase 3 — Report

8. **Report** -- use the output format at the bottom of this file.

• The `Analyzer` line must contain the actual Step 6 tool output (or `run_code_analyzer=unavailable: <reason>` after attempting invocation).
• The `Testing` line must contain the actual Step 7 results (or `test_execution=unavailable: <reason>` after attempting invocation).
• A report missing either line is incomplete. Always attempt the tool invocation before recording unavailable.

---

Rules

Hard-Stop Constraints (Must Enforce)

If any constraint would be violated in generated code, **stop and explain the problem** before proceeding:

| Constraint | Rationale | |---|---| | Place all SOQL outside loops | Avoid query governor limits (100 queries) | | Place all DML outside loops | Avoid DML governor limits (150 statements) | | Declare a sharing keyword on every class | Prevent unintended `without sharing` defaults and data exposure | | Use Custom Metadata/Labels/describe calls instead of hardcoded IDs | Ensure portability across orgs | | Always handle exceptions (log, rethrow, or recover) | Prevent silent failures | | Use bind variables for all dynamic SOQL with user input | Prevent SOQL injection | | Use Apex-native collections (`List`, `Map`, `Set`) rather than Java types | Prevent compile errors | | Verify methods exist in Apex before use | Prevent reliance on non-existent APIs | | Avoid `System.debug()` in main code paths | Debug statements evaluate even when loggign is not active and consume CPU. Use a logging framework if required on main code paths | | Never use `@future` methods | Use Queueable with `System.Finalizer`; `@future` cannot chain, cannot be called from Batch, and cannot accept non-primitive types |

Bulkification & Governor Limits

• All public APIs accept a