sf-forcekit 1.0.0

package/templates/ai-dir/architecture.md

@@ -0,0 +1,123 @@
+# Architecture
+
+> System design, data model, and integration map for this Salesforce project.
+
+## Overview
+
+<!-- Brief description of the application's purpose and business domain -->
+
+**Domain:** [e.g., Sales Cloud, Service Cloud, Experience Cloud, Custom Platform]
+**Primary Users:** [e.g., Sales Reps, Service Agents, Partners, Community Users]
+**Org Strategy:** [e.g., Single Org, Multi-Org, Sandbox Strategy]
+
+---
+
+## Data Model
+
+### Core Objects
+
+<!-- List custom objects and their relationships. Use a table or ERD. -->
+
+| Object API Name | Label | Type | Description |
+|----------------|-------|------|-------------|
+| `Account` | Account | Standard | — |
+| `Contact` | Contact | Standard | — |
+| <!-- Add rows --> | | | |
+
+### Key Relationships
+
+```
+Account (1) ──── (N) Contact
+Account (1) ──── (N) Opportunity
+<!-- Add your object relationships -->
+```
+
+### Record Types & Business Processes
+
+| Object | Record Type | Sales/Support Process | Description |
+|--------|------------|----------------------|-------------|
+| <!-- Add rows --> | | | |
+
+---
+
+## Architecture Layers
+
+```
+┌─────────────────────────────────────────────────┐
+│                  UI Layer                        │
+│   LWC Components  │  Aura (Legacy)  │  Flows    │
+├─────────────────────────────────────────────────┤
+│               Controller Layer                   │
+│   LWC Controllers  │  Aura Controllers           │
+├─────────────────────────────────────────────────┤
+│                Service Layer                     │
+│   *Service.cls — All business logic lives here   │
+├─────────────────────────────────────────────────┤
+│               Domain / Trigger Layer             │
+│   One Trigger per Object → TriggerHandler.cls    │
+├─────────────────────────────────────────────────┤
+│               Selector Layer                     │
+│   *Selector.cls — All SOQL queries               │
+├─────────────────────────────────────────────────┤
+│              Platform Services                   │
+│   Platform Events │ Queueable │ Batch │ Schedule │
+├─────────────────────────────────────────────────┤
+│             Integration Layer                    │
+│   Named Credentials │ REST/SOAP Callouts         │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Integration Map
+
+<!-- List all external system integrations -->
+
+| System | Direction | Protocol | Auth Method | Named Credential | Frequency |
+|--------|-----------|----------|-------------|-----------------|-----------|
+| <!-- e.g., ERP --> | Outbound | REST | OAuth 2.0 | `ERP_API` | Real-time |
+| <!-- Add rows --> | | | | | |
+
+---
+
+## Automation Inventory
+
+### Triggers
+
+| Object | Trigger Name | Handler Class | Context |
+|--------|-------------|---------------|---------|
+| <!-- Add rows --> | | | Before Insert, After Update, etc. |
+
+### Flows
+
+| Flow Name | Type | Object | Purpose |
+|-----------|------|--------|---------|
+| <!-- Add rows --> | Record-Triggered (Before/After) | | |
+
+### Scheduled / Batch Jobs
+
+| Class Name | Type | Schedule | Purpose |
+|-----------|------|----------|---------|
+| <!-- Add rows --> | Schedulable / Batchable | | |
+
+---
+
+## Security Model
+
+### Profiles & Permission Sets
+
+| Name | Type | Purpose |
+|------|------|---------|
+| <!-- Add rows --> | Profile / Perm Set / Perm Set Group | |
+
+### Sharing Model
+
+| Object | OWD | Sharing Rules | Apex Managed Sharing? |
+|--------|-----|--------------|----------------------|
+| <!-- Add rows --> | Private / Public Read / Public Read-Write | | Yes / No |
+
+---
+
+## Notes
+
+<!-- Any additional architectural decisions, constraints, or context -->

package/templates/ai-dir/commands.md

@@ -0,0 +1,276 @@
+# CLI Commands Cookbook
+
+> Every `sf` CLI command you'll need, organized by workflow.
+> Agents: Use these exact commands. Don't guess flags — run `--help` if unsure.
+
+---
+
+## Quick Reference — Most Used
+
+```bash
+# Deploy all
+sf project deploy start --target-org <target_org> --source-dir force-app
+
+# Deploy one class
+sf project deploy start --target-org <target_org> --metadata "ApexClass:AccountService"
+
+# Run all tests
+sf apex run test --target-org <target_org> --code-coverage --result-format human
+
+# Run one test class
+sf apex run test --target-org <target_org> --tests AccountServiceTest --code-coverage --result-format human
+
+# Open org in browser
+sf org open --target-org <target_org>
+
+# SOQL query
+sf data query --query "SELECT Id, Name FROM Account LIMIT 5" --target-org <target_org>
+```
+
+---
+
+## Metadata Verification
+
+> Used by `source-of-truth.md` verification workflow. Always prefer these over guessing.
+
+```bash
+# Does this object exist?
+sf data query --query "SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName = 'MyObject__c'" \
+  --target-org <target_org> --use-tooling-api
+
+# Does this field exist on an object?
+sf data query --query "SELECT QualifiedApiName, DataType FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'Account' AND QualifiedApiName = 'MyField__c'" \
+  --target-org <target_org> --use-tooling-api
+
+# List all custom fields on an object
+sf data query --query "SELECT QualifiedApiName, DataType FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'Account'" \
+  --target-org <target_org> --use-tooling-api
+
+# Does this Apex class exist?
+sf data query --query "SELECT Name, Status FROM ApexClass WHERE Name = 'AccountService'" \
+  --target-org <target_org> --use-tooling-api
+
+# List active flows
+sf data query --query "SELECT DeveloperName, ProcessType, Status FROM FlowDefinitionView WHERE IsActive = true" \
+  --target-org <target_org> --use-tooling-api
+
+# Custom Labels
+sf data query --query "SELECT Name, Value FROM ExternalString" \
+  --target-org <target_org> --use-tooling-api
+
+# Named Credentials
+sf data query --query "SELECT DeveloperName, Endpoint FROM NamedCredential" \
+  --target-org <target_org> --use-tooling-api
+
+# Custom Metadata Types
+sf data query --query "SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName LIKE '%__mdt'" \
+  --target-org <target_org> --use-tooling-api
+```
+
+---
+
+## Deploy & Retrieve
+
+```bash
+# Validate only (dry run — no actual deploy)
+sf project deploy start --target-org <target_org> --source-dir force-app --dry-run
+
+# Deploy with tests (required for Production)
+sf project deploy start --target-org <target_org> --source-dir force-app \
+  --test-level RunLocalTests
+
+# Deploy specific tests
+sf project deploy start --target-org <target_org> --source-dir force-app \
+  --test-level RunSpecifiedTests --tests "AccountServiceTest,CaseServiceTest"
+
+# Check last deploy status
+sf project deploy report --target-org <target_org>
+
+# Retrieve by metadata type
+sf project retrieve start --target-org <target_org> --metadata "ApexClass:AccountService"
+
+# Retrieve by manifest
+sf project retrieve start --target-org <target_org> --manifest manifest/package.xml
+
+# Destructive deploy (remove metadata from org)
+sf project deploy start --target-org <target_org> \
+  --manifest manifest/package.xml \
+  --post-destructive-changes manifest/destructiveChanges.xml
+```
+
+---
+
+## Testing
+
+```bash
+# Run all local tests with coverage
+sf apex run test --target-org <target_org> \
+  --code-coverage --result-format human --test-level RunLocalTests
+
+# Run specific test class
+sf apex run test --target-org <target_org> \
+  --tests AccountServiceTest --code-coverage --result-format human
+
+# Run specific test method
+sf apex run test --target-org <target_org> \
+  --tests "AccountServiceTest.testBulkInsert" --code-coverage --result-format human
+
+# Run tests with JSON output (for parsing)
+sf apex run test --target-org <target_org> \
+  --code-coverage --result-format json --output-dir test-results --json
+
+# Run anonymous Apex script
+sf apex run --target-org <target_org> --file scripts/apex/debug-script.apex
+
+# Run inline anonymous Apex
+echo "System.debug(UserInfo.getUserName());" | sf apex run --target-org <target_org>
+```
+
+---
+
+## Debugging
+
+```bash
+# Tail debug logs in real-time
+sf apex tail log --target-org <target_org>
+
+# List recent debug logs
+sf apex log list --target-org <target_org>
+
+# View a specific log
+sf apex log get --target-org <target_org> --log-id <logId>
+
+# View org limits (API calls, storage, etc.)
+sf limits api display --target-org <target_org>
+```
+
+---
+
+## Data Operations
+
+```bash
+# SOQL query
+sf data query --query "SELECT Id, Name FROM Account WHERE CreatedDate = TODAY" \
+  --target-org <target_org>
+
+# Tooling API query
+sf data query --query "SELECT Id, Name, ApiVersion FROM ApexClass ORDER BY Name" \
+  --target-org <target_org> --use-tooling-api
+
+# Insert record
+sf data create record --target-org <target_org> \
+  --sobject Account --values "Name='Test Account' Industry='Technology'"
+
+# Update record
+sf data update record --target-org <target_org> \
+  --sobject Account --record-id 001XXXXXXXXXXXX --values "Industry='Finance'"
+
+# Delete record
+sf data delete record --target-org <target_org> \
+  --sobject Account --record-id 001XXXXXXXXXXXX
+
+# Bulk import CSV
+sf data import bulk --target-org <target_org> \
+  --sobject Account --file data/accounts.csv
+
+# Bulk export
+sf data query --query "SELECT Id, Name FROM Account" \
+  --target-org <target_org> --result-format csv > data/accounts-export.csv
+
+# Count records
+sf data query --query "SELECT COUNT() FROM Account" --target-org <target_org>
+```
+
+---
+
+## Org Management
+
+```bash
+# Login to org (web browser)
+sf org login web --alias <alias>
+
+# Login with auth URL (CI/CD)
+sf org login sfdx-url --sfdx-url-file authfile.txt --alias <alias>
+
+# List authenticated orgs
+sf org list
+
+# Open org in browser
+sf org open --target-org <target_org>
+
+# Open specific page
+sf org open --target-org <target_org> --path "/lightning/setup/ApexClasses/home"
+
+# Display org info
+sf org display --target-org <target_org>
+
+# Set default org
+sf config set target-org=<alias>
+```
+
+---
+
+## Helper Script Commands
+
+```bash
+# Scan project and update inventory.md
+python3 .ai/scripts/update_state.py scan
+
+# Sync org details + limits into org-context.local.md
+python3 .ai/scripts/update_state.py sync-org
+
+# Pre-cache schema (objects + fields) for offline verification
+python3 .ai/scripts/update_state.py cache-schema
+
+# Static analysis / lint check
+python3 .ai/scripts/update_state.py check
+python3 .ai/scripts/update_state.py check --files "force-app/main/default/classes/AccountService.cls"
+
+# Verify metadata exists in org
+python3 .ai/scripts/update_state.py verify --type object --name MyObject__c
+python3 .ai/scripts/update_state.py verify --type field --name MyField__c --object Account
+python3 .ai/scripts/update_state.py verify --type class --name AccountService
+
+# Session management
+python3 .ai/scripts/update_state.py session-start --agent "Claude" --goal "Implement X"
+python3 .ai/scripts/update_state.py task-start "Task description"
+python3 .ai/scripts/update_state.py task-complete "Task description" --files "file1.cls,file2.cls"
+python3 .ai/scripts/update_state.py session-end --summary "Summary" --files "files"
+
+# Clean for open-source distribution
+python3 .ai/scripts/update_state.py clean
+```
+
+---
+
+## Common Patterns
+
+### Deploy → Test → Verify Cycle
+
+```bash
+# 1. Deploy
+sf project deploy start --target-org <target_org> --source-dir force-app
+
+# 2. Run affected tests
+sf apex run test --target-org <target_org> --tests "AccountServiceTest" --code-coverage --result-format human
+
+# 3. Verify coverage
+sf apex run test --target-org <target_org> --code-coverage --result-format human --test-level RunLocalTests
+```
+
+### Retrieve Unknown Metadata From Org
+
+```bash
+# When you need to see what's in the org but not in local source
+sf project retrieve start --target-org <target_org> --metadata "CustomObject:MyObject__c"
+sf project retrieve start --target-org <target_org> --metadata "ApexClass:*"
+```
+
+### Create Scratch Org (for package dev)
+
+```bash
+sf org create scratch --definition-file config/project-scratch-def.json \
+  --alias scratch-dev --duration-days 7 --set-default
+sf project deploy start --target-org scratch-dev --source-dir force-app
+sf apex run test --target-org scratch-dev --test-level RunLocalTests
+```

package/templates/ai-dir/context-snapshots/TEMPLATE.md

@@ -0,0 +1,64 @@
+# Context Snapshot — YYYY-MM-DD
+
+> Point-in-time capture of project state for agent session continuity.
+> Copy this template and fill in at the start of each major session.
+
+---
+
+## Session Info
+
+| Field | Value |
+|-------|-------|
+| **Date** | |
+| **Agent** | [Claude / Copilot / Cursor / etc.] |
+| **Session Goal** | |
+| **Branch** | |
+
+---
+
+## What Was Done
+
+<!-- List what was accomplished in this session -->
+
+- 
+
+---
+
+## What's Next
+
+<!-- What should the next session pick up -->
+
+- 
+
+---
+
+## Key Decisions Made
+
+<!-- Any architectural or design decisions -->
+
+- 
+
+---
+
+## Open Questions
+
+<!-- Unresolved questions for the developer -->
+
+- 
+
+---
+
+## Files Changed
+
+<!-- List modified files for quick reference -->
+
+| File | Change |
+|------|--------|
+| | |
+
+---
+
+## Notes
+
+<!-- Any additional context for future sessions -->
+

package/templates/ai-dir/conventions.md

@@ -0,0 +1,242 @@
+# Coding Conventions
+
+> Enforced standards for all Salesforce development in this project.
+> These rules are NON-NEGOTIABLE — agents must follow them without exception.
+
+---
+
+## Apex Standards
+
+### Bulkification (Non-Negotiable)
+
+- **NEVER** put SOQL or DML inside loops. No exceptions.
+- All triggers and services must handle **200+ records** per transaction.
+- Use `Map<Id, SObject>` patterns for efficient lookups.
+- Aggregate queries (`COUNT()`, `SUM()`, `GROUP BY`) over iterative counting.
+
+```apex
+// ✅ CORRECT — Bulkified
+Map<Id, Account> accountMap = new Map<Id, Account>(
+    [SELECT Id, Name FROM Account WHERE Id IN :accountIds WITH USER_MODE]
+);
+for (Contact c : contacts) {
+    Account a = accountMap.get(c.AccountId);
+}
+
+// ❌ WRONG — SOQL in loop
+for (Contact c : contacts) {
+    Account a = [SELECT Id, Name FROM Account WHERE Id = :c.AccountId];
+}
+```
+
+### Security (Non-Negotiable)
+
+- **`WITH USER_MODE`** on ALL SOQL queries (API v60.0+). Fall back to `WITH SECURITY_ENFORCED` for older versions.
+- **`with sharing`** by default on ALL classes. Use `without sharing` ONLY with documented justification in a code comment.
+- **`Security.stripInaccessible()`** before DML when handling external/untrusted data.
+- **Never** hardcode IDs, credentials, or endpoints.
+
+```apex
+// ✅ CORRECT
+public with sharing class AccountService {
+    public static List<Account> getAccounts(Set<Id> ids) {
+        return [SELECT Id, Name FROM Account WHERE Id IN :ids WITH USER_MODE];
+    }
+}
+
+// ❌ WRONG — missing sharing, missing USER_MODE
+public class AccountService {
+    public static List<Account> getAccounts(Set<Id> ids) {
+        return [SELECT Id, Name FROM Account WHERE Id IN :ids];
+    }
+}
+```
+
+### Architecture Pattern
+
+All code follows a **strict layered architecture**:
+
+```
+Trigger → TriggerHandler → Service → Selector
+```
+
+| Layer | Responsibility | Naming |
+|-------|---------------|--------|
+| **Trigger** | Entry point only. Delegates immediately. | `ObjectNameTrigger` |
+| **Trigger Handler** | Routes events (before/after insert/update/delete). | `ObjectNameTriggerHandler` |
+| **Service** | ALL business logic. Stateless methods. | `ObjectNameService` |
+| **Selector** | ALL SOQL queries. Reusable, testable. | `ObjectNameSelector` |
+| **Domain** | Complex object-specific logic (optional). | `ObjectNames` (plural) |
+
+**Rules:**
+- **One trigger per object** — no exceptions.
+- **Zero business logic in triggers** — handlers delegate to services.
+- **Zero SOQL in services** — services call selectors.
+- **Unit of Work** — batch DML at end of transaction, not scattered throughout.
+
+### Error Handling
+
+```apex
+// ✅ CORRECT
+try {
+    HttpResponse response = new Http().send(request);
+    if (response.getStatusCode() != 200) {
+        throw new IntegrationException(
+            'Callout failed: ' + response.getStatusCode() + ' ' + response.getBody()
+        );
+    }
+} catch (CalloutException e) {
+    Logger.error('Callout to ' + endpoint + ' failed', e);
+    throw new IntegrationException('External service unavailable', e);
+}
+```
+
+- Wrap callouts and integrations in `try/catch` with structured logging.
+- Use **custom exceptions** extending `Exception` for domain errors.
+- **NEVER** swallow exceptions silently (empty catch blocks).
+- Include meaningful context in error messages.
+
+### Testing Standards
+
+| Requirement | Standard |
+|------------|----------|
+| Minimum coverage | **75%** (target **90%+**) |
+| `SeeAllData=true` | **BANNED** — never use |
+| Test data | `@TestSetup` for shared data |
+| Assertions | Meaningful messages: `System.assertEquals(expected, actual, 'Context')` |
+| Bulk testing | Test with **200+ records** |
+| Negative paths | Test error conditions and exceptions |
+| Permission testing | Test with restricted user profiles |
+
+```apex
+@IsTest
+private class AccountServiceTest {
+
+    @TestSetup
+    static void setupTestData() {
+        List<Account> accounts = TestDataFactory.createAccounts(200);
+        insert accounts;
+    }
+
+    @IsTest
+    static void testGetAccounts_BulkPositive() {
+        List<Account> accounts = [SELECT Id FROM Account];
+        System.assertEquals(200, accounts.size(), 'Should have 200 test accounts');
+
+        Test.startTest();
+        List<Account> result = AccountService.getAccounts(
+            new Map<Id, Account>(accounts).keySet()
+        );
+        Test.stopTest();
+
+        System.assertEquals(200, result.size(), 'Service should return all 200 accounts');
+    }
+}
+```
+
+---
+
+## Naming Conventions
+
+### Apex Classes
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Trigger | `{Object}Trigger` | `AccountTrigger` |
+| Trigger Handler | `{Object}TriggerHandler` | `AccountTriggerHandler` |
+| Service | `{Object}Service` | `AccountService` |
+| Selector | `{Object}Selector` | `AccountSelector` |
+| Domain | `{Objects}` (plural) | `Accounts` |
+| Controller | `{Feature}Controller` | `AccountSearchController` |
+| Batch | `{Purpose}Batch` | `AccountCleanupBatch` |
+| Queueable | `{Purpose}Queueable` | `SyncAccountsQueueable` |
+| Schedulable | `{Purpose}Scheduler` | `DailyCleanupScheduler` |
+| Test | `{ClassName}Test` | `AccountServiceTest` |
+| Exception | `{Domain}Exception` | `IntegrationException` |
+| Utility | `{Purpose}Util` | `DateUtil` |
+| Wrapper/DTO | `{Purpose}DTO` | `AccountResponseDTO` |
+
+### Apex Methods
+
+- **camelCase** — `getAccountsByIds()`, `validateContacts()`
+- Prefix with verb — `get`, `create`, `update`, `delete`, `validate`, `process`, `sync`
+- Boolean methods — prefix with `is`, `has`, `can`, `should`
+
+### Variables
+
+- **camelCase** — `accountMap`, `contactList`, `isActive`
+- Collections — use plural or descriptive suffix: `accountIds`, `contactsByAccountId`
+- Constants — `UPPER_SNAKE_CASE`: `MAX_RETRY_COUNT`
+
+---
+
+## LWC Standards
+
+### Component Structure
+
+```
+lwc/
+  accountSummary/
+    accountSummary.html
+    accountSummary.js
+    accountSummary.css
+    accountSummary.js-meta.xml
+    __tests__/
+      accountSummary.test.js
+```
+
+### Rules
+
+- **camelCase** folder names: `accountSummary/`, NOT `AccountSummary/`
+- Use **`@wire`** for reactive data. Imperative Apex only when wire won't work.
+- **No inline styles** — use CSS custom properties and component CSS files.
+- Always handle **loading**, **error**, and **empty** states in the template.
+- Use **Lightning Design System (SLDS)** classes — don't reinvent the wheel.
+
+```html
+<!-- ✅ CORRECT — handles all states -->
+<template>
+    <template if:true={isLoading}>
+        <lightning-spinner alternative-text="Loading"></lightning-spinner>
+    </template>
+    <template if:true={error}>
+        <c-error-panel errors={error}></c-error-panel>
+    </template>
+    <template if:true={hasData}>
+        <!-- Component content -->
+    </template>
+    <template if:false={hasData}>
+        <c-empty-state message="No records found"></c-empty-state>
+    </template>
+</template>
+```
+
+### LWC Naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Component | `camelCase` | `accountSummary` |
+| Event | `camelCase` verb | `recordselected` |
+| Property | `camelCase` | `@api recordId` |
+| Method | `camelCase` verb | `handleSearch()` |
+
+---
+
+## Flow Standards
+
+- **Record-Triggered Flows** over Process Builder (deprecated) and Workflow Rules.
+- **Before-Save** flows for field updates (no DML consumed).
+- **After-Save** flows only when related record updates or platform events needed.
+- Add **fault paths** to every DML and callout element.
+- **Never hardcode IDs** — use Custom Labels or Custom Metadata Types.
+- Flow naming: `{Object}_{Trigger}_{Purpose}` — e.g., `Account_AfterSave_UpdateContacts`
+
+---
+
+## General Rules
+
+- **No hardcoded IDs** anywhere — use Custom Labels, Custom Metadata, Custom Settings.
+- **No hardcoded credentials** — use Named Credentials exclusively.
+- **API version**: v66.0 (unless project specifies otherwise).
+- **One class per file** — no inner classes except for private DTOs/wrappers.
+- **Comments**: Meaningful Javadoc on all public methods. Don't state the obvious.