scc-universal 1.2.1 → 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/skills/sf-harness-audit/SKILL.md

@@ -24,7 +24,7 @@ Check what's installed in the current project:
 
 ```bash
 # Check for SCC installation markers
-ls -la .claude/hooks/ 2>/dev/null
+ls -la .claude/hooks/scripts/ 2>/dev/null
 ls -la .claude/agents/ 2>/dev/null
 ls -la .claude/skills/ 2>/dev/null
 ```
@@ -44,7 +44,7 @@ Rate each category 0-10 using these rubrics:
 | 7-8 | All standard profile hooks active |
 | 9-10 | Strict profile enabled, all hooks active including Code Analyzer integration |
 
-Check: `cat .claude/hooks/hooks.json | grep -c '"command"'` to count active hooks.
+Check: `npx scc-universal status` to see installed hooks and their profiles.
 Check: `echo $SCC_HOOK_PROFILE` to verify profile level.
 
 **Agent Coverage (0-10)**

package/.cursor/skills/sf-quickstart/SKILL.md

@@ -102,7 +102,7 @@ Based on the project state, suggest 3-5 commands to start with:
 | Low test coverage | `sf-apex-testing` skill -- analyze gaps |
 | Deployment files present | `sf-deployment` skill -- pre-deployment check |
 | Security review needed | `sf-security` skill -- full security audit |
-| Build errors | `/sf-build-fix` -- fix build and deployment errors |
+| Build errors | `sf-build-fix` -- fix build and deployment errors |
 | Any project | `/sf-help` -- browse all available commands and skills |
 
 ### Step 5 — Verify SCC Installation

package/.cursor-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/README.md

@@ -106,7 +106,8 @@ npx scc-universal uninstall    # Remove SCC-managed files
 |---|---|---|
 | Agents | `.claude/agents/*.md` | `.cursor/agents/*.md` |
 | Skills | `.claude/skills/*/SKILL.md` | `.cursor/skills/*/SKILL.md` |
-| Hooks | Merged into `.claude/settings.json` | `.cursor/hooks.json` |
+| Hooks (config) | Merged into `.claude/settings.json` | `.cursor/hooks.json` |
+| Hooks (scripts) | `.claude/hooks/scripts/`, `.claude/hooks/lib/` | `.cursor/hooks/scripts/`, `.cursor/hooks/lib/` |
 | MCP config | `.mcp.json` (project root) | `.cursor/mcp.json` |
 
 ### Install Profiles
@@ -420,52 +421,21 @@ Control which hooks run via the `SCC_HOOK_PROFILE` environment variable:
 
 ## Tips and Best Practices
 
-### Salesforce-Specific Workflows
+### Typical Workflows
 
-**New Feature Development:**
+**New Feature:** Describe what you want to build — sf-architect activates automatically, designs the solution, and delegates to domain agents (sf-apex-agent, sf-lwc-agent, sf-flow-agent) with TDD.
 
-1. `/blueprint` - Plan the implementation (metadata types, governor limits)
-2. `/sf-tdd-workflow` - Write tests first, then implement
-3. `/sf-apex-best-practices` - Review your code
-4. `/sf-deployment` - Deploy to target org
+**Bug Fix:** Describe the error — sf-bugfix-agent activates, diagnoses root cause, applies minimal fix.
 
-**Code Review:**
-
-1. `/sf-apex-best-practices` - Full review of uncommitted changes
-2. `/sf-security` - Security-focused audit
-3. `/sf-governor-limits` - Check for governor limit issues
-
-**Performance Optimization:**
-
-1. `/sf-soql-optimization` - Fix expensive queries
-2. `/sf-governor-limits` - Find limit violations
-3. Use the `sf-review-agent` for deep analysis
-
-### Context Window Management
-
-- Keep MCP servers minimal (SF CLI MCP + 2-3 others)
-- Use specific prompts: "Review AccountTrigger.cls" not "review everything"
-- Use `/compact` when context gets large
-
-### Parallel Workflows
-
-- Use `/fork` for non-overlapping tasks
-- Use git worktrees for parallel scratch org work:
-
-```bash
-git worktree add ../feature-branch feature-branch
-cd ../feature-branch
-sf org create scratch --alias feature-scratch
-```
+**Code Review:** Ask to review before deploy — sf-review-agent runs a full quality gate (security, governor limits, test coverage, deploy readiness).
 
 ### Key Principles
 
 1. **Governor limits are king** — Every agent checks for limit violations
 2. **Test-first approach** — 75% is the SF minimum, aim for 85%+
-3. **Use the right agent** — Specialized agents give better results than generic prompts
+3. **Be specific** — "Review AccountTrigger.cls" not "review everything"
 4. **Hook profiles matter** — Start with `standard`, move to `strict` for CI
-5. **Context is precious** — Be specific in prompts, disable unused MCPs
-6. **Security baked in** — CRUD/FLS and sharing model from the start
+5. **Security baked in** — CRUD/FLS and sharing model from the start
 
 ---
 

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/docs/ARCHITECTURE.md

@@ -117,9 +117,10 @@ npx scc-universal install all
     ├── Resolve component list for profile
     ├── Generate install plan (scripts/dev/install-plan.js)
     ├── Execute plan (scripts/cli/install-apply.js)
-    │   ├── Copy agents to target
-    │   ├── Copy skills to target
-    │   └── Register hooks
+    │   ├── Copy agents to target (.claude/agents/)
+    │   ├── Copy skills to target (.claude/skills/)
+    │   ├── Copy hook scripts + lib (.claude/hooks/scripts/, .claude/hooks/lib/)
+    │   └── Merge hook config into .claude/settings.json
     └── Update state store (scripts/lib/state-store.js)
 ```
 

package/docs/authoring-guide.md

@@ -360,7 +360,7 @@ Before submitting a pull request that adds new content, verify:
 - [ ] `async: true` is set unless the hook must block execution
 - [ ] `timeout` is set to a reasonable value
 - [ ] Test file is created in `tests/hooks/`
-- [ ] Cursor mirror is updated in `.cursor/hooks/` if applicable
+- [ ] Cursor hooks are auto-generated by `npm run build` (no manual mirror needed)
 - [ ] `node scripts/ci/validate-hooks.js` passes
 - [ ] `node tests/hooks/my-hook.test.js` passes
 

package/docs/hook-development.md

@@ -385,7 +385,7 @@ if (failCount > 0) process.exit(1);
 
 ### Step 4 -- Update the Cursor Mirror
 
-For Cursor IDE parity, add a corresponding hook in `.cursor/hooks/`. Cursor hooks use different lifecycle names but the adapter layer (`adapter.js`) maps them.
+For Cursor IDE parity, run `npm run build` to regenerate `.cursor/hooks.json`. The adapter layer maps Claude Code lifecycle events to Cursor equivalents automatically.
 
 | Claude Code Event | Cursor Equivalent |
 |---|---|

package/examples/agentforce-action/README.md

@@ -221,7 +221,7 @@ Flow: Case Creation from Chat
 
 ## SCC Skills
 
-- `/sf-agentforce-development` -- scaffold and review Agentforce actions
-- `/sf-apex-best-practices` -- review the action class for best practices
-- `/sf-tdd-workflow` -- write tests first, then implement the action
-- `/sf-governor-limits` -- check governor limit compliance in bulk scenarios
+- `sf-agentforce-development` -- scaffold and review Agentforce actions
+- `sf-apex-best-practices` -- review the action class for best practices
+- `sf-tdd-workflow` -- write tests first, then implement the action
+- `sf-governor-limits` -- check governor limit compliance in bulk scenarios

package/examples/devops-pipeline/README.md

@@ -319,7 +319,7 @@ jobs:
 
 ## SCC Skills
 
-- `/sf-deployment` -- validate and deploy metadata to a target org
-- `/sf-devops-ci-cd` -- CI/CD pipeline patterns with scratch orgs
-- `/sf-build-fix` -- diagnose and fix deployment failures
-- `/sf-apex-testing` -- run Apex tests with coverage analysis
+- `sf-deployment` -- validate and deploy metadata to a target org
+- `sf-devops-ci-cd` -- CI/CD pipeline patterns with scratch orgs
+- `sf-build-fix` -- diagnose and fix deployment failures
+- `sf-apex-testing` -- run Apex tests with coverage analysis

package/examples/integration-pattern/README.md

@@ -410,7 +410,7 @@ private class PaymentGatewayService_Test {
 
 ## SCC Skills
 
-- `/sf-security` -- verify Named Credential usage and no hardcoded secrets
-- `/sf-apex-best-practices` -- review callout service code for best practices
-- `/sf-tdd-workflow` -- write tests first using mock classes
-- `/sf-governor-limits` -- check callout limits in async and batch contexts
+- `sf-security` -- verify Named Credential usage and no hardcoded secrets
+- `sf-apex-best-practices` -- review callout service code for best practices
+- `sf-tdd-workflow` -- write tests first using mock classes
+- `sf-governor-limits` -- check callout limits in async and batch contexts

package/examples/platform-events/README.md

@@ -486,7 +486,7 @@ private class OrderEventPublisher_Test {
 
 ## SCC Skills
 
-- `/sf-platform-events-cdc` -- review Platform Event and CDC implementations
-- `/sf-apex-best-practices` -- review publisher and subscriber Apex code
-- `/sf-lwc-development` -- review the empApi subscription component
-- `/sf-governor-limits` -- check event publish limits and bulk compliance
+- `sf-platform-events-cdc` -- review Platform Event and CDC implementations
+- `sf-apex-best-practices` -- review publisher and subscriber Apex code
+- `sf-lwc-development` -- review the empApi subscription component
+- `sf-governor-limits` -- check event publish limits and bulk compliance

package/examples/security-audit/README.md

@@ -239,6 +239,6 @@ sf scanner run --target "force-app/" \
 
 ## SCC Skills
 
-- `/sf-security` -- run a comprehensive security audit on your codebase
-- `/sf-apex-best-practices` -- review Apex code including security best practices
-- `/sf-governor-limits` -- check for governor limit issues (overlaps with security for SOQL)
+- `sf-security` -- run a comprehensive security audit on your codebase
+- `sf-apex-best-practices` -- review Apex code including security best practices
+- `sf-governor-limits` -- check for governor limit issues (overlaps with security for SOQL)