@claude-code-mastery/starter-kit 1.0.0

package/.claude/hooks/check-branch.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Branch Protection Hook — PreToolUse (Bash)
+# Blocks committing directly to main/master when auto_branch is enabled.
+# Exit code 2 = block operation and tell Claude why.
+#
+# Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+INPUT=$(cat)
+
+# Extract command from JSON — try jq first, fall back to grep/sed (no Python needed)
+if command -v jq &>/dev/null; then
+    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+else
+    # Lightweight fallback: extract "command" value from JSON via grep/sed
+    COMMAND=$(echo "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//;s/"$//')
+fi
+
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Only check git commit commands
+if ! echo "$COMMAND" | grep -qE 'git\s+commit'; then
+    exit 0
+fi
+
+# Detect target directory from git -C <path> in the command
+# Only match real paths (starting with / ~ . or alphanumeric), not placeholders like <dir>
+TARGET_DIR=""
+if echo "$COMMAND" | grep -qE 'git\s+-C\s+[/~.\w]'; then
+    TARGET_DIR=$(echo "$COMMAND" | sed -nE 's/.*git\s+-C\s+([^ ]+)\s+.*/\1/p' | head -1)
+fi
+
+# Also detect: cd /some/path && git commit (common cross-repo pattern)
+# Extract the first cd target from commands like "cd /path && git ..."
+if [ -z "$TARGET_DIR" ] && echo "$COMMAND" | grep -qE '^cd\s+[^ ]+'; then
+    CD_DIR=$(echo "$COMMAND" | sed -nE 's/^cd\s+([^ &;]+).*/\1/p' | head -1)
+    # Expand leading tilde — [ -d "~/path" ] doesn't expand tilde inside quotes
+    CD_DIR="${CD_DIR/#\~/$HOME}"
+    if [ -n "$CD_DIR" ] && [ -d "$CD_DIR" ]; then
+        TARGET_DIR="$CD_DIR"
+    fi
+fi
+
+# Resolve git dir — if git -C was used with a valid path, check THAT repo
+if [ -n "$TARGET_DIR" ] && [ -d "$TARGET_DIR" ]; then
+    if ! git -C "$TARGET_DIR" rev-parse --is-inside-work-tree &>/dev/null; then
+        exit 0
+    fi
+    BRANCH=$(git -C "$TARGET_DIR" branch --show-current 2>/dev/null)
+    # Allow initial commits (no previous commits in the target repo)
+    if ! git -C "$TARGET_DIR" rev-parse HEAD &>/dev/null 2>&1; then
+        exit 0
+    fi
+else
+    # CWD-based git check
+    if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+        exit 0
+    fi
+    BRANCH=$(git branch --show-current 2>/dev/null)
+    # Allow initial commits (no previous commits yet)
+    if ! git rev-parse HEAD &>/dev/null 2>&1; then
+        exit 0
+    fi
+fi
+
+# Only care about main/master
+if [ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ]; then
+    exit 0
+fi
+
+# Check auto_branch setting (default: true)
+# Look for claude-mastery-project.conf in the target repo first, then CWD.
+# If neither has the conf file, this is not a starter kit project — skip the check.
+AUTO_BRANCH="true"
+CONF_FOUND=false
+CONF="claude-mastery-project.conf"
+
+# Determine where to look for the conf — target dir or CWD
+CONF_SEARCH_DIR=""
+if [ -n "$TARGET_DIR" ] && [ -d "$TARGET_DIR" ]; then
+    CONF_SEARCH_DIR="$TARGET_DIR"
+else
+    CONF_SEARCH_DIR="."
+fi
+
+if [ -f "${CONF_SEARCH_DIR}/${CONF}" ]; then
+    CONF_FOUND=true
+    SETTING=$(grep -E '^\s*auto_branch\s*=' "${CONF_SEARCH_DIR}/${CONF}" 2>/dev/null | head -1 | sed 's/.*=\s*//' | sed 's/\s*#.*//' | tr -d ' ')
+    if [ -n "$SETTING" ]; then
+        AUTO_BRANCH="$SETTING"
+    fi
+elif [ -z "$TARGET_DIR" ] && [ -f "$CONF" ]; then
+    # Fallback: conf exists in CWD — only when no cross-repo target was detected
+    CONF_FOUND=true
+    SETTING=$(grep -E '^\s*auto_branch\s*=' "$CONF" 2>/dev/null | head -1 | sed 's/.*=\s*//' | sed 's/\s*#.*//' | tr -d ' ')
+    if [ -n "$SETTING" ]; then
+        AUTO_BRANCH="$SETTING"
+    fi
+fi
+
+# If no starter-kit conf found anywhere, this isn't a starter-kit project — allow commit
+if [ "$CONF_FOUND" = false ]; then
+    exit 0
+fi
+
+if [ "$AUTO_BRANCH" = "true" ]; then
+    echo "BLOCKED: You're committing directly to '$BRANCH' with auto_branch enabled." >&2
+    echo "Create a feature branch first:" >&2
+    echo "  git checkout -b feat/<feature-name>" >&2
+    echo "  Or use: /worktree <name>" >&2
+    exit 2
+fi
+
+# auto_branch is explicitly false — user chose to work on main
+exit 0

package/.claude/hooks/check-e2e.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# E2E Test Check Hook — PreToolUse (Bash)
+# Warns before pushing to main if no real E2E tests exist.
+# Exit code 2 = block operation and tell Claude why.
+#
+# Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null)
+
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Only check git push commands
+if ! echo "$COMMAND" | grep -qE 'git\s+push'; then
+    exit 0
+fi
+
+# Must be in a git repo
+if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+    exit 0
+fi
+
+# Determine if pushing to main/master
+BRANCH=$(git branch --show-current 2>/dev/null)
+PUSHING_TO_MAIN=false
+
+# Check if command explicitly targets main/master
+if echo "$COMMAND" | grep -qE 'git\s+push\s+\S+\s+(main|master)'; then
+    PUSHING_TO_MAIN=true
+fi
+
+# Check if current branch is main/master (push without explicit branch)
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+    if ! echo "$COMMAND" | grep -qE 'git\s+push\s+\S+\s+\S+'; then
+        # No explicit branch in command — pushing current branch
+        PUSHING_TO_MAIN=true
+    fi
+fi
+
+if [ "$PUSHING_TO_MAIN" = "false" ]; then
+    exit 0
+fi
+
+# Check for real E2E test files (excluding the example template)
+E2E_DIR="tests/e2e"
+if [ ! -d "$E2E_DIR" ]; then
+    echo "WARNING: No tests/e2e/ directory found." >&2
+    echo "Consider creating E2E tests: /create-e2e <feature>" >&2
+    exit 0
+fi
+
+# Count .spec.ts and .test.ts files, excluding the example template
+REAL_TESTS=$(find "$E2E_DIR" -name "*.spec.ts" -o -name "*.test.ts" 2>/dev/null \
+    | grep -v "example-homepage.spec.ts" \
+    | wc -l | tr -d ' ')
+
+# Also check for Go test files
+GO_TESTS=$(find "$E2E_DIR" -name '*_test.go' 2>/dev/null | wc -l | tr -d ' ')
+if [ "$REAL_TESTS" -eq 0 ] && [ "$GO_TESTS" -gt 0 ]; then
+    REAL_TESTS=$GO_TESTS
+fi
+
+if [ "$REAL_TESTS" -eq 0 ]; then
+    echo "WARNING: No E2E tests found (only the example template exists)." >&2
+    echo "Consider creating E2E tests: /create-e2e <feature>" >&2
+    exit 0
+fi
+
+exit 0

package/.claude/hooks/check-env-sync.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Env Example Sync Hook — Stop
+# Warns if .env has keys that .env.example doesn't document.
+# SECURITY: Only reads key NAMES, never values.
+#
+# Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+# Both files must exist
+if [ ! -f ".env" ] || [ ! -f ".env.example" ]; then
+    exit 0
+fi
+
+# Extract sorted key names from a file (ignoring comments, blank lines, export prefix)
+extract_keys() {
+    grep -E '^(export\s+)?[A-Za-z_][A-Za-z0-9_]*=' "$1" 2>/dev/null \
+        | sed 's/^export\s*//' \
+        | cut -d'=' -f1 \
+        | sort -u
+}
+
+ENV_KEYS=$(extract_keys .env)
+EXAMPLE_KEYS=$(extract_keys .env.example)
+
+# Find keys in .env that are missing from .env.example
+MISSING=""
+while IFS= read -r key; do
+    if [ -n "$key" ] && ! echo "$EXAMPLE_KEYS" | grep -qx "$key"; then
+        MISSING="${MISSING}\n  - $key"
+    fi
+done <<< "$ENV_KEYS"
+
+if [ -n "$MISSING" ]; then
+    echo "" >&2
+    echo "ENV SYNC: Keys in .env missing from .env.example:" >&2
+    echo -e "$MISSING" >&2
+    echo "" >&2
+    echo "Other developers won't know these variables exist." >&2
+    echo "Add them to .env.example with placeholder values." >&2
+fi
+
+exit 0

package/.claude/hooks/check-file-length.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""PostToolUse (Write|Edit) — enforce the 300-line file limit.
+
+The write already happened (PostToolUse can't undo it), so exit 2 feeds the file
+back to Claude as a "split this now" instruction before it moves on. Only counts
+real source files; skips generated and vendored paths.
+"""
+import json
+import os
+import sys
+
+LIMIT = 300
+CODE_EXT = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".go", ".rs", ".java")
+SKIP_SUBSTR = ("/node_modules/", "/dist/", "/build/", "/.next/", "/coverage/", "/.git/")
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    path = (data.get("tool_input", {}) or {}).get("file_path", "") or ""
+    if not path or not path.endswith(CODE_EXT):
+        sys.exit(0)
+    if any(s in path for s in SKIP_SUBSTR):
+        sys.exit(0)
+
+    try:
+        with open(path, "r", encoding="utf-8", errors="ignore") as f:
+            n = sum(1 for _ in f)
+    except OSError:
+        sys.exit(0)
+
+    if n > LIMIT:
+        sys.stderr.write(
+            os.path.basename(path) + " is now " + str(n) + " lines, over the "
+            + str(LIMIT) + "-line limit. Split it by concern (one responsibility "
+            "per file) before moving on.\n"
+        )
+        sys.exit(2)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/check-ports.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Port Conflict Check Hook — PreToolUse (Bash)
+# Blocks starting a server when the target port is already in use.
+# Exit code 2 = block operation and tell Claude why.
+#
+# Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null)
+
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+PORT=""
+
+# 1. Explicit port flags: -p 3000, --port 3000, --port=3000
+if echo "$COMMAND" | grep -qoE '(-p|--port[= ])\s*[0-9]+'; then
+    PORT=$(echo "$COMMAND" | grep -oE '(-p|--port[= ])\s*[0-9]+' | grep -oE '[0-9]+' | head -1)
+fi
+
+# 2. PORT= environment variable prefix
+if [ -z "$PORT" ] && echo "$COMMAND" | grep -qE 'PORT=[0-9]+'; then
+    PORT=$(echo "$COMMAND" | grep -oE 'PORT=[0-9]+' | head -1 | cut -d'=' -f2)
+fi
+
+# 3. Known pnpm script names -> known ports
+if [ -z "$PORT" ]; then
+    case "$COMMAND" in
+        *dev:test:website*)   PORT=4000 ;;
+        *dev:test:api*)       PORT=4010 ;;
+        *dev:test:dashboard*) PORT=4020 ;;
+        *dev:website*)        PORT=3000 ;;
+        *dev:api*)            PORT=3001 ;;
+        *dev:dashboard*)      PORT=3002 ;;
+    esac
+fi
+
+# No port detected — nothing to check
+if [ -z "$PORT" ]; then
+    exit 0
+fi
+
+# Check if lsof is available
+if ! command -v lsof &>/dev/null; then
+    exit 0
+fi
+
+# Check if port is in use
+PID=$(lsof -ti:"$PORT" 2>/dev/null | head -1)
+
+if [ -n "$PID" ]; then
+    PROC=$(ps -p "$PID" -o comm= 2>/dev/null || echo "unknown")
+    echo "BLOCKED: Port $PORT is already in use by $PROC (PID: $PID)." >&2
+    echo "Kill it first: lsof -ti:$PORT | xargs kill -9" >&2
+    exit 2
+fi
+
+exit 0

package/.claude/hooks/check-rulecatch.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# RuleCatch Check Hook — Stop
+# Runs when Claude finishes a turn — reports any rule violations detected.
+# Guaranteed to run (stronger than CLAUDE.md command instructions).
+#
+# Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+# Check if RuleCatch CLI is available
+if ! command -v npx &>/dev/null; then
+    exit 0
+fi
+
+# Check if @rulecatch/ai-pooler is available (quick check)
+# If not installed, skip silently — don't block the user
+# Always use latest to make sure the ai-pooler is up to date
+if ! npx @rulecatch/ai-pooler@latest check --help &>/dev/null 2>&1; then
+    exit 0
+fi
+
+# Run RuleCatch violation check for the current session
+# --quiet: only output if violations found
+# --format: short summary suitable for hook output
+RESULT=$(npx @rulecatch/ai-pooler@latest check --quiet --format summary 2>/dev/null)
+
+if [ -n "$RESULT" ] && [ "$RESULT" != "0 violations" ]; then
+    echo "" >&2
+    echo "📋 RuleCatch: $RESULT" >&2
+    echo "   Run 'pnpm ai:monitor' for details or check your dashboard." >&2
+    # Exit 0 = inform but don't block (violations are warnings, not blockers)
+    exit 0
+fi
+
+exit 0

package/.claude/hooks/check-rybbit.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Rybbit Pre-Deploy Check Hook — PreToolUse (Bash)
+# Blocks deployment commands when Rybbit analytics is configured but not set up.
+# Exit code 2 = block operation and tell Claude why.
+#
+# Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null)
+
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Skip commands that are git operations — commits, adds, etc. are never deployments
+if echo "$COMMAND" | grep -qE 'git\s+(commit|add|push|merge|rebase|checkout|branch|tag|log|diff|status)'; then
+    exit 0
+fi
+
+# Only check actual deployment commands (not file writes that mention deployment keywords)
+# - docker push: actual push to registry
+# - vercel deploy/--prod: actual Vercel deploy
+# - curl.*application.deploy: actual Dokploy API call
+# Avoids false positives from heredocs, cat, echo, python file writes, etc.
+if ! echo "$COMMAND" | grep -qEi '(docker\s+push|vercel\s+deploy|vercel\s+--prod|curl.*application\.deploy)'; then
+    exit 0
+fi
+
+# Check if project uses Rybbit
+CONF="claude-mastery-project.conf"
+if [ ! -f "$CONF" ]; then
+    exit 0
+fi
+
+if ! grep -q 'analytics\s*=\s*rybbit' "$CONF" 2>/dev/null; then
+    exit 0
+fi
+
+# Project uses Rybbit — verify it's configured
+if [ ! -f ".env" ]; then
+    echo "BLOCKED: Rybbit analytics is configured in this project but .env file is missing." >&2
+    echo "Create .env with NEXT_PUBLIC_RYBBIT_SITE_ID=<your-site-id> before deploying." >&2
+    echo "Get your site ID from https://app.rybbit.io" >&2
+    exit 2
+fi
+
+SITE_ID=$(grep -E '^NEXT_PUBLIC_RYBBIT_SITE_ID=' .env 2>/dev/null | head -1 | cut -d'=' -f2- | tr -d ' "'"'"'')
+
+if [ -z "$SITE_ID" ]; then
+    echo "BLOCKED: NEXT_PUBLIC_RYBBIT_SITE_ID is missing from .env." >&2
+    echo "Add NEXT_PUBLIC_RYBBIT_SITE_ID=<your-site-id> to .env before deploying." >&2
+    echo "Get your site ID from https://app.rybbit.io" >&2
+    exit 2
+fi
+
+# Check for placeholder values
+if echo "$SITE_ID" | grep -qEi '(your_site|placeholder|changeme|your-site|example)'; then
+    echo "BLOCKED: NEXT_PUBLIC_RYBBIT_SITE_ID appears to be a placeholder ('$SITE_ID')." >&2
+    echo "Set a real site ID from https://app.rybbit.io before deploying." >&2
+    exit 2
+fi
+
+exit 0

package/.claude/hooks/lint-on-save.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Lint on Save Hook — PostToolUse
+# Runs linter after Claude writes/edits a file.
+# Keep hooks FAST (<5 seconds) or Claude may not wait (V5 lesson).
+#
+# Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+# Read the tool input from stdin
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))" 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+EXTENSION="${FILE_PATH##*.}"
+
+case "$EXTENSION" in
+    ts|tsx)
+        # TypeScript — run type check on the specific file if tsc is available
+        if command -v npx &> /dev/null && [ -f "tsconfig.json" ]; then
+            npx tsc --noEmit --pretty "$FILE_PATH" 2>&1 | head -20
+        fi
+        ;;
+    js|jsx)
+        # JavaScript — run eslint if available
+        if command -v npx &> /dev/null && [ -f ".eslintrc*" ] || [ -f "eslint.config.*" ]; then
+            npx eslint --no-error-on-unmatched-pattern "$FILE_PATH" 2>&1 | head -20
+        fi
+        ;;
+    py)
+        # Python — run ruff or flake8 if available
+        if command -v ruff &> /dev/null; then
+            ruff check "$FILE_PATH" 2>&1 | head -20
+        elif command -v flake8 &> /dev/null; then
+            flake8 "$FILE_PATH" 2>&1 | head -20
+        fi
+        ;;
+    vue)
+        # Vue — run vue-tsc if available
+        if command -v npx &> /dev/null && [ -f "tsconfig.json" ]; then
+            npx vue-tsc --noEmit 2>&1 | head -20
+        fi
+        ;;
+    svelte)
+        # Svelte — run svelte-check if available
+        if command -v npx &> /dev/null; then
+            npx svelte-check --tsconfig ./tsconfig.json 2>&1 | head -20
+        fi
+        ;;
+    go)
+        # Go — run go vet if available
+        if command -v go &> /dev/null; then
+            go vet "$FILE_PATH" 2>&1 | head -20
+        fi
+        ;;
+esac
+
+exit 0

package/.claude/hooks/verify-no-secrets.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Verify No Secrets Hook — Stop
+# Checks staged git files for accidentally committed secrets.
+# Runs when Claude finishes a turn — catches secrets before they're committed.
+#
+# Based on Claude Code Mastery Guides V1-V5 by TheDecipherist
+
+# Only run if we're in a git repo
+if ! git rev-parse --is-inside-work-tree &>/dev/null 2>&1; then
+    exit 0
+fi
+
+# Check if there are staged files
+STAGED=$(git diff --cached --name-only 2>/dev/null)
+if [ -z "$STAGED" ]; then
+    exit 0
+fi
+
+VIOLATIONS=""
+
+# Check for sensitive files being staged (match basename only — anchored)
+SENSITIVE_BASENAMES=".env .env.local .env.production .env.staging secrets.json credentials.json service-account.json .npmrc"
+for pattern in $SENSITIVE_BASENAMES; do
+    while IFS= read -r file; do
+        basename=$(basename "$file")
+        if [ "$basename" = "$pattern" ]; then
+            VIOLATIONS="${VIOLATIONS}\n  - SENSITIVE FILE STAGED: $file"
+        fi
+    done <<< "$STAGED"
+done
+
+# Check for private key files (anchored to basename)
+while IFS= read -r file; do
+    basename=$(basename "$file")
+    case "$basename" in
+        id_rsa|id_ed25519|id_ecdsa|id_dsa|*.pem|*.key)
+            VIOLATIONS="${VIOLATIONS}\n  - PRIVATE KEY FILE STAGED: $file"
+            ;;
+    esac
+done <<< "$STAGED"
+
+# Check staged file contents for common secret patterns
+while IFS= read -r file; do
+    if [ -f "$file" ]; then
+        # Generic API key / secret / password / token patterns
+        if grep -qEi '(api[_-]?key|secret[_-]?key|password|token)\s*[:=]\s*["\x27][A-Za-z0-9+/=_-]{16,}' "$file" 2>/dev/null; then
+            VIOLATIONS="${VIOLATIONS}\n  - POSSIBLE SECRET in $file"
+        fi
+        # AWS access keys
+        if grep -qE 'AKIA[0-9A-Z]{16}' "$file" 2>/dev/null; then
+            VIOLATIONS="${VIOLATIONS}\n  - AWS ACCESS KEY in $file"
+        fi
+        # GitHub tokens (ghp_, gho_, ghs_, ghr_, github_pat_)
+        if grep -qE '(ghp_[A-Za-z0-9]{36,}|gho_[A-Za-z0-9]{36,}|ghs_[A-Za-z0-9]{36,}|ghr_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})' "$file" 2>/dev/null; then
+            VIOLATIONS="${VIOLATIONS}\n  - GITHUB TOKEN in $file"
+        fi
+        # Slack tokens
+        if grep -qE '(xoxb-|xoxp-|xoxo-|xoxa-)[0-9A-Za-z-]{20,}' "$file" 2>/dev/null; then
+            VIOLATIONS="${VIOLATIONS}\n  - SLACK TOKEN in $file"
+        fi
+        # Stripe keys
+        if grep -qE '(sk_live_|pk_live_|rk_live_)[A-Za-z0-9]{20,}' "$file" 2>/dev/null; then
+            VIOLATIONS="${VIOLATIONS}\n  - STRIPE KEY in $file"
+        fi
+        # PEM-format private keys
+        if grep -qE '-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----' "$file" 2>/dev/null; then
+            VIOLATIONS="${VIOLATIONS}\n  - PEM PRIVATE KEY in $file"
+        fi
+    fi
+done <<< "$STAGED"
+
+if [ -n "$VIOLATIONS" ]; then
+    echo -e "⚠️  POTENTIAL SECRETS DETECTED:${VIOLATIONS}" >&2
+    echo "" >&2
+    echo "Review staged files before committing." >&2
+    # Exit 2 = block and inform Claude
+    exit 2
+fi
+
+exit 0

package/.claude/settings.json

@@ -0,0 +1,34 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "bash .claude/hooks/check-rybbit.sh" },
+          { "type": "command", "command": "bash .claude/hooks/check-branch.sh" },
+          { "type": "command", "command": "bash .claude/hooks/check-ports.sh" },
+          { "type": "command", "command": "bash .claude/hooks/check-e2e.sh" },
+          { "type": "command", "command": "python3 .claude/hooks/block-dangerous-bash.py" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "bash .claude/hooks/lint-on-save.sh" },
+          { "type": "command", "command": "python3 .claude/hooks/check-file-length.py" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "bash .claude/hooks/verify-no-secrets.sh" },
+          { "type": "command", "command": "bash .claude/hooks/check-rulecatch.sh" },
+          { "type": "command", "command": "bash .claude/hooks/check-env-sync.sh" }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/api-conventions/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: api-conventions
+description: Service structure conventions for this codebase: routing, layering, and where code lives. Use whenever writing or modifying a service's server entry, route definitions, handlers, or adapters. Loads inline so it shapes structure as code is written.
+---
+
+# Service Architecture Conventions
+
+Every service is three layers, one direction: `server.ts` → `handlers/` → `adapters/`. Apply while writing, not after.
+
+## Versioning
+
+- All routes live under `/api/v1/`. New endpoints are versioned from the first line. No unversioned routes "for now."
+
+## server.ts is thin
+
+- `server.ts` defines routes and delegates. Nothing else.
+- No business logic in `server.ts` or in a route definition. A route wires the request to a handler and returns its result.
+
+## handlers/ hold the logic
+
+- Business logic lives in `handlers/`, one file per domain.
+- A handler owns its domain's rules and orchestration. It calls adapters for anything external. It does not reach outside the process itself.
+
+## adapters/ wrap everything external
+
+- Database, external APIs, queues, anything outside the process goes through an adapter in `adapters/`. Handlers never touch them directly.
+- **The database adapter uses StrictDB when it's installed, otherwise the native driver. Never Mongoose.** A handler that imports a driver or calls an external API inline is wrong, that belongs in an adapter. The data adapter is the one place driver code lives, which is also where the `mongodb-rules` apply.
+
+## Service (package) separation
+
+- A service owns its domain and is reached through its interface. A package does not reach into another package's internals or its data. Call the owning service.
+- Code two services both need is hoisted to a shared layer, never imported sideways from a sibling.
+
+The test: routes in `server.ts` read request-in, handler-call, response-out. Logic sits in `handlers/`. Anything that leaves the process goes through `adapters/`, and the data adapter is StrictDB.