sf-forcekit 1.0.0

package/templates/ai-dir/performance.md

@@ -0,0 +1,312 @@
+# Performance Guide
+
+> Governor limits, SOQL optimization, heap management, and async patterns.
+> Consult this before writing any code that touches large datasets or complex logic.
+
+---
+
+## Governor Limits — Quick Reference
+
+| Limit | Sync | Async | Monitor With |
+|-------|------|-------|--------------|
+| SOQL queries | 100 | 200 | `Limits.getQueries()` |
+| SOQL rows returned | 50,000 | 50,000 | `Limits.getQueryRows()` |
+| DML statements | 150 | 150 | `Limits.getDmlStatements()` |
+| DML rows | 10,000 | 10,000 | `Limits.getDmlRows()` |
+| CPU time | 10,000 ms | 60,000 ms | `Limits.getCpuTime()` |
+| Heap size | 6 MB | 12 MB | `Limits.getHeapSize()` |
+| Callouts | 100 | 100 | `Limits.getCallouts()` |
+| Future calls | 50 | 0 | `Limits.getFutureCalls()` |
+| Queueable jobs | 50 | 1 | `Limits.getQueueableJobs()` |
+
+---
+
+## SOQL Optimization
+
+### Indexing Rules
+
+Salesforce auto-indexes:
+- `Id`, `Name`, `OwnerId`, `CreatedDate`, `LastModifiedDate`, `SystemModstamp`
+- All lookup/master-detail fields
+- `RecordTypeId`
+- External ID fields (`__c` with External ID checked)
+
+**Custom indexes** — Request via Salesforce Support for high-volume objects.
+
+### Query Performance Checklist
+
+```apex
+// ✅ GOOD — Selective, uses indexed field
+[SELECT Id, Name FROM Account
+ WHERE Id IN :accountIds
+ WITH USER_MODE]
+
+// ✅ GOOD — Narrow date range on indexed field
+[SELECT Id FROM Case
+ WHERE CreatedDate = LAST_N_DAYS:30
+ WITH USER_MODE]
+
+// ❌ BAD — Leading wildcard forces table scan
+[SELECT Id FROM Account
+ WHERE Name LIKE '%test%'
+ WITH USER_MODE]
+
+// ❌ BAD — Negative filter, not selective
+[SELECT Id FROM Account
+ WHERE Industry != 'Technology'
+ WITH USER_MODE]
+
+// ❌ BAD — OR across non-indexed fields
+[SELECT Id FROM Account
+ WHERE Custom_Field_1__c = 'X' OR Custom_Field_2__c = 'Y'
+ WITH USER_MODE]
+```
+
+### Query Plan Analysis
+
+```
+/services/data/v66.0/query?explain=SELECT+Id+FROM+Account+WHERE+Name='Test'
+```
+
+| Result | Meaning | Action |
+|--------|---------|--------|
+| `Index` | Uses index | ✅ Good |
+| `TableScan` | Full table scan | ❌ Add index or restructure |
+| `Selectivity: 0.xx` | % of table scanned | < 10% is good |
+
+### Reducing SOQL Count
+
+```apex
+// ❌ BAD — Separate queries per object (wastes SOQL budget)
+List<Account> accounts = [SELECT Id FROM Account WHERE Id IN :ids WITH USER_MODE];
+List<Contact> contacts = [SELECT Id FROM Contact WHERE AccountId IN :ids WITH USER_MODE];
+List<Case> cases = [SELECT Id FROM Case WHERE AccountId IN :ids WITH USER_MODE];
+
+// ✅ GOOD — Single parent query with subqueries
+List<Account> accounts = [
+    SELECT Id, Name,
+        (SELECT Id, Name FROM Contacts),
+        (SELECT Id, Subject FROM Cases)
+    FROM Account
+    WHERE Id IN :ids
+    WITH USER_MODE
+];
+```
+
+---
+
+## Heap Management
+
+### When Heap Matters
+
+| Scenario | Risk Level |
+|----------|-----------|
+| Processing 50K+ records | 🔴 High |
+| JSON deserializing large payloads | 🔴 High |
+| Building large Maps/Sets | 🟡 Medium |
+| String concatenation in loops | 🟡 Medium |
+| Normal CRUD operations | 🟢 Low |
+
+### Heap Reduction Patterns
+
+```apex
+// ❌ BAD — Loads entire result set into memory
+List<Account> allAccounts = [SELECT Id, Name, Description FROM Account WITH USER_MODE];
+
+// ✅ GOOD — Use SOQL for filtering, only load what you need
+List<Account> activeAccounts = [
+    SELECT Id, Name
+    FROM Account
+    WHERE IsActive__c = true
+    WITH USER_MODE
+    LIMIT 2000
+];
+
+// ✅ BETTER — For 50K+ records, use Batch Apex with QueryLocator
+global class LargeDataBatch implements Database.Batchable<SObject> {
+    global Database.QueryLocator start(Database.BatchableContext bc) {
+        return Database.getQueryLocator([
+            SELECT Id, Name FROM Account WITH USER_MODE
+        ]);
+    }
+    // QueryLocator bypasses 50K row limit — processes up to 50M rows
+}
+```
+
+### Apex Cursors (v66.0+)
+
+```apex
+// ✅ NEW — Process large result sets in chunks without heap pressure
+Database.Cursor cursor = Database.getCursor(
+    'SELECT Id, Name FROM Account WITH USER_MODE'
+);
+Integer total = cursor.getNumRecords();
+
+// Fetch in chunks of 200
+for (Integer offset = 0; offset < total; offset += 200) {
+    List<Account> chunk = (List<Account>) cursor.fetch(offset, 200);
+    processChunk(chunk);
+}
+```
+
+---
+
+## CPU Time Optimization
+
+### Common CPU Hogs
+
+| Pattern | Fix |
+|---------|-----|
+| Nested loops (`O(n²)`) | Use Map-based lookups |
+| String concatenation in loops | Use `List<String>.join()` |
+| `Schema.getGlobalDescribe()` in loops | Cache outside loop |
+| Complex SOQL field references in loops | Pre-build maps |
+| Regular expressions | Pre-compile Pattern |
+
+### Map-Based Lookup Pattern
+
+```apex
+// ❌ O(n²) — Nested loop
+for (Contact c : contacts) {
+    for (Account a : accounts) {
+        if (c.AccountId == a.Id) {
+            // process
+        }
+    }
+}
+
+// ✅ O(n) — Map lookup
+Map<Id, Account> accountMap = new Map<Id, Account>(accounts);
+for (Contact c : contacts) {
+    Account a = accountMap.get(c.AccountId);
+    if (a != null) {
+        // process
+    }
+}
+```
+
+---
+
+## Async Pattern Selection
+
+| Need | Pattern | Why |
+|------|---------|-----|
+| Simple fire-and-forget | `@future` | Lowest overhead |
+| Complex types / chaining | `Queueable` | **Preferred default** |
+| 50K+ records | `Batch Apex` | QueryLocator = 50M rows |
+| Time-based processing | `Schedulable` → Batch | Cron trigger |
+| Cross-system / decoupled | `Platform Events` | Event-driven |
+| Mixed DML | `@future` or `Queueable` | Separate transactions |
+
+### Queueable Pattern (Preferred)
+
+```apex
+public class ProcessAccountsQueueable implements Queueable {
+    private List<Id> accountIds;
+    private Integer retryCount;
+
+    public ProcessAccountsQueueable(List<Id> accountIds) {
+        this(accountIds, 0);
+    }
+
+    public ProcessAccountsQueueable(List<Id> accountIds, Integer retryCount) {
+        this.accountIds = accountIds;
+        this.retryCount = retryCount;
+    }
+
+    public void execute(QueueableContext context) {
+        try {
+            AccountService.heavyProcessing(accountIds);
+        } catch (Exception e) {
+            if (retryCount < 3) {
+                System.enqueueJob(new ProcessAccountsQueueable(accountIds, retryCount + 1));
+            } else {
+                Logger.error('Max retries exceeded', e);
+            }
+        }
+    }
+}
+```
+
+---
+
+## DML Optimization
+
+### Partial DML for Fault Tolerance
+
+```apex
+// ✅ Use Database methods with allOrNone=false for bulk tolerance
+Database.SaveResult[] results = Database.insert(records, false);
+for (Database.SaveResult sr : results) {
+    if (!sr.isSuccess()) {
+        for (Database.Error err : sr.getErrors()) {
+            Logger.error('Insert failed for record: ' + err.getMessage());
+        }
+    }
+}
+```
+
+### Batch DML at End of Transaction
+
+```apex
+// ❌ BAD — Scattered DML throughout method
+public static void processOrder(Order__c order) {
+    update order;                    // DML 1
+    insert lineItems;               // DML 2
+    update relatedAccount;          // DML 3
+    EventBus.publish(statusEvent);  // DML 4
+}
+
+// ✅ GOOD — Collect and batch
+public static void processOrder(Order__c order) {
+    List<SObject> toUpdate = new List<SObject>();
+    List<SObject> toInsert = new List<SObject>();
+
+    toUpdate.add(order);
+    toInsert.addAll(lineItems);
+    toUpdate.add(relatedAccount);
+
+    insert toInsert;
+    update toUpdate;
+    EventBus.publish(statusEvent);
+}
+```
+
+---
+
+## In-Code Monitoring
+
+Add this to performance-critical methods:
+
+```apex
+public static void criticalMethod(List<Account> accounts) {
+    Long startCpu = Limits.getCpuTime();
+    Integer startQueries = Limits.getQueries();
+    Integer startHeap = Limits.getHeapSize();
+
+    // ... method logic ...
+
+    System.debug(LoggingLevel.INFO, String.format(
+        '>>> Performance: CPU={0}ms, SOQL={1}, Heap={2}KB',
+        new List<Object>{
+            Limits.getCpuTime() - startCpu,
+            Limits.getQueries() - startQueries,
+            (Limits.getHeapSize() - startHeap) / 1024
+        }
+    ));
+}
+```
+
+---
+
+## Red Flags (Performance Code Smells)
+
+| Smell | Risk | Fix |
+|-------|------|-----|
+| SOQL inside `for` loop | 🔴 101 limit | Move query before loop, use Map |
+| DML inside `for` loop | 🔴 151 limit | Collect, single DML after loop |
+| `Schema.getGlobalDescribe()` per record | 🔴 CPU timeout | Cache once, reuse |
+| `String += ` in loop with 1000+ iterations | 🟡 Heap + CPU | Use `List<String>` + `.join()` |
+| Loading all fields (`SELECT *` equivalent) | 🟡 Heap | Select only needed fields |
+| Recursive trigger without guard | 🔴 Stack overflow | Static `Set<Id>` guard |
+| `for (SObject s : [SELECT ...])` inside another loop | 🔴 101 limit | Pre-query, use Map |

package/templates/ai-dir/prompts/agentforce.md

@@ -0,0 +1,163 @@
+# Agentforce Development Rules
+
+> Instructions for AI agents when building Agentforce Topics, Actions, and Prompt Templates.
+
+---
+
+## Core Principle
+
+**Declarative First, Code Second.**
+
+```
+Can a Standard Action do it?    → Use Standard Action
+Can a Flow do it?               → Use Flow Action
+Need complex logic?             → Use @InvocableMethod Apex Action
+Need AI-generated text?         → Use Prompt Template Action
+```
+
+---
+
+## Action Design Rules
+
+### 1. Descriptions Are Everything
+
+The Atlas Reasoning Engine chooses actions based on natural language descriptions. Write them like you're explaining to a smart colleague what this action does and WHEN to use it.
+
+```apex
+// ✅ GOOD
+@InvocableMethod(
+    label='Get Account Health Score'
+    description='Calculates a health score (0-100) for an Account based on recent activity, '
+        + 'open cases, and engagement metrics. Use when the user asks about account health, '
+        + 'risk level, engagement, or churn probability.'
+)
+
+// ❌ BAD
+@InvocableMethod(
+    label='Process Account'
+    description='Does account stuff'
+)
+```
+
+### 2. Input/Output Descriptions
+
+Every `@InvocableVariable` needs a clear description:
+
+```apex
+public class AccountHealthRequest {
+    @InvocableVariable(
+        label='Account ID'
+        description='The 18-character Salesforce ID of the Account to analyze'
+        required=true
+    )
+    public Id accountId;
+
+    @InvocableVariable(
+        label='Include Forecast'
+        description='Set to true to include a 90-day churn forecast in the response'
+        required=false
+    )
+    public Boolean includeForecast;
+}
+```
+
+### 3. Return Meaningful Responses
+
+Actions should return structured data that the agent can reason about:
+
+```apex
+public class AccountHealthResponse {
+    @InvocableVariable(label='Health Score' description='Score from 0-100, higher is healthier')
+    public Integer healthScore;
+
+    @InvocableVariable(label='Risk Level' description='LOW, MEDIUM, or HIGH')
+    public String riskLevel;
+
+    @InvocableVariable(label='Summary' description='Human-readable summary of account health')
+    public String summary;
+
+    @InvocableVariable(label='Recommendations' description='List of recommended actions')
+    public List<String> recommendations;
+}
+```
+
+---
+
+## Topic Design
+
+### Naming
+- Use clear, business-domain names: "Order Management", "Account Health", "Case Resolution"
+- Avoid technical names: "API Handler", "Data Processor"
+
+### Scope
+- Each Topic should cover a coherent set of related tasks
+- Don't make Topics too broad (entire CRM) or too narrow (single field update)
+
+### Instructions
+Write Topic instructions as if briefing a new team member:
+```
+You help customers with their orders. You can look up order status, modify shipping 
+addresses for orders that haven't shipped yet, and process return requests. Always 
+verify the customer's identity before making changes. If an order has already shipped, 
+direct the customer to the returns process instead.
+```
+
+---
+
+## Prompt Template Rules
+
+1. **Ground in data** — Use merge fields from Data Cloud or CRM objects
+2. **Be specific** — Tell the LLM exactly what format you want
+3. **Set guardrails** — Include what the agent should NOT do
+4. **Test extensively** — Different inputs, edge cases, adversarial prompts
+
+### Template Structure
+```
+You are a {role} helping with {domain}.
+
+## Context
+{Merge fields from Salesforce data}
+
+## Task
+{What to generate/analyze}
+
+## Format
+{Expected output format}
+
+## Guardrails
+- Do NOT {restrictions}
+- Always {requirements}
+```
+
+---
+
+## Guardrails & Safety
+
+| Mechanism | Purpose |
+|-----------|---------|
+| **Agent Script** | Enforce deterministic if/then workflows for critical tasks |
+| **Content Safety Policies** | Filter inappropriate output |
+| **Einstein Trust Layer** | PII masking before LLM, audit logging |
+| **Topic Scoping** | Limit what each agent can access |
+| **Command Center** | Monitor performance, audit trails, policy enforcement |
+
+---
+
+## Testing Agentforce Components
+
+1. **Unit test** all `@InvocableMethod` classes (standard Apex testing)
+2. **Preview** in Agent Builder with sample conversations
+3. **Validate action selection** — Does Atlas pick the right action for the right query?
+4. **Edge cases** — Empty results, invalid input, error responses
+5. **Multi-turn** — Test conversation flows, not just single queries
+
+---
+
+## Checklist
+
+- [ ] Action descriptions are clear, specific, and include "use when" guidance
+- [ ] All input/output variables have labels and descriptions
+- [ ] Apex actions follow all standard Apex conventions (bulkified, secure, tested)
+- [ ] Prompt templates are grounded in live data (not hallucination-prone)
+- [ ] Guardrails configured for sensitive operations
+- [ ] Tested in Agent Builder preview before deployment

package/templates/ai-dir/prompts/apex.md

@@ -0,0 +1,165 @@
+# Apex Generation Rules
+
+> Instructions for AI agents when generating Apex code in this project.
+
+---
+
+## Before Writing Any Apex
+
+1. **Check `conventions.md`** for naming, architecture, and security rules.
+2. **Check `architecture.md`** for existing classes and patterns in this project.
+3. **Identify the correct layer** — is this a Trigger, Handler, Service, or Selector?
+
+---
+
+## Mandatory Rules
+
+### Architecture
+
+- **One trigger per object** → delegates to `{Object}TriggerHandler`
+- **Handler** routes events → calls `{Object}Service` methods
+- **Service** contains all business logic → calls `{Object}Selector` for data
+- **Selector** contains all SOQL → returns typed collections
+- **Zero business logic in triggers or handlers**
+
+### Security
+
+```apex
+// EVERY class starts with:
+public with sharing class ClassName {
+
+// EVERY SOQL query uses:
+[SELECT ... FROM ... WITH USER_MODE]
+
+// Use stripInaccessible when handling external data:
+SObjectAccessDecision decision = Security.stripInaccessible(AccessType.CREATABLE, records);
+insert decision.getRecords();
+```
+
+### Bulkification
+
+```apex
+// ✅ ALWAYS — Collections and maps
+public static void processContacts(List<Contact> contacts) {
+    Set<Id> accountIds = new Set<Id>();
+    for (Contact c : contacts) {
+        accountIds.add(c.AccountId);
+    }
+    Map<Id, Account> accountMap = new Map<Id, Account>(
+        AccountSelector.getByIds(accountIds)
+    );
+    // Process using map lookups, not queries
+}
+
+// ❌ NEVER
+for (Contact c : contacts) {
+    Account a = [SELECT Id FROM Account WHERE Id = :c.AccountId]; // SOQL IN LOOP!
+}
+```
+
+### Error Handling
+
+```apex
+// Custom exceptions for domain errors
+public class OrderProcessingException extends Exception {}
+
+// Structured try/catch with context
+try {
+    // risky operation
+} catch (SpecificException e) {
+    Logger.error('Context: what was happening', e);
+    throw new DomainException('User-friendly message', e);
+}
+// NEVER: catch (Exception e) { } — empty catch
+```
+
+---
+
+## Templates
+
+When generating a new class, use these skeletons:
+
+### Trigger
+```apex
+trigger {Object}Trigger on {Object__c} (
+    before insert, before update, before delete,
+    after insert, after update, after delete, after undelete
+) {
+    new {Object}TriggerHandler().run();
+}
+```
+
+### Trigger Handler
+```apex
+public with sharing class {Object}TriggerHandler extends TriggerHandler {
+    public override void beforeInsert() {
+        {Object}Service.onBeforeInsert((List<{Object__c}>) Trigger.new);
+    }
+    public override void afterUpdate() {
+        {Object}Service.onAfterUpdate(
+            (List<{Object__c}>) Trigger.new,
+            (Map<Id, {Object__c}>) Trigger.oldMap
+        );
+    }
+    // Add only the events you need
+}
+```
+
+### Service
+```apex
+public with sharing class {Object}Service {
+    public static void onBeforeInsert(List<{Object__c}> newRecords) {
+        // Business logic here
+    }
+
+    public static void onAfterUpdate(List<{Object__c}> newRecords, Map<Id, {Object__c}> oldMap) {
+        // Change detection
+        List<{Object__c}> changed = new List<{Object__c}>();
+        for ({Object__c} record : newRecords) {
+            if (record.Status__c != oldMap.get(record.Id).Status__c) {
+                changed.add(record);
+            }
+        }
+        if (!changed.isEmpty()) {
+            processStatusChange(changed);
+        }
+    }
+}
+```
+
+### Selector
+```apex
+public with sharing class {Object}Selector {
+    public static List<{Object__c}> getByIds(Set<Id> ids) {
+        return [
+            SELECT Id, Name, Status__c, Account__c
+            FROM {Object__c}
+            WHERE Id IN :ids
+            WITH USER_MODE
+        ];
+    }
+
+    public static List<{Object__c}> getByAccountIds(Set<Id> accountIds) {
+        return [
+            SELECT Id, Name, Status__c, Account__c
+            FROM {Object__c}
+            WHERE Account__c IN :accountIds
+            WITH USER_MODE
+            ORDER BY CreatedDate DESC
+        ];
+    }
+}
+```
+
+---
+
+## Checklist Before Returning Apex Code
+
+- [ ] Uses `with sharing`
+- [ ] All SOQL has `WITH USER_MODE`
+- [ ] No SOQL or DML in loops
+- [ ] Handles 200+ records
+- [ ] Custom exception for domain errors
+- [ ] try/catch on callouts with logging
+- [ ] Follows naming conventions from `conventions.md`
+- [ ] Methods have Javadoc comments