clarus-dev-stack 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# Clarus Dev Stack
+
+Curated Claude Code skills and guardrail hooks for Salesforce consulting work.
+**Curated and supported by Mike Carter, Clarus Group.**
+
+## Install (or update): one line
+
+```
+npx clarus-dev-stack
+```
+
+That installs/refreshes BOTH streams:
+
+1. **Vendor stream:** the official Salesforce skills library ([forcedotcom/sf-skills](https://github.com/forcedotcom/sf-skills), 69 skills, maintained by Salesforce)
+2. **Clarus stream:** house skills and enforcement hooks (below)
+
+Re-running the same command is the update mechanism. It is idempotent and safe.
+
+## What the Clarus stream adds
+
+### Skills (knowledge that fires automatically)
+
+| Skill | What it protects |
+|---|---|
+| `clarus-conventions` | House standards: deploy discipline, FLS pairing rule, Apex standards, "the org must never be ahead of git" |
+| `clarus-test-discipline` | Never mutate production business logic to make a failing Apex test pass. Diagnose test-side first; production changes need explicit human approval |
+| `clarus-org-guard` | Companion to the org-guard hook: explains blocks, builds verified org-lock files |
+| `clarus-deploy-error-translator` | Translates cryptic Salesforce deploy errors into plain English + a fix |
+| `clarus-permset-watcher` | Catches "deployed-but-invisible": new metadata missing FLS/permset grants |
+| `clarus-datapack-guard` | OmniStudio DataPack import chunking; Dev Edition timeout-rollback protection |
+| `clarus-kill-images` | Strips base64 images from conversation history to control context bloat |
+
+### Hooks (deterministic enforcement, not suggestions)
+
+| Hook | Event | What it enforces |
+|---|---|---|
+| `clarus-org-guard` | Before every `sf` command | **Blocks** destructive commands unless the target org is allow-listed in the project's `.claude/org-lock.json` AND its real org ID (via `sf org display`) matches the lock. No lock file = no deploys. No `--target-org` = blocked |
+| `clarus-git-sync` | After every deploy | The org must never be ahead of git: warns when a deploy lands with uncommitted/unpushed changes |
+| `clarus-fls-audit` | After every deploy | Scans deployed metadata for missing canonical-permset grants |
+| `clarus-commit-cadence` | End of each turn | Nudges for a checkpoint commit when uncommitted work outlives the cadence window (default 90 min, configurable) |
+| `clarus-precompact-images` | Before compaction | Strips image payloads from the transcript |
+
+## The org-lock file (required for deploys)
+
+Each project gets `<project root>/.claude/org-lock.json`:
+
+```json
+{
+  "write":    { "my-sandbox": "00Dxx0000000001" },
+  "readonly": { "my-prod":    "00Dxx0000000002" },
+  "canonicalPermset": "My_Project_Admin",
+  "commitCadenceMinutes": 90
+}
+```
+
+Easiest path: open Claude Code in the project and say **"set up my org lock file"**. The clarus-org-guard skill runs the verified flow (real org IDs from `sf org display`, human confirmation before anything enters the `write` list).
+
+## Requirements
+
+- Node 18+ (for `npx`)
+- Claude Code
+- `sf` CLI (for org verification)
+- macOS/Linux (hooks use `python3`, present by default on macOS)
+
+## Architecture: two streams, zero merges
+
+Vendor skills are never edited, so Salesforce updates always apply cleanly. Clarus skills are prefixed `clarus-` and live alongside them; at runtime Claude composes both (vendor = the textbook, Clarus = the house style and the tripwires). Per-project specifics stay in each repo's `.claude/org-lock.json` and `CLAUDE.md`.
+
+## Support
+
+Questions, false positives, new tripwire candidates: Mike Carter.

package/bin/install.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/* Clarus Dev Stack installer
+ * - Installs the official Salesforce skills library (forcedotcom/sf-skills)
+ * - Installs Clarus skills into ~/.claude/skills/
+ * - Installs Clarus hook scripts into ~/.claude/hooks/clarus/
+ * - Merges hook registrations into ~/.claude/settings.json (idempotent, backed up)
+ * Curated by Mike Carter, Clarus Group.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execSync, spawnSync } = require("child_process");
+
+const PKG_ROOT = path.resolve(__dirname, "..");
+const HOME = os.homedir();
+const CLAUDE = path.join(HOME, ".claude");
+const SKILLS_DST = path.join(CLAUDE, "skills");
+const HOOKS_DST = path.join(CLAUDE, "hooks", "clarus");
+const SETTINGS = path.join(CLAUDE, "settings.json");
+
+const BANNER = `
+=============================================
+  CLARUS DEV STACK v1.0.0
+  Curated by Mike Carter, Clarus Group
+=============================================
+`;
+
+function log(s) { console.log(s); }
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function ensureHook(settings, event, matcher, command, ifFilter) {
+  settings.hooks = settings.hooks || {};
+  settings.hooks[event] = settings.hooks[event] || [];
+  // Dedupe: skip if any existing hook command in this event already references our script
+  const scriptName = path.basename(command.split(" ").pop());
+  for (const grp of settings.hooks[event]) {
+    for (const h of grp.hooks || []) {
+      if (h.command && h.command.includes(scriptName)) return false;
+    }
+  }
+  const hook = { type: "command", command, timeout: 60 };
+  if (ifFilter) hook.if = ifFilter;
+  const group = { hooks: [hook] };
+  if (matcher) group.matcher = matcher;
+  settings.hooks[event].push(group);
+  return true;
+}
+
+function main() {
+  log(BANNER);
+
+  // 0) Preflight
+  if (!fs.existsSync(CLAUDE)) fs.mkdirSync(CLAUDE, { recursive: true });
+  fs.mkdirSync(SKILLS_DST, { recursive: true });
+  fs.mkdirSync(HOOKS_DST, { recursive: true });
+
+  // 1) Official Salesforce skills (vendor stream)
+  log("[1/4] Installing official Salesforce skills (forcedotcom/sf-skills)...");
+  const res = spawnSync("npx", ["-y", "skills", "add", "forcedotcom/sf-skills",
+    "-g", "-y", "-s", "*", "-a", "claude-code"], { stdio: "inherit" });
+  if (res.status !== 0) {
+    log("  WARNING: official skills install did not complete cleanly. " +
+        "Re-run later with: npx skills add forcedotcom/sf-skills -g -y -s '*' -a claude-code");
+  }
+
+  // 2) Clarus skills (house stream)
+  log("[2/4] Installing Clarus skills...");
+  const skillsSrc = path.join(PKG_ROOT, "skills");
+  let count = 0;
+  for (const name of fs.readdirSync(skillsSrc)) {
+    copyDir(path.join(skillsSrc, name), path.join(SKILLS_DST, name));
+    count++;
+    log("  + " + name);
+  }
+
+  // 3) Clarus hook scripts
+  log("[3/4] Installing Clarus hook scripts...");
+  const hooksSrc = path.join(PKG_ROOT, "hooks");
+  for (const f of fs.readdirSync(hooksSrc)) {
+    const dst = path.join(HOOKS_DST, f);
+    fs.copyFileSync(path.join(hooksSrc, f), dst);
+    fs.chmodSync(dst, 0o755);
+    log("  + " + f);
+  }
+
+  // 4) Register hooks in settings.json (backup + idempotent merge)
+  log("[4/4] Registering hooks in ~/.claude/settings.json...");
+  let settings = {};
+  if (fs.existsSync(SETTINGS)) {
+    const raw = fs.readFileSync(SETTINGS, "utf8");
+    try {
+      settings = JSON.parse(raw);
+    } catch (e) {
+      log("  ERROR: settings.json is not valid JSON. Aborting hook registration " +
+          "(skills are installed). Fix the file and re-run.");
+      process.exit(1);
+    }
+    const backup = SETTINGS + ".bak." + new Date().toISOString().replace(/[:.]/g, "-");
+    fs.copyFileSync(SETTINGS, backup);
+    log("  backup: " + backup);
+  }
+
+  const H = (f) => `python3 "${path.join(HOOKS_DST, f)}"`;
+  const added = [];
+  // Org guard: deterministic wrong-org protection
+  if (ensureHook(settings, "PreToolUse", "Bash", H("clarus-org-guard.py"), "Bash(sf *)"))
+    added.push("PreToolUse: clarus-org-guard (blocks unverified org writes)");
+  // Git sync: org must never be ahead of git
+  if (ensureHook(settings, "PostToolUse", "Bash", H("clarus-git-sync.py"), "Bash(sf project deploy *)"))
+    added.push("PostToolUse: clarus-git-sync (commit after deploy)");
+  // FLS audit: deployed-but-invisible detection
+  if (ensureHook(settings, "PostToolUse", "Bash", H("clarus-fls-audit.py"), "Bash(sf project deploy *)"))
+    added.push("PostToolUse: clarus-fls-audit (permset gap warnings)");
+  // Commit cadence nag
+  if (ensureHook(settings, "Stop", null, H("clarus-commit-cadence.py")))
+    added.push("Stop: clarus-commit-cadence (checkpoint reminders)");
+  // PreCompact image strip — skip if an equivalent strip hook already exists
+  const hasStrip = JSON.stringify(settings.hooks?.PreCompact || []).includes("strip_images");
+  if (!hasStrip) {
+    if (ensureHook(settings, "PreCompact", null, H("clarus-precompact-images.py")))
+      added.push("PreCompact: clarus-precompact-images (context bloat control)");
+  } else {
+    log("  ~ PreCompact image strip already present; skipped duplicate");
+  }
+
+  fs.writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + "\n");
+  added.forEach((a) => log("  + " + a));
+
+  log(`
+=============================================
+  DONE. ${count} Clarus skills + ${added.length} hooks installed,
+  plus the official Salesforce skills library.
+
+  Verify: open Claude Code and type /skills
+  Note:   org deploys now require a per-project
+          .claude/org-lock.json (ask Claude:
+          "set up my org lock file")
+  Update: re-run  npx clarus-dev-stack
+=============================================
+`);
+}
+
+main();

package/hooks/clarus-commit-cadence.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Clarus commit-cadence: Stop hook.
+
+At the end of each turn, if the project repo has uncommitted changes AND the
+last commit is older than the cadence window, nudge for a checkpoint commit.
+Cadence is configurable via commitCadenceMinutes in .claude/org-lock.json
+(default 90). Never blocks; reminder only.
+"""
+import json
+import os
+import subprocess
+import sys
+import time
+
+DEFAULT_CADENCE_MIN = 90
+
+
+def find_lock(start):
+    d = os.path.abspath(start)
+    home = os.path.expanduser("~")
+    while True:
+        p = os.path.join(d, ".claude", "org-lock.json")
+        if os.path.isfile(p):
+            return p
+        if d in ("/", home):
+            return None
+        d = os.path.dirname(d)
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        payload = {}
+    cwd = payload.get("cwd") or os.getcwd()
+
+    cadence = DEFAULT_CADENCE_MIN
+    lock_path = find_lock(cwd)
+    if lock_path:
+        try:
+            with open(lock_path) as fh:
+                cadence = int(json.load(fh).get("commitCadenceMinutes", cadence))
+        except Exception:
+            pass
+
+    try:
+        inside = subprocess.run(
+            ["git", "-C", cwd, "rev-parse", "--is-inside-work-tree"],
+            capture_output=True, text=True, timeout=10,
+        )
+        if inside.stdout.strip() != "true":
+            sys.exit(0)
+        status = subprocess.run(
+            ["git", "-C", cwd, "status", "--porcelain"],
+            capture_output=True, text=True, timeout=10,
+        )
+        dirty = [l for l in status.stdout.splitlines() if l.strip()]
+        if not dirty:
+            sys.exit(0)
+        last = subprocess.run(
+            ["git", "-C", cwd, "log", "-1", "--format=%ct"],
+            capture_output=True, text=True, timeout=10,
+        )
+        last_ts = int(last.stdout.strip()) if last.returncode == 0 and last.stdout.strip() else 0
+    except Exception:
+        sys.exit(0)
+
+    age_min = (time.time() - last_ts) / 60 if last_ts else 10**6
+    if age_min < cadence:
+        sys.exit(0)
+
+    hrs = age_min / 60
+    age_str = f"{hrs:.1f}h" if hrs >= 1 else f"{int(age_min)}m"
+    print(json.dumps({
+        "systemMessage": (f"Clarus commit-cadence: {len(dirty)} uncommitted change(s), "
+                          f"last commit {age_str} ago (cadence {cadence}m). "
+                          "Checkpoint commit recommended.")
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/clarus-fls-audit.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Clarus FLS audit: PostToolUse hook on Bash.
+
+After `sf project deploy start`, checks whether newly deployed fields, objects,
+Apex classes, VF pages, and tabs are granted in the project's canonical
+permission set (canonicalPermset in .claude/org-lock.json). Warns on gaps:
+Salesforce does not auto-grant FLS, so missing grants mean deployed-but-invisible.
+"""
+import glob
+import json
+import os
+import re
+import sys
+
+
+def find_project_file(start, rel):
+    d = os.path.abspath(start)
+    home = os.path.expanduser("~")
+    while True:
+        p = os.path.join(d, rel)
+        if os.path.exists(p):
+            return d, p
+        if d in ("/", home):
+            return None, None
+        d = os.path.dirname(d)
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+    cmd = (payload.get("tool_input") or {}).get("command") or ""
+    if not re.search(r"\bsf\s+project\s+deploy\s+start\b", cmd):
+        sys.exit(0)
+
+    cwd = payload.get("cwd") or os.getcwd()
+    root, lock_path = find_project_file(cwd, os.path.join(".claude", "org-lock.json"))
+    if not lock_path:
+        sys.exit(0)
+    try:
+        with open(lock_path) as fh:
+            permset_name = json.load(fh).get("canonicalPermset")
+    except Exception:
+        sys.exit(0)
+    if not permset_name:
+        sys.exit(0)
+
+    permset_path = os.path.join(
+        root, "force-app", "main", "default", "permissionsets",
+        permset_name + ".permissionset-meta.xml")
+    if not os.path.isfile(permset_path):
+        sys.exit(0)
+    with open(permset_path) as fh:
+        permset = fh.read()
+
+    # Source dirs from the command; default to force-app
+    dirs = re.findall(r"--source-dir[=\s]+\"?([^\s\"]+)", cmd) or ["force-app"]
+    gaps = []
+    for src in dirs:
+        for part in src.split(","):
+            base = part if os.path.isabs(part) else os.path.join(root, part)
+            for f in glob.glob(os.path.join(base, "**", "fields", "*.field-meta.xml"), recursive=True):
+                obj = re.search(r"/objects/([^/]+)/fields/", f)
+                field = os.path.basename(f).replace(".field-meta.xml", "")
+                if obj and f"<field>{obj.group(1)}.{field}</field>" not in permset:
+                    # formula/required fields don't need FLS, but warn anyway; cheap to dismiss
+                    gaps.append(f"FLS: {obj.group(1)}.{field}")
+            for f in glob.glob(os.path.join(base, "**", "classes", "*.cls-meta.xml"), recursive=True):
+                cls = os.path.basename(f).replace(".cls-meta.xml", "")
+                if f"<apexClass>{cls}</apexClass>" not in permset:
+                    gaps.append(f"Apex class access: {cls}")
+            for f in glob.glob(os.path.join(base, "**", "pages", "*.page-meta.xml"), recursive=True):
+                pg = os.path.basename(f).replace(".page-meta.xml", "")
+                if f"<apexPage>{pg}</apexPage>" not in permset:
+                    gaps.append(f"VF page access: {pg}")
+
+    if not gaps:
+        sys.exit(0)
+    shown = gaps[:12]
+    more = f" (+{len(gaps) - 12} more)" if len(gaps) > 12 else ""
+    msg = (f"Clarus FLS audit: {len(gaps)} resource(s) in this deploy are NOT granted in "
+           f"{permset_name}: " + "; ".join(shown) + more +
+           ". Deployed-but-invisible risk. Add the grants or confirm they are intentional.")
+    print(json.dumps({
+        "systemMessage": msg,
+        "hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": msg},
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/clarus-git-sync.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Clarus git-sync: PostToolUse hook on Bash.
+
+Fires after `sf project deploy start` commands. Rule: the org must never be
+ahead of git. If the repo is dirty after a deploy, remind agent + human to
+commit and push the deployed source.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+    cmd = (payload.get("tool_input") or {}).get("command") or ""
+    if not re.search(r"\bsf\s+project\s+deploy\s+start\b", cmd):
+        sys.exit(0)
+    # Skip check-only validates; nothing landed in the org
+    if "--dry-run" in cmd or re.search(r"\bdeploy\s+validate\b", cmd):
+        sys.exit(0)
+
+    cwd = payload.get("cwd") or os.getcwd()
+    try:
+        inside = subprocess.run(
+            ["git", "-C", cwd, "rev-parse", "--is-inside-work-tree"],
+            capture_output=True, text=True, timeout=10,
+        )
+        if inside.stdout.strip() != "true":
+            sys.exit(0)
+        status = subprocess.run(
+            ["git", "-C", cwd, "status", "--porcelain"],
+            capture_output=True, text=True, timeout=10,
+        )
+        dirty = [l for l in status.stdout.splitlines() if l.strip()]
+        ahead = subprocess.run(
+            ["git", "-C", cwd, "rev-list", "--count", "@{u}..HEAD"],
+            capture_output=True, text=True, timeout=10,
+        )
+        unpushed = ahead.stdout.strip() if ahead.returncode == 0 else "?"
+    except Exception:
+        sys.exit(0)
+
+    if not dirty and unpushed in ("0", "?"):
+        sys.exit(0)
+
+    parts = []
+    if dirty:
+        parts.append(f"{len(dirty)} uncommitted change(s)")
+    if unpushed not in ("0", "?"):
+        parts.append(f"{unpushed} unpushed commit(s)")
+    detail = " and ".join(parts)
+    msg = (f"Clarus git-sync: deploy completed but the repo has {detail}. "
+           "Clarus rule: the org must never be ahead of git. Commit the deployed "
+           "source (and push) before moving on.")
+    print(json.dumps({
+        "systemMessage": msg,
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": msg,
+        },
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/clarus-org-guard.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Clarus org-guard: PreToolUse hook on Bash.
+
+Blocks destructive sf commands unless the target org is explicitly allow-listed
+in the project's .claude/org-lock.json AND its real org ID matches the lock.
+Deterministic enforcement; the companion skill clarus-org-guard handles UX.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+DESTRUCTIVE = [
+    r"\bsf\s+project\s+deploy\b",          # deploy + validate (validate runs tests in target)
+    r"\bsf\s+data\s+(update|delete|import|upsert|create)\b",
+    r"\bsf\s+apex\s+run\b(?!\s+test)",     # anonymous apex; `sf apex run test` is excluded
+    r"\bsf\s+force:source:(push|deploy)\b",
+    r"\bsf\s+project\s+delete\b",
+]
+
+
+def deny(reason):
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": "CLARUS ORG-GUARD: " + reason,
+        }
+    }))
+    sys.exit(0)
+
+
+def find_lock(start):
+    d = os.path.abspath(start)
+    home = os.path.expanduser("~")
+    while True:
+        p = os.path.join(d, ".claude", "org-lock.json")
+        if os.path.isfile(p):
+            return p
+        if d in ("/", home):
+            return None
+        d = os.path.dirname(d)
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+    cmd = (payload.get("tool_input") or {}).get("command") or ""
+    if "sf " not in cmd and not cmd.strip().startswith("sf"):
+        sys.exit(0)
+    if not any(re.search(p, cmd) for p in DESTRUCTIVE):
+        sys.exit(0)  # read-only sf command, pass through
+
+    cwd = payload.get("cwd") or os.getcwd()
+    lock_path = find_lock(cwd)
+    if not lock_path:
+        deny("destructive sf command in a project with no .claude/org-lock.json. "
+             "Create one first (see clarus-org-guard skill): verify each org with "
+             "`sf org display --target-org <alias> --json`, confirm with the human, "
+             "then write {\"write\": {\"<alias>\": \"<15-char org id>\"}, \"readonly\": {...}}.")
+
+    try:
+        with open(lock_path) as fh:
+            lock = json.load(fh)
+    except Exception as e:
+        deny(f"org-lock.json at {lock_path} is unreadable or invalid JSON ({e}). Fix it before deploying.")
+
+    m = re.search(r"(?:--target-org|-o)[=\s]+\"?([A-Za-z0-9_.@\-]+)", cmd)
+    if not m:
+        deny("destructive sf command without an explicit --target-org. "
+             "Clarus rule: no implicit default-org writes, ever. Add --target-org <alias>.")
+    alias = m.group(1)
+
+    write_orgs = {k: str(v)[:15] for k, v in (lock.get("write") or {}).items()}
+    ro_orgs = {k: str(v)[:15] for k, v in (lock.get("readonly") or {}).items()}
+
+    if alias in ro_orgs:
+        deny(f"'{alias}' is READ-ONLY in {lock_path}. Destructive commands against it are forbidden.")
+    if alias not in write_orgs:
+        deny(f"'{alias}' is not in the write allowlist in {lock_path}. "
+             "If this org genuinely belongs there, follow the verified flow in the "
+             "clarus-org-guard skill (human confirmation required).")
+
+    # Ground-truth verification: does the alias actually point at the locked org?
+    try:
+        out = subprocess.run(
+            ["sf", "org", "display", "--target-org", alias, "--json"],
+            capture_output=True, text=True, timeout=45,
+        )
+        info = json.loads(out.stdout)
+        actual = str((info.get("result") or {}).get("id") or "")[:15]
+    except Exception as e:
+        deny(f"could not verify org identity for '{alias}' ({e}). "
+             "Refusing to write to an unverified org. Check `sf org display --target-org "
+             f"{alias}` manually.")
+
+    expected = write_orgs[alias]
+    if not actual:
+        deny(f"`sf org display` returned no org id for '{alias}'. Refusing unverified write.")
+    if actual != expected:
+        deny(f"ORG ID MISMATCH for alias '{alias}': lock file expects {expected}, "
+             f"but the alias currently points at {actual}. The alias may have been "
+             "re-authed to a different org. Do NOT proceed; confirm with the human.")
+
+    # Verified: allow silently.
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/clarus-precompact-images.py

@@ -0,0 +1,36 @@
+import json, os, glob
+
+cwd = os.getcwd().replace('/', '-').lstrip('-')
+base = os.path.expanduser('~/.claude/projects/')
+project_dir = os.path.join(base, '-' + cwd)
+if os.path.isdir(project_dir):
+    jsonl_files = [f for f in glob.glob(os.path.join(project_dir, '*.jsonl'))]
+    if jsonl_files:
+        jsonl_path = max(jsonl_files, key=os.path.getmtime)
+        with open(jsonl_path, 'r') as f:
+            lines = f.readlines()
+        cleaned = []
+        stripped = 0
+        for line in lines:
+            try:
+                obj = json.loads(line)
+                if isinstance(obj, dict) and 'message' in obj:
+                    msg = obj['message']
+                    if isinstance(msg, dict) and 'content' in msg:
+                        content = msg['content']
+                        if isinstance(content, list):
+                            new_content = []
+                            for block in content:
+                                if isinstance(block, dict) and block.get('type') == 'image':
+                                    stripped += 1
+                                    new_content.append({'type': 'text', 'text': '[image removed by PreCompact hook]'})
+                                else:
+                                    new_content.append(block)
+                            msg['content'] = new_content
+                cleaned.append(json.dumps(obj) + '\n')
+            except:
+                cleaned.append(line)
+        with open(jsonl_path, 'w') as f:
+            f.writelines(cleaned)
+        if stripped > 0:
+            print(json.dumps({'systemMessage': f'PreCompact: stripped {stripped} images from JSONL'}))

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "clarus-dev-stack",
+  "version": "1.0.0",
+  "description": "Clarus Dev Stack: curated Claude Code skills and guardrail hooks for Salesforce consulting work. Curated by Mike Carter, Clarus Group.",
+  "bin": {
+    "clarus-dev-stack": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "hooks/",
+    "README.md"
+  ],
+  "keywords": [
+    "claude-code",
+    "salesforce",
+    "agent-skills",
+    "clarus"
+  ],
+  "author": "Mike Carter <mcarter@clarusgroup.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/clarus-conventions/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: clarus-conventions
+description: |
+  Clarus Group house conventions for Salesforce work. This skill SUPPLEMENTS the official Salesforce skills (generating-apex, deploying-metadata, generating-custom-field, etc.) with firm-level standards. Where guidance conflicts, Clarus conventions win for Clarus engagement work.
+
+  TRIGGER when: generating or modifying any Salesforce metadata (Apex, fields, objects, flows, permsets, LWC), deploying to any org, or starting work in a Salesforce project.
+
+  SKIP when: the work is not Salesforce-related, or the project is explicitly not a Clarus engagement.
+---
+
+# Clarus Conventions
+
+These are firm standards. They encode scar tissue from real engagements. Apply them on top of whatever the official Salesforce skills recommend.
+
+## Deploy discipline
+
+1. **Every `sf` command carries an explicit `--target-org`.** Never rely on the default org. The default org is how wrong-org accidents happen.
+2. **Never use `--ignore-conflicts` against a client org.** Conflicts are information.
+3. **Validate before deploying to any production or UAT org** when the change set is non-trivial: check-only first, then deploy.
+4. **"Unchanged" in a deploy result does NOT mean a component is accessible or working.** It only means metadata matched.
+
+## The FLS pairing rule (the #1 Salesforce deploy gotcha)
+
+Salesforce does NOT auto-grant field-level security or object access when metadata deploys. Every new field, object, Apex class, VF page, or tab MUST ship with its permission set grant in the same change, or it will be deployed-but-invisible ("No such column" errors while the metadata looks fine). When a field is unexpectedly inaccessible, diagnose in this order, do not skip ahead: (1) FLS, (2) object CRUD, (3) record ownership/sharing, (4) field actually exists in the org (describe-confirm, not repo-confirm), (5) guest/site user context. Only then consider caching or platform bugs.
+
+## Apex standards
+
+1. No hardcoded record IDs, org IDs, or URLs in Apex. Use Custom Metadata, Custom Settings, or Named Credentials.
+2. Bulkify everything. Assume 200+ records in every trigger context.
+3. Test data comes from a TestDataFactory pattern, never from `SeeAllData=true`.
+4. One trigger per object, logic in handler classes.
+
+## Source control
+
+1. **The org must never be ahead of git.** After every successful deploy to a client org, commit the deployed source and push to the remote in the same work session. A deployed-but-uncommitted change is invisible to the rest of the team and unrecoverable if the sandbox refreshes.
+2. Commit at meaningful checkpoints, not just at the end of the day. If the working tree has substantial uncommitted changes and the last commit is hours old, stop and commit.
+3. Commit messages describe the business change, not just the file change.
+
+## Org safety
+
+1. Org allowlists live in each project's `.claude/org-lock.json` (see clarus-org-guard). If a project has no lock file, create one before the first deploy.
+2. Production orgs are read-only for comparison unless the engagement explicitly includes a production deployment window.

package/skills/clarus-datapack-guard/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: clarus-datapack-guard
+description: |
+  Clarus tripwire for OmniStudio DataPack imports, especially in Developer Editions and scratch orgs. The official deploying-omnistudio-datapacks skill covers the vlocity CLI path and settings/dependency errors; this skill covers the UI import wizard timeout-and-rollback failure mode it does not encode (gap verified 2026-06-12).
+
+  TRIGGER when: importing or deploying OmniStudio/Vlocity DataPacks (any path: UI import wizard, vlocity CLI, packDeploy), especially into Developer Edition or scratch orgs; when a DataPack import times out, rolls back, or partially activates; when bulk-activating Data Mappers or OmniScripts after import.
+
+  SKIP when: standard sf metadata deploys (use deploying-metadata), or OmniStudio authoring work (use the building-omnistudio-* skills).
+---
+
+# Clarus DataPack Guard
+
+## The failure mode this protects against
+
+Large DataPack imports into Developer Edition orgs can hit activation timeouts and ROLL BACK the whole import, silently losing work and leaving partial state. The UI import wizard is most vulnerable; it gives no chunking control by default.
+
+## The rules
+
+1. **Chunk imports by component type.** Import Data Mappers SEPARATELY from OmniScripts. Never one giant combined import into a Dev Edition.
+2. **Activate in passes, not in bulk through the wizard.** If post-import activation times out, activate via Apex DML on `OmniDataTransform` (core runtime) or the package equivalent. Pattern that works: query the inactive records, set `IsActive = true` in batches via anonymous Apex.
+3. **Know your runtime before you start.** Core runtime (OmniProcess / OmniDataTransform standard objects) vs managed package (`omnistudio__` / `vlocity_*` namespaced objects) changes every API name in your activation scripts. Detect first (the official analyzing-omnistudio-dependencies skill does namespace detection).
+4. **Inventory before import.** Hand-inventory the DataPack JSON contents (component counts by type) so you know what "complete" looks like and can verify nothing silently rolled back.
+5. **After any timeout: verify, never assume.** Query actual record counts and activation status against the org. A timed-out import may have partially committed.

package/skills/clarus-deploy-error-translator/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: clarus-deploy-error-translator
+description: Auto-fire after any `sf project deploy` that returns "Status: Failed" or "Component Failures". Reads the error message and translates Salesforce-speak into plain English with a specific suggested fix. Especially useful for cryptic platform errors like "An unexpected error occurred", "setup object in use", "license doesn't allow", or LightningTypeBundle / GenAi* failures.
+---
+
+When a deploy fails:
+
+1. Extract the error message text and component name from the deploy output.
+2. Match against known patterns:
+
+| Pattern | Plain English | Fix |
+|---|---|---|
+| "setup object in use" | Something else still references it | Find consumer (Bot? Plugin? Apex? Permset?) and delete in dependency order |
+| "license doesn't allow the permission" | Permset license can't grant this perm | Match permset license to user license; remove the perm or change license |
+| "license can't be updated" | Can't change license on existing permset | Delete and recreate |
+| "no such column" | Field exists in metadata but lacks FLS | Add field to a permset's fieldPermissions |
+| "Element X is duplicated" | XML schema expects each entry in own wrapper | Each X needs its own outer element, not multiple inside one |
+| "An unexpected error occurred. ErrorId: N" | Platform-side opaque error | Capture ErrorId; check if related metadata is in broken state; consider Salesforce Support |
+| "LightningTypeBundle ... could not be found" | GenAiFunction lacks input/output schema files | Add `input/schema.json` and `output/schema.json` next to the GenAiFunction XML |
+| "An action with developer name X already exists" | Standalone GenAiFunction conflicts with bundle's plannerActions | Either delete standalone or rename bundle action |
+| "Property 'X' not valid in version Y" | sourceApiVersion in sfdx-project.json too low | Bump to 65.0 or whatever the message says |
+
+3. Output: 2-3 sentence translation + the specific next step.

package/skills/clarus-kill-images/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: clarus-kill-images
+description: |
+  Strip base64 image data from ALL JSONL files in the current Claude Code project (conversations + subagents) to reduce file size and prevent context bloat. Replaces `image` content blocks with a short text placeholder, preserving structure while removing the huge base64 payload.
+
+  TRIGGER when the user asks to strip, clean, remove, or purge images from conversation history or JSONL files. Also trigger on phrases like "kill images," "clean up conversation history," "reduce project size," "my JSONL files are too big," or when a conversation mentions that image content is bloating the transcript/context.
+
+  SKIP when the user wants to preserve images for reference, when operating outside a Claude Code project directory, or when the request is about actual image files (PNG/JPG/etc.) rather than base64 content inside JSONL.
+---
+
+# Kill Images
+
+## Instructions
+
+1. Find the current project's JSONL files:
+   - Look in `~/.claude/projects/` for a directory matching the current working directory (sanitized with dashes)
+   - Process ALL `.jsonl` files: top-level conversations AND subagent files in `*/subagents/` subdirectories
+
+2. Run this Python script via Bash to strip images:
+
+```python
+import json, os, sys, glob
+
+# Find project dir matching cwd
+cwd = os.getcwd().replace('/', '-').lstrip('-')
+base = os.path.expanduser('~/.claude/projects/')
+project_dir = os.path.join(base, '-' + cwd)
+
+if not os.path.isdir(project_dir):
+    print(f"No project dir found at {project_dir}")
+    sys.exit(1)
+
+# Find ALL .jsonl files: top-level + subagents
+jsonl_files = glob.glob(os.path.join(project_dir, '*.jsonl')) + \
+              glob.glob(os.path.join(project_dir, '*/subagents/*.jsonl'))
+
+if not jsonl_files:
+    print("No JSONL files found")
+    sys.exit(1)
+
+total_stripped = 0
+total_saved = 0
+
+class Counter:
+    def __init__(self):
+        self.n = 0
+
+for jsonl_path in jsonl_files:
+    orig_size = os.path.getsize(jsonl_path)
+    with open(jsonl_path, 'r') as f:
+        lines = f.readlines()
+
+    cleaned = []
+    counter = Counter()
+    for line in lines:
+        try:
+            obj = json.loads(line)
+            def replace_images(o, c=counter):
+                if isinstance(o, list):
+                    new_list = []
+                    for item in o:
+                        if isinstance(item, dict) and item.get('type') == 'image':
+                            c.n += 1
+                            new_list.append({'type': 'text', 'text': '[image removed by kill-images]'})
+                        else:
+                            replace_images(item, c)
+                            new_list.append(item)
+                    o.clear()
+                    o.extend(new_list)
+                elif isinstance(o, dict):
+                    for v in o.values():
+                        if isinstance(v, (dict, list)):
+                            replace_images(v, c)
+            replace_images(obj)
+            cleaned.append(json.dumps(obj) + '\n')
+        except:
+            cleaned.append(line)
+
+    stripped = counter.n
+    if stripped > 0:
+        with open(jsonl_path, 'w') as f:
+            f.writelines(cleaned)
+        new_size = os.path.getsize(jsonl_path)
+        saved = orig_size - new_size
+        total_stripped += stripped
+        total_saved += saved
+        print(f"{os.path.basename(jsonl_path)}: {stripped} images stripped, saved {saved / 1024 / 1024:.1f}MB")
+
+if total_stripped == 0:
+    print(f"Scanned {len(jsonl_files)} file(s) — no images found.")
+else:
+    print(f"\nTotal: {total_stripped} images stripped across {len(jsonl_files)} file(s), saved {total_saved / 1024 / 1024:.1f}MB")
+```
+
+3. Report the results to the user (files touched, images stripped, MB saved).

package/skills/clarus-org-guard/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: clarus-org-guard
+description: |
+  Companion skill to the Clarus org-guard HOOK (the deterministic enforcer). Explains org-lock blocks, helps create and maintain .claude/org-lock.json files, and enforces org identity verification practices. The hook physically blocks destructive sf commands against unlisted or mismatched orgs; this skill handles the human-facing side.
+
+  TRIGGER when: a command is blocked by the Clarus org guard, a project needs an org-lock.json created, the user asks about org safety or wrong-org protection, a new org alias enters the project, or any work begins in a Salesforce project that has no .claude/org-lock.json.
+
+  SKIP when: non-Salesforce projects.
+---
+
+# Clarus Org Guard (companion skill)
+
+## What the hook does (so you can explain it)
+
+A PreToolUse hook intercepts every Bash command containing `sf`. For DESTRUCTIVE commands (deploy, data update/delete/import/upsert/create, apex run), it enforces:
+
+1. An explicit `--target-org` is present. No implicit default-org writes, ever.
+2. The alias is in the project's `.claude/org-lock.json` under `write`.
+3. The alias's ACTUAL org ID (via `sf org display`) matches the locked org ID. This catches re-authed aliases silently pointing at the wrong org.
+4. Orgs under `readonly` allow retrieves/queries but never writes.
+5. No lock file in the project = destructive commands are blocked until one exists.
+
+The hook's decision is deterministic. Do not attempt to work around a block; resolve it.
+
+## The lock file format
+
+`<project root>/.claude/org-lock.json`:
+
+```json
+{
+  "write": {
+    "my-sandbox-alias": "00DgP00000215qv"
+  },
+  "readonly": {
+    "my-prod-alias": "00DDp000001Q5P3"
+  },
+  "canonicalPermset": "My_Project_Admin",
+  "commitCadenceMinutes": 90
+}
+```
+
+Org IDs are the 15-character prefix (the 18-char form is also accepted; comparison uses the first 15). `canonicalPermset` and `commitCadenceMinutes` are optional and consumed by other Clarus hooks.
+
+## Creating a lock file (the verified way)
+
+NEVER write an org ID into the lock file from memory or from documentation alone. Verify against ground truth:
+
+1. Run `sf org display --target-org <alias> --json` and read the actual `id`.
+2. Show the human the alias, username, instance URL, and org ID.
+3. Ask the human to confirm which orgs belong in `write` vs `readonly`.
+4. Write the file only after explicit confirmation. Adding an org to `write` is a human decision, always.
+
+## When a block fires
+
+1. Read the block reason to the human in plain language.
+2. If the org genuinely belongs in the lock file, run the verified creation flow above.
+3. If the command targeted the wrong org, say so plainly: the guard just did its job.
+4. Never suggest bypassing the hook, removing the lock file, or running the command with a different alias to evade the block.

package/skills/clarus-permset-watcher/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: clarus-permset-watcher
+description: |
+  Auto-fire when ANY Salesforce metadata file is written/edited that creates new accessibility surface (custom fields, custom objects, Apex classes, Visualforce pages, custom tabs, GenAi actions). Salesforce does NOT auto-grant FLS/object access to deployed metadata. The result is "deployed but invisible": fields show in metadata API and FieldDefinition but cause "No such column" errors in SOQL/UI. THIS IS THE #1 SALESFORCE DEPLOY GOTCHA. CHECK FOR IT FIRST.
+
+  TRIGGER on edits to `*.field-meta.xml`, `*.object-meta.xml`, `*.cls-meta.xml`, `*.page-meta.xml`, `*.tab-meta.xml`, `*.genAiFunction-meta.xml`, or `*.flow-meta.xml`. Remind the developer to add the new resource to the project's canonical permission set before they waste time debugging "missing fields".
+
+  SKIP when: the edit removes a resource, or the resource is already granted in the canonical permset.
+---
+
+# Clarus Permset Watcher
+
+## Finding the canonical permission set (in order)
+
+1. `canonicalPermset` key in `<project root>/.claude/org-lock.json`
+2. A permset named in the project's CLAUDE.md
+3. If neither exists: list the permsets in `force-app/main/default/permissionsets/` and ASK the human which one is canonical for this project, then record the answer in org-lock.json so this question never repeats.
+
+## What needs which grant
+
+| File pattern | Permission needed | Add to canonical permset as |
+|---|---|---|
+| `objects/*/fields/*.field-meta.xml` | FLS | `<fieldPermissions>` with `field`, `readable`, `editable` |
+| `objects/*.object-meta.xml` (new object) | Object access | `<objectPermissions>` with allowRead/Edit/Create/Delete |
+| `classes/*.cls-meta.xml` | Apex class access | `<classAccesses>` with `apexClass`, `enabled=true` |
+| `pages/*.page-meta.xml` | VF page access | `<pageAccesses>` with `apexPage`, `enabled=true` |
+| `tabs/*.tab-meta.xml` | Tab visibility | `<tabSettings>` with visibility |
+| `genAiFunctions/*/*.genAiFunction-meta.xml` | The Apex wrapper class needs class access | `<classAccesses>` for the `<invocationTarget>` Apex class |
+| `flows/*.flow-meta.xml` (active flows) | Flow access (only if profile-restricted) | usually inherited but check |
+
+## Behavior
+
+1. Detect the type from the file path.
+2. Read the affected resource's name (field name, object name, class name, etc.).
+3. Resolve the canonical permset (see above) and read it.
+4. If the resource is NOT in the permset, warn:
+
+```
+FLS/Permset gap on <resource_name>. This deploy will succeed but the resource will be
+INVISIBLE to users until you add it to <canonical permset>. Fix: <exact XML block>.
+```
+
+5. Offer to add the grant in the same change. The grant ships WITH the metadata, not after.

package/skills/clarus-test-discipline/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: clarus-test-discipline
+description: |
+  Clarus guardrail: never change production business logic just to make a failing Apex test pass. Protects business logic from silent mutation during test-fix loops.
+
+  TRIGGER when: an Apex test fails and a fix is being attempted, when iterating on test classes against existing production code, when coverage requirements force changes, or when any edit to a non-test class happens during a test-fixing session.
+
+  SKIP when: writing brand-new code with brand-new tests (no existing behavior to protect), or when the human has explicitly stated the production logic itself is wrong and approved changing it.
+---
+
+# Clarus Test Discipline
+
+## The rule
+
+A failing test is a question, not an instruction. It asks: "is the test wrong, or is the code wrong?" Answer the question BEFORE changing anything. The most common and most dangerous failure mode in agent-assisted Apex work is silently rewriting production business logic until the test goes green.
+
+## When a test fails, diagnose in this order
+
+1. **Test data.** Is the test creating valid, complete records? Missing required fields, missing parent records, and validation rule collisions cause most failures. Fix: the test's data setup.
+2. **Test assumptions.** Does the assertion reflect the actual business requirement? A wrong expected value is a test bug. Fix: the assertion, with a comment explaining the requirement.
+3. **Test isolation.** Order-of-execution issues, missing Test.startTest/stopTest, governor limits inside the test, mocking gaps. Fix: the test structure.
+4. **Environment.** Org-specific config the test assumes (custom settings, metadata records, feature flags). Fix: the test's setup or a TestDataFactory addition.
+5. **ONLY THEN consider that the production code is wrong.**
+
+## If the production code appears wrong
+
+STOP. Do not edit it. Present the case to the human:
+
+```
+The test expects X. The production code does Y.
+I believe the code is wrong because <reason>.
+Changing <class.method> would alter live business behavior: <what changes for users>.
+Approve the production change, or should the test reflect current behavior?
+```
+
+Only proceed after explicit approval. The human owns business behavior; the agent owns test mechanics.
+
+## Forbidden moves (never do these to reach green)
+
+1. Weakening an assertion (`assertEquals` to `assertNotEquals`, removing asserts, asserting true).
+2. Adding `Test.isRunningTest()` branches to production code to bypass logic under test.
+3. Changing field values, formulas, or conditional logic in production classes without approval.
+4. Commenting out or deleting the failing test.
+5. Catch-and-swallow in production code to suppress the exception the test exposes.
+
+## Coverage pressure
+
+When coverage is below threshold, the fix is MORE test scenarios, never trimmed production logic. Dead code discovered during coverage work gets reported to the human, not silently deleted.