scc-universal 1.1.0

package/.cursor/skills/prompt-optimizer/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: prompt-optimizer
+description: >-
+  Use when improving a Salesforce, Apex, or LWC prompt. Analyze intent and gaps, match SCC skills/agents, output a ready-to-paste optimized prompt. Advisory only.
+---
+
+# Prompt Optimizer
+
+Analyze a draft prompt, critique it, match it to SCC ecosystem components,
+and output a complete optimized prompt the user can paste and run.
+
+## When to Use
+
+- User says "optimize this prompt", "improve my prompt", "rewrite this prompt"
+- User says "help me write a better prompt for..."
+- User says "what's the best way to ask Claude Code to..."
+- User pastes a draft prompt and asks for feedback or enhancement
+- User says "I don't know how to prompt for this"
+- User says "how should I use SCC for..."
+- User explicitly invokes `/prompt-optimizer`
+
+### Do Not Use When
+
+- User wants the task done directly (just execute it)
+- User says "optimize this code", "optimize performance" — these are refactoring tasks, not prompt optimization
+- User is asking about SCC configuration (use `configure-scc` instead)
+- User wants a skill inventory (use `/sf-harness-audit` skill instead)
+- User says "just do it"
+
+## How It Works
+
+**Advisory only — do not execute the user's task.**
+
+Do NOT write code, create files, run commands, or take any implementation
+action. Your ONLY output is an analysis plus an optimized prompt.
+
+If the user says "just do it" or "don't optimize, just execute",
+do not switch into implementation mode inside this skill. Tell the user this
+skill only produces optimized prompts, and instruct them to make a normal
+task request if they want execution instead.
+
+Run this 6-phase pipeline sequentially. Present results using the Output Format below.
+
+### Analysis Pipeline
+
+### Phase 0: Project Detection
+
+Before analyzing the prompt, detect the current project context:
+
+1. Check if a `CLAUDE.md` exists in the working directory — read it for project conventions
+2. Detect tech stack from project files:
+   - `sfdx-project.json` → Salesforce (Apex / LWC / SOQL / Flow / Agentforce)
+   - `package.json` → Node.js / LWC tooling / Jest tests
+3. Note detected tech stack for use in Phase 3 and Phase 4
+
+If no project files are found (e.g., the prompt is abstract or for a new project),
+skip detection and flag "tech stack unknown" in Phase 4.
+
+### Phase 1: Intent Detection
+
+Classify the user's task into one or more categories:
+
+| Category | Signal Words | Example |
+|----------|-------------|---------|
+| New Feature | build, create, add, implement | "Build a lead scoring trigger" |
+| Bug Fix | fix, broken, not working, error | "Fix the trigger recursion" |
+| Refactor | refactor, clean up, restructure | "Refactor to trigger framework" |
+| Research | how to, what is, explore, investigate | "How to add Platform Events" |
+| Testing | test, coverage, verify | "Add tests for AccountService" |
+| Review | review, audit, check | "Review my Apex trigger" |
+| Documentation | document, update docs | "Update the API docs" |
+| Infrastructure | deploy, CI, scratch org, DevOps | "Set up CI/CD with scratch orgs" |
+| Design | design, architecture, plan | "Design the data model" |
+
+### Phase 2: Scope Assessment
+
+If Phase 0 detected a project, use codebase size as a signal. Otherwise, estimate
+from the prompt description alone and mark the estimate as uncertain.
+
+| Scope | Heuristic | Orchestration |
+|-------|-----------|---------------|
+| TRIVIAL | Single file, < 50 lines | Direct execution |
+| LOW | Single component or module | Single command or skill |
+| MEDIUM | Multiple components, same domain | Command chain + sf-review-agent agent |
+| HIGH | Cross-domain, 5+ files | Use sf-architect agent first, then phased execution |
+| EPIC | Multi-session, multi-PR, architectural shift | Use sf-architect agent for multi-session plan |
+
+### Phase 3: SCC Component Matching
+
+Map intent + scope + tech stack (from Phase 0) to specific SCC components.
+
+#### By Intent Type
+
+| 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 |
+| Documentation | /update-docs | — | doc-updater, deep-researcher |
+| Infrastructure | /sf-deployment | sf-devops-ci-cd, sf-deployment | sf-architect |
+| Design (EPIC) | — | — | sf-architect, sf-architect |
+
+#### By Tech Stack
+
+| Tech Stack | Skills to Add | Agent |
+|------------|--------------|-------|
+| Apex | sf-apex-best-practices, sf-apex-testing, sf-security | sf-review-agent |
+| LWC | sf-lwc-development, sf-lwc-testing | sf-lwc-agent |
+| SOQL | sf-soql-optimization | sf-apex-agent |
+| Flow | sf-flow-development | sf-flow-agent |
+| Agentforce | sf-agentforce-development | sf-agentforce-agent |
+| DevOps | sf-devops-ci-cd, sf-deployment | sf-architect |
+| Security | sf-security | sf-review-agent |
+| EPIC | — | sf-architect, sf-architect |
+
+### Phase 4: Missing Context Detection
+
+Scan the prompt for missing critical information. Check each item and mark
+whether Phase 0 auto-detected it or the user must supply it:
+
+- [ ] **Tech stack** — Detected in Phase 0, or must user specify?
+- [ ] **Target scope** — Files, directories, or modules mentioned?
+- [ ] **Acceptance criteria** — How to know the task is done?
+- [ ] **Error handling** — Edge cases and failure modes addressed?
+- [ ] **Security requirements** — Auth, input validation, secrets?
+- [ ] **Testing expectations** — Unit, integration, E2E?
+- [ ] **Performance constraints** — Governor limits, bulk patterns, SOQL selectivity?
+- [ ] **UI/UX requirements** — Design specs, SLDS compliance, accessibility? (if LWC)
+- [ ] **Database changes** — Schema, migrations, indexes? (if data layer)
+- [ ] **Existing patterns** — Reference files or conventions to follow?
+- [ ] **Scope boundaries** — What NOT to do?
+
+**If 3+ critical items are missing**, ask the user up to 3 clarification
+questions before generating the optimized prompt. Then incorporate the
+answers into the optimized prompt.
+
+### Phase 5: Workflow & Model Recommendation
+
+Determine where this prompt sits in the development lifecycle:
+
+```
+Research → Plan → Implement (TDD) → Review → Verify → Commit
+```
+
+For MEDIUM+ tasks, always start with the sf-architect agent. For EPIC tasks, use the sf-architect agent.
+
+**Model recommendation** (include in output):
+
+| Scope | Recommended Model | Rationale |
+|-------|------------------|-----------|
+| TRIVIAL-LOW | Sonnet | Fast, cost-efficient for simple tasks |
+| MEDIUM | Sonnet | Best coding model for standard work |
+| HIGH | Sonnet (main) + Opus (planning) | Opus for architecture, Sonnet for implementation |
+| EPIC | Opus (sf-architect) + Sonnet (execution) | Deep reasoning for multi-session planning |
+
+**Multi-prompt splitting** (for HIGH/EPIC scope):
+
+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
+- Use /save-session and /resume-session to preserve context between sessions
+
+---
+
+## Output Format
+
+Present your analysis in this exact structure. Respond in the same language
+as the user's input.
+
+### Section 1: Prompt Diagnosis
+
+**Strengths:** List what the original prompt does well.
+
+**Issues:**
+
+| Issue | Impact | Suggested Fix |
+|-------|--------|---------------|
+| (problem) | (consequence) | (how to fix) |
+
+**Needs Clarification:** Numbered list of questions the user should answer.
+If Phase 0 auto-detected the answer, state it instead of asking.
+
+### Section 2: Recommended SCC Components
+
+| Type | Component | Purpose |
+|------|-----------|---------|
+| 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 |
+
+### Section 3: Optimized Prompt — Full Version
+
+Present the complete optimized prompt inside a single fenced code block.
+The prompt must be self-contained and ready to copy-paste. Include:
+
+- Clear task description with context
+- Tech stack (detected or specified)
+- /command invocations at the right workflow stages
+- Acceptance criteria
+- Verification steps
+- 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).
+
+### Section 4: Optimized Prompt — Quick Version
+
+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.` |
+| 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.` |
+| Docs | `/update-docs. Use deep-researcher agent.` |
+| EPIC | `Use sf-architect agent for "[objective]". Execute phases with sf-review-agent agent gates.` |
+
+### Section 5: Enhancement Rationale
+
+| Enhancement | Reason |
+|-------------|--------|
+| (what was added) | (why it matters) |
+
+### Footer
+
+> Not what you need? Tell me what to adjust, or make a normal task request
+> if you want execution instead of prompt optimization.
+
+---
+
+## Examples
+
+### Trigger Examples
+
+- "Optimize this prompt for SCC"
+- "Rewrite this prompt so Claude Code uses the right commands"
+- "How should I prompt SCC for this task?"
+
+### Example 1: Vague Salesforce Prompt (Project Detected)
+
+**User input:**
+
+```
+Help me write an Account trigger
+```
+
+**Phase 0 detects:** `sfdx-project.json` → Salesforce project; `package.json` with Jest
+
+**Optimized Prompt (Full):**
+
+```
+Implement an Account trigger using the project's existing Trigger Framework pattern.
+
+Technical requirements:
+- Follow the project's existing trigger handler architecture (check for TriggerHandler base class or similar framework)
+- Implement bulkification — all SOQL queries and DML operations must be outside loops
+- Add appropriate error handling and custom exception classes
+- Follow Salesforce governor limits best practices
+
+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)
+3. Implement AccountTrigger and AccountTriggerHandler
+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:
+- Use WITH USER_MODE for SOQL queries
+- Verify CRUD/FLS permissions
+
+Acceptance criteria:
+- Test coverage 85%+
+- Zero governor limit violations
+- Passes /sf-security review
+```
+
+### Example 2: Moderate English Prompt
+
+**User input:**
+
+```
+Add a REST API endpoint for account creation with validation
+```
+
+**Phase 0 detects:** `sfdx-project.json` → Salesforce project
+
+**Optimized Prompt (Full):**
+
+```
+Add a REST API endpoint for account creation (POST /api/accounts).
+
+Tech stack: Salesforce Apex REST (detected from sfdx-project.json)
+
+Requirements:
+- @RestResource(urlMapping='/api/accounts')
+- Input validation: Name (required), Industry, BillingCountry
+- Auth: Connected App OAuth — caller must have Account create permission
+- Return 201 with created Account Id on success
+- Return 400 with validation errors on invalid input
+- Return 403 for insufficient permissions
+
+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
+3. Implement AccountAPI class following existing REST patterns
+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:
+- Modify existing Account fields or validation rules
+- Add new custom fields without a separate plan step
+```
+
+### Example 3: EPIC Project
+
+**User input:**
+
+```
+Migrate our legacy Apex triggers to a trigger framework
+```
+
+**Optimized Prompt (Full):**
+
+```
+Use the sf-architect agent to plan: "Migrate all legacy Apex triggers to trigger framework"
+
+Before executing, answer these questions in the blueprint:
+1. Which trigger framework is preferred (custom TriggerHandler, Apex Commons, or other)?
+2. How many triggers exist and which objects are highest priority?
+3. Are there existing test classes that need to be preserved?
+4. What is the deployment strategy (all at once vs object-by-object)?
+
+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 4: Migrate remaining triggers
+- Phase N: Remove legacy trigger code, run full regression
+
+Each phase = 1 deployment unit, with sf-review-agent agent gates between phases.
+Use /save-session between phases. Use /resume-session to continue.
+
+Recommended: Opus for blueprint planning, Sonnet for phase execution.
+```
+
+---
+
+## Related Components
+
+| Component | When to Reference |
+|-----------|------------------|
+| `configure-scc` | User hasn't set up SCC yet |
+| `/sf-harness-audit` (skill) | Audit which components are installed (use instead of hardcoded catalog) |
+| `search-first` | Research phase in optimized prompts |
+| `sf-architect` (agent) | EPIC-scope optimized prompts |
+| `strategic-compact` | Long session context management |
+| `strategic-compact` (token tips) | Token optimization recommendations |

package/.cursor/skills/refactor-clean/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: refactor-clean
+description: >-
+  Use when cleaning up Salesforce Apex or LWC code. Dead code removal and consolidation using PMD and Salesforce Code Analyzer for safe cleanup.
+disable-model-invocation: true
+---
+
+# Refactor Clean — Dead Code Removal and Consolidation
+
+Remove dead code and consolidate duplicates safely. Uses Salesforce Code Analyzer (`sf code-analyzer run`) for detection when available, falls back to manual analysis.
+
+## When to Use
+
+- When cleaning up unused Apex classes, methods, or LWC components
+- When consolidating duplicate utility methods across multiple service classes
+- When preparing a codebase for a security review or AppExchange submission
+- When Salesforce Code Analyzer or PMD reports high-severity findings that need cleanup
+- When reducing technical debt by removing commented-out code and unreferenced classes
+
+## Workflow
+
+### Step 1 — Detect Dead Code
+
+**Option A: Salesforce Code Analyzer (preferred)**
+
+```bash
+sf code-analyzer run --target force-app --format table
+sf code-analyzer run --target force-app --format json | jq '.[] | select(.severity <= 2)'
+```
+
+**Option B: Manual analysis**
+
+```bash
+# Find Apex classes with no references.
+# Uses sfdx-project.json packageDirectories to find all source paths,
+# rather than hardcoding force-app/main/default.
+# Note: This heuristic searches source files for class name strings. Results may
+# be incomplete — classes can be referenced dynamically (Type.forName), from
+# managed packages, external integrations, or metadata not in source control.
+# Always verify before deleting.
+SRC_DIRS=$(node -e "
+  const p = require('./sfdx-project.json');
+  console.log(p.packageDirectories.map(d => d.path).join(' '));
+" 2>/dev/null || echo "force-app")
+for dir in $SRC_DIRS; do
+  find "$dir" -name "*.cls" -not -name "*Test*" | while read cls; do
+    name=$(basename "$cls" .cls)
+    # Note: Use word-boundary matching for precise results to avoid partial name matches
+    refs=$(grep -rlw "$name" $SRC_DIRS --include="*.cls" --include="*.trigger" --include="*.js" --include="*.xml" 2>/dev/null | grep -v "$cls" | wc -l)
+    if [ "$refs" -eq 0 ]; then echo "UNREFERENCED: $name"; fi
+  done
+done
+
+# Find unused methods within a class (private methods not called internally)
+grep -n "private.*void\|private.*String\|private.*List\|private.*Map" <file>.cls
+```
+
+### Step 2 — Classify Safety
+
+Categorize each finding before removing anything:
+
+| Safety Level | Criteria | Action |
+|-------------|----------|--------|
+| **SAFE** | Private methods with no internal callers, unreferenced private classes, commented-out code blocks | Remove immediately |
+| **CAUTION** | Public methods not referenced in code (may be called by Flows, Process Builders, or external systems) | Check metadata references first |
+| **DANGER** | `global` methods, `@AuraEnabled`, `@InvocableMethod`, `@InvocableVariable`, `@RemoteAction`, `@HttpGet/Post`, managed package components | Do NOT remove without explicit verification |
+
+### Step 3 — Check Metadata References
+
+Before removing any CAUTION or DANGER items:
+
+```bash
+# Check if a method is referenced in Flows
+grep -rl "ClassName.MethodName" force-app/main/default/flows/
+
+# Check if a class is used in Process Builders
+grep -rl "ClassName" force-app/main/default/workflows/
+
+# Check if a class is referenced in Custom Metadata
+grep -rl "ClassName" force-app/main/default/customMetadata/
+
+# Check if an LWC component is used in FlexiPages
+grep -rl "c-component-name" force-app/main/default/flexipages/
+
+# Check if a class is referenced in page layouts
+grep -rl "ClassName" force-app/main/default/layouts/
+```
+
+### Step 4 — Managed Package Considerations
+
+Never remove without checking:
+
+- `@AuraEnabled` methods — may be called by LWC/Aura components not in your source
+- `@InvocableMethod` — may be called by Flows you can't see in source control
+- `global` methods — may be called by subscriber orgs or external packages
+- `webService` methods — may be called by external integrations
+- Methods referenced in Permission Sets or Custom Permissions
+
+### Step 5 — Remove One at a Time
+
+For each SAFE item:
+
+1. Delete the dead code
+2. Run tests: `sf apex run test --test-level RunLocalTests --wait 15`
+3. Verify deployment: `sf project deploy start --dry-run --wait 10`
+4. If tests fail, revert the deletion immediately
+
+### Step 6 — Consolidate Duplicates
+
+After dead code removal, look for consolidation opportunities:
+
+1. Identify similar methods across classes (same logic, different names)
+2. Extract shared logic into a utility/service class
+3. Update all callers to use the shared implementation
+4. Run full test suite after each consolidation
+
+## Safety Rules
+
+- Always create a checkpoint before starting: `/checkpoint refactor-start`
+- Remove one item at a time — never batch deletions
+- Run tests after each removal
+- Never remove `@AuraEnabled`, `@InvocableMethod`, or `global` without verifying all callers
+- Check metadata references (Flows, Process Builders, FlexiPages) before deleting any public method
+- Keep a log of what was removed and why
+
+## Examples
+
+```
+refactor-clean Remove unused Apex classes and dead methods from force-app/
+refactor-clean Consolidate duplicate utility methods across AccountService and ContactService
+refactor-clean Find and remove unreferenced LWC components
+refactor-clean Run Salesforce Code Analyzer and clean up all HIGH severity PMD findings
+```

package/.cursor/skills/resume-session/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: resume-session
+description: >-
+  Use when resuming a previous Salesforce development session. Load saved org context and Apex work-in-progress to continue where the last session ended.
+---
+
+# Resume Session — Restore and Orient from a Saved Session
+
+Load the last saved session state and orient fully before doing any work.
+This skill is the counterpart to the save-session skill.
+
+## When to Use
+
+- Starting a new session to continue work from a previous day
+- After starting a fresh session due to context limits
+- When handing off a session file from another source (just provide the file path)
+- Any time you have a session file and want Claude to fully absorb it before proceeding
+
+## Usage
+
+```
+/resume-session                                                      # loads most recent file in ~/.claude/sessions/
+/resume-session 2026-03-18                                           # loads most recent session for that date
+/resume-session ~/.claude/sessions/2026-03-18-apex-trig-session.md   # loads a specific file
+```
+
+## Process
+
+### Step 1: Find the session file
+
+If no argument provided:
+
+1. Check `~/.claude/sessions/`
+2. Pick the most recently modified `*-session.md` file
+3. If the folder does not exist or has no matching files, tell the user:
+
+   ```
+   No session files found in ~/.claude/sessions/
+   Run /save-session at the end of a session to create one.
+   ```
+
+   Then stop.
+
+If an argument is provided:
+
+- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/sessions/` for matching files
+  and load the most recently modified variant for that date
+- If it looks like a file path, read that file directly
+- If not found, report clearly and stop
+
+### Step 2: Read the entire session file
+
+Read the complete file. Do not summarize yet.
+
+### Step 3: Confirm understanding
+
+Respond with a structured briefing in this exact format:
+
+```
+SESSION LOADED: [actual resolved path to the file]
+
+PROJECT: [project name / topic from file]
+
+WHAT WE'RE BUILDING:
+[2-3 sentence summary in your own words]
+
+CURRENT STATE:
+Working: [count] items confirmed
+In Progress: [list files that are in progress]
+Not Started: [list planned but untouched]
+
+WHAT NOT TO RETRY:
+[list every failed approach with its reason — this is critical]
+
+OPEN QUESTIONS / BLOCKERS:
+[list any blockers or unanswered questions]
+
+NEXT STEP:
+[exact next step if defined in the file]
+
+Ready to continue. What would you like to do?
+```
+
+### Step 4: Wait for the user
+
+Do NOT start working automatically. Do NOT touch any files. Wait for the user to say what to do next.
+
+---
+
+## Edge Cases
+
+**Multiple sessions for the same date:**
+Load the most recently modified matching file for that date.
+
+**Session file references files that no longer exist:**
+Note this during the briefing — "WARNING: `path/to/file.cls` referenced in session but not found on disk."
+
+**Session file is from more than 7 days ago:**
+Note the gap — "WARNING: This session is from N days ago. Things may have changed." — then proceed normally.
+
+**Session file is empty or malformed:**
+Report: "Session file found but appears empty or unreadable. You may need to create a new one with /save-session."
+
+---
+
+## Notes
+
+- Never modify the session file when loading it — it's a read-only historical record
+- The briefing format is fixed — do not skip sections even if they are empty
+- "What Not To Retry" must always be shown, even if it just says "None"
+- After resuming, the user may want to run `/save-session` again at the end of the new session