scc-universal 1.1.0

package/.cursor/hooks/before-submit-prompt.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const prompt = input.prompt || input.content || input.message || '';
+    const secretPatterns = [
+      /sk-[a-zA-Z0-9]{20,}/,       // OpenAI API keys
+      /ghp_[a-zA-Z0-9]{36,}/,      // GitHub personal access tokens
+      /AKIA[A-Z0-9]{16}/,          // AWS access keys
+      /xox[bpsa]-[a-zA-Z0-9-]+/,   // Slack tokens
+      /-----BEGIN (RSA |EC )?PRIVATE KEY-----/, // Private keys
+    ];
+    for (const pattern of secretPatterns) {
+      if (pattern.test(prompt)) {
+        console.error('[SCC] WARNING: Potential secret detected in prompt!');
+        console.error('[SCC] Remove secrets before submitting. Use environment variables instead.');
+        break;
+      }
+    }
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/pre-compact.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const { readStdin, runExistingHook, transformToClaude } = require('./adapter');
+readStdin().then(raw => {
+  const claudeInput = JSON.parse(raw || '{}');
+  runExistingHook('pre-compact.js', transformToClaude(claudeInput));
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/session-end.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
+readStdin().then(raw => {
+  const input = JSON.parse(raw || '{}');
+  const claudeInput = transformToClaude(input);
+  if (hookEnabled('session:end:marker', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-end-marker.js', claudeInput);
+  }
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/session-start.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
+readStdin().then(raw => {
+  const input = JSON.parse(raw || '{}');
+  const claudeInput = transformToClaude(input);
+  if (hookEnabled('session:start', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-start.js', claudeInput);
+  }
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/stop.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+const { readStdin, runExistingHook, transformToClaude, hookEnabled } = require('./adapter');
+readStdin().then(raw => {
+  const input = JSON.parse(raw || '{}');
+  const claudeInput = transformToClaude(input);
+
+  if (hookEnabled('stop:check-console-log', ['standard', 'strict'])) {
+    runExistingHook('check-console-log.js', claudeInput);
+  }
+  if (hookEnabled('stop:session-end', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('session-end.js', claudeInput);
+  }
+  if (hookEnabled('stop:cost-tracker', ['minimal', 'standard', 'strict'])) {
+    runExistingHook('cost-tracker.js', claudeInput);
+  }
+
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/subagent-start.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const agent = input.agent_name || input.agent || 'unknown';
+    console.error(`[SCC] Agent spawned: ${agent}`);
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks/subagent-stop.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const { readStdin } = require('./adapter');
+readStdin().then(raw => {
+  try {
+    const input = JSON.parse(raw);
+    const agent = input.agent_name || input.agent || 'unknown';
+    console.error(`[SCC] Agent completed: ${agent}`);
+  } catch {}
+  process.stdout.write(raw);
+}).catch(() => process.exit(0));

package/.cursor/hooks.json

@@ -0,0 +1,107 @@
+{
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "node .cursor/hooks/session-start.js",
+        "event": "sessionStart",
+        "description": "Display Salesforce project context: detected org, scratch orgs, CLI version"
+      }
+    ],
+    "sessionEnd": [
+      {
+        "command": "node .cursor/hooks/session-end.js",
+        "event": "sessionEnd",
+        "description": "Persist session state and evaluate patterns"
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "command": "npx block-no-verify@1.1.2",
+        "event": "beforeShellExecution",
+        "description": "Block git hook-bypass flag to protect pre-commit, commit-msg, and pre-push hooks from being skipped"
+      },
+      {
+        "command": "node .cursor/hooks/before-shell-execution.js",
+        "event": "beforeShellExecution",
+        "description": "Validate SF CLI commands, SFDX deprecation warnings, git push reminder"
+      }
+    ],
+    "afterShellExecution": [
+      {
+        "command": "node .cursor/hooks/after-shell-execution.js",
+        "event": "afterShellExecution",
+        "description": "PR URL logging, build/deploy completion notice"
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "node .cursor/hooks/after-file-edit.js",
+        "event": "afterFileEdit",
+        "description": "Quality gate, governor checks, console.log warning, auto-format"
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": "node .cursor/hooks/before-read-file.js",
+        "event": "beforeReadFile",
+        "description": "Warn when reading sensitive files (.env, .key, .pem)"
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "node .cursor/hooks/before-submit-prompt.js",
+        "event": "beforeSubmitPrompt",
+        "description": "Detect secrets in prompts (sk-, ghp_, AKIA patterns)"
+      }
+    ],
+    "subagentStart": [
+      {
+        "command": "node .cursor/hooks/subagent-start.js",
+        "event": "subagentStart",
+        "description": "Log agent spawning for observability"
+      }
+    ],
+    "subagentStop": [
+      {
+        "command": "node .cursor/hooks/subagent-stop.js",
+        "event": "subagentStop",
+        "description": "Log agent completion"
+      }
+    ],
+    "afterTabFileEdit": [
+      {
+        "command": "node .cursor/hooks/after-tab-file-edit.js",
+        "event": "afterTabFileEdit",
+        "description": "Auto-format Tab edits"
+      }
+    ],
+    "beforeMCPExecution": [
+      {
+        "command": "node .cursor/hooks/before-mcp-execution.js",
+        "event": "beforeMCPExecution",
+        "description": "Log MCP server/tool invocations for observability"
+      }
+    ],
+    "afterMCPExecution": [
+      {
+        "command": "node .cursor/hooks/after-mcp-execution.js",
+        "event": "afterMCPExecution",
+        "description": "Log MCP result status (OK/FAILED) for observability"
+      }
+    ],
+    "preCompact": [
+      {
+        "command": "node .cursor/hooks/pre-compact.js",
+        "event": "preCompact",
+        "description": "Save state before context compaction"
+      }
+    ],
+    "stop": [
+      {
+        "command": "node .cursor/hooks/stop.js",
+        "event": "stop",
+        "description": "Console.log audit, session summary, cost tracking"
+      }
+    ]
+  }
+}

package/.cursor/skills/aside/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: aside
+description: >-
+  Use when you need a quick Salesforce answer mid-task. Answer a side question about Apex, org config, or metadata without losing context, then resume work automatically.
+---
+
+# Aside — Quick Side Question Without Losing Context
+
+Ask a question mid-task and get an immediate, focused answer — then continue right where you left off. The current task, files, and context are never modified.
+
+## When to Use
+
+- You're curious about something while Claude is working and don't want to lose momentum
+- You need a quick explanation of code Claude is currently editing
+- You want a second opinion or clarification on a decision without derailing the task
+- You need to understand an error, concept, or pattern before Claude proceeds
+- You want to ask something unrelated to the current task without starting a new session
+
+## Usage
+
+```
+/aside <your question>
+/aside what does this function actually return?
+/aside is this pattern thread-safe?
+/aside why are we using X instead of Y here?
+/aside what's the difference between foo() and bar()?
+/aside should we be worried about the SOQL in a loop we just added?
+```
+
+## Process
+
+### Step 1: Freeze the current task state
+
+Before answering anything, mentally note:
+
+- What is the active task? (what file, feature, or problem was being worked on)
+- What step was in progress at the moment the aside was invoked?
+- What was about to happen next?
+
+Do NOT touch, edit, create, or delete any files during the aside.
+
+### Step 2: Answer the question directly
+
+Answer the question in the most concise form that is still complete and useful.
+
+- Lead with the answer, not the reasoning
+- Keep it short — if a full explanation is needed, offer to go deeper after the task
+- If the question is about the current file or code being worked on, reference it precisely (file path and line number if relevant)
+- If answering requires reading a file, read it — but read only, never write
+
+Format the response as:
+
+```
+ASIDE: [restate the question briefly]
+
+[Your answer here]
+
+— Back to task: [one-line description of what was being done]
+```
+
+### Step 3: Resume the main task
+
+After delivering the answer, immediately continue the active task from the exact point it was paused. Do not ask for permission to resume unless the aside answer revealed a blocker or a reason to reconsider the current approach.
+
+---
+
+## Edge Cases
+
+**No question provided (aside invoked with nothing after it):**
+Respond:
+
+```
+ASIDE: no question provided
+
+What would you like to know? (ask your question and I'll answer without losing the current task context)
+
+— Back to task: [one-line description of what was being done]
+```
+
+**Question reveals a potential problem with the current task:**
+Flag it clearly before resuming:
+
+```
+ASIDE: [answer]
+
+Warning: This answer suggests [issue] with the current approach. Want to address this before continuing, or proceed as planned?
+```
+
+Wait for the user's decision before resuming.
+
+**Question is actually a task redirect (not a side question):**
+If the question implies changing what is being built, clarify:
+
+```
+ASIDE: That sounds like a direction change, not just a side question.
+Do you want to:
+  (a) Answer this as information only and keep the current plan
+  (b) Pause the current task and change approach
+```
+
+Wait for the user's answer.
+
+**No active task (nothing in progress when aside is invoked):**
+Still use the standard wrapper:
+
+```
+ASIDE: [restate the question briefly]
+
+[Your answer here]
+
+— Back to task: no active task to resume
+```
+
+**Multiple aside questions in a row:**
+Answer each one in sequence. After the last answer, resume the main task.

package/.cursor/skills/checkpoint/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: checkpoint
+description: >-
+  Use when saving Salesforce development progress. Create a named checkpoint via git stash before risky Apex deploys or org changes for easy recovery.
+disable-model-invocation: true
+---
+
+# Checkpoint — Named Progress Snapshots
+
+Save current progress as a named checkpoint for easy recovery.
+
+## When to Use
+
+- When you want to save work-in-progress before attempting a risky change
+- When starting a refactoring pass and need a safe rollback point
+- When switching between tasks and want to preserve current state
+- When you need to snapshot progress at key milestones during a long session
+- When collaborating and want to share a recoverable state with another agent or session
+
+## Usage
+
+```text
+checkpoint [name]
+```
+
+## Workflow
+
+1. **Create checkpoint** — `git stash push --include-untracked -m "checkpoint: <name> [<timestamp>]"`
+2. **Log metadata** — Append to `.claude/checkpoints.log`:
+   - Timestamp
+   - Checkpoint name
+   - Files changed (count)
+   - Current branch
+3. **Verify** — Confirm working tree is clean after stash
+
+## Operations
+
+- `checkpoint save <name>` — Create new checkpoint
+- `checkpoint list` — Show all checkpoints from log
+- `checkpoint restore <name>` — Apply the named stash (`git stash apply`; keeps the stash entry safe). Find the stash reference via `git stash list | grep "<name>"`, then `git stash apply stash@{N}`. After verifying the restore, drop with `git stash drop stash@{N}`.
+- `checkpoint verify` — Verify current state matches last checkpoint
+
+## Examples
+
+```
+checkpoint save before-trigger-refactor
+checkpoint list
+checkpoint restore before-trigger-refactor
+checkpoint verify
+```

package/.cursor/skills/configure-scc/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: configure-scc
+description: >-
+  Use when setting up SCC for Salesforce Apex and LWC development. Interactive wizard to install profiles, modules, and customize the harness for your org.
+---
+
+# Configure SCC
+
+Interactive guide for installing and configuring Salesforce Claude Code.
+
+## When to Use
+
+- When installing SCC for the first time on a Salesforce project
+- When adding new modules or profiles to an existing SCC installation
+- When customizing hook behavior or profiles for your team's workflow
+- When troubleshooting SCC configuration or missing components
+- When setting up SCC for different team members or CI/CD environments
+
+## Installation
+
+### Quick Install
+
+```bash
+# Install globally
+npm install -g scc-universal
+
+# Install with a profile
+npx scc install all      # Everything (all agents, skills, rules)
+npx scc install apex     # Apex-focused development
+npx scc install lwc      # LWC-focused development
+```
+
+### Profile Details
+
+| Profile | Includes |
+|---------|----------|
+| `apex` | Common rules + Apex rules, agents, skills |
+| `lwc` | Common rules + LWC rules, agents, skills |
+| `full` | All agents, skills, rules |
+
+### Diagnostics
+
+```bash
+npx scc doctor    # Check for missing/drifted files
+npx scc status    # View installed components
+npx scc repair    # Restore drifted files
+npx scc uninstall # Remove SCC-managed files
+```
+
+## Hook Configuration
+
+### Profiles
+
+```bash
+# Set hook profile (controls which hooks run)
+export SCC_HOOK_PROFILE=minimal    # Session start + stop only
+export SCC_HOOK_PROFILE=standard   # Default — includes quality checks
+export SCC_HOOK_PROFILE=strict     # All hooks including auto-format
+```
+
+### Disable Specific Hooks
+
+```bash
+export SCC_DISABLED_HOOKS=governor-check,cost-tracker
+```
+
+## Package Manager
+
+SCC auto-detects your package manager. Override with:
+
+```bash
+export CLAUDE_PACKAGE_MANAGER=npm  # or pnpm, yarn, bun
+```
+
+## Environment-Specific Configuration
+
+### Sandbox / Scratch Org Development
+
+```bash
+# Set default target org for SF CLI commands
+sf config set target-org=my-scratch-org
+
+# Scratch org duration is set via --duration-days flag or scratch org definition file
+# sf org create scratch -f config/project-scratch-def.json --duration-days 7
+```
+
+### CI/CD Environments
+
+```bash
+# Minimal hooks for CI (fast, no interactive prompts)
+export SCC_HOOK_PROFILE=minimal
+
+# Disable all cost/session tracking in CI
+export SCC_DISABLED_HOOKS=cost-tracker,session-start,session-end,evaluate-session
+```
+
+### Team Setup
+
+Share SCC configuration across your team by adding to your project's `.env.example`:
+
+```bash
+# .env.example — copy to .env and customize
+SCC_HOOK_PROFILE=standard
+CLAUDE_PACKAGE_MANAGER=npm
+```
+
+## Troubleshooting
+
+### Common Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `npx scc install` fails | Node.js < 20 | Upgrade: `nvm install 20` |
+| Hooks not firing | SCC not installed in project | Run `npx scc doctor` to check |
+| `Permission denied` on hooks | Script not executable | Run `npx scc repair` |
+| Skills not loading | Wrong install profile | Run `npx scc install all` |
+| `sf` command not found | SF CLI not installed | Install: `npm install -g @salesforce/cli` |
+| `sf` commands fail with errors | SF CLI version too old | Upgrade: `npm update -g @salesforce/cli` (SCC requires SF CLI v2.x / `sf` not `sfdx`) |
+| Hooks slow down session | Too many hooks enabled | Switch to `SCC_HOOK_PROFILE=minimal` |
+
+### Diagnostic Commands
+
+```bash
+# Full diagnostic report
+npx scc doctor
+
+# See exactly what's installed
+npx scc list-installed
+
+# Preview what WOULD be installed (dry run)
+npx scc plan apex
+
+# Check state store
+npx scc status
+
+# Reset everything and reinstall
+npx scc uninstall && npx scc install all
+```
+
+### Upgrading SCC
+
+```bash
+# Update to latest version
+npm install -g scc-universal@latest
+
+# Repair any drifted files after upgrade
+npx scc repair
+
+# Verify upgrade
+npx scc doctor
+```
+
+## Verification
+
+```bash
+npm test              # Run all validators
+npx scc doctor        # Check installation health
+sf --version          # Verify SF CLI is installed
+npx scc status        # Confirm installed components
+```