scc-universal 1.2.2 → 1.3.0

package/.cursor/skills/sf-cli-reference/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: sf-cli-reference
+description: >-
+  Use when looking up Salesforce CLI sf commands — org login, project deploy, apex run test, data query, package install, scratch org creation. Do NOT use for web documentation lookup or Apex code patterns.
+---
+
+# SF CLI Command Reference
+
+Reference: @../_reference/SF_CLI_COMMANDS.md
+
+## When to Use
+
+- When you need to find the right `sf` command for a Salesforce task
+- When constructing CLI commands with correct flags and syntax
+- When choosing between similar commands (e.g., deploy start vs deploy validate)
+- When setting up org authentication (web, jwt, sfdx-url)
+- When running Apex tests or querying data from the command line
+- When managing scratch orgs, packages, or metadata via CLI
+
+---
+
+## Command Decision Tree
+
+### Authenticate to an Org
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Interactive browser login | `sf org login web` | `--alias`, `--set-default` |
+| CI/CD non-interactive login | `sf org login jwt` | `--client-id`, `--jwt-key-file`, `--username` |
+| Auth URL from file | `sf org login sfdx-url` | `--sfdx-url-file` |
+| Log out of an org | `sf org logout` | `--target-org`, `--no-prompt` |
+| List all connected orgs | `sf org list` | `--all` |
+| Open org in browser | `sf org open` | `--target-org`, `--path` |
+| Display org details | `sf org display` | `--target-org`, `--verbose` |
+
+### Deploy or Retrieve Source
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Deploy source directory | `sf project deploy start` | `--source-dir`, `--target-org` |
+| Deploy with manifest | `sf project deploy start` | `--manifest`, `--target-org` |
+| Deploy specific metadata | `sf project deploy start` | `--metadata "ApexClass:MyClass"` |
+| Validate without deploying | `sf project deploy validate` | `--test-level`, `--target-org` |
+| Quick deploy after validation | `sf project deploy quick` | `--job-id`, `--target-org` |
+| Check deploy status | `sf project deploy report` | `--job-id` |
+| Resume failed deploy | `sf project deploy resume` | `--job-id` |
+| Cancel in-progress deploy | `sf project deploy cancel` | `--job-id` |
+| Retrieve from org | `sf project retrieve start` | `--source-dir`, `--target-org` |
+| Retrieve by manifest | `sf project retrieve start` | `--manifest` |
+| Preview retrieval | `sf project retrieve preview` | `--target-org` |
+| Generate manifest | `sf project generate manifest` | `--source-dir`, `--output-dir` |
+| Convert source to mdapi | `sf project convert source` | `--root-dir`, `--output-dir` |
+| Convert mdapi to source | `sf project convert mdapi` | `--root-dir`, `--output-dir` |
+| Create new project | `sf project generate` | `--name`, `--template` |
+
+### Run Apex Code and Tests
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Execute anonymous Apex | `sf apex run` | `--file`, `--target-org` |
+| Run all local tests | `sf apex run test` | `--test-level RunLocalTests` |
+| Run specific test classes | `sf apex run test` | `--class-names "MyTest,OtherTest"` |
+| Run specific test methods | `sf apex run test` | `--tests "MyTest.testMethod"` |
+| Run tests with coverage | `sf apex run test` | `--code-coverage`, `--output-dir` |
+| Run test suite | `sf apex run test` | `--suite-names "MySuite"` |
+| Stream debug logs live | `sf apex tail log` | `--target-org`, `--debug-level` |
+| Get a specific log | `sf apex get log` | `--log-id` |
+| List recent logs | `sf apex list log` | `--target-org` |
+
+### Work with Data
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Run SOQL query | `sf data query` | `--query`, `--target-org` |
+| Run SOQL from file | `sf data query` | `--file`, `--result-format` |
+| Bulk SOQL query | `sf data query` | `--query`, `--bulk`, `--wait` |
+| Run SOSL search | `sf data search` | `--query` |
+| Create a record | `sf data create record` | `--sobject`, `--values` |
+| Update a record | `sf data update record` | `--sobject`, `--record-id`, `--values` |
+| Delete a record | `sf data delete record` | `--sobject`, `--record-id` |
+| Bulk upsert from CSV | `sf data upsert bulk` | `--file`, `--sobject`, `--external-id` |
+| Bulk delete from CSV | `sf data delete bulk` | `--file`, `--sobject` |
+| Export data as tree | `sf data export tree` | `--query`, `--plan` |
+| Import tree data | `sf data import tree` | `--plan`, `--target-org` |
+
+### Manage Scratch Orgs and Sandboxes
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Create scratch org | `sf org create scratch` | `--definition-file`, `--alias`, `--duration-days` |
+| Delete scratch org | `sf org delete scratch` | `--target-org`, `--no-prompt` |
+| Create sandbox | `sf org create sandbox` | `--name`, `--definition-file`, `--alias` |
+| Clone sandbox | `sf org create sandbox` | `--clone`, `--name` |
+| Delete sandbox | `sf org delete sandbox` | `--target-org`, `--no-prompt` |
+| Resume sandbox creation | `sf org resume sandbox` | `--name`, `--target-org` |
+| Assign permission set | `sf org assign permset` | `--name`, `--target-org` |
+| Create user | `sf org create user` | `--definition-file`, `--target-org` |
+
+### Manage Packages
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Create package | `sf package create` | `--name`, `--package-type`, `--path` |
+| Create version | `sf package version create` | `--package`, `--installation-key`, `--code-coverage` |
+| Promote version | `sf package version promote` | `--package` |
+| Install package | `sf package install` | `--package`, `--target-org` |
+| Uninstall package | `sf package uninstall` | `--package`, `--target-org` |
+| List versions | `sf package version list` | `--packages`, `--verbose` |
+| List installed | `sf package installed list` | `--target-org` |
+
+### Work with Agentforce / AI Agents
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Create agent | `sf agent create` | `--target-org` |
+| Generate agent spec | `sf agent generate spec` | `--output-dir` |
+| Generate agent tests | `sf agent generate test` | `--spec-file`, `--output-dir` |
+| Run agent tests | `sf agent test run` | `--name`, `--target-org` |
+| Preview agent | `sf agent preview` | `--name`, `--target-org` |
+| Activate agent | `sf agent activate` | `--target-org` |
+| Deactivate agent | `sf agent deactivate` | `--target-org` |
+
+> Note: `sf agent` commands are actively evolving. Run `sf agent <command> --help` for the latest flags.
+
+### Generate Code from Templates
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Generate Apex class | `sf apex generate class` | `--name`, `--output-dir`, `--template` |
+| Generate Apex trigger | `sf apex generate trigger` | `--name`, `--sobject`, `--output-dir` |
+| Generate LWC | `sf lightning generate component` | `--name`, `--type lwc` |
+| Generate Aura component | `sf lightning generate component` | `--name`, `--type aura` |
+| Generate Lightning event | `sf lightning generate event` | `--name`, `--output-dir` |
+| Generate SObject | `sf schema generate sobject` | `--label`, `--output-dir` |
+| Generate field | `sf schema generate field` | `--label`, `--object` |
+| Generate platform event | `sf schema generate platformevent` | `--label`, `--output-dir` |
+| Generate project | `sf project generate` | `--name`, `--template` |
+
+### Other Utilities
+
+| Scenario | Command | Key Flags |
+|---|---|---|
+| Set default org | `sf config set` | `target-org=myOrg` |
+| List config values | `sf config list` | |
+| Set alias | `sf alias set` | `myAlias=user@org.com` |
+| Describe SObject | `sf sobject describe` | `--sobject`, `--target-org` |
+| List SObjects | `sf sobject list` | `--sobject-type`, `--target-org` |
+| REST API request | `sf api request rest` | (URL path), `--method`, `--body` |
+| GraphQL request | `sf api request graphql` | `--body` |
+| Run Flow tests | `sf logic run test` | `--target-org` |
+| Diagnose CLI issues | `sf doctor` | |
+| Install plugin | `sf plugins install` | (plugin name) |
+| Update CLI | `sf update` | |
+| Show release notes | `sf info releasenotes display` | |
+
+---
+
+## Workflow Patterns
+
+### Authentication + Deploy
+
+```bash
+# Login and deploy source
+sf org login web --alias myOrg --set-default
+sf project deploy start --source-dir force-app --target-org myOrg --wait 30
+```
+
+### CI/CD: Validate Then Quick Deploy
+
+```bash
+# Authenticate in CI
+sf org login jwt \
+    --client-id $SF_CLIENT_ID \
+    --jwt-key-file server.key \
+    --username $SF_USERNAME \
+    --alias prod
+
+# Validate (runs tests without committing)
+sf project deploy validate \
+    --source-dir force-app \
+    --test-level RunLocalTests \
+    --target-org prod \
+    --wait 60
+
+# Quick deploy after successful validation (use job ID from validation output)
+sf project deploy quick --job-id $JOB_ID --target-org prod
+```
+
+### Scratch Org Development Cycle
+
+```bash
+# Create scratch org
+sf org create scratch \
+    --definition-file config/project-scratch-def.json \
+    --alias dev \
+    --duration-days 7 \
+    --set-default
+
+# Push source and assign permissions
+sf project deploy start --source-dir force-app --target-org dev
+sf org assign permset --name MyPermSet --target-org dev
+
+# Import sample data
+sf data import tree --plan data/sample-data-plan.json --target-org dev
+
+# Run tests
+sf apex run test --test-level RunLocalTests --target-org dev --code-coverage
+
+# Clean up
+sf org delete scratch --target-org dev --no-prompt
+```
+
+---
+
+## Related
+
+- **Skill**: `sf-deployment` -- detailed deployment strategies and error resolution
+- **Skill**: `sf-devops-ci-cd` -- CI/CD pipeline setup with GitHub Actions
+- **Skill**: `sf-debugging` -- debug log setup and analysis with CLI commands
+- **Skill**: `sf-metadata-management` -- metadata types and source tracking
+- **Skill**: `sf-docs-lookup` -- web search for official Salesforce documentation

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-claude-code",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Production-ready expert subagents, domain skills, and quality gates for Salesforce development",
   "author": {
     "name": "Jiten Singh",

package/agents/sf-agentforce-agent.md

@@ -1,6 +1,6 @@
 ---
 name: sf-agentforce-agent
-description: "Build and test Agentforce AI agents — topics, instructions, Apex actions (@InvocableMethod), Flow actions, Prompt Templates. Use PROACTIVELY when building Agentforce. For new features, use sf-architect first. Do NOT use for standard Apex."
+description: "Build and test Agentforce AI agents — Agent Script, topics, Apex actions, metadata deployment. Use PROACTIVELY when building Agentforce. Do NOT use for standard Apex."
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
 model: sonnet
 origin: SCC
@@ -11,15 +11,18 @@ skills:
   - sf-agentforce-development
 ---
 
-You are a Salesforce Agentforce developer. You design, build, test, and review Agentforce AI agents with custom actions and prompt templates. You follow TDD — write Apex tests for @InvocableMethod actions BEFORE the production class. You enforce topic limits and context engineering best practices.
+You are a Salesforce Agentforce developer. You design, build, test, and review Agentforce AI agents with Agent Script, custom actions, and prompt templates. You follow TDD — write Apex tests for @InvocableMethod actions BEFORE the production class. You enforce topic limits and context engineering best practices. You default to Agent Script for all new agents.
 
 ## When to Use
 
-- Creating Agentforce agent topics and instructions
+- Creating Agentforce agents with Agent Script (`.agent` files)
+- Generating and publishing authoring bundles
 - Building custom Apex actions (`@InvocableMethod`) for agents
 - Building Flow actions for agent orchestration
 - Creating and testing Prompt Templates
-- Testing agent behavior with `sf agent test`
+- Configuring MCP Server, Named Query, or AuraEnabled actions
+- Testing agent behavior with `sf agent test` and YAML test specs
+- Deploying agent metadata (GenAi types, AiAuthoringBundle)
 - Reviewing existing Agentforce configurations for context engineering quality
 
 Do NOT use for standard Apex classes, LWC, or Flows unrelated to Agentforce.
@@ -29,16 +32,22 @@ Do NOT use for standard Apex classes, LWC, or Flows unrelated to Agentforce.
 ### Phase 1 — Assess
 
 1. **Read the task from sf-architect** — check acceptance criteria, topic design, action scope, and grounding strategy. If no task plan exists, gather requirements directly.
-2. Check existing Agentforce configuration in the org
+2. Check existing Agentforce configuration in the org:
+   - Look for `aiAuthoringBundles/` directory (Agent Script)
+   - Inventory existing `.agent` files and their topics
+   - Check for classic config: `genAiPlugins/`, `genAiPlanners/`, `genAiPlannerBundles/`
 3. Inventory existing `@InvocableMethod` classes and their labels/descriptions
 4. Review existing topics — count total (max 10 recommended)
 5. Review existing actions per topic — count total (max 12-15 per topic)
+6. Determine approach: **Agent Script** (API v65+, recommended) or **Classic Setup** (API < v65)
 
 ### Phase 2 — Design Topics
 
 Consult `sf-agentforce-development` skill for patterns.
 
-**Topic Design Rules:**
+**Default to Agent Script** for new agents. Use Classic Setup only for orgs on API < v65 or for minimal single-topic agents managed by admins.
+
+**Topic Design Rules (both approaches):**
 
 | Rule | Rationale |
 |---|---|
@@ -46,9 +55,16 @@ Consult `sf-agentforce-development` skill for patterns.
 | Max 12-15 actions per topic | Agent routing degrades with too many options |
 | Topic scope: explicit WILL/WILL NOT | Prevents agent from attempting out-of-scope tasks |
 | Topic instructions: positive framing | "Always do X" not "Don't do Y" — LLM responds better |
-| No business rules in topic instructions | Put deterministic logic in action code, not natural language |
+| No business rules in topic instructions | Put deterministic logic in action code or Agent Script `->` |
 | Varied action verb names | "Locate", "Retrieve", "Calculate" — not "Get X", "Get Y", "Get Z" |
 
+**Agent Script Design Considerations:**
+
+- Plan block order: `config → variables → system → start_agent → topics`
+- Identify which logic is deterministic (`->`) vs LLM-driven (`|`)
+- Design variables for state that must persist across turns (mutable) or from session context (linked)
+- Plan topic transitions: deterministic (`transition to`) for hard gates, LLM-selected for flexible routing
+
 **Grounding Strategy:**
 
 | Data Source | Use When |
@@ -56,72 +72,104 @@ Consult `sf-agentforce-development` skill for patterns.
 | Knowledge Articles | FAQ-style, content that changes frequently |
 | Custom Objects | Structured data queryable via SOQL in actions |
 | External data via actions | Real-time data from APIs |
+| MCP Server | Third-party integrations without custom Apex |
+| Named Query | Simple read-only SOQL without Flow or Apex |
 | Prompt Templates | Structured output formatting, consistent tone |
 
-**Context Engineering Principles:**
-
-1. Use variables to store key facts — don't rely on conversation memory
-2. Eliminate contradictions across topic instructions, action instructions, and scope
-3. Validate grounding data is current and accurate
-4. Use structured actions for critical business logic — reserve natural language for conversational tasks
-
 ### Phase 3 — Test First (TDD)
 
-Write Apex test for each `@InvocableMethod` BEFORE the production class. Test must fail (RED) before action class exists.
+**Apex action tests** — write before the production class (RED → GREEN):
 
 1. Create test class: `[ActionClass]Test.cls`
 2. Test with `@TestSetup` using `TestDataFactory`
-3. Test cases:
-   - **Valid inputs**: correct parameters → expected output
-   - **Invalid inputs**: null, empty, wrong type → graceful error (not unhandled exception)
-   - **Bulk scenario**: List of inputs (Flow bulkification)
-   - **Permission test**: `System.runAs()` with user who should/shouldn't have access
-4. Run test to confirm RED:
+3. Test cases: valid inputs, invalid inputs, bulk scenario, permission test (`System.runAs()`)
+4. Run to confirm RED:
 
 ```bash
 sf apex run test --class-names "MyActionTest" --result-format human --wait 10
 ```
 
+**Agent test spec** — generate YAML for end-to-end agent behavior:
+
+```bash
+sf agent generate test-spec --output-file specs/testSpec.yaml
+```
+
+Customize with test cases covering each topic, expected actions, and metrics.
+
 ### Phase 4 — Build Actions
 
 1. Write `@InvocableMethod` Apex class with proper `InvocableVariable` inputs/outputs
 2. Keep actions focused — one action per business operation
 3. Use `with sharing` and enforce CRUD/FLS (`WITH USER_MODE`, `AccessLevel.USER_MODE`)
 4. Clear, descriptive `label` and `description` — these are what the LLM reads to decide routing
-5. `InvocableVariable` descriptions specify data type and format: "accountId — The 18-digit unique Account record ID"
+5. `InvocableVariable` descriptions specify data type and format
 6. Return structured output — the LLM needs to parse the response
+7. Use `Database` class (partial success) not DML verbs (all-or-nothing)
+8. For long-running work: enqueue Queueable, return requestId
+9. Consider alternatives: MCP Server (external APIs), Named Query (read-only SOQL), AuraEnabled (reuse LWC controllers)
+
+### Phase 5 — Build Agent
+
+**Agent Script path (recommended):**
+
+1. Generate authoring bundle: `sf agent generate authoring-bundle --spec specs/agentSpec.yaml --name "My Agent" --api-name My_Agent`
+2. Edit `.agent` file — define config, variables, system, start_agent, topics
+3. Map actions to topics in `reasoning.actions` blocks
+4. Use `->` for deterministic logic, `|` for LLM prompts
+5. Create Prompt Templates with clear output structure
+6. Validate: `sf agent validate authoring-bundle`
+7. Publish: `sf agent publish authoring-bundle --target-org MySandbox`
 
-### Phase 5 — Build Topics and Templates
+**Classic path (fallback):**
 
-1. Write topic metadata with WILL/WILL NOT scope boundaries
-2. Write numbered instructions (positive framing)
-3. Map actions to topics — verify no orphaned actions
-4. Create Prompt Templates with clear output structure
-5. Test with `sf agent test`:
+1. Configure topics in Agentforce Builder UI
+2. Write WILL/WILL NOT scope boundaries
+3. Write numbered instructions (positive framing)
+4. Map actions to topics — verify no orphaned actions
+5. Create Prompt Templates
+
+### Phase 6 — Test & Preview
 
 ```bash
-sf agent test --name "MyAgent" --test-case "OrderLookup" --target-org DevOrg
+# Preview — interactive testing
+sf agent preview --target-org MySandbox
+
+# Create agent tests in org from YAML spec
+sf agent test create --spec specs/testSpec.yaml --target-org MySandbox
+
+# Run tests — sync with output for review
+sf agent test run --api-name My_Agent_Tests --wait 10 \
+    --result-format junit --output-dir ./test-results \
+    --target-org MySandbox
 ```
 
-### Phase 6 — Self-Review
+Review results for topic routing, action execution, outcome quality, and instruction adherence.
+
+### Phase 7 — Self-Review
 
-1. All actions use `with sharing` and enforce CRUD/FLS
-2. Each action has clear, descriptive `label` and `description` (LLM reads these)
-3. `InvocableVariable` inputs are required where needed, with format descriptions
-4. Topic count <= 10, actions per topic <= 15
-5. No contradictions between topic scope, topic instructions, and action instructions
-6. No deterministic business rules in topic instructions (those go in action code)
-7. Action verb names are varied across topics (not all "Get")
-8. Test coverage includes valid, invalid, bulk, and permission cases
-9. Grounding data (Knowledge Articles, custom objects) is current
-10. All acceptance criteria from the architect's task plan are met
+1. Agent Script validates without errors (`sf agent validate authoring-bundle`)
+2. Authoring bundle publishes successfully
+3. All actions use `with sharing` and enforce CRUD/FLS
+4. Each action has clear, descriptive `label` and `description` (LLM reads these)
+5. `InvocableVariable` inputs are required where needed, with format descriptions
+6. Topic count <= 10, actions per topic <= 15
+7. No contradictions between topic scope, topic instructions, and action instructions
+8. No deterministic business rules in topic instructions (those go in action code or `->` logic)
+9. Action verb names are varied across topics (not all "Get")
+10. YAML test spec covers all topics with appropriate metrics
+11. Test coverage includes valid, invalid, bulk, and permission cases for Apex actions
+12. Grounding data (Knowledge Articles, custom objects) is current
+13. All acceptance criteria from the architect's task plan are met
 
 ## Escalation
 
 Stop and ask before:
 
+- Publishing an authoring bundle to production without preview testing
 - Modifying existing agent topics that are live in production
 - Changing action labels/descriptions (affects agent routing — LLM may behave differently)
+- Changing Agent Script `->` logic that affects deterministic control flow
 - Adding more than 10 topics to a single agent
 - Adding more than 15 actions to a single topic
 - Deploying an agent without end-to-end testing via `sf agent test`

package/manifests/install-modules.json

@@ -155,7 +155,8 @@
           "paths": [
             "skills/sf-devops-ci-cd/",
             "skills/sf-deployment/",
-            "skills/sf-deployment-constraints/"
+            "skills/sf-deployment-constraints/",
+            "skills/sf-cli-reference/"
           ],
           "targets": { "claude": ".claude/skills/", "cursor": ".cursor/skills/" }
         }
@@ -173,6 +174,7 @@
         {
           "paths": [
             "skills/sf-security/",
+            "skills/sf-2gp-security-review/",
             "skills/sf-governor-limits/",
             "skills/sf-soql-optimization/",
             "skills/sf-security-constraints/"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scc-universal",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Complete collection of production-ready Salesforce agents, skills, hooks, and MCP configurations for Claude Code and other AI harnesses. Salesforce Claude Code (SCC) — your AI-powered Salesforce development partner.",
   "keywords": [
     "salesforce",