Merge branch 'main' into main

README.md

@@ -1,16 +1,15 @@
 # Agentforce Vibes Library
 
-AI skills and rules library for Agentforce Vibes development of Salesforce metadata.
+AI skills library for Agentforce Vibes development of Salesforce metadata.
 
 ## 📚 About
 
-This repository curates Salesforce-focused skills and system rules from the wider developer community to accelerate Agentforce Vibes agentic workflows. 
+This repository curates Salesforce-focused skills from the wider developer community to accelerate Agentforce Vibes agentic workflows. 
 
 ## 🗂️ Structure
 
 ```
 afv-library/
-├── rules/                # Single-file guardrails and standards
 ├── skills/               # Directory-based executable workflows
 │   ├── generating-apex/
 │   ├── generating-custom-object/
@@ -19,14 +18,14 @@ afv-library/
 ├── samples/              # Synced sample apps (e.g. from npm)
 │   └── ui-bundle-template-app-react-sample-b2e/
 │   └── ...
-├── scripts/              
+├── scripts/
 │   └── ...
 └── README.md
 ```
 
 ## Manual Usage
 
-Browse the repository and copy/paste any rule or skill directly into Agentforce Vibes or your preferred AI tool.
+Browse the repository and copy/paste any skill directly into Agentforce Vibes or your preferred AI tool.
 
 ## Samples
 
@@ -42,7 +41,7 @@ The GitHub Action runs these same commands and opens a PR only when the npm pack
 
 ## 🛠️ Agent Skills
 
-Agent Skills extend rules by bundling executable workflows, scripts, and reference materials into self-contained directories. Skills follow the open [Agent Skills specification](https://agentskills.io/) and are portable across many agent tools (Cursor, Claude Code, VS Code extensions, etc.).
+Agent Skills are modular capabilities that bundle executable workflows, scripts, and reference materials into self-contained directories. Skills follow the open [Agent Skills specification](https://agentskills.io/) and are portable across many agent tools (Agentforce Vibes, Cursor, Claude Code, etc).
 
 ### Directory Structure
 

rules/a4v-expert-global-rule.md

@@ -1,88 +0,0 @@
-# Rule: Salesforce Metadata Generation
-
-## Objective
-Enforce: **skill load -> API context -> file generation** for all Salesforce metadata.
-
-## Constraints
-
-1. **Never write** without a loaded metadata type skill for that type.
-2. **One type at a time** - complete the full cycle for the current type before moving to the next type.
-3. **Always attempt `salesforce-api-context` MCP** for each type before writing; if it is unavailable after a real attempt, proceed with the loaded skill only.
-4. **Child types need their own API context response** - if adding child metadata inside a parent metadata file, load the child metadata skill and use `salesforce-api-context` MCP for each child type separately; do not rely on the parent's schema or API context response for child metadata creation. The same fallback in constraint 3 applies.
-5. **Max one clarifying question** before starting.
-6. **Do not call `execute_metadata_action` unless a skill instructs you to do so.**
-
-## Skill Selection
-
-- Search available skills and load the best-matching app-level skill first when the request asks for a Lightning app, end-to-end solution, or a business app spanning multiple metadata types.
-- Search available skills and load the best-matching per-type metadata skill first when the request targets individual metadata components.
-
-## Initial Gate
-
-Never create files or generate metadata before completing skill selection.
-
-1. Determine whether the request is app-level or metadata-type-level.
-2. Search available skills for the request and identify the best-matching candidate skill.
-3. If the request is app-level, load the best-matching app-level skill by reading its contents and use it to identify metadata types and dependency order.
-4. If the request is metadata-type-level, identify the target metadata type and the best-matching per-type metadata skill for that type. Do not treat skill selection as the per-type skill-load step.
-5. Confirm skill selection with:
-   `intent=<app|type> selected_skill=<exact-skill-name|none> skill_selection=complete|pending`
-6. Set `skill_selection=complete` only after the exact selected skill name has been identified and recorded.
-7. Print this exact skill-selection status line in the chat before proceeding.
-
-Do not continue until `skill_selection=complete` and `selected_skill=<exact-skill-name|none>` are recorded.
-
-## Per-Type Loop (a-e)
-
-For each metadata type in scope, whether identified by an app-level skill or requested directly, execute steps a through e below one metadata type at a time. Do not create or modify files for the current metadata type, and do not move to the next metadata type, until steps a through e are complete.
-
-**a. Load Skill**
-- Search available skills for the best-matching skill for the current metadata type and load it by reading its SKILL.md.
-- Record `selected_skill=<exact-skill-name|none>` for the current metadata type before proceeding.
-- Load once per type, not per record.
-- If no skill exists after a real search, stop and ask for guidance instead of writing without a skill.
-
-**b. Use `salesforce-api-context` MCP**
-- Use one or more of these tools as required:
-  - `get_metadata_type_sections`
-  - `get_metadata_type_context`
-  - `get_metadata_type_fields`
-  - `get_metadata_type_fields_properties`
-  - `search_metadata_types`
-- Attempt API context for every type before writing.
-- Record which tools were called for the current metadata type before proceeding.
-- If API context is unavailable after a real attempt, record that state and continue with the loaded skill only.
-- Treat templates, generators, pipelines, and CLI bootstraps as implementation aids, not as replacements for this gate.
-
-**c. Pre-Write Gate**
-- Before EVERY write: confirm `selected_skill=<exact-skill-name>` is recorded and that skill is loaded for this type.
-- Before EVERY write: confirm `mcp_tools=<tool-list>` is recorded for this type, or confirm `mcp=unavailable` after a real attempt.
-- If `selected_skill=none` or the skill is missing -> stop.
-- If `mcp_tools=none` and `mcp` is not `unavailable` -> stop and call MCP now.
-
-**d. Generate Files**
-- Use skill constraints + API context when available.
-- Use skill constraints only when API context was unavailable after a real attempt.
-- Generate all records for this type now.
-
-**e. Checkpoint**
-- Record:
-  `type=<metadata-type> selected_skill=<exact-skill-name|none> skill=complete|pending mcp=complete|pending|unavailable mcp_tools=<tool-list|none>`
-- Skill loaded? API context called or unavailable after a real attempt? All files written?
-- Only proceed to the next type when all are true.
-
-## Anti-Patterns
-
-| Don't | Why | Do |
-|-------|-----|-----|
-| Never write without loading the metadata skill | Missing platform constraints | Search for and load the skill before any write |
-| Never mark `skill_selection=complete` without `selected_skill=<exact-skill-name|none>` | Fake gate completion | Record the exact selected skill before continuing |
-| Never treat skill selection as skill loading | Fake gate completion | Perform the actual per-type skill load in step a |
-| Never skip the Initial Gate | Sequence breach | Complete skill selection before any generation |
-| Never reload a skill per record | Wastes tokens | Load once per type |
-| Never skip the API context attempt for any type | No schema for those types | Attempt API context for EVERY type |
-| Never write using API context alone without a loaded skill | Missing platform constraints | Stop and ask for guidance when no skill exists |
-| Never write without recorded `mcp_tools` or `mcp=unavailable` | No evidence of MCP gate completion | Record MCP tool usage before any write |
-| Never ask more than 1 clarifying question | Token waste | Max 1 question |
-| Never skip any gate in the loop (skill load, API context, pre-write, checkpoint) | Wrong artifacts | Follow all mandatory gates in the loop (a-e) |
-| Never write with a missing checkpoint | Aware violation | Stop and complete missing step |

skills/generating-apex-test/assets/test-class-template.cls

@@ -1,7 +1,7 @@
 /**
- * @description Test class for {ClassUnderTest}.
- *              Tests bulk operations (251+ records), positive/negative paths,
- *              and exception handling.
+ * Test class for {ClassUnderTest}.
+ * Tests bulk operations (251+ records), positive/negative paths,
+ * and exception handling.
  */
 @isTest
 private class {ClassUnderTest}Test {

skills/generating-apex-test/references/assertion-patterns.md

@@ -26,7 +26,7 @@ Assert.isTrue(accounts.size() > 0); // vague — use areEqual with exact count
 ### Good: Descriptive message, tests specific behavior
 
 ```apex
-Assert.areEqual(true, result, 'Service should return true for valid input');
+Assert.isTrue(result, 'Service should return true for valid input');
 Assert.areEqual(200, accounts.size(), 'All 200 accounts should be processed');
 ```
 

skills/generating-apex-test/references/async-testing.md

@@ -140,7 +140,7 @@ static void shouldExecuteFutureMethod() {
     Test.stopTest();
 
     Account updated = [SELECT Id, Processed__c FROM Account WHERE Id = :acc.Id];
-    Assert.areEqual(true, updated.Processed__c, 'Future should process record');
+    Assert.isTrue(updated.Processed__c, 'Future should process record');
 }
 ```
 

skills/generating-apex/SKILL.md

@@ -6,7 +6,7 @@ description: Primary Apex authoring skill for class generation, refactoring, and
 # 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`.
+invocable methods, and triggers; and for evidence-based review of existing `.cls` OR `.trigger`.
 
 ## Required Inputs
 
@@ -16,11 +16,11 @@ Gather or infer before authoring:
 - 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
+- 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 `@InvocableMethod`)
+- Access: `public` (use `global` only when required by managed packages or `@RestResource`)
 - API version: `66.0` (minimum version)
 - ApexDoc comments: yes
 
@@ -48,9 +48,9 @@ All steps are sequential. Do not skip, merge, or reorder. If blocked, stop and a
 
 4. **Author with guardrails** -- apply every rule in the Rules section below
    - Generate `{ClassName}.cls` with ApexDoc
-   - Generate `{ClassName}.cls-meta.xml`
+   - Generate `{ClassName}.cls-meta.xml`   
 
-5. **Generate test classes** -- delegate to `generating-apex-test` to create `{ClassName}Test.cls` and `{ClassName}Test.cls-meta.xml`. Do not write test code in this skill. If the test skill is unavailable, record `test_skill=unavailable: <reason>` in Step 8.
+5. **Generate test classes** -- Load the skill `generating-apex-test` 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  `generating-apex-test` skill to generate tests.
 
 ### Phase 2 — Validate (required before reporting)
 
@@ -64,7 +64,7 @@ Writing files is the midpoint, not the finish line. Steps 6 and 7 each require a
 
 7. **Execute Apex tests**
    - Run org tests including `{ClassName}Test` via `sf apex run test` or MCP.
-   - Delegate all test fixes/coverage work to `generating-apex-test`; iterate until green.
+   - Delegate all test generation/fixes/coverage work to `generating-apex-test`; 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.
 
@@ -93,7 +93,7 @@ If any constraint would be violated in generated code, **stop and explain the pr
 | 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 |
-| Prefer structured logging over `System.debug()` | Debug string concatenation consumes CPU even when not observed |
+| 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
@@ -142,6 +142,8 @@ Before finalizing, verify: CRUD/FLS enforced (SOQL + DML) · explicit sharing ke
 - Preserve exception cause chains: `new CustomException('message', cause)` (do not replace stack trace with concatenated messages)
 - Provide a custom exception class per service domain when meaningful
 - In `@AuraEnabled` methods, catch exceptions and rethrow as `AuraHandledException`
+- Fallback option: when no meaningful domain exception exists, catch generic `Exception` and either rethrow it or wrap it in a minimal custom exception that preserves the original cause.
+
 
 ### Null Safety
 
@@ -196,8 +198,9 @@ Class-level format:
 
 ```apex
 /**
- * @author Generated by Apex Skill
+ * Provides services for geolocation and address conversion.
  */
+public with sharing class GeolocationService { }
 ```
 
 Method-level format:
@@ -357,6 +360,10 @@ Deliverables per class:
 - `{ClassName}Test.cls` (generated via `generating-apex-test` skill)
 - `{ClassName}Test.cls-meta.xml` (generated via `generating-apex-test` skill)
 
+Deliverables per trigger:
+- `{TriggerName}.trigger`
+- `{TriggerName}.trigger-meta.xml` (default API version `66.0` or higher unless specified)
+
 Meta XML template:
 
 ```xml
@@ -396,4 +403,4 @@ Deploy: <dry-run or next step>
 
 ## Troubleshooting Boundary
 
-This skill handles production `.cls`/`.trigger` issues only: compile/parse failures, deployment dependency errors, runtime governor-limit failures. For test execution, assertions, coverage, or `sf apex run test` failures, delegate to `generating-apex-test`.
+This skill handles production `.cls`/`.trigger`/`.apex` issues only: compile/parse failures, deployment dependency errors, runtime governor-limit failures. For test execution, assertions, coverage, or `sf apex run test` failures, delegate to `generating-apex-test`.

skills/generating-apex/assets/abstract.cls

@@ -6,7 +6,6 @@
 >>>>>>> Stashed changes
  *              Provides common behavior and defines extension points for subclasses.
  *              Subclasses must implement the abstract methods to provide specific behavior.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Extending this abstract class:

skills/generating-apex/assets/batch.cls

@@ -2,7 +2,6 @@
  * Batch Apex class for {describe the batch operation}.
  *              Processes {SObject} records in configurable batch sizes.
  *              Implements Database.Stateful to track cumulative results across chunks.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Execute with default batch size

skills/generating-apex/assets/domain.cls

@@ -2,7 +2,6 @@
  * Domain class for {SObject}.
  *              Encapsulates field-level defaults, derivations, and validations.
  *              Operates only on in-memory SObject data — no SOQL or DML.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class {SObject}Domain {
 

skills/generating-apex/assets/dto.cls

@@ -2,7 +2,6 @@
  * Data Transfer Object for {describe the data this DTO represents}.
  *              Used to pass structured data between layers without exposing SObjects.
  *              Serialization-friendly for use with JSON.serialize/deserialize and API responses.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Create from constructor

skills/generating-apex/assets/exception.cls

@@ -2,7 +2,6 @@
  * Custom exception for {describe when this exception is thrown}.
  *              Use this exception to signal domain-specific errors that callers
  *              can catch and handle distinctly from system exceptions.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * throw new {ClassName}('Account merge failed: duplicate detected.');

skills/generating-apex/assets/interface.cls

@@ -1,7 +1,6 @@
 /**
  * Interface for {describe the capability or contract this interface defines}.
  *              Implement this interface to provide {describe what implementations do}.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * public class EmailNotificationService implements {InterfaceName} {

skills/generating-apex/assets/invocable.cls

@@ -2,7 +2,6 @@
  * Invocable Apex action for {describe the action}.
  * Callable from Flows, Process Builder, and Agentforce.
  * Accepts bulkified List<Request>, returns List<Response>.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class {ClassName} {
 

skills/generating-apex/assets/queueable.cls

@@ -2,7 +2,6 @@
  * Queueable Apex class for {describe the async operation}.
  *              Accepts data through the constructor for stateful processing.
  *              Optionally implements Database.AllowsCallouts for external integrations.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Enqueue the job

skills/generating-apex/assets/schedulable.cls

@@ -2,7 +2,6 @@
  * Schedulable Apex class for {describe the scheduled operation}.
  *              Delegates heavy processing to a Batch or Queueable job.
  *              Keep execute() lightweight — it should only launch other jobs.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Schedule to run daily at 2 AM

skills/generating-apex/assets/selector.cls

@@ -2,7 +2,6 @@
  * Selector class for {SObject} queries.
  *              Encapsulates all SOQL for {SObject} records.
  *              All methods return bulkified results (Lists or Maps).
- * @author Generated by Apex Class Writer Skill
  */
 public inherited sharing class {SObject}Selector {
 

skills/generating-apex/assets/service.cls

@@ -2,7 +2,6 @@
  * Service class for {SObject} business logic.
  *              Follows separation of concerns: delegates queries to {SObject}Selector
  *              and SObject manipulation to {SObject}Domain where applicable.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class {SObject}Service {
 

skills/generating-apex/assets/trigger.cls

@@ -1,5 +1,5 @@
 /**
- * @author Generated by Apex Class Writer Skill
+ * {SObject} Trigger
  */
 trigger {SObject}Trigger on {SObject} (
     before insert,

skills/generating-apex/assets/utility.cls

@@ -2,7 +2,6 @@
  * Utility class for {describe the category of utilities: String, Date, Collection, etc.}.
  *              All methods are static and side-effect-free (no SOQL, no DML).
  *              Private constructor prevents instantiation.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class {ClassName} {
 

skills/generating-apex/references/AccountDeduplicationBatch.cls

@@ -3,7 +3,6 @@
  *              Compares Accounts by Name and BillingPostalCode to find potential duplicates.
  *              Flags duplicates by setting the Is_Potential_Duplicate__c checkbox.
  *              Implements Database.Stateful to track results across batch chunks.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Run with default batch size (200)

skills/generating-apex/references/AccountSelector.cls

@@ -2,7 +2,6 @@
  * Selector class for Account queries.
  *              Encapsulates all SOQL for Account records.
  *              All methods return bulkified results (Lists or Maps).
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class AccountSelector {
 

skills/generating-apex/references/AccountService.cls

@@ -2,7 +2,6 @@
  * Service class for Account business logic.
  *              Provides account deduplication, enrichment, and territory assignment.
  *              Delegates queries to AccountSelector and SObject manipulation to AccountDomain.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class AccountService {