scc-universal 1.1.0

package/.cursor/skills/strategic-compact/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: strategic-compact
+description: >-
+  Use when managing context during long Salesforce Apex development sessions. Suggests manual compaction at logical intervals to preserve deploy and org context across phases.
+---
+
+# Strategic Compact Skill
+
+Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
+
+## When to Use
+
+- When running long Salesforce development sessions that approach context limits (200K+ tokens)
+- When transitioning between distinct development phases (org exploration -> planning -> implementation)
+- When switching between unrelated Salesforce domains (Apex -> LWC -> Flow configuration)
+- After completing a major milestone (feature shipped, deployment succeeded) before starting new work
+- When responses slow down or become less coherent due to context pressure
+
+## Why Strategic Compaction?
+
+Auto-compaction triggers at arbitrary points:
+
+- Often mid-task, losing important context about org structure or governor limits
+- No awareness of logical task boundaries
+- Can interrupt complex multi-step Salesforce operations (deploy pipeline, test runs)
+
+Strategic compaction at logical boundaries:
+
+- **After org exploration, before implementation** — Compact metadata/schema context, keep implementation plan
+- **After completing a feature** — Fresh start for next feature
+- **Before switching domains** — Clear Apex context before LWC work
+
+## How It Works
+
+The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and:
+
+1. **Tracks tool calls** — Counts tool invocations in session
+2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)
+3. **Periodic reminders** — Reminds every 25 calls after threshold
+
+## Compaction Decision Guide
+
+| Phase Transition | Compact? | Why |
+|-----------------|----------|-----|
+| Org exploration -> Planning | Yes | Org metadata is bulky; plan is the distilled output |
+| Planning -> Apex implementation | Yes | Plan is saved to a file; free up context for code |
+| Apex implementation -> LWC work | Yes | Clear Apex context for unrelated frontend work |
+| Apex implementation -> Apex testing | Maybe | Keep if tests reference recent code; compact if switching focus |
+| Debugging -> Next feature | Yes | Debug traces pollute context for unrelated work |
+| Mid-implementation | No | Losing class names, field APIs, and partial state is costly |
+| After a failed deployment | Yes | Clear the dead-end reasoning before trying a new approach |
+| Trigger work -> Flow work | Yes | Different domains with different context needs |
+
+## What Survives Compaction
+
+Understanding what persists helps you compact with confidence:
+
+| Persists | Lost |
+|----------|------|
+| CLAUDE.md instructions | Intermediate reasoning and analysis |
+| Task list (if saved to a file) | File contents you previously read |
+| Project-level settings and rules | Multi-step conversation context |
+| Git state (commits, branches) | Tool call history and counts |
+| Files on disk | Nuanced user preferences stated verbally |
+| Org metadata on disk | SOQL query results from exploration |
+
+## Best Practices
+
+1. **Compact after planning** — Once plan is finalized and saved to a file, compact to start fresh
+2. **Compact after debugging** — Clear error-resolution context before continuing
+3. **Don't compact mid-implementation** — Preserve context for related Apex/LWC changes
+4. **Read the suggestion** — The hook tells you *when*, you decide *if*
+5. **Write before compacting** — Save important context (org structure, field APIs) to files or memory before compacting
+6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing trigger handler next`
+
+## Salesforce-Specific Tips
+
+- **Save org metadata before compacting** — Object/field lists, record type IDs, profile names
+- **Save governor limit findings** — If you discovered limit issues, document them first
+- **Save deployment results** — Deployment errors/warnings should be saved before compacting
+- **Keep test results accessible** — Write failing test details to a file before compacting
+
+## Token Optimization Patterns
+
+### Trigger-Table Lazy Loading
+
+> **Note:** This is an aspirational optimization pattern -- SCC currently loads skills based on frontmatter triggers, not a runtime lazy-loading table.
+
+Instead of loading full skill content at session start, use a trigger table that maps keywords to skill paths. Skills load only when triggered, reducing baseline context by 50%+:
+
+| Trigger Keywords | Skill | Load When |
+|---------|-------|-----------|
+| "test", "tdd", "coverage" | sf-apex-testing | User mentions testing |
+| "security", "sharing", "crud" | sf-security | Security-related work |
+| "deploy", "scratch org", "ci" | sf-deployment | Deployment context |
+| "soql", "query", "selectivity" | sf-soql-optimization | Query optimization |
+| "trigger", "handler", "fflib" | sf-trigger-frameworks | Trigger development |
+
+### Context Composition Awareness
+
+Monitor what consumes your context window:
+
+- **CLAUDE.md files** — Always loaded, keep lean
+- **Loaded skills** — Each skill adds 1-5K tokens; SCC has 58 skills
+- **Conversation history** — Grows with each exchange
+- **Tool results** — File reads, SOQL results, test output add bulk
+- **Rules** — Always-on guidelines consume baseline context
+
+### Duplicate Instruction Detection
+
+Common sources of duplicate context in SCC projects:
+
+- Skills that repeat CLAUDE.md instructions
+- Multiple skills covering overlapping domains (e.g., security guidance in both `sf-security` and `sf-governor-limits` skills)
+- Agent descriptions that duplicate skill content
+
+## Save-Before-Compact Examples
+
+Before compacting, write critical context to files so it survives:
+
+### Save Org Metadata
+
+```bash
+# Save field list for target object
+sf sobject describe --sobject Account --json > .claude/org-context/account-fields.json
+
+# Save record type IDs
+sf data query --query "SELECT Id, Name, DeveloperName FROM RecordType WHERE SobjectType = 'Account'" --json > .claude/org-context/record-types.json
+```
+
+### Save Investigation Findings
+
+```markdown
+<!-- .claude/session-notes.md — write before compacting -->
+## Governor Limit Findings (2026-03-24)
+- AccountTriggerHandler.cls line 45: SOQL in loop (CRITICAL)
+- OrderService.cls: 3 DML statements could be combined (MEDIUM)
+- Coverage: AccountService 82%, OrderService 61% (needs work)
+
+## Deployment Blockers
+- Missing field: Account.Risk_Category__c not in target org
+- Flow "Auto Case Assignment" references deleted queue
+```
+
+### Save Test Results
+
+```markdown
+<!-- .claude/test-results.md -->
+## Last Test Run
+- 142/145 passing
+- Failed: OrderServiceTest.shouldHandleBulkUpdate (NPE at line 89)
+- Failed: CaseTriggerTest.shouldEscalateHighPriority (assertion at line 34)
+- Failed: IntegrationTest.shouldCallExternalAPI (callout not mocked)
+- Coverage: 78% org-wide
+```
+
+## Multi-Session Continuity
+
+For work spanning multiple sessions, use compact + session commands:
+
+```
+Session 1: Plan feature
+  +-- /save-session -> saves plan, org context, findings
+  +-- /compact -> clean slate
+
+Session 2: Implement Apex
+  +-- /resume-session -> restores plan context
+  +-- [implement Apex classes]
+  +-- /save-session -> saves implementation state
+  +-- /compact
+
+Session 3: Implement LWC + Deploy
+  +-- /resume-session -> restores implementation context
+  +-- [build LWC, deploy, verify]
+```
+
+## Large Project Handling
+
+For projects with 100K+ lines of code:
+
+- **Don't read entire codebase** — Use Grep/Glob to find specific files
+- **Use codemaps** — `deep-researcher` agent creates navigable index without loading full files
+- **Compact aggressively between features** — Each feature is a fresh context
+- **Save architecture notes to files** — Don't rely on conversation memory for class relationships
+- **Use agents for parallel investigation** — Subagents have their own context windows
+
+## Approximate Token Costs (as of the current API version per @../_reference/API_VERSIONS.md — may vary with model and encoding)
+
+| Content Type | Approximate Tokens | Notes |
+|-------------|-------------------|-------|
+| CLAUDE.md | 2-5K | Always loaded |
+| Each rule file | 500-2K | All active rules loaded |
+| Each loaded skill | 1-5K | Loaded on demand |
+| Apex class (500 lines) | 3-5K | When Read tool is used |
+| LWC component (3 files) | 2-4K | HTML + JS + CSS |
+| SOQL query result (100 rows) | 2-8K | Depends on field count |
+| Test output (full suite) | 5-15K | Use `--result-format human` to reduce |
+| Debug log (1000 lines) | 8-15K | Filter with `--log-level WARN` |
+
+## Related
+
+- `suggest-compact.js` hook — Automatic compaction suggestions
+- `/save-session` and `/resume-session` — State that survives compaction
+- `sf-debugging` skill — Debug context preservation
+- `learning-engine` agent — Extracts patterns before session ends

package/.cursor/skills/update-docs/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: update-docs
+description: >-
+  Use when syncing documentation after Salesforce Apex code changes. Update README, API docs, and deploy metadata references to match the current org codebase.
+disable-model-invocation: true
+---
+
+# Update Docs — Synchronize Documentation with Codebase
+
+Synchronize documentation with the current state of the Salesforce codebase. Scans metadata, extracts project structure, and updates documentation files.
+
+## When to Use
+
+- After making code changes that affect the project structure or API surface
+- When new Apex classes, triggers, LWC components, or flows have been added or removed
+- When deployment steps or prerequisites have changed
+- To check for stale documentation that hasn't been updated in 90+ days
+- When regenerating API documentation for `@RestResource`, `@AuraEnabled`, or `@InvocableMethod` classes
+
+## Workflow
+
+### Step 1 — Scan Project Metadata
+
+Read project configuration to understand the tech stack:
+
+```bash
+# Core project config
+cat sfdx-project.json
+
+# Package dependencies
+cat sfdx-project.json | grep -A5 "packageDirectories"
+
+# Node.js tooling
+cat package.json 2>/dev/null | grep -A10 '"scripts"'
+```
+
+### Step 2 — Inventory Source Components
+
+Count and categorize all Salesforce metadata:
+
+```bash
+# Apex classes
+find force-app -name "*.cls" -not -name "*Test.cls" | wc -l
+
+# Apex test classes
+find force-app -name "*Test.cls" | wc -l
+
+# Apex triggers
+find force-app -name "*.trigger" | wc -l
+
+# LWC components
+find force-app -path "*/lwc/*/*.js" | wc -l
+
+# Custom objects
+find force-app -name "*.object-meta.xml" | wc -l
+
+# Flows
+find force-app -name "*.flow-meta.xml" | wc -l
+
+# Permission sets
+find force-app -name "*.permissionset-meta.xml" | wc -l
+```
+
+### Step 3 — Update README Sections
+
+Update these sections with `<!-- AUTO-GENERATED-START -->` / `<!-- AUTO-GENERATED-END -->` markers:
+
+**Project Structure:**
+
+```markdown
+## Project Structure
+
+| Component | Count | Location |
+|-----------|-------|----------|
+| Apex Classes | 45 | `force-app/main/default/classes/` |
+| Apex Triggers | 8 | `force-app/main/default/triggers/` |
+| Test Classes | 32 | `force-app/main/default/classes/*Test.cls` |
+| LWC Components | 12 | `force-app/main/default/lwc/` |
+| Custom Objects | 15 | `force-app/main/default/objects/` |
+| Flows | 6 | `force-app/main/default/flows/` |
+```
+
+**Setup Instructions:**
+
+- Scratch org creation command from `config/project-scratch-def.json`
+- Data seeding scripts if present
+- Permission set assignments
+
+**Available Commands:**
+
+- List custom SF CLI commands from `package.json` scripts
+- Document any custom sfdx plugins
+
+### Step 4 — Generate API Documentation
+
+For classes with `@RestResource`, `@AuraEnabled`, or `@InvocableMethod`:
+
+```markdown
+## API Endpoints
+
+### AccountController (@RestResource)
+- `GET /services/apexrest/accounts` — List accounts
+- `POST /services/apexrest/accounts` — Create account
+
+### AccountService (@AuraEnabled methods)
+- `getAccountDetails(Id accountId)` — Returns account with contacts
+- `updateAccountStatus(Id accountId, String status)` — Updates status
+```
+
+### Step 5 — Generate Deployment Guide
+
+Create or update deployment documentation:
+
+```markdown
+## Deployment Guide
+
+### Prerequisites
+- SF CLI v2.x installed
+- Target org authenticated: `sf org login web --alias <alias>`
+
+### Deploy Steps
+1. Validate: `sf project deploy validate --target-org <alias> --test-level RunLocalTests`
+2. Deploy: `sf project deploy start --target-org <alias> --test-level RunLocalTests`
+
+### Metadata Dependencies
+`sf project deploy start` handles dependency resolution automatically — no manual ordering is needed. If a deployment fails due to a missing dependency, verify that all referenced metadata is included in the source being deployed.
+```
+
+### Step 6 — Check Staleness
+
+Flag documentation files not updated in 90+ days:
+
+```bash
+find . -name "README.md" -o -name "CONTRIBUTING.md" -o -name "*.md" -path "*/docs/*" | while read f; do
+  last_modified=$(git log -1 --format=%ai -- "$f" 2>/dev/null)
+  if [ -n "$last_modified" ]; then
+    last_epoch=$(date -d "$last_modified" +%s 2>/dev/null || date -j -f "%Y-%m-%d %H:%M:%S %z" "$last_modified" +%s 2>/dev/null)
+    days=$(( ($(date +%s) - $last_epoch) / 86400 ))
+    if [ "$days" -gt 90 ]; then echo "STALE ($days days): $f"; fi
+  fi
+done
+```
+
+### Step 7 — Verify Auto-Generated Markers
+
+Ensure all auto-generated sections have proper markers so future updates don't clobber manual content. Only modify content between `<!-- AUTO-GENERATED-START -->` and `<!-- AUTO-GENERATED-END -->` markers.
+
+## Rules
+
+- Only update sections between auto-generated markers
+- Never overwrite manually-written content
+- Always show a diff before writing changes
+- Preserve existing formatting and style of the document
+
+## Examples
+
+```
+/update-docs
+/update-docs Sync the README with the new Agentforce integration feature
+/update-docs Regenerate API documentation for all @RestResource classes
+/update-docs Check for stale documentation and suggest updates
+```

package/.cursor/skills/update-platform-docs/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: update-platform-docs
+description: >-
+  Update Salesforce platform reference docs with latest release features and deprecation announcements. Use when SessionStart hook warns docs are outdated or a new Salesforce release has shipped. Do NOT use for Apex or LWC development.
+disable-model-invocation: true
+---
+
+# Update Platform Reference Docs
+
+## When to Use
+
+- When the SessionStart hook warns that platform docs are outdated (>4 months since last verified)
+- When a new Salesforce release has shipped (Spring, Summer, or Winter)
+- When you hear about new Salesforce feature deprecations or retirements
+
+## Files to Update
+
+Two reference files in `skills/_reference/`:
+
+1. **API_VERSIONS.md** — Release feature tracker (24-month rolling window)
+2. **DEPRECATIONS.md** — Retired features, upcoming retirements, naming changes (cumulative)
+
+## Update Procedure
+
+### Step 1 — Research current release
+
+WebSearch for the latest Salesforce release information:
+
+```
+Search: "Salesforce [Season] '[Year] release notes new features developer site:developer.salesforce.com"
+Search: "Salesforce [Season] '[Year] release highlights"
+```
+
+### Step 2 — Research deprecations
+
+WebSearch for deprecation and retirement announcements:
+
+```
+Search: "Salesforce feature retirements [current year] site:help.salesforce.com"
+Search: "Salesforce deprecated features [current year]"
+```
+
+### Step 3 — Update API_VERSIONS.md
+
+1. Read current `skills/_reference/API_VERSIONS.md`
+2. Add new release section at TOP with `Added: YYYY-MM` tag
+3. Include all new GA features, Beta features (marked clearly), and breaking changes
+4. Remove any sections where `Added:` date is older than 24 months
+5. Update the "Last verified" date
+6. Update "Current" label to point to the new release
+
+### Step 4 — Update DEPRECATIONS.md
+
+1. Read current `skills/_reference/DEPRECATIONS.md`
+2. Append any NEW deprecation entries with `Added: YYYY-MM` tag
+3. Move "Retiring Soon" entries to "Already Retired" if retirement date has passed
+4. Remove entries where `Added:` date is older than 24 months (exception: keep "Retiring Soon" entries until retirement date + 24 months)
+5. Check for new product renames and add them
+6. Update Beta feature status (promote to GA if applicable, remove if GA'd >24 months ago)
+7. Update the "Last verified" date
+
+### Step 5 — Verify
+
+After updating, confirm changes:
+
+```bash
+# Check no v62.0 or other old version references leaked back
+grep -r "old_version" skills/_reference/API_VERSIONS.md skills/_reference/DEPRECATIONS.md
+
+# Run CI validation
+node scripts/ci/validate-skills.js
+```
+
+## Important Rules
+
+- Releases and deprecations are INDEPENDENT — a new release does NOT deprecate the previous one
+- Every entry gets an `Added: YYYY-MM` tag for 24-month retention tracking
+- Beta features must be clearly marked as "Beta" or "Pilot" with "do NOT use in production"
+- Use current product names (see Product Renames table in DEPRECATIONS.md)
+- Only add information verified from official Salesforce sources (developer.salesforce.com, help.salesforce.com)
+
+## Related
+
+- **Hook**: `check-platform-docs-age.js` — SessionStart hook that triggers this skill's warning
+- **Reference**: `@../_reference/API_VERSIONS.md` — Feature tracker
+- **Reference**: `@../_reference/DEPRECATIONS.md` — Deprecation guard

package/.cursor-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "salesforce-claude-code",
+  "version": "1.1.0",
+  "description": "Production-ready AI agents, skills, and hooks for Salesforce development",
+  "author": {
+    "name": "Jiten Singh",
+    "email": "jitencseng@gmail.com"
+  },
+  "homepage": "https://github.com/jiten-singh-shahi/salesforce-claude-code",
+  "repository": "https://github.com/jiten-singh-shahi/salesforce-claude-code",
+  "license": "MIT",
+  "keywords": [
+    "salesforce",
+    "apex",
+    "lwc",
+    "soql",
+    "agentforce",
+    "sf-cli",
+    "devops"
+  ],
+  "logo": "assets/logo.svg",
+  "skills": ".cursor/skills/",
+  "agents": ".cursor/agents/",
+  "hooks": ".cursor/hooks.json",
+  "mcpServers": "./mcp-configs/mcp-servers.json"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jitendra Singh
+
+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.