@kennethsolomon/shipkit 3.10.2 → 3.11.0

package/skills/sk:setup-claude/templates/.claude/settings.json.template

@@ -26,50 +26,134 @@
   "hooks": {
     "SessionStart": [
       {
-        "type": "command",
-        "command": "bash .claude/hooks/session-start.sh",
-        "timeout": 10000
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/session-start.sh",
+            "timeout": 10000
+          }
+        ]
       }
     ],
     "PreCompact": [
       {
-        "type": "command",
-        "command": "bash .claude/hooks/pre-compact.sh",
-        "timeout": 10000
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/pre-compact.sh",
+            "timeout": 10000
+          }
+        ]
       }
     ],
     "PreToolUse": [
       {
-        "type": "command",
-        "command": "bash .claude/hooks/validate-commit.sh",
-        "timeout": 10000,
-        "matcher": {
-          "tool_name": "Bash",
-          "command_pattern": "git commit*"
-        }
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/validate-commit.sh",
+            "timeout": 10000
+          }
+        ]
       },
       {
-        "type": "command",
-        "command": "bash .claude/hooks/validate-push.sh",
-        "timeout": 5000,
-        "matcher": {
-          "tool_name": "Bash",
-          "command_pattern": "git push*"
-        }
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/validate-push.sh",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/config-protection.sh",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/suggest-compact.sh",
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/safety-guard.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/post-edit-format.sh",
+            "timeout": 10000
+          }
+        ]
       }
     ],
     "SubagentStart": [
       {
-        "type": "command",
-        "command": "bash .claude/hooks/log-agent.sh",
-        "timeout": 5000
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/log-agent.sh",
+            "timeout": 5000
+          }
+        ]
       }
     ],
     "Stop": [
       {
-        "type": "command",
-        "command": "bash .claude/hooks/session-stop.sh",
-        "timeout": 10000
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/session-stop.sh",
+            "timeout": 10000
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/console-log-warning.sh",
+            "timeout": 10000
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/cost-tracker.sh",
+            "timeout": 5000
+          }
+        ]
       }
     ]
   }

package/skills/sk:setup-claude/templates/CLAUDE.md.template

@@ -281,26 +281,33 @@ Create entries in: `[ARCH_CHANGELOG_DIR]`
 | `/sk:accessibility` | WCAG 2.1 AA audit — runs after design, before implementation |
 | `/sk:api-design` | Design API contracts (endpoints, payloads, auth, errors) before implementation |
 | `/sk:autopilot` | Hands-free workflow — all 8 steps, auto-skip, auto-advance, auto-commit |
-| `/sk:brainstorm` | Explore requirements and design |
+| `/sk:brainstorm` | Explore requirements and design (includes search-first research) |
 | `/sk:branch` | Create feature branch auto-named from current task |
 | `/sk:change` | Handle mid-workflow requirement changes — re-enter at correct step |
 | `/sk:context` | Load all context files + output session brief for fast session start |
+| `/sk:context-budget` | Audit context window token consumption and find savings |
 | `/sk:dashboard` | Read-only workflow Kanban board — localhost server, multi-worktree |
 | `/sk:debug` | Investigate and debug issues (bug fix entry point) |
 | `/sk:e2e` | E2E behavioral verification using agent-browser (final quality gate) |
+| `/sk:eval` | Define, run, and report on evaluations for agent reliability |
 | `/sk:execute-plan` | Execute `tasks/todo.md` checkboxes in batches |
 | `/sk:fast-track` | Abbreviated workflow for small changes — skip planning, keep all gates |
 | `/sk:features` | Sync feature specs with shipped implementation |
 | `/sk:finish-feature` | Changelog + PR creation |
 | `/sk:frontend-design` | UI mockup before implementation. Prompts to create Pencil visual mockup |
 | `/sk:gates` | Run all quality gates in optimized parallel batches |
+| `/sk:health` | Harness self-audit scorecard (7 categories, 0-70) |
 | `/sk:hotfix` | Emergency fix workflow — skip design/TDD, quality gates enforced |
+| `/sk:learn` | Extract reusable patterns from sessions into learned instincts |
 | `/sk:lint` | Auto-detect and run all project linters + dependency audits |
 | `/sk:perf` | Performance audit — bundle, N+1, Core Web Vitals, memory |
 | `/sk:release` | Version bump + changelog + tag |
+| `/sk:resume-session` | Resume a previously saved session with full context restoration |
 | `/sk:retro` | Post-ship retrospective: velocity, blockers, action items |
 | `/sk:reverse-doc` | Generate architecture/design docs from existing code |
 | `/sk:review` | Self-review with simplify pre-pass + multi-dimensional review |
+| `/sk:safety-guard` | Protect against destructive ops (careful/freeze/guard modes) |
+| `/sk:save-session` | Save current session state for cross-session continuity |
 | `/sk:scope-check` | Compare implementation against plan, detect scope creep |
 | `/sk:security-check` | OWASP security audit on changed files |
 | `/sk:seo-audit` | SEO audit — dual-mode (source templates + dev server), ask-before-fix |

package/skills/sk:setup-claude/templates/hooks/config-protection.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# config-protection.sh — PreToolUse hook for Edit/Write
+# Blocks modifications to linter/formatter configs.
+# Override: SHIPKIT_ALLOW_CONFIG_EDIT=1
+
+set -euo pipefail
+
+if [[ "${SHIPKIT_ALLOW_CONFIG_EDIT:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# Read the tool input from stdin
+INPUT=$(cat)
+
+# Extract the file path from the tool input
+FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"\s*:\s*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+
+# Protected config patterns
+PROTECTED_CONFIGS=(
+  ".eslintrc"
+  ".eslintrc.js"
+  ".eslintrc.cjs"
+  ".eslintrc.json"
+  ".eslintrc.yml"
+  ".eslintrc.yaml"
+  "eslint.config.js"
+  "eslint.config.mjs"
+  "eslint.config.cjs"
+  ".prettierrc"
+  ".prettierrc.js"
+  ".prettierrc.cjs"
+  ".prettierrc.json"
+  ".prettierrc.yml"
+  ".prettierrc.yaml"
+  "prettier.config.js"
+  "prettier.config.mjs"
+  "biome.json"
+  "biome.jsonc"
+  ".stylelintrc"
+  ".stylelintrc.json"
+  ".stylelintrc.js"
+  "stylelint.config.js"
+  "phpstan.neon"
+  "phpstan.neon.dist"
+  "pint.json"
+  "rector.php"
+  ".php-cs-fixer.php"
+  ".php-cs-fixer.dist.php"
+  ".rubocop.yml"
+  ".golangci.yml"
+  ".golangci.yaml"
+  "rustfmt.toml"
+  ".clang-format"
+)
+
+for config in "${PROTECTED_CONFIGS[@]}"; do
+  if [[ "$BASENAME" == "$config" ]]; then
+    echo "BLOCKED: Modifying linter/formatter config '$BASENAME'."
+    echo "Fix the code instead of weakening the rules."
+    echo "Override: set SHIPKIT_ALLOW_CONFIG_EDIT=1"
+    exit 2
+  fi
+done
+
+exit 0

package/skills/sk:setup-claude/templates/hooks/console-log-warning.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# console-log-warning.sh — Stop hook
+# Scans git-modified files for debug statements and warns if found.
+
+set -uo pipefail
+
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+cd "$PROJECT_ROOT"
+
+MODIFIED_FILES=$(git diff --name-only --diff-filter=ACMR 2>/dev/null)
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null)
+ALL_FILES=$(echo -e "${MODIFIED_FILES}\n${STAGED_FILES}" | sort -u | grep -v '^$')
+
+if [[ -z "$ALL_FILES" ]]; then
+  exit 0
+fi
+
+DEBUG_PATTERNS='console\.log\|console\.warn\|console\.error\|console\.debug\|console\.trace\|debugger\b\|\bdd(\|\bdump(\|\bvar_dump(\|\bprint_r(\|\blog\.Print\|log\.Debug\|\bpdb\.set_trace\|\bbreakpoint()'
+
+FOUND=0
+REPORT=""
+
+while IFS= read -r file; do
+  [[ -z "$file" || ! -f "$file" ]] && continue
+  MATCHES=$(grep -n "$DEBUG_PATTERNS" "$file" 2>/dev/null || true)
+  if [[ -n "$MATCHES" ]]; then
+    FOUND=$((FOUND + 1))
+    REPORT+="  $file:\n"
+    while IFS= read -r match; do
+      REPORT+="    $match\n"
+    done <<< "$MATCHES"
+  fi
+done <<< "$ALL_FILES"
+
+if [[ $FOUND -gt 0 ]]; then
+  echo ""
+  echo "WARNING: Debug statements found in $FOUND modified file(s):"
+  echo -e "$REPORT"
+  echo "Consider removing before committing."
+fi
+
+exit 0

package/skills/sk:setup-claude/templates/hooks/cost-tracker.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# cost-tracker.sh — Stop hook (async)
+# Logs session metadata to .claude/sessions/cost-log.jsonl
+
+set -uo pipefail
+
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+SESSIONS_DIR="$PROJECT_ROOT/.claude/sessions"
+LOG_FILE="$SESSIONS_DIR/cost-log.jsonl"
+
+mkdir -p "$SESSIONS_DIR"
+
+BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+DATE=$(date +"%Y-%m-%d")
+
+# Count commits made during this session (last 8 hours)
+RECENT_COMMITS=$(git log --since="8 hours ago" --oneline 2>/dev/null | wc -l | tr -d ' ')
+
+# Count modified files
+MODIFIED_COUNT=$(git diff --name-only 2>/dev/null | wc -l | tr -d ' ')
+STAGED_COUNT=$(git diff --cached --name-only 2>/dev/null | wc -l | tr -d ' ')
+
+echo "{\"timestamp\":\"$TIMESTAMP\",\"date\":\"$DATE\",\"branch\":\"$BRANCH\",\"commits\":$RECENT_COMMITS,\"modified_files\":$MODIFIED_COUNT,\"staged_files\":$STAGED_COUNT}" >> "$LOG_FILE"
+
+exit 0

package/skills/sk:setup-claude/templates/hooks/post-edit-format.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# post-edit-format.sh — PostToolUse hook for Edit
+# Auto-formats the edited file using the project's formatter.
+
+set -uo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"\s*:\s*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+
+if [[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+EXT="${FILE_PATH##*.}"
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+format_file() {
+  # Biome (JS/TS/JSON)
+  if [[ -f "$PROJECT_ROOT/biome.json" || -f "$PROJECT_ROOT/biome.jsonc" ]]; then
+    if [[ "$EXT" =~ ^(js|jsx|ts|tsx|json|jsonc)$ ]]; then
+      npx biome format --write "$FILE_PATH" 2>/dev/null && return 0
+    fi
+  fi
+
+  # Prettier (JS/TS/CSS/HTML/MD)
+  if [[ -f "$PROJECT_ROOT/.prettierrc" || -f "$PROJECT_ROOT/.prettierrc.json" || -f "$PROJECT_ROOT/.prettierrc.js" || -f "$PROJECT_ROOT/.prettierrc.cjs" || -f "$PROJECT_ROOT/prettier.config.js" || -f "$PROJECT_ROOT/prettier.config.mjs" ]]; then
+    if [[ "$EXT" =~ ^(js|jsx|ts|tsx|css|scss|html|md|json|yaml|yml|vue|svelte)$ ]]; then
+      npx prettier --write "$FILE_PATH" 2>/dev/null && return 0
+    fi
+  fi
+
+  # Pint (PHP)
+  if [[ -f "$PROJECT_ROOT/pint.json" || -f "$PROJECT_ROOT/vendor/bin/pint" ]]; then
+    if [[ "$EXT" == "php" ]]; then
+      "$PROJECT_ROOT/vendor/bin/pint" "$FILE_PATH" 2>/dev/null && return 0
+    fi
+  fi
+
+  # gofmt (Go)
+  if [[ "$EXT" == "go" ]]; then
+    command -v gofmt &>/dev/null && gofmt -w "$FILE_PATH" 2>/dev/null && return 0
+  fi
+
+  # cargo fmt (Rust)
+  if [[ "$EXT" == "rs" ]]; then
+    command -v rustfmt &>/dev/null && rustfmt "$FILE_PATH" 2>/dev/null && return 0
+  fi
+
+  return 0
+}
+
+format_file
+exit 0

package/skills/sk:setup-claude/templates/hooks/safety-guard.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# safety-guard.sh — PreToolUse hook for Bash/Edit/Write
+# Reads .claude/safety-guard.json for active mode and directory constraints.
+
+set -uo pipefail
+
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+GUARD_CONFIG="$PROJECT_ROOT/.claude/safety-guard.json"
+
+if [[ ! -f "$GUARD_CONFIG" ]]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+MODE=$(python3 -c "import json; print(json.load(open('$GUARD_CONFIG')).get('mode', 'off'))" 2>/dev/null || echo "off")
+
+if [[ "$MODE" == "off" ]]; then
+  exit 0
+fi
+
+# Extract tool info
+TOOL_NAME="${TOOL_NAME:-}"
+FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"\s*:\s*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+COMMAND=$(echo "$INPUT" | grep -oE '"command"\s*:\s*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')
+
+# Careful mode: block destructive commands
+if [[ "$MODE" == "careful" || "$MODE" == "guard" ]]; then
+  if [[ -n "$COMMAND" ]]; then
+    DESTRUCTIVE_PATTERNS=(
+      "rm -rf"
+      "rm -fr"
+      "git push --force"
+      "git push -f"
+      "git reset --hard"
+      "git clean -f"
+      "DROP TABLE"
+      "DROP DATABASE"
+      "chmod 777"
+      "chmod -R 777"
+      "--no-verify"
+    )
+    for pattern in "${DESTRUCTIVE_PATTERNS[@]}"; do
+      if echo "$COMMAND" | grep -qi "$pattern"; then
+        echo "BLOCKED by safety-guard (careful mode): destructive command detected."
+        echo "  Command: $COMMAND"
+        echo "  Pattern: $pattern"
+        echo "  Disable: /sk:safety-guard off"
+        exit 2
+      fi
+    done
+  fi
+fi
+
+# Freeze mode: block writes outside specified directory
+if [[ "$MODE" == "freeze" || "$MODE" == "guard" ]]; then
+  FREEZE_DIR=$(python3 -c "import json; print(json.load(open('$GUARD_CONFIG')).get('freeze_dir', ''))" 2>/dev/null || echo "")
+  if [[ -n "$FREEZE_DIR" && -n "$FILE_PATH" ]]; then
+    # Resolve to absolute paths for comparison
+    ABS_FREEZE=$(cd "$PROJECT_ROOT" && cd "$FREEZE_DIR" 2>/dev/null && pwd || echo "$PROJECT_ROOT/$FREEZE_DIR")
+    ABS_FILE=$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && echo "$(pwd)/$(basename "$FILE_PATH")" || echo "$FILE_PATH")
+
+    if [[ "$ABS_FILE" != "$ABS_FREEZE"* ]]; then
+      echo "BLOCKED by safety-guard (freeze mode): write outside frozen directory."
+      echo "  File: $FILE_PATH"
+      echo "  Allowed: $FREEZE_DIR"
+      echo "  Disable: /sk:safety-guard off"
+      exit 2
+    fi
+  fi
+fi
+
+exit 0

package/skills/sk:setup-claude/templates/hooks/suggest-compact.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# suggest-compact.sh — PreToolUse hook for Edit/Write
+# Tracks tool call count and suggests /compact at threshold.
+
+set -uo pipefail
+
+THRESHOLD="${SHIPKIT_COMPACT_THRESHOLD:-50}"
+REPEAT_INTERVAL=25
+
+# Use a session-scoped counter file
+COUNTER_FILE="/tmp/shipkit-tool-count-${PPID:-$$}"
+
+# Read current count
+COUNT=0
+if [[ -f "$COUNTER_FILE" ]]; then
+  COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+fi
+
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+# Check if we should suggest compaction
+if [[ $COUNT -eq $THRESHOLD ]]; then
+  echo ""
+  echo "HINT: You've made $COUNT+ tool calls this session."
+  echo "Consider running /compact if context feels heavy."
+elif [[ $COUNT -gt $THRESHOLD ]]; then
+  PAST_THRESHOLD=$((COUNT - THRESHOLD))
+  if [[ $((PAST_THRESHOLD % REPEAT_INTERVAL)) -eq 0 ]]; then
+    echo ""
+    echo "HINT: $COUNT tool calls this session. Consider /compact."
+  fi
+fi
+
+exit 0

package/skills/sk:setup-optimizer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sk:setup-optimizer
-description: "Diagnose, update workflow, enrich, and maintain CLAUDE.md. The single command to keep any CLAUDE.md current."
+description: "Diagnose, update workflow, deploy hooks, enrich CLAUDE.md, and keep project infrastructure current. The single command for ongoing ShipKit maintenance."
 triggers:
   - optimize claude
   - optimize setup
@@ -20,14 +20,15 @@ allowed-tools:
 
 ## Overview
 
-The single command to keep your CLAUDE.md current. Diagnoses problems, updates the workflow to the latest version, scans your codebase, and enriches with project context — all while preserving your customizations.
+The single command to keep your entire ShipKit project infrastructure current. Diagnoses problems, updates the workflow, deploys missing hooks, scans your codebase, and enriches CLAUDE.md with project context — all while preserving your customizations.
 
 ### What It Does
 
 1. **Diagnoses** — finds missing sections, stale info, inconsistencies, and gaps
 2. **Updates workflow** — refreshes the workflow section to the latest template version
-3. **Discovers** — scans project structure, docs, and workflows
-4. **Enriches** — merges discoveries into CLAUDE.md while preserving your edits
+3. **Deploys hooks** — installs missing hooks and updates settings.json wiring
+4. **Discovers** — scans project structure, docs, and workflows
+5. **Enriches** — merges discoveries into CLAUDE.md while preserving your edits
 
 ## Usage
 
@@ -44,9 +45,10 @@ Before making any changes, runs a diagnostic pass on the existing CLAUDE.md:
 - **Inconsistencies** — compares documented vs actual project state (directories, scripts, workflows)
 - **Section completeness** — flags sections that exist but are empty or have only placeholder text
 - **Outdated workflow** — checks if the workflow matches the current 8-step flow with `/sk:gates` as single gate step
-- **Missing commands** — checks for `sk:start`, `sk:autopilot`, `sk:team` in the Commands table
+- **Missing commands** — checks for `sk:start`, `sk:autopilot`, `sk:team`, `sk:learn`, `sk:context-budget`, `sk:health`, `sk:save-session`, `sk:resume-session`, `sk:safety-guard`, `sk:eval` in the Commands table
 - **Auto-skip rules** — checks for auto-skip detection rules in the workflow section
 - **Stale tracker references** — checks for `tasks/workflow-status.md` references (removed — progress tracked via git branch + todo.md checkboxes)
+- **Missing hooks** — checks if `.claude/hooks/` exists and contains both core and enhanced hooks
 
 Reports findings before proceeding. If issues are found, they inform subsequent steps.
 
@@ -89,6 +91,54 @@ Explore → Design → Plan → Branch → Write Tests + Implement → Commit
 4. Insert missing sections (Sub-Agent Patterns, Project Memory, etc.) in their correct positions
 5. Preserve all `<!-- LOCK -->` and project-specific sections
 
+### Step 1.5: Hooks Deployment
+
+After updating the workflow, check and deploy hooks:
+
+1. **Check if `.claude/hooks/` exists** — if not, create it
+2. **Check for core hooks** — `session-start.sh`, `session-stop.sh`, `pre-compact.sh`, `validate-commit.sh`, `validate-push.sh`, `log-agent.sh`
+3. **Check for enhanced hooks** — `config-protection.sh`, `post-edit-format.sh`, `console-log-warning.sh`, `cost-tracker.sh`, `suggest-compact.sh`, `safety-guard.sh`
+4. **Check `.claude/settings.json`** — verify hooks are wired correctly
+
+**Report status and prompt:**
+
+> "Hooks: [X/6 core, Y/6 enhanced] installed
+> Install missing hooks? [y/n]"
+
+**If yes:**
+
+1. **Locate templates** — resolve the ShipKit templates directory:
+   - `~/.claude/skills/sk:setup-claude/templates/hooks/` (symlinked install)
+   - Or the npm global path if installed via `npm install -g`
+
+2. **Deploy missing hook scripts** (create-if-missing, never overwrite existing):
+   ```bash
+   # For each missing hook file:
+   cp "$TEMPLATE_DIR/hooks/<hook>.sh" ".claude/hooks/<hook>.sh"
+   chmod +x ".claude/hooks/<hook>.sh"
+   ```
+
+3. **Update `.claude/settings.json`** — read the latest `settings.json.template` and merge new hook entries into the existing settings.json:
+   - **Preserve** existing hooks, permissions, statusline config
+   - **Add** only missing hook entries (new PreToolUse, PostToolUse, Stop entries)
+   - **Never remove** existing entries — additive merge only
+
+4. **Report what was deployed:**
+   ```
+   Deployed hooks:
+     + config-protection.sh (PreToolUse — blocks linter config edits)
+     + post-edit-format.sh (PostToolUse — auto-format after edits)
+     + console-log-warning.sh (Stop — warn on debug statements)
+     + cost-tracker.sh (Stop — session metadata logging)
+     + suggest-compact.sh (PreToolUse — compact suggestions)
+     + safety-guard.sh (PreToolUse — freeze/careful mode)
+     ~ Updated .claude/settings.json with new hook wiring
+   ```
+
+**If no:** skip hook deployment, continue to Step 2.
+
+**Idempotency:** Never overwrite existing hook files — the user may have customized them. Only deploy hooks that don't exist yet. For settings.json, merge additively.
+
 ### Step 2: Scan & Enrich
 
 After workflow update, proceeds with codebase discovery and enrichment:
@@ -183,10 +233,11 @@ This content will never be regenerated.
 
 ## When to Use
 
-✅ **Use `/optimize-claude` when:**
+✅ **Use `/sk:setup-optimizer` when:**
+- ShipKit was updated and your project needs the latest hooks/commands
 - You've added new directories to your project
 - You've created documentation files
 - You want to refresh project context
-- Monthly maintenance of CLAUDE.md
+- Monthly maintenance of CLAUDE.md and hooks
 
-✅ **Safe to run multiple times during development** - Your customizations are always preserved!
+✅ **Safe to run multiple times** — existing customizations and hook files are never overwritten.

package/skills/sk:start/SKILL.md

@@ -53,6 +53,31 @@ Read the task description from arguments. Scan for signal keywords to determine
 | `backend` only | `solo` |
 | `unknown` | `solo` (default) |
 
+### Step 1.5 — Missing Context Detection (automatic, no prompt)
+
+After classification, scan the task description for gaps. This is informational only — does NOT block.
+
+**Critical context checks:**
+
+| Check | How to detect | Auto-resolve |
+|-------|--------------|--------------|
+| Tech stack specified? | Look for framework/language keywords | Auto-detect from package.json, composer.json, go.mod, Cargo.toml |
+| Acceptance criteria present? | Look for "should", "must", "when", "given" | Cannot auto-resolve — flag for user |
+| Scope boundaries stated? | Look for "only", "not", "exclude", "just" | Cannot auto-resolve — flag for user |
+| Security requirements? | Check if task involves auth, user data, payments, tokens | Flag: "This touches auth/user data — consider security requirements" |
+| Testing expectations? | Look for "test", "coverage", "spec" | Default: 100% coverage on new code (per workflow) |
+
+**If 3+ critical items are missing**, include in the recommendation output:
+
+```
+Missing Context (3 items — consider clarifying):
+  - No acceptance criteria detected
+  - No scope boundaries stated (what should NOT change?)
+  - Task involves user data but no security requirements mentioned
+```
+
+This check runs silently. If <3 items missing, no output.
+
 ### Step 2 — Recommend (one prompt, user confirms or overrides)
 
 Present the classification and recommendation: