sf-forcekit 1.0.0

package/License

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohit Vaghela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# ForceKit ⚡
+
+> **Salesforce enterprise-grade AI context layer and agent skill for Salesforce DX projects.**
+
+ForceKit provides a structured, token-efficient `.ai/` context system that shields AI agents from hallucinations, enforces strict layered architecture patterns, and manages session state. It also bundles a complete **agent skill** configuration that you can drop directly into your agent's config folder.
+
+---
+
+## 🚀 Key Features
+
+*   **Anti-Hallucination Protocol (Non-Negotiable)**: Strictly enforces verification rules so agents don't guess API names, custom fields, or Apex methods.
+*   **Tiered Reading Architecture**: Organizes context files into tiers (T0 to T3) to save token budget while maintaining situational awareness.
+*   **Enterprise-Grade Apex Standards**: Automates rules for bulkification, user mode queries (`WITH USER_MODE`), and trigger bypass patterns.
+*   **Automated State Scannner**: Includes an inventory script that scans and indexes objects, classes, LWCs, and flows.
+*   **Next-Session Handoff**: Keeps a rolling session log so agents can hand off work to each other across sessions without loss of context.
+
+---
+
+## 📦 Directory Structure
+
+```
+forcekit/
+├── SKILL.md                 # Agent-facing skill description & triggers
+├── README.md                # This user guide
+├── scripts/
+│   └── scaffold.sh          # Installer script to generate .ai/ in target projects
+├── references/              # Context guides read by the active agent skill
+│   ├── conventions.md
+│   ├── testing-strategy.md
+│   └── ...
+└── templates/
+    └── ai-dir/              # Source files for bootstrapping new projects
+```
+
+---
+
+## ⚙️ How to Use / Install
+
+### Option A: Zero Install (npx, bunx, pnpm dlx)
+You don't need to install anything! Run this command directly inside your Salesforce DX project root to scaffold the `.ai/` directory:
+
+```bash
+# Using npm
+npx sf-forcekit
+
+# Using bun
+bunx sf-forcekit
+
+# Using pnpm
+pnpm dlx sf-forcekit
+```
+
+---
+
+### Option B: Local AI Agent Skill
+If you want to use ForceKit as a registered local skill inside your AI agent (like Google Antigravity, Claude Code, Windsurf, Codex, etc.) so it can auto-trigger on command:
+
+1. Clone this repository into your agent's skills directory:
+   ```bash
+   git clone https://github.com/<your-username>/forcekit.git ~/.gemini/config/skills/forcekit
+   ```
+2. Restart your agent or start a new session. The agent will automatically register the `forcekit` skill!
+
+Once the skill is active, you can tell the agent:
+> *"scaffold a salesforce context layer"*
+> OR
+> *"initialize forcekit in this project"*
+
+---
+
+## 🛠️ Scaffolding Output
+
+The scaffold process generates the following structure in your project root:
+```
+my-sfdx-project/
+└── .ai/
+    ├── README.md
+    ├── rules.md             # Rules for agent behavior
+    ├── org-context.md       # Target org details
+    ├── current-state.md     # Active session log & tech debt
+    ├── inventory.md         # Auto-scanned metadata index
+    ├── scripts/
+    │   └── update_state.py  # Automation tool
+    └── ...
+```
+
+---
+
+## 🤖 AI Agent Compatibility
+
+ForceKit is designed to work with all major AI developer agents and IDE extensions:
+*   **Google Antigravity & Gemini**: Full custom skill registration and guideline enforcement.
+*   **Claude Code**: Supports standard `agentskills` trigger formatting.
+*   **Codex & Windsurf**: Integrates with local workspace context rules and custom commands.
+*   **GitHub Copilot**: Automatically reads project state from the `.ai/` folder.
+*   **Cursor**: Seamlessly references `.ai/` files via `@` context inclusion.
+
+---
+
+## 🤝 Contributing
+
+Contributions to improve Salesforce AI development patterns are welcome! Feel free to open issues or submit pull requests.
+
+## 📄 License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// Colors helper
+const GREEN = '\x1b[32m';
+const BLUE = '\x1b[34m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const NC = '\x1b[0m';
+
+console.log(`${BLUE}=== ForceKit: Salesforce AI Context Scaffolder ===${NC}`);
+
+// Verify sfdx-project.json exists
+if (!fs.existsSync(path.join(process.cwd(), 'sfdx-project.json'))) {
+    console.log(`${YELLOW}Warning: sfdx-project.json not found in current directory.${NC}`);
+    console.log('Are you running this from the root of your Salesforce DX project?\n');
+}
+
+const targetDir = path.join(process.cwd(), '.ai');
+const templateDir = path.join(__dirname, '..', 'templates', 'ai-dir');
+
+function copyRecursiveSync(src, dest) {
+    const exists = fs.existsSync(src);
+    const stats = exists && fs.statSync(src);
+    const isDirectory = exists && stats.isDirectory();
+    if (isDirectory) {
+        if (!fs.existsSync(dest)) {
+            fs.mkdirSync(dest, { recursive: true });
+        }
+        fs.readdirSync(src).forEach((childItemName) => {
+            copyRecursiveSync(path.join(src, childItemName), path.join(dest, childItemName));
+        });
+    } else {
+        fs.copyFileSync(src, dest);
+    }
+}
+
+function doScaffold() {
+    if (fs.existsSync(targetDir)) {
+        console.log(`${YELLOW}Warning: Target directory .ai/ already exists.${NC}`);
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+        rl.question('Do you want to overwrite it? (y/n) ', (answer) => {
+            rl.close();
+            if (answer.toLowerCase() === 'y') {
+                console.log('Cleaning up existing .ai/ directory...');
+                fs.rmSync(targetDir, { recursive: true, force: true });
+                runCopy();
+            } else {
+                console.log(`${RED}Scaffold aborted.${NC}`);
+                process.exit(1);
+            }
+        });
+    } else {
+        runCopy();
+    }
+}
+
+function runCopy() {
+    console.log('Bootstrapping .ai/ directory structure...');
+    try {
+        copyRecursiveSync(templateDir, targetDir);
+        // Make python script executable if on Unix
+        const pythonScript = path.join(targetDir, 'scripts', 'update_state.py');
+        if (fs.existsSync(pythonScript) && process.platform !== 'win32') {
+            fs.chmodSync(pythonScript, '755');
+        }
+        console.log(`${GREEN}✓ Success! ForceKit context layer generated at ./.ai/${NC}\n`);
+        console.log('Next steps:');
+        console.log(`  1. Edit ${BLUE}.ai/org-context.md${NC} with your Salesforce org details.`);
+        console.log(`  2. Run ${BLUE}python3 .ai/scripts/update_state.py scan${NC} to initialize project inventory.`);
+        console.log(`  3. Start code generation using the tiered reading instructions in ${BLUE}.ai/README.md${NC}.\n`);
+        console.log('Happy Coding! ⚡');
+    } catch (err) {
+        console.error(`${RED}Error scaffolding project: ${err.message}${NC}`);
+        process.exit(1);
+    }
+}
+
+doScaffold();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "sf-forcekit",
+  "version": "1.0.0",
+  "description": "Scaffold a structured .ai/ context layer for Salesforce DX projects — anti-hallucination, layered architecture, session memory, and governor limit awareness for AI agents.",
+  "main": "bin/cli.js",
+  "bin": {
+    "sf-forcekit": "./bin/cli.js",
+    "forcekit": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "templates/ai-dir",
+    "License"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "salesforce",
+    "sfdx",
+    "ai",
+    "context",
+    "agents",
+    "claude-code",
+    "antigravity",
+    "copilot",
+    "cursor",
+    "apex",
+    "lwc",
+    "devops",
+    "dx",
+    "forcekit"
+  ],
+  "author": "Rohit Vaghela",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rvaghela20/forcekit.git"
+  },
+  "homepage": "https://github.com/rvaghela20/forcekit#readme",
+  "bugs": {
+    "url": "https://github.com/rvaghela20/forcekit/issues"
+  }
+}

package/templates/ai-dir/README.md

@@ -0,0 +1,155 @@
+# .ai/ — Salesforce Project AI Context
+
+> A structured context layer for AI-assisted Salesforce development.
+> Drop this `.ai/` directory into the root of any SFDX project to give agents full situational awareness.
+
+## Quick Start for Agents
+
+> [!IMPORTANT]
+> **Agents: Read `rules.md` FIRST.** It defines your read order, auto-update obligations, and code generation rules.
+
+```
+1. Read rules.md          → Your behavior rules
+2. Read org-context.md    → Org details and CLI config
+3. Read current-state.md  → What's happening NOW + session history
+4. Read conventions.md    → Coding standards
+5. Start working — and UPDATE current-state.md as you go
+```
+
+## Directory Structure
+
+```
+.ai/
+├── rules.md                   ← 🤖 AGENT START HERE — behavior rules, auto-update protocol
+├── README.md                  ← You are here
+│
+├── ── CORE (Always Read) ──────────────────────────────────
+├── source-of-truth.md         ← 🚫 ANTI-HALLUCINATION — verification commands, standard library
+├── inventory.md               ← 🤖 AUTO-UPDATED — registry of everything in the project
+├── org-context.md             ← Org type, edition, limits, installed packages
+├── current-state.md           ← 🤖 AUTO-UPDATED — live status, session log, tech debt, next steps
+│
+├── ── STANDARDS (Read Per Task) ───────────────────────────
+├── conventions.md             ← Coding standards (Apex, LWC, Flows, naming)
+├── architecture.md            ← System design, data model, integration map
+├── testing-strategy.md        ← Test philosophy, patterns, TestDataFactory, coverage rules
+├── performance.md             ← Governor limits, SOQL optimization, heap, async patterns
+│
+├── ── REFERENCE (Read As Needed) ──────────────────────────
+├── commands.md                ← sf CLI cookbook — every command organized by workflow
+├── deployment.md              ← Deploy/retrieve workflows, CI/CD config
+├── integrations.md            ← External systems, Named Credentials, callout patterns
+├── agentforce.md              ← Agentforce Topics, Actions, Prompt Templates
+├── debugging-notes.md         ← Debug techniques, log categories, common errors
+├── known-issues.md            ← Platform bugs, workarounds, tech debt
+│
+├── ── GENERATION RULES ────────────────────────────────────
+├── prompts/                   ← Agent-specific instruction sets
+│   ├── apex.md                ← Apex generation rules
+│   ├── lwc.md                 ← LWC generation rules
+│   ├── testing.md             ← Test class generation rules
+│   ├── flows.md               ← Flow building guidance
+│   ├── security.md            ← Security review & CRUD/FLS rules
+│   └── agentforce.md          ← Agentforce/Einstein development rules
+│
+├── ── TEMPLATES & TOOLS ───────────────────────────────────
+├── templates/                 ← Copy-paste boilerplate starters
+│   ├── TriggerHandler.cls     ← Base class with routing + bypass control
+│   ├── Service.cls            ← Service layer template
+│   ├── Selector.cls           ← Selector/repository template
+│   └── TestClass.cls          ← Test class template
+├── scripts/                   ← Automation scripts
+│   └── update_state.py        ← Scan, sync, verify, lint, session management
+└── context-snapshots/         ← Point-in-time project snapshots
+    └── TEMPLATE.md            ← Copy per session for deep context preservation
+```
+
+## File Priority Tiers
+
+Agents should optimize context window usage by reading files in priority order:
+
+| Tier | Files | When to Read | ~Size |
+|------|-------|-------------|-------|
+| **T0 — Always** | `rules.md`, `org-context.md`, `current-state.md`, `inventory.md` | Every session start | ~20 KB |
+| **T1 — Per Task** | `conventions.md`, `source-of-truth.md`, + relevant `prompts/*.md` | Before writing code | ~20 KB |
+| **T2 — Situational** | `architecture.md`, `testing-strategy.md`, `performance.md` | When task involves design, tests, or optimization | ~15 KB |
+| **T3 — Reference** | `commands.md`, `deployment.md`, `integrations.md`, `debugging-notes.md`, `known-issues.md`, `agentforce.md` | When specifically needed | ~35 KB |
+
+> [!TIP]
+> **Total .ai/ context ≈ 90 KB.** For tight context windows, read only T0 + T1. For full sessions, read T0–T2.
+
+## How It Works
+
+### For Humans
+
+1. **Copy** this `.ai/` folder into any new SFDX project root.
+2. **Fill in** `org-context.md` with your target org details (or run `python3 .ai/scripts/update_state.py sync-org`).
+3. **Review** `current-state.md` to see what the AI has been doing — session logs, decisions, files changed.
+4. **Correct** anything in `current-state.md` if the agent got it wrong.
+
+### For AI Agents
+
+1. **Read** `rules.md` first — it's your operating manual.
+2. **Auto-update** `current-state.md` as you work:
+   - Log your session (date, goal, what you did)
+   - Track active work (in progress / completed)
+   - Record blockers and decisions
+   - List every file you create or change
+3. **Snapshot** context into `context-snapshots/YYYY-MM-DD.md` at end of long sessions.
+
+### Auto-Update Flow
+
+```
+Agent starts session
+    │
+    ├──→ Reads rules.md + current-state.md
+    │
+    ├──→ Adds session entry to Session Log
+    │
+    ├──→ Works on task
+    │    ├── Updates "In Progress" items
+    │    ├── Appends to "Files Changed"
+    │    └── Logs blockers/decisions as they arise
+    │
+    └──→ Session ends
+         ├── Marks items completed
+         ├── Writes session summary
+         └── Creates context snapshot (if major session)
+```
+
+## Multi-Agent Compatibility
+
+This structure is designed to work with:
+- **Claude Code / Antigravity** — reads `rules.md` as project rules
+- **GitHub Copilot** — reads `.ai/` as project context
+- **Cursor** — `.ai/` files surface in context window
+- **Agentforce for Developers** — mirror `prompts/` into `.sfdx/a4d/rules/`
+- **Any LLM agent** — markdown is universally parseable
+
+## Maintenance
+
+| File | Updated By | Frequency |
+|------|-----------|-----------| 
+| `rules.md` | Human | Rarely (on process change) |
+| `org-context.md` | Human / Script | Once per org (or `sync-org`) |
+| `conventions.md` | Human | Rarely (on standards update) |
+| `architecture.md` | Human + Agent | Per major feature / data model change |
+| `testing-strategy.md` | Human | Rarely (on test philosophy change) |
+| `performance.md` | Human | Per API version / new patterns |
+| `commands.md` | Human | On CLI updates |
+| `current-state.md` | **🤖 Agent (auto)** | **Every session, continuously** |
+| `inventory.md` | **🤖 Agent (auto)** | **After creating/deleting metadata** |
+| `deployment.md` | Human | On CI/CD pipeline changes |
+| `known-issues.md` | Human + Agent | As discovered |
+| `context-snapshots/` | **🤖 Agent (auto)** | Per session or milestone |
+
+## Helper Script Reference
+
+```bash
+python3 .ai/scripts/update_state.py scan          # Scan project → update inventory.md
+python3 .ai/scripts/update_state.py sync-org       # Fetch org details → update org-context.local.md
+python3 .ai/scripts/update_state.py cache-schema   # Cache objects/fields for offline verification
+python3 .ai/scripts/update_state.py check          # Static analysis / code style lint
+python3 .ai/scripts/update_state.py verify --type class --name AccountService  # Verify metadata exists
+python3 .ai/scripts/update_state.py clean          # Strip local data for open-source distribution
+```

package/templates/ai-dir/agentforce.md

@@ -0,0 +1,213 @@
+# Agentforce
+
+> Einstein Bots, Copilot Actions, Prompt Templates, and autonomous agent development.
+
+---
+
+## Overview
+
+Agentforce is Salesforce's autonomous AI agent platform (successor to Einstein Copilot). Agents can interact with users, trigger autonomously on events, and take actions grounded in live CRM data.
+
+### Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Agent** | AI entity (Service Agent, Sales Agent, Custom Agent) |
+| **Topic** | Category of tasks/intents the agent handles (e.g., "Order Management") |
+| **Action** | Tool the agent invokes — Standard, Flow, Apex, or Prompt Template |
+| **Atlas Reasoning Engine** | The AI planner that decides which actions to invoke based on natural language |
+| **Einstein Trust Layer** | Masks sensitive PII before sending data to LLM, audits all interactions |
+
+---
+
+## Architecture
+
+```
+User / Event Trigger
+        │
+        ▼
+┌──────────────────────┐
+│   Agentforce Agent   │
+│  (Supervisor / Child)│
+├──────────────────────┤
+│   Atlas Reasoning    │  ← Uses Topic descriptions + Action descriptions
+│      Engine          │     to decide what to do
+├──────────────────────┤
+│   Trust Layer        │  ← PII masking, audit logging, guardrails
+├──────────────────────┤
+│   Actions            │
+│  ┌────────────────┐  │
+│  │ Standard Action│  │  ← Out-of-the-box (e.g., Query Records)
+│  │ Flow Action    │  │  ← Triggered Flows / Screen Flows
+│  │ Apex Action    │  │  ← @InvocableMethod classes
+│  │ Prompt Template│  │  ← Prompt Builder templates
+│  └────────────────┘  │
+├──────────────────────┤
+│   Data Cloud         │  ← Grounding data, context
+└──────────────────────┘
+```
+
+---
+
+## Development Rules
+
+### 1. Declarative First
+
+Always check if a standard action or Flow can solve the problem before writing custom Apex.
+
+```
+Decision Tree:
+  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
+```
+
+### 2. Action Descriptions Are Critical
+
+The Atlas Reasoning Engine uses **natural language descriptions** to decide when to invoke actions. Poor descriptions = wrong action selection.
+
+```apex
+// ✅ GOOD — Clear, specific description
+@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, or engagement.'
+)
+public static List<Integer> getHealthScore(List<Id> accountIds) { ... }
+
+// ❌ BAD — Vague description
+@InvocableMethod(
+    label='Process Account'
+    description='Does account stuff'
+)
+```
+
+### 3. Apex Actions for Agentforce
+
+```apex
+/**
+ * @description Apex action for Agentforce to retrieve order status.
+ * Action: Invocable from Agentforce Topics.
+ */
+public with sharing class OrderStatusAction {
+
+    public class OrderStatusRequest {
+        @InvocableVariable(label='Order Number' description='The order number to look up' required=true)
+        public String orderNumber;
+    }
+
+    public class OrderStatusResponse {
+        @InvocableVariable(label='Status' description='Current order status')
+        public String status;
+
+        @InvocableVariable(label='Expected Delivery' description='Expected delivery date')
+        public Date expectedDelivery;
+
+        @InvocableVariable(label='Message' description='Human-readable status summary')
+        public String message;
+    }
+
+    @InvocableMethod(
+        label='Get Order Status'
+        description='Retrieves the current status and expected delivery date for a given order number. Use when customers ask about their order, shipment, or delivery.'
+    )
+    public static List<OrderStatusResponse> getOrderStatus(List<OrderStatusRequest> requests) {
+        // Bulkified implementation
+        List<OrderStatusResponse> responses = new List<OrderStatusResponse>();
+        Set<String> orderNumbers = new Set<String>();
+
+        for (OrderStatusRequest req : requests) {
+            orderNumbers.add(req.orderNumber);
+        }
+
+        Map<String, Order> orderMap = new Map<String, Order>();
+        for (Order o : [
+            SELECT Id, OrderNumber, Status, ExpectedDeliveryDate__c
+            FROM Order
+            WHERE OrderNumber IN :orderNumbers
+            WITH USER_MODE
+        ]) {
+            orderMap.put(o.OrderNumber, o);
+        }
+
+        for (OrderStatusRequest req : requests) {
+            OrderStatusResponse resp = new OrderStatusResponse();
+            Order o = orderMap.get(req.orderNumber);
+            if (o != null) {
+                resp.status = o.Status;
+                resp.expectedDelivery = o.ExpectedDeliveryDate__c;
+                resp.message = 'Order ' + o.OrderNumber + ' is ' + o.Status;
+            } else {
+                resp.message = 'Order not found: ' + req.orderNumber;
+            }
+            responses.add(resp);
+        }
+        return responses;
+    }
+}
+```
+
+### 4. Prompt Templates
+
+- Use **Prompt Builder** in Setup to create reusable prompt templates
+- Ground templates with **Data Cloud** merge fields for accurate, hallucination-resistant output
+- Test templates with different personas and edge cases
+
+### 5. Guardrails
+
+- Use **Agent Script** for mission-critical tasks (enforces if/then deterministic workflows)
+- Configure **Content Safety Policies** for output filtering
+- Enable **Audit Trails** in Command Center for monitoring
+
+---
+
+## Multi-Agent Orchestration
+
+```
+┌─────────────────────────┐
+│   Supervisor Agent      │  ← Single front door
+│   (routes to children)  │
+├─────────────────────────┤
+│                         │
+│  ┌───────┐ ┌──────────┐│
+│  │ Sales │ │ Service  ││
+│  │ Agent │ │ Agent    ││
+│  └───────┘ └──────────┘│
+│  ┌───────┐ ┌──────────┐│
+│  │ Custom│ │ Analytics││
+│  │ Agent │ │ Agent    ││
+│  └───────┘ └──────────┘│
+└─────────────────────────┘
+```
+
+- Use a **Supervisor Agent** as the entry point
+- Route to **specialist agents** based on Topic matching
+- Each child agent has its own Topics and Actions
+- Monitor via **Command Center**
+
+---
+
+## Testing Agentforce
+
+1. **Unit test** all `@InvocableMethod` classes like standard Apex
+2. **Test in Agent Builder** preview panel with sample conversations
+3. **Validate** action descriptions by checking if Atlas picks the correct action
+4. **Edge cases**: What happens when the action returns no data? Empty input? Error?
+
+---
+
+## Agentforce for Developers (A4D) Rules
+
+Salesforce recognizes `.sfdx/a4d/rules/*.md` files for AI coding assistant rules:
+
+```
+.sfdx/
+  a4d/
+    rules/
+      apex.md      ← Apex generation rules
+      html.md      ← LWC HTML template rules
+      css.md       ← Component CSS rules
+      js.md        ← LWC JavaScript rules
+```
+
+These are auto-detected by Agentforce for Developers during code generation. Consider mirroring your `.ai/prompts/` content here for A4D compatibility.