scc-universal 1.2.1 → 1.3.0

package/.claude-plugin/plugin.json

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

package/.cursor/agents/sf-agentforce-agent.md

@@ -1,19 +1,22 @@
 ---
 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.
+  Build and test Agentforce AI agents — Agent Script, topics, Apex actions, metadata deployment. Use PROACTIVELY when building Agentforce. Do NOT use for standard Apex.
 model: inherit
 ---
 
-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.
@@ -23,16 +26,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 |
 |---|---|
@@ -40,9 +49,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 |
@@ -50,72 +66,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/.cursor/skills/prompt-optimizer/SKILL.md

@@ -93,13 +93,13 @@ Map intent + scope + tech stack (from Phase 0) to specific SCC components.
 
 | Intent | Invocable Skills | Skills | Agents |
 |--------|----------|--------|--------|
-| New Feature | /sf-tdd-workflow, /sf-apex-best-practices | sf-apex-best-practices, sf-apex-enterprise-patterns | sf-architect, sf-apex-agent, sf-review-agent |
-| Bug Fix | /sf-tdd-workflow, /sf-build-fix | sf-apex-testing, sf-debugging | sf-bugfix-agent, sf-apex-agent |
-| Refactor | /refactor-clean, /sf-apex-best-practices | sf-trigger-frameworks, sf-apex-enterprise-patterns | refactor-cleaner, sf-review-agent |
-| Testing | /sf-tdd-workflow, /sf-apex-testing, /sf-e2e-testing | sf-apex-testing, sf-tdd-workflow | sf-apex-agent |
-| Review | /sf-apex-best-practices, /sf-lwc-development, /sf-security | sf-security | sf-review-agent, sf-review-agent |
+| New Feature | sf-tdd-workflow, sf-apex-best-practices | sf-apex-best-practices, sf-apex-enterprise-patterns | sf-architect, sf-apex-agent, sf-review-agent |
+| Bug Fix | sf-tdd-workflow, sf-build-fix | sf-apex-testing, sf-debugging | sf-bugfix-agent, sf-apex-agent |
+| Refactor | /refactor-clean, sf-apex-best-practices | sf-trigger-frameworks, sf-apex-enterprise-patterns | refactor-cleaner, sf-review-agent |
+| Testing | sf-tdd-workflow, sf-apex-testing, sf-e2e-testing | sf-apex-testing, sf-tdd-workflow | sf-apex-agent |
+| Review | sf-apex-best-practices, sf-lwc-development, sf-security | sf-security | sf-review-agent, sf-review-agent |
 | Documentation | /update-docs | — | doc-updater, deep-researcher |
-| Infrastructure | /sf-deployment | sf-devops-ci-cd, sf-deployment | sf-architect |
+| Infrastructure | sf-deployment | sf-devops-ci-cd, sf-deployment | sf-architect |
 | Design (EPIC) | — | — | sf-architect, sf-architect |
 
 #### By Tech Stack
@@ -161,7 +161,7 @@ For tasks that exceed a single session, split into sequential prompts:
 
 - Prompt 1: Research + Plan (use search-first skill, then sf-architect agent)
 - Prompt 2-N: Implement one phase per prompt (each ends with sf-review-agent agent)
-- Final Prompt: Integration test + /sf-apex-best-practices across all phases
+- Final Prompt: Integration test + sf-apex-best-practices across all phases
 - Use /save-session and /resume-session to preserve context between sessions
 
 ---
@@ -188,7 +188,7 @@ If Phase 0 auto-detected the answer, state it instead of asking.
 
 | Type | Component | Purpose |
 |------|-----------|---------|
-| Command | /sf-tdd-workflow | TDD workflow for Apex |
+| Command | sf-tdd-workflow | TDD workflow for Apex |
 | Skill | sf-apex-best-practices | Apex coding standards |
 | Agent | sf-review-agent | Post-implementation review |
 | Model | Sonnet | Recommended for this scope |
@@ -206,7 +206,7 @@ The prompt must be self-contained and ready to copy-paste. Include:
 - Scope boundaries (what NOT to do)
 
 For items that reference blueprint, write: "Use the sf-architect agent to..."
-(not `/blueprint`, since sf-architect is an agent, not a command).
+(not `sf-architect agent`, since sf-architect is an agent, not a command).
 
 ### Section 4: Optimized Prompt — Quick Version
 
@@ -214,12 +214,12 @@ A compact version for experienced SCC users. Vary by intent type:
 
 | Intent | Quick Pattern |
 |--------|--------------|
-| New Feature | `Use sf-architect agent for [feature]. /sf-tdd-workflow to implement. /sf-apex-best-practices. Use sf-review-agent agent.` |
-| Bug Fix | `/sf-tdd-workflow — write failing test for [bug]. Fix to green. Use sf-review-agent agent.` |
-| Refactor | `/refactor-clean [scope]. /sf-apex-best-practices. Use sf-review-agent agent.` |
+| New Feature | `Use sf-architect agent for [feature]. sf-tdd-workflow to implement. sf-apex-best-practices. Use sf-review-agent agent.` |
+| Bug Fix | `sf-tdd-workflow — write failing test for [bug]. Fix to green. Use sf-review-agent agent.` |
+| Refactor | `/refactor-clean [scope]. sf-apex-best-practices. Use sf-review-agent agent.` |
 | Research | `Use search-first skill for [topic]. Use sf-architect agent based on findings.` |
-| Testing | `/sf-tdd-workflow [class]. /sf-e2e-testing for critical flows. /sf-apex-testing.` |
-| Review | `/sf-apex-best-practices. Then use sf-review-agent agent.` |
+| Testing | `sf-tdd-workflow [class]. sf-e2e-testing for critical flows. sf-apex-testing.` |
+| Review | `sf-apex-best-practices. Then use sf-review-agent agent.` |
 | Docs | `/update-docs. Use deep-researcher agent.` |
 | EPIC | `Use sf-architect agent for "[objective]". Execute phases with sf-review-agent agent gates.` |
 
@@ -267,9 +267,9 @@ Technical requirements:
 
 Workflow:
 1. Use sf-architect agent to plan trigger handler structure and business logic
-2. /sf-tdd-workflow — write failing test class first (use @TestSetup and test data factory)
+2. sf-tdd-workflow — write failing test class first (use @TestSetup and test data factory)
 3. Implement AccountTrigger and AccountTriggerHandler
-4. /sf-apex-best-practices to review implementation
+4. sf-apex-best-practices to review implementation
 5. Use sf-review-agent agent to verify all tests pass and coverage reaches 75%+
 
 Security requirements:
@@ -279,7 +279,7 @@ Security requirements:
 Acceptance criteria:
 - Test coverage 85%+
 - Zero governor limit violations
-- Passes /sf-security review
+- Passes sf-security review
 ```
 
 ### Example 2: Moderate English Prompt
@@ -309,10 +309,10 @@ Requirements:
 
 Workflow:
 1. Use sf-architect agent for the endpoint structure, validation logic, and error response envelope
-2. /sf-tdd-workflow — write tests for success, validation failure, permission failure
+2. sf-tdd-workflow — write tests for success, validation failure, permission failure
 3. Implement AccountAPI class following existing REST patterns
-4. /sf-security — verify CRUD/FLS enforcement
-5. /sf-apex-best-practices
+4. sf-security — verify CRUD/FLS enforcement
+5. sf-apex-best-practices
 6. Use sf-review-agent agent — run full test suite, confirm no regressions
 
 Do not:
@@ -342,7 +342,7 @@ Before executing, answer these questions in the blueprint:
 The blueprint should produce phases like:
 - Phase 1: Audit all existing triggers and document business logic
 - Phase 2: Implement TriggerHandler base class and factory
-- Phase 3: Migrate highest-priority object triggers with /sf-tdd-workflow gates
+- Phase 3: Migrate highest-priority object triggers with sf-tdd-workflow gates
 - Phase 4: Migrate remaining triggers
 - Phase N: Remove legacy trigger code, run full regression
 

package/.cursor/skills/sf-2gp-security-review/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: sf-2gp-security-review
+description: >-
+  Use when user asks for a 2GP security review, AppExchange readiness check, or pass/fail prediction for Apex, LWC, SOQL. Do NOT use for general security patterns.
+disable-model-invocation: true
+---
+
+# Salesforce 2GP Managed Package Security Review
+
+## When to Use
+
+- User asks for a 2GP managed package security review or AppExchange readiness assessment
+- User wants a pass/fail prediction for their managed package security review submission
+- User needs a 2GP license qualification checklist or submission readiness scoring
+
+This skill performs a comprehensive security review of a Salesforce 2GP managed package,
+assesses readiness for AppExchange security review, and produces a pass/fail prediction
+with actionable remediation steps.
+
+## How This Skill Works
+
+When invoked, you will:
+
+1. **Discover** the package structure (scan for Apex, LWC, objects, permissions, config)
+2. **Audit** every file against the security review criteria below
+3. **Score** each category (PASS / WARN / FAIL)
+4. **Produce** a structured report with an overall pass/fail prediction and remediation plan
+
+The output is a detailed markdown report saved to the project's `docs/security/` directory.
+
+---
+
+## Step 1 — Package Discovery
+
+Before auditing, build a complete inventory of the package contents. Run these searches
+against the project's `force-app/` directory:
+
+```
+Apex classes:      force-app/**/classes/*.cls
+Apex triggers:     force-app/**/triggers/*.trigger
+LWC components:    force-app/**/lwc/*/
+Aura components:   force-app/**/aura/*/
+Visualforce pages: force-app/**/pages/*.page
+Custom objects:    force-app/**/objects/*/
+Permission sets:   force-app/**/permissionsets/*/
+Custom metadata:   force-app/**/customMetadata/*/
+Static resources:  force-app/**/staticresources/*/
+Named credentials: force-app/**/namedCredentials/*/
+Remote site settings: force-app/**/remoteSiteSettings/*/
+Connected apps:    force-app/**/connectedApps/*/
+```
+
+Record the count of each metadata type. This inventory becomes the header of your report.
+
+---
+
+## Step 2 — Security Audit Categories
+
+Audit every file from Step 1 against 15 categories. For each category, assign a status:
+PASS (no issues), WARN (minor issues, unlikely to fail review), or FAIL (will likely
+fail AppExchange security review).
+
+Audit criteria, grep patterns, and PASS/WARN/FAIL thresholds for all 15 categories:
+
+@../_reference/APPEXCHANGE_REVIEW.md
+
+Supporting reference for implementation patterns:
+
+- CRUD/FLS, sharing, injection, XSS, Named Credentials: @../_reference/SECURITY_PATTERNS.md
+- Sharing model details: @../_reference/SHARING_MODEL.md
+- Testing standards and annotations: @../_reference/TESTING_STANDARDS.md
+- Namespace, versioning, package CLI: @../_reference/PACKAGE_DEVELOPMENT.md
+- Governor limits and anti-patterns: @../_reference/GOVERNOR_LIMITS.md
+- LWC lifecycle and patterns: @../_reference/LWC_PATTERNS.md
+
+**Categories:**
+
+1. CRUD/FLS Enforcement (CRITICAL — #1 failure reason)
+2. Sharing Model Enforcement
+3. SOQL/DML Injection Prevention
+4. Sensitive Data Exposure
+5. XSS and Content Security Policy
+6. External Callout Security
+7. Third-Party Library Vulnerabilities
+8. Code Coverage
+9. Namespace and Packaging Compliance
+10. Permission Model
+11. Governor Limit Safety
+12. Lightning Web Security (LWS) Compliance
+13. Connected App and OAuth Configuration
+14. Data at Rest and in Transit
+15. Documentation and Submission Readiness
+
+---
+
+## Step 3 — 2GP License Qualification Checklist
+
+After the security audit, assess readiness for 2GP licensing and AppExchange distribution.
+Check every item and mark as DONE, NOT DONE, or N/A.
+
+Full checklist (Dev Hub, package config, code quality, submission, ISV, post-review):
+
+@../_reference/APPEXCHANGE_REVIEW.md (section: 2GP License Qualification Checklist)
+
+---
+
+## Step 4 — Pass/Fail Prediction
+
+After completing the audit and checklist, calculate the overall score using the scoring
+rules and produce one of these verdicts: READY TO SUBMIT / NEEDS REMEDIATION / MAJOR
+REWORK NEEDED.
+
+Scoring rules and verdict criteria:
+
+@../_reference/APPEXCHANGE_REVIEW.md (section: Scoring Rules)
+
+---
+
+## Step 5 — Report Output
+
+Generate a markdown report with this structure and save it to `docs/security/security-review-report.md`:
+
+```markdown
+# Security Review Report — [Package Name]
+Generated: [Date]
+Package Version: [version from sfdx-project.json]
+Namespace: [namespace]
+
+## Package Inventory
+| Metadata Type | Count |
+|--------------|-------|
+| Apex Classes | X |
+| ... | ... |
+
+## Security Audit Results
+### Overall Verdict: [READY TO SUBMIT / NEEDS REMEDIATION / MAJOR REWORK]
+Score: X/15 categories passing
+
+### Category Results
+| # | Category | Status | Issues |
+|---|----------|--------|--------|
+| 1 | CRUD/FLS Enforcement | PASS/WARN/FAIL | Details |
+| ... | ... | ... | ... |
+
+### Critical Findings (FAIL)
+[List each FAIL with file path, line number, and specific remediation]
+
+### Warnings
+[List each WARN with recommendation]
+
+## 2GP License Qualification
+[Checklist with DONE/NOT DONE status for each item]
+
+## Remediation Plan
+[Prioritized list of fixes, ordered by: automatic fails first, then likely fails, then warnings]
+
+## Appendix: Scanner Commands
+[Commands the user should run for Code Analyzer, Checkmarx, etc.]
+```
+
+---
+
+## Related
+
+- Scanner commands: @../_reference/APPEXCHANGE_REVIEW.md (section: Scanner Commands)
+- Top 20 failures: @../_reference/APPEXCHANGE_REVIEW.md (section: Top 20 Failures)
+- 2026 platform changes: @../_reference/APPEXCHANGE_REVIEW.md (section: 2026 Considerations)