scc-universal 1.1.0

package/skills/continuous-agent-loop/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: continuous-agent-loop
+origin: SCC
+user-invocable: true
+description: >-
+  Use when building autonomous Claude Code loops for Salesforce Apex and LWC
+  projects. Patterns from sequential pipelines to RFC-driven multi-agent DAG
+  systems with quality gates. Do NOT use for single-shot Apex tasks.
+---
+
+# Continuous Agent Loop
+
+Patterns, architectures, and reference implementations for running Claude Code autonomously in loops on Salesforce projects. Covers sequential `claude -p` pipelines through RFC-driven multi-agent DAG orchestration with Apex test gates.
+
+## When to Use
+
+- Setting up autonomous Salesforce development workflows (Apex TDD cycles, LWC iteration)
+- Choosing the right loop architecture for your problem (simple deploy vs complex feature)
+- Building CI/CD-style continuous development pipelines with SF CLI gates
+- Running parallel agents for multi-layer Salesforce work (Apex + LWC + Integration)
+- Adding quality gates (governor limits, coverage thresholds) to autonomous workflows
+
+## Loop Selection Flow
+
+```text
+Start
+  |
+  +-- Need strict CI/PR control? -- yes --> continuous-pr
+  |
+  +-- Need RFC decomposition? -- yes --> rfc-dag
+  |
+  +-- Need exploratory parallel generation? -- yes --> infinite
+  |
+  +-- default --> sequential
+```
+
+## Loop Pattern Spectrum
+
+| Pattern | Complexity | Best For |
+|---------|-----------|----------|
+| [Sequential Pipeline](#1-sequential-pipeline) | Low | Daily Apex dev steps, scripted SFDX workflows |
+| [Infinite Agentic Loop](#2-infinite-agentic-loop) | Medium | Parallel Apex/LWC generation from a spec |
+| [Continuous Claude PR Loop](#3-continuous-claude-pr-loop) | Medium | Multi-day Apex TDD iterations with CI gates |
+| [De-Sloppify Pattern](#4-the-de-sloppify-pattern) | Add-on | Quality cleanup after any Implementer step |
+| [Ralphinho / RFC-Driven DAG](#5-ralphinho--rfc-driven-dag) | High | Large Salesforce features with parallel units and merge queue |
+
+---
+
+## 1. Sequential Pipeline
+
+**The simplest loop.** Chain `claude -p` calls — each is a focused step with a clear prompt.
+
+```bash
+#!/bin/bash
+set -e
+
+# Step 1: Implement with TDD
+claude -p "Read docs/order-service-spec.md. Implement OrderService.cls with TDD.
+Target 85% coverage. No SOQL or DML inside for loops."
+
+# Step 2: De-sloppify
+claude -p "Review changes. Remove: unnecessary null checks, tests verifying platform
+behavior, System.debug statements, commented-out code.
+Run 'sf apex run test --class-names OrderServiceTest' after cleanup."
+
+# Step 3: Verify
+claude -p "Run 'sf project deploy start --dry-run --source-dir force-app/main/default/classes'.
+Fix any failures. Do not add new features."
+
+# Step 4: Commit
+claude -p "Commit with message: feat: add order service with test coverage"
+```
+
+**Variations:** Use `--model opus` for architecture analysis, `--model haiku` for simple fixes. Use `--allowedTools "Read,Grep,Glob"` for read-only analysis passes.
+
+---
+
+## 2. Infinite Agentic Loop
+
+**Two-prompt system** for parallel sub-agents. Useful for generating multiple Apex test class variants or LWC component iterations from a spec.
+
+```
+PROMPT 1 (Orchestrator)              PROMPT 2 (Sub-Agents)
+┌─────────────────────┐             ┌──────────────────────┐
+│ Parse spec file      │             │ Receive full context  │
+│ Scan output dir      │  deploys   │ Read assigned number  │
+│ Plan iteration       │────────────│ Follow spec exactly   │
+│ Assign creative dirs │  N agents  │ Generate unique output │
+└─────────────────────┘             └──────────────────────┘
+```
+
+### Key Insight: Uniqueness via Assignment
+
+Don't rely on agents to self-differentiate. The orchestrator **assigns** each agent a specific test scenario and iteration number. Batching: 1-5 simultaneously, 6-20 in batches of 5, infinite in waves of 3-5.
+
+---
+
+## 3. Continuous Claude PR Loop
+
+**Production-grade shell script** that runs Claude Code in a continuous loop, creating PRs, waiting for CI (including Apex test runs), and merging automatically.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  1. Create branch (continuous-claude/iteration-N)   │
+│  2. Run claude -p with Apex TDD prompt              │
+│  3. (Optional) Reviewer pass                        │
+│  4. Commit + Push + Create PR                       │
+│  5. Wait for CI (sf apex run test --code-coverage)  │
+│  6. CI failure? → Auto-fix pass (claude -p)         │
+│  7. Merge PR (squash) → Return to main → repeat     │
+│  Limit by: --max-runs N | --max-cost $X             │
+└─────────────────────────────────────────────────────┘
+```
+
+### Cross-Iteration Context: SHARED_TASK_NOTES.md
+
+The critical innovation — a file that persists across iterations:
+
+```markdown
+## Progress
+- [x] OrderService.cls — 82% coverage (iteration 1)
+- [ ] OrderController.cls — 45% coverage, needs work
+
+## Next Steps
+- Focus on OrderController.cls
+- Named credential for external API is set up
+```
+
+Claude reads this at iteration start, updates at iteration end.
+
+---
+
+## 4. The De-Sloppify Pattern
+
+**Add-on for any loop.** When you ask an LLM to implement Apex with TDD, it over-tests:
+
+- Tests verifying Salesforce platform behavior
+- Defensive null checks for schema-guaranteed fields
+- Excessive try/catch blocks
+
+**Solution:** Don't constrain the Implementer — let it be thorough. Then add a focused cleanup pass:
+
+```bash
+# Implement (thorough)
+claude -p "Implement OrderService.cls with full TDD."
+
+# De-sloppify (separate context)
+claude -p "Review changes. Remove tests for platform behavior, redundant null checks,
+System.debug statements, commented-out code. Run 'sf apex run test' after cleanup."
+```
+
+> Two focused agents outperform one constrained agent.
+
+---
+
+## 5. Ralphinho / RFC-Driven DAG
+
+**Most sophisticated.** RFC-driven pipeline that decomposes a Salesforce feature into a dependency DAG, runs each unit through quality stages, and lands via merge queue.
+
+```
+Salesforce RFC/PRD
+       │
+  DECOMPOSITION (sf-architect)
+  Break into: Apex → LWC → Integration → Metadata layers
+       │
+┌──────────────────────────────────────────────────┐
+│  For each DAG layer (sequential, by dependency): │
+│                                                  │
+│  Quality Pipelines (parallel per unit):          │
+│  Research → Plan → Implement → Test → Review     │
+│  Apex: governor check + ≥75% coverage gate       │
+│  LWC: Jest tests + accessibility check           │
+│                                                  │
+│  Merge Queue:                                    │
+│  Rebase → sf deploy validate → Apex tests →      │
+│  Pass → Land  |  Fail → Evict + re-enter         │
+└──────────────────────────────────────────────────┘
+```
+
+### Complexity Tiers
+
+| Tier | Pipeline Stages |
+|------|----------------|
+| **trivial** | implement → sf deploy validate |
+| **small** | implement → apex test → code-review |
+| **medium** | research → plan → implement → apex test → governor-check → review-fix |
+| **large** | + sf-architect final review |
+
+### When to Use Ralphinho vs SCC-Native
+
+| Signal | Ralphinho | SCC-Native |
+|--------|----------|------------|
+| 10+ interdependent work units | Yes | No |
+| Need worktree isolation | Yes | No |
+| Single feature with 3 layers | No | Yes |
+| Quick Apex + LWC iteration | No | Yes |
+
+---
+
+## Salesforce Loop Patterns
+
+| Pattern | Loop Type | Stop Condition |
+|---------|-----------|---------------|
+| **Governor Fix** | sequential | No more governor violations |
+| **Coverage Ramp** | sequential | All classes at 75%+ (85% target) |
+| **PB→Flow Migration** | continuous-pr | All Process Builders converted |
+| **Trigger Framework Migration** | sequential | All triggers use handler pattern |
+| **Deployment Monitor** | infinite (30s) | Deploy succeeds/fails/cancelled |
+
+### SF-Specific Checkpoint Format
+
+```
+── SF Checkpoint #N ────────────────────────
+  Apex Tests:    142/145 passing (+3)
+  Coverage:      78% → 82% (target: 85%)
+  Governor:      2 violations remaining (was 8)
+  Deploy:        Validates against scratch org
+  Iteration:     N/max
+────────────────────────────────────────────
+```
+
+---
+
+## Choosing the Right Pattern
+
+```
+Is the task a single focused Salesforce change?
+├─ Yes → Sequential Pipeline
+└─ No → Is there a written RFC/spec?
+         ├─ Yes → Need parallel layers?
+         │        ├─ Yes → RFC-Driven DAG
+         │        └─ No → Continuous Claude PR Loop
+         └─ No → Need many variants from a spec?
+                  ├─ Yes → Infinite Agentic Loop
+                  └─ No → Sequential + De-Sloppify
+```
+
+### Combining Patterns
+
+1. **Sequential + De-Sloppify** — Most common. Every Apex implement step gets a cleanup pass.
+2. **Continuous Claude + De-Sloppify** — Add `--review-prompt` with de-sloppify directive.
+3. **Any loop + Quality Gates** — Use the `sf-review-agent` agent as a gate before commits.
+4. **Model routing** — `--model haiku` for simple fixes, `--model opus` for architecture.
+
+## Anti-Patterns
+
+1. **Infinite loops without exit conditions** — Always have max-runs, max-cost, or completion signal.
+2. **No context bridge** — Use `SHARED_TASK_NOTES.md` to bridge `claude -p` invocations.
+3. **Retrying same failure** — Capture failure output and feed to next attempt.
+4. **Negative instructions instead of cleanup** — Don't say "don't add System.debug." Add a separate de-sloppify pass.
+5. **All agents in one context** — Separate concerns into different agent processes.
+6. **Ignoring deploy dependency order** — Apex before LWC before metadata.
+
+## References
+
+| Project | Author | SCC Context |
+|---------|--------|-------------|
+| Ralphinho | enitrat | Adapted for Salesforce layers |
+| Infinite Agentic Loop | disler | Useful for Apex test generation |
+| Continuous Claude | AnandChowdhary | Use with sf apex run test as CI gate |
+
+## Related
+
+- **Agent**: `loop-operator` — For monitoring and managing autonomous agent loops

package/skills/mcp-server-patterns/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: mcp-server-patterns
+origin: SCC
+user-invocable: false
+description: >-
+  Use when building MCP servers for Salesforce Apex or org integration.
+  Node/TypeScript SDK patterns — tools, resources, prompts, Zod validation,
+  stdio vs Streamable HTTP. Do NOT use for Apex class writing or deployment.
+---
+
+# MCP Server Patterns
+
+The Model Context Protocol (MCP) lets AI assistants call tools, read resources, and use prompts from your server. Use this skill when building or maintaining MCP servers, or integrating with the official Salesforce MCP server. The SDK API evolves; check Context7 (query-docs for "MCP") or the official MCP documentation for current method names and signatures.
+
+## When to Use
+
+Use when: implementing a new MCP server, adding tools or resources, choosing stdio vs HTTP, integrating with `@salesforce/mcp`, upgrading the SDK, or debugging MCP registration and transport issues.
+
+## How It Works
+
+### Core Concepts
+
+- **Tools**: Actions the model can invoke (e.g. search, run a command). Register with `registerTool()` or `tool()` depending on SDK version.
+- **Resources**: Read-only data the model can fetch (e.g. file contents, API responses). Register with `registerResource()` or `resource()`. Handlers typically receive a `uri` argument.
+- **Prompts**: Reusable, parameterised prompt templates the client can surface (e.g. in Claude Desktop). Register with `registerPrompt()` or equivalent.
+- **Transport**: stdio for local clients (e.g. Claude Desktop); Streamable HTTP is preferred for remote (Cursor, cloud). Legacy HTTP/SSE is for backward compatibility.
+
+The Node/TypeScript SDK may expose `tool()` / `resource()` or `registerTool()` / `registerResource()`; the official SDK has changed over time. Always verify against the current [MCP docs](https://modelcontextprotocol.io) or Context7.
+
+### Transport Decision Guide
+
+| Transport | Use When | Examples |
+|-----------|----------|---------|
+| **stdio** | Local client, same machine, Claude Desktop/Code | Development, local testing |
+| **Streamable HTTP** | Remote clients, cloud deployment, multi-user | Cursor, production APIs |
+| **Legacy HTTP/SSE** | Backward compatibility only | Older clients |
+
+Keep server logic (tools + resources) independent of transport so you can plug in stdio or HTTP in the entrypoint.
+
+## Examples
+
+### Install and Server Setup
+
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+
+// Register a tool
+server.tool(
+  "search-records",
+  "Search Salesforce records by keyword",
+  { query: z.string(), objectType: z.string().default("Account") },
+  async ({ query, objectType }) => {
+    // Your implementation here
+    return { content: [{ type: "text", text: JSON.stringify(results) }] };
+  }
+);
+
+// Connect via stdio
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+> **Note:** Registration API varies by SDK version — some versions use positional args `server.tool(name, description, schema, handler)`, others use object syntax. Check the official MCP docs or Context7 for current `@modelcontextprotocol/sdk` signatures.
+
+Use **Zod** (or the SDK's preferred schema format) for input validation.
+
+## Salesforce MCP Integration
+
+### Official @salesforce/mcp Server
+
+MCP config is auto-installed by `npx scc install` (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor). The official `@salesforce/mcp` server provides these toolsets:
+
+| Toolset | What It Does |
+|---------|-------------|
+| `orgs` | Org management, auth, user info |
+| `metadata` | Deploy, retrieve, list metadata types |
+| `data` | SOQL queries, record CRUD, bulk operations |
+| `users` | User management, permission sets |
+| `testing` | Run Apex tests, get coverage results |
+| `code-analysis` | PMD/scanner, code quality checks |
+| `lwc-experts` | LWC development guidance |
+| `devops` | Source tracking, scratch org operations |
+
+### Using @salesforce/mcp in Claude Code
+
+```json
+{
+  "mcpServers": {
+    "salesforce": {
+      "command": "npx",
+      "args": ["-y", "@salesforce/mcp@latest"],
+      "env": {
+        "SF_ORG_ALIAS": "my-org"
+      }
+    }
+  }
+}
+```
+
+### Building Custom Salesforce MCP Tools
+
+When `@salesforce/mcp` doesn't cover your use case (org-specific business logic, custom validation rules, internal APIs), build a custom MCP server:
+
+```typescript
+import { execFileSync } from "child_process";
+
+server.tool(
+  "validate-account-hierarchy",
+  "Check account hierarchy depth and circular references",
+  { accountId: z.string().regex(/^[a-zA-Z0-9]{15,18}$/, "Must be a valid 15- or 18-char Salesforce ID") },
+  async ({ accountId }) => {
+    const result = execFileSync("sf", [
+      "data", "query",
+      "--sobject", "Account",
+      "--where", `Id='${accountId}'`,
+      "--fields", "Id,ParentId",
+      "--json"
+    ], { timeout: 30000, encoding: "utf-8" });
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+```
+
+## Best Practices
+
+- **Schema first**: Define input schemas with Zod for every tool; document parameters and return shape.
+- **Input validation**: Validate and sanitize all inputs before passing to SF CLI or SOQL. Never interpolate raw user input into shell commands or queries.
+- **Errors**: Return structured errors or messages the model can interpret; avoid raw stack traces.
+- **Idempotency**: Prefer idempotent tools where possible so retries are safe.
+- **Timeouts**: Set explicit timeouts on `execSync`/`exec` calls (e.g., `{ timeout: 30000 }`) and on HTTP requests.
+- **Security**: Never pass raw user input to SOQL queries — use bind variables or parameterized queries. Use Named Credentials for external callouts. Validate Salesforce IDs with Zod regex (`/^[a-zA-Z0-9]{15,18}$/`) before passing to SF CLI.
+
+## Official SDKs and Docs
+
+- **JavaScript/TypeScript**: `@modelcontextprotocol/sdk` (npm). Use Context7 with library name "MCP" for current registration and transport patterns.
+- **Go**: Official Go SDK on GitHub (`modelcontextprotocol/go-sdk`).
+- **C#**: Official C# SDK for .NET.
+- **Salesforce MCP**: `@salesforce/mcp` (npm) — official Salesforce MCP server.

package/skills/model-route/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: model-route
+description: >-
+  Use when selecting Claude model tier for Salesforce development tasks. Recommend haiku, sonnet,
+  or opus based on Apex complexity, deploy risk, and budget.
+origin: SCC
+user-invocable: true
+---
+
+# Model Route — Task-to-Model Tier Recommendation
+
+Recommend the best model tier for the current task by complexity and budget.
+
+## When to Use
+
+- Before starting a task where model choice significantly affects quality or cost
+- When deciding between haiku, sonnet, and opus for a Salesforce development task
+- When the user wants cost-conscious model selection guidance
+- When routing sub-agent work to the appropriate model tier
+
+## Usage
+
+`/model-route [task-description] [--budget low|med|high]`
+
+## Routing Heuristic
+
+- `haiku`: deterministic, low-risk mechanical changes
+- `sonnet`: default for implementation and refactors
+- `opus`: architecture, deep review, ambiguous requirements
+
+> Model names (haiku, sonnet, opus) refer to the current Claude model mapped to that tier in your Claude Code configuration.
+
+## Output Format
+
+- recommended model
+- confidence level
+- why this model fits
+- fallback model if first attempt fails
+
+## Salesforce Routing Examples
+
+### Opus — Complex Reasoning Tasks
+
+Use `opus` when the task requires deep understanding of Salesforce architecture, security implications, or governor limit analysis across multiple execution paths.
+
+| Task | Why Opus |
+|------|----------|
+| Governor limit audit across trigger/flow/batch chains | Must trace cumulative DML/SOQL across async boundaries, understand order of execution, and reason about worst-case heap/CPU scenarios |
+| Security review of `@RestResource` or `with sharing`/`without sharing` decisions | Requires nuanced reasoning about record access, CRUD/FLS enforcement, SOQL injection vectors, and org-wide defaults |
+| Architecture review for large-scale data model changes | Must evaluate cascade effects on triggers, flows, validation rules, sharing rules, and downstream integrations |
+
+### Haiku — Mechanical / Low-Risk Tasks
+
+Use `haiku` when the task is deterministic, well-scoped, and unlikely to have subtle correctness issues.
+
+| Task | Why Haiku |
+|------|-----------|
+| Formatting LWC components (fix indentation, add missing `@api` decorators) | Purely mechanical — no logic changes, just style compliance |
+| Simple Apex fixes (rename a variable, fix a typo in a label, add a missing null check) | Single-line or few-line changes with obvious correctness |
+| Adding `<meta.xml>` boilerplate or updating `apiVersion` across components | Repetitive, pattern-based edits with no ambiguity |
+
+### Sonnet — Balanced Implementation Tasks
+
+Use `sonnet` (default) for standard development work that requires understanding but follows well-known patterns.
+
+| Task | Why Sonnet |
+|------|------------|
+| Code review of an Apex trigger handler or service class | Needs to understand patterns and spot issues, but follows standard review criteria |
+| Generating Apex test classes with `@TestSetup`, mocking, and assertions | Requires understanding the class under test, but test generation follows repeatable patterns |
+| Implementing a new LWC component with wire adapters and error handling | Standard implementation work — needs context awareness but not deep architectural reasoning |
+
+## Arguments
+
+- `[task-description]` optional free-text
+- `--budget low|med|high` optional
+
+## Examples
+
+```
+/model-route Review the sharing model for the new Patient__c object hierarchy
+/model-route Fix the CSS alignment on the accountDashboard LWC --budget low
+/model-route Generate test coverage for OpportunityTriggerHandler
+/model-route Audit all SOQL queries in force-app for governor limit risks --budget high
+```