Merge feat/230-breaking-change-detection into development

Resolved conflict in hooks.json - combined SessionStart and PostToolUse hooks

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -8,6 +8,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+#### Sprint 3: Hooks (V5.2.0 Plugin Enhancements)
+Implementation of 6 foundational hooks across 4 plugins.
+
+**git-flow v1.1.0:**
+- **Commit message enforcement hook** - PreToolUse hook validates conventional commit format on all `git commit` commands (not just `/commit`). Blocks invalid commits with format guidance.
+- **Branch name validation hook** - PreToolUse hook validates branch naming on `git checkout -b` and `git switch -c`. Enforces `type/description` format, lowercase, max 50 chars.
+
+**clarity-assist v1.1.0:**
+- **Vagueness detection hook** - UserPromptSubmit hook detects vague prompts and suggests `/clarify` when ambiguity, missing context, or unclear scope detected.
+
+**data-platform v1.1.0:**
+- **Schema diff detection hook** - PostToolUse hook monitors edits to schema files (dbt models, SQL migrations). Warns on breaking changes (column removal, type narrowing, constraint addition).
+
+**contract-validator v1.1.0:**
+- **SessionStart auto-validate hook** - Smart validation that only runs when plugin files changed since last check. Detects interface compatibility issues at session start.
+- **Breaking change detection hook** - PostToolUse hook monitors plugin interface files (README.md, plugin.json). Warns when changes would break consumers.
+
+**Sprint Completed:**
+- Milestone: Sprint 3 - Hooks (closed 2026-01-28)
+- Issues: #225, #226, #227, #228, #229, #230
+- Wiki: [Change V5.2.0: Plugin Enhancements Proposal](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0:-Plugin-Enhancements-Proposal)
+- Lessons: Background agent permissions, agent runaway detection, MCP branch detection bug
+
+### Known Issues
+- **MCP Bug #231:** Branch detection in Gitea MCP runs from installed plugin directory, not user's project directory. Workaround: close issues via Gitea web UI.
+
+---
+
 #### Gitea MCP Server - create_pull_request Tool
 - **`create_pull_request`**: Create new pull requests via MCP
   - Parameters: title, body, head (source branch), base (target branch), labels

plugins/clarity-assist/hooks/hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/vagueness-check.sh"
+      }
+    ]
+  }
+}

plugins/clarity-assist/hooks/vagueness-check.sh

@@ -0,0 +1,216 @@
+#!/bin/bash
+# clarity-assist vagueness detection hook
+# Analyzes user prompts for vagueness and suggests /clarity-assist when beneficial
+# All output MUST have [clarity-assist] prefix
+# This is a NON-BLOCKING hook - always exits 0
+
+PREFIX="[clarity-assist]"
+
+# Check if auto-suggest is enabled (default: true)
+AUTO_SUGGEST="${CLARITY_ASSIST_AUTO_SUGGEST:-true}"
+if [[ "$AUTO_SUGGEST" != "true" ]]; then
+    exit 0
+fi
+
+# Threshold for vagueness score (default: 0.6)
+THRESHOLD="${CLARITY_ASSIST_VAGUENESS_THRESHOLD:-0.6}"
+
+# Read user prompt from stdin
+PROMPT=""
+if [[ -t 0 ]]; then
+    # No stdin available
+    exit 0
+else
+    PROMPT=$(cat)
+fi
+
+# Skip empty prompts
+if [[ -z "$PROMPT" ]]; then
+    exit 0
+fi
+
+# Skip if prompt is a command (starts with /)
+if [[ "$PROMPT" =~ ^[[:space:]]*/[a-zA-Z] ]]; then
+    exit 0
+fi
+
+# Skip if prompt mentions specific files or paths
+if [[ "$PROMPT" =~ \.(py|js|ts|sh|md|json|yaml|yml|txt|css|html|go|rs|java|c|cpp|h)([[:space:]]|$|[^a-zA-Z]) ]] || \
+   [[ "$PROMPT" =~ [/\\][a-zA-Z0-9_-]+[/\\] ]] || \
+   [[ "$PROMPT" =~ (src|lib|test|docs|plugins|hooks|commands)/ ]]; then
+    exit 0
+fi
+
+# Initialize vagueness score
+SCORE=0
+
+# Count words in the prompt
+WORD_COUNT=$(echo "$PROMPT" | wc -w | tr -d ' ')
+
+# ============================================================================
+# Vagueness Signal Detection
+# ============================================================================
+
+# Signal 1: Very short prompts (< 10 words) are often vague
+if [[ "$WORD_COUNT" -lt 10 ]]; then
+    # But very short specific commands are OK
+    if [[ "$WORD_COUNT" -lt 3 ]]; then
+        # Extremely short - probably intentional or a command
+        :
+    else
+        SCORE=$(echo "$SCORE + 0.3" | bc)
+    fi
+fi
+
+# Signal 2: Vague action phrases (no specific outcome)
+VAGUE_ACTIONS=(
+    "help me"
+    "help with"
+    "do something"
+    "work on"
+    "look at"
+    "check this"
+    "fix it"
+    "fix this"
+    "make it better"
+    "make this better"
+    "improve it"
+    "improve this"
+    "update this"
+    "update it"
+    "change it"
+    "change this"
+    "can you"
+    "could you"
+    "would you"
+    "please help"
+)
+
+PROMPT_LOWER=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+for phrase in "${VAGUE_ACTIONS[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$phrase"* ]]; then
+        SCORE=$(echo "$SCORE + 0.2" | bc)
+        break
+    fi
+done
+
+# Signal 3: Ambiguous scope indicators
+AMBIGUOUS_SCOPE=(
+    "somehow"
+    "something"
+    "somewhere"
+    "anything"
+    "whatever"
+    "stuff"
+    "things"
+    "etc"
+    "and so on"
+)
+
+for word in "${AMBIGUOUS_SCOPE[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$word"* ]]; then
+        SCORE=$(echo "$SCORE + 0.15" | bc)
+        break
+    fi
+done
+
+# Signal 4: Missing context indicators (no reference to what/where)
+# Check if prompt lacks specificity markers
+HAS_SPECIFICS=false
+
+# Specific technical terms suggest clarity
+SPECIFIC_MARKERS=(
+    "function"
+    "class"
+    "method"
+    "variable"
+    "error"
+    "bug"
+    "test"
+    "api"
+    "endpoint"
+    "database"
+    "query"
+    "component"
+    "module"
+    "service"
+    "config"
+    "install"
+    "deploy"
+    "build"
+    "run"
+    "execute"
+    "create"
+    "delete"
+    "add"
+    "remove"
+    "implement"
+    "refactor"
+    "migrate"
+    "upgrade"
+    "debug"
+    "log"
+    "exception"
+    "stack"
+    "memory"
+    "performance"
+    "security"
+    "auth"
+    "token"
+    "session"
+    "route"
+    "controller"
+    "model"
+    "view"
+    "template"
+    "schema"
+    "migration"
+    "commit"
+    "branch"
+    "merge"
+    "pull"
+    "push"
+)
+
+for marker in "${SPECIFIC_MARKERS[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$marker"* ]]; then
+        HAS_SPECIFICS=true
+        break
+    fi
+done
+
+if [[ "$HAS_SPECIFICS" == false ]] && [[ "$WORD_COUNT" -gt 3 ]]; then
+    SCORE=$(echo "$SCORE + 0.2" | bc)
+fi
+
+# Signal 5: Question without context
+if [[ "$PROMPT" =~ \?$ ]] && [[ "$WORD_COUNT" -lt 8 ]]; then
+    # Short questions without specifics are often vague
+    if [[ "$HAS_SPECIFICS" == false ]]; then
+        SCORE=$(echo "$SCORE + 0.15" | bc)
+    fi
+fi
+
+# Cap score at 1.0
+if (( $(echo "$SCORE > 1.0" | bc -l) )); then
+    SCORE="1.0"
+fi
+
+# ============================================================================
+# Output suggestion if score exceeds threshold
+# ============================================================================
+
+# Compare score to threshold using bc
+if (( $(echo "$SCORE >= $THRESHOLD" | bc -l) )); then
+    # Format score as percentage for display
+    SCORE_PCT=$(echo "$SCORE * 100" | bc | cut -d'.' -f1)
+
+    # Gentle, non-blocking suggestion
+    echo "$PREFIX Your prompt could benefit from more clarity."
+    echo "$PREFIX Consider running /clarity-assist to refine your request."
+    echo "$PREFIX (Vagueness score: ${SCORE_PCT}% - this is a suggestion, not a block)"
+fi
+
+# Always exit 0 - this hook is non-blocking
+exit 0

plugins/contract-validator/hooks/auto-validate.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+# contract-validator SessionStart auto-validate hook
+# Validates plugin contracts only when plugin files have changed since last check
+# All output MUST have [contract-validator] prefix
+
+PREFIX="[contract-validator]"
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+# Enable/disable auto-check (default: true)
+AUTO_CHECK="${CONTRACT_VALIDATOR_AUTO_CHECK:-true}"
+
+# Cache location for storing last check hash
+CACHE_DIR="$HOME/.cache/claude-plugins/contract-validator"
+HASH_FILE="$CACHE_DIR/last-check.hash"
+
+# Marketplace location (installed plugins)
+MARKETPLACE_PATH="$HOME/.claude/plugins/marketplaces/leo-claude-mktplace"
+
+# ============================================================================
+# Early exit if disabled
+# ============================================================================
+
+if [[ "$AUTO_CHECK" != "true" ]]; then
+    exit 0
+fi
+
+# ============================================================================
+# Smart mode: Check if plugin files have changed
+# ============================================================================
+
+# Function to compute hash of all plugin manifest files
+compute_plugin_hash() {
+    local hash_input=""
+
+    if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+        # Hash all plugin.json, hooks.json, and agent files
+        while IFS= read -r -d '' file; do
+            if [[ -f "$file" ]]; then
+                hash_input+="$(md5sum "$file" 2>/dev/null | cut -d' ' -f1)"
+            fi
+        done < <(find "$MARKETPLACE_PATH/plugins" \
+            \( -name "plugin.json" -o -name "hooks.json" -o -name "*.md" -path "*/agents/*" \) \
+            -print0 2>/dev/null | sort -z)
+    fi
+
+    # Also include marketplace.json
+    if [[ -f "$MARKETPLACE_PATH/.claude-plugin/marketplace.json" ]]; then
+        hash_input+="$(md5sum "$MARKETPLACE_PATH/.claude-plugin/marketplace.json" 2>/dev/null | cut -d' ' -f1)"
+    fi
+
+    # Compute final hash
+    echo "$hash_input" | md5sum | cut -d' ' -f1
+}
+
+# Ensure cache directory exists
+mkdir -p "$CACHE_DIR" 2>/dev/null
+
+# Compute current hash
+CURRENT_HASH=$(compute_plugin_hash)
+
+# Check if we have a previous hash
+if [[ -f "$HASH_FILE" ]]; then
+    PREVIOUS_HASH=$(cat "$HASH_FILE" 2>/dev/null)
+
+    # If hashes match, no changes - skip validation
+    if [[ "$CURRENT_HASH" == "$PREVIOUS_HASH" ]]; then
+        exit 0
+    fi
+fi
+
+# ============================================================================
+# Run validation (hashes differ or no cache)
+# ============================================================================
+
+ISSUES_FOUND=0
+WARNINGS=""
+
+# Function to add warning
+add_warning() {
+    WARNINGS+="  - $1"$'\n'
+    ((ISSUES_FOUND++))
+}
+
+# 1. Check all installed plugins have valid plugin.json
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    for plugin_dir in "$MARKETPLACE_PATH/plugins"/*/; do
+        if [[ -d "$plugin_dir" ]]; then
+            plugin_name=$(basename "$plugin_dir")
+            plugin_json="$plugin_dir/.claude-plugin/plugin.json"
+
+            if [[ ! -f "$plugin_json" ]]; then
+                add_warning "$plugin_name: missing .claude-plugin/plugin.json"
+                continue
+            fi
+
+            # Basic JSON validation
+            if ! python3 -c "import json; json.load(open('$plugin_json'))" 2>/dev/null; then
+                add_warning "$plugin_name: invalid JSON in plugin.json"
+                continue
+            fi
+
+            # Check required fields
+            if ! python3 -c "
+import json
+with open('$plugin_json') as f:
+    data = json.load(f)
+required = ['name', 'version', 'description']
+missing = [r for r in required if r not in data]
+if missing:
+    exit(1)
+" 2>/dev/null; then
+                add_warning "$plugin_name: plugin.json missing required fields"
+            fi
+        fi
+    done
+fi
+
+# 2. Check hooks.json files are properly formatted
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    while IFS= read -r -d '' hooks_file; do
+        plugin_name=$(basename "$(dirname "$(dirname "$hooks_file")")")
+
+        # Validate JSON
+        if ! python3 -c "import json; json.load(open('$hooks_file'))" 2>/dev/null; then
+            add_warning "$plugin_name: invalid JSON in hooks/hooks.json"
+            continue
+        fi
+
+        # Validate hook structure
+        if ! python3 -c "
+import json
+with open('$hooks_file') as f:
+    data = json.load(f)
+if 'hooks' not in data:
+    exit(1)
+valid_events = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart', 'SessionEnd', 'Notification', 'Stop', 'SubagentStop', 'PreCompact']
+for event in data['hooks']:
+    if event not in valid_events:
+        exit(1)
+    for hook in data['hooks'][event]:
+        # Support both flat structure (type at top) and nested structure (matcher + hooks array)
+        if 'type' in hook:
+            # Flat structure: {type: 'command', command: '...'}
+            pass
+        elif 'matcher' in hook and 'hooks' in hook:
+            # Nested structure: {matcher: '...', hooks: [{type: 'command', ...}]}
+            for nested_hook in hook['hooks']:
+                if 'type' not in nested_hook:
+                    exit(1)
+        else:
+            exit(1)
+" 2>/dev/null; then
+            add_warning "$plugin_name: hooks.json has invalid structure or events"
+        fi
+    done < <(find "$MARKETPLACE_PATH/plugins" -path "*/hooks/hooks.json" -print0 2>/dev/null)
+fi
+
+# 3. Check agent references are valid (agent files exist and are markdown)
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    while IFS= read -r -d '' agent_file; do
+        plugin_name=$(basename "$(dirname "$(dirname "$agent_file")")")
+        agent_name=$(basename "$agent_file")
+
+        # Check file is not empty
+        if [[ ! -s "$agent_file" ]]; then
+            add_warning "$plugin_name: empty agent file $agent_name"
+            continue
+        fi
+
+        # Check file has markdown content (at least a header)
+        if ! grep -q '^#' "$agent_file" 2>/dev/null; then
+            add_warning "$plugin_name: agent $agent_name missing markdown header"
+        fi
+    done < <(find "$MARKETPLACE_PATH/plugins" -path "*/agents/*.md" -print0 2>/dev/null)
+fi
+
+# ============================================================================
+# Store new hash and report results
+# ============================================================================
+
+# Always store the new hash (even if issues found - we don't want to recheck)
+echo "$CURRENT_HASH" > "$HASH_FILE"
+
+# Report any issues found (non-blocking warning)
+if [[ $ISSUES_FOUND -gt 0 ]]; then
+    echo "$PREFIX Plugin contract validation found $ISSUES_FOUND issue(s):"
+    echo "$WARNINGS"
+    echo "$PREFIX Run /validate-contracts for full details"
+fi
+
+# Always exit 0 (non-blocking)
+exit 0

plugins/contract-validator/hooks/breaking-change-check.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# contract-validator breaking change detection hook
+# Warns when plugin interface changes might break consumers
+# This is a PostToolUse hook - non-blocking, warnings only
+
+PREFIX="[contract-validator]"
+
+# Check if warnings are enabled (default: true)
+if [[ "${CONTRACT_VALIDATOR_BREAKING_WARN:-true}" != "true" ]]; then
+    exit 0
+fi
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Extract file_path from JSON input
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no file_path found, exit silently
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file is a plugin interface file
+is_interface_file() {
+    local file="$1"
+
+    case "$file" in
+        */plugin.json) return 0 ;;
+        */.claude-plugin/plugin.json) return 0 ;;
+        */hooks.json) return 0 ;;
+        */hooks/hooks.json) return 0 ;;
+        */.mcp.json) return 0 ;;
+        */agents/*.md) return 0 ;;
+        */commands/*.md) return 0 ;;
+        */skills/*.md) return 0 ;;
+    esac
+
+    return 1
+}
+
+# Exit if not an interface file
+if ! is_interface_file "$FILE_PATH"; then
+    exit 0
+fi
+
+# Check if file exists and is in a git repo
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+# Get the directory containing the file
+FILE_DIR=$(dirname "$FILE_PATH")
+FILE_NAME=$(basename "$FILE_PATH")
+
+# Try to get the previous version from git
+cd "$FILE_DIR" 2>/dev/null || exit 0
+
+# Check if we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    exit 0
+fi
+
+# Get previous version (HEAD version before current changes)
+PREV_CONTENT=$(git show HEAD:"$FILE_PATH" 2>/dev/null || echo "")
+
+# If no previous version, this is a new file - no breaking changes possible
+if [ -z "$PREV_CONTENT" ]; then
+    exit 0
+fi
+
+# Read current content
+CURR_CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+
+if [ -z "$CURR_CONTENT" ]; then
+    exit 0
+fi
+
+BREAKING_CHANGES=()
+
+# Detect breaking changes based on file type
+case "$FILE_PATH" in
+    */plugin.json|*/.claude-plugin/plugin.json)
+        # Check for removed or renamed fields in plugin.json
+
+        # Check if name changed
+        PREV_NAME=$(echo "$PREV_CONTENT" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)
+        CURR_NAME=$(echo "$CURR_CONTENT" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)
+        if [ -n "$PREV_NAME" ] && [ "$PREV_NAME" != "$CURR_NAME" ]; then
+            BREAKING_CHANGES+=("Plugin name changed - consumers may need updates")
+        fi
+
+        # Check if version had major bump (semantic versioning)
+        PREV_VER=$(echo "$PREV_CONTENT" | grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([0-9]*\)\..*/\1/')
+        CURR_VER=$(echo "$CURR_CONTENT" | grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([0-9]*\)\..*/\1/')
+        if [ -n "$PREV_VER" ] && [ -n "$CURR_VER" ] && [ "$CURR_VER" -gt "$PREV_VER" ] 2>/dev/null; then
+            BREAKING_CHANGES+=("Major version bump detected - verify breaking changes documented")
+        fi
+        ;;
+
+    */hooks.json|*/hooks/hooks.json)
+        # Check for removed hook events
+        PREV_EVENTS=$(echo "$PREV_CONTENT" | grep -oE '"(PreToolUse|PostToolUse|UserPromptSubmit|SessionStart|SessionEnd|Notification|Stop|SubagentStop|PreCompact)"' | sort -u)
+        CURR_EVENTS=$(echo "$CURR_CONTENT" | grep -oE '"(PreToolUse|PostToolUse|UserPromptSubmit|SessionStart|SessionEnd|Notification|Stop|SubagentStop|PreCompact)"' | sort -u)
+
+        # Find removed events
+        REMOVED_EVENTS=$(comm -23 <(echo "$PREV_EVENTS") <(echo "$CURR_EVENTS") 2>/dev/null)
+        if [ -n "$REMOVED_EVENTS" ]; then
+            BREAKING_CHANGES+=("Hook events removed: $(echo $REMOVED_EVENTS | tr '\n' ' ')")
+        fi
+
+        # Check for changed matchers
+        PREV_MATCHERS=$(echo "$PREV_CONTENT" | grep -o '"matcher"[[:space:]]*:[[:space:]]*"[^"]*"' | sort -u)
+        CURR_MATCHERS=$(echo "$CURR_CONTENT" | grep -o '"matcher"[[:space:]]*:[[:space:]]*"[^"]*"' | sort -u)
+        if [ "$PREV_MATCHERS" != "$CURR_MATCHERS" ]; then
+            BREAKING_CHANGES+=("Hook matchers changed - verify tool coverage")
+        fi
+        ;;
+
+    */.mcp.json)
+        # Check for removed MCP servers
+        PREV_SERVERS=$(echo "$PREV_CONTENT" | grep -o '"[^"]*"[[:space:]]*:' | grep -v "mcpServers" | sort -u)
+        CURR_SERVERS=$(echo "$CURR_CONTENT" | grep -o '"[^"]*"[[:space:]]*:' | grep -v "mcpServers" | sort -u)
+
+        REMOVED_SERVERS=$(comm -23 <(echo "$PREV_SERVERS") <(echo "$CURR_SERVERS") 2>/dev/null)
+        if [ -n "$REMOVED_SERVERS" ]; then
+            BREAKING_CHANGES+=("MCP servers removed - tools may be unavailable")
+        fi
+        ;;
+
+    */agents/*.md)
+        # Check if agent file was significantly reduced (might indicate removal of capabilities)
+        PREV_LINES=$(echo "$PREV_CONTENT" | wc -l)
+        CURR_LINES=$(echo "$CURR_CONTENT" | wc -l)
+
+        # If more than 50% reduction, warn
+        if [ "$PREV_LINES" -gt 10 ] && [ "$CURR_LINES" -lt $((PREV_LINES / 2)) ]; then
+            BREAKING_CHANGES+=("Agent definition significantly reduced - capabilities may be removed")
+        fi
+
+        # Check if agent name/description changed in frontmatter
+        PREV_DESC=$(echo "$PREV_CONTENT" | head -20 | grep -i "description" | head -1)
+        CURR_DESC=$(echo "$CURR_CONTENT" | head -20 | grep -i "description" | head -1)
+        if [ -n "$PREV_DESC" ] && [ "$PREV_DESC" != "$CURR_DESC" ]; then
+            BREAKING_CHANGES+=("Agent description changed - verify consumer expectations")
+        fi
+        ;;
+
+    */commands/*.md|*/skills/*.md)
+        # Check if command/skill was significantly changed
+        PREV_LINES=$(echo "$PREV_CONTENT" | wc -l)
+        CURR_LINES=$(echo "$CURR_CONTENT" | wc -l)
+
+        if [ "$PREV_LINES" -gt 10 ] && [ "$CURR_LINES" -lt $((PREV_LINES / 2)) ]; then
+            BREAKING_CHANGES+=("Command/skill significantly reduced - behavior may change")
+        fi
+        ;;
+esac
+
+# Output warnings if any breaking changes detected
+if [[ ${#BREAKING_CHANGES[@]} -gt 0 ]]; then
+    echo ""
+    echo "$PREFIX WARNING: Potential breaking changes in $(basename "$FILE_PATH")"
+    echo "$PREFIX ============================================"
+    for change in "${BREAKING_CHANGES[@]}"; do
+        echo "$PREFIX   - $change"
+    done
+    echo "$PREFIX ============================================"
+    echo "$PREFIX Consider updating CHANGELOG and notifying consumers"
+    echo ""
+fi
+
+# Always exit 0 - non-blocking
+exit 0

plugins/contract-validator/hooks/hooks.json

@@ -0,0 +1,21 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/auto-validate.sh"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/breaking-change-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/data-platform/hooks/hooks.json

@@ -5,6 +5,17 @@
         "type": "command",
         "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh"
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/schema-diff-check.sh"
+          }
+        ]
+      }
     ]
   }
 }

plugins/data-platform/hooks/schema-diff-check.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+# data-platform schema diff detection hook
+# Warns about potentially breaking schema changes
+# This is a command hook - non-blocking, warnings only
+
+PREFIX="[data-platform]"
+
+# Check if warnings are enabled (default: true)
+if [[ "${DATA_PLATFORM_SCHEMA_WARN:-true}" != "true" ]]; then
+    exit 0
+fi
+
+# Read tool input from stdin (JSON with file_path)
+INPUT=$(cat)
+
+# Extract file_path from JSON input
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no file_path found, exit silently
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file is a schema-related file
+is_schema_file() {
+    local file="$1"
+
+    # Check file extension
+    case "$file" in
+        *.sql) return 0 ;;
+        */migrations/*.py) return 0 ;;
+        */migrations/*.sql) return 0 ;;
+        */models/*.py) return 0 ;;
+        */models/*.sql) return 0 ;;
+        *schema.prisma) return 0 ;;
+        *schema.graphql) return 0 ;;
+        */dbt/models/*.sql) return 0 ;;
+        */dbt/models/*.yml) return 0 ;;
+        */alembic/versions/*.py) return 0 ;;
+    esac
+
+    # Check directory patterns
+    if echo "$file" | grep -qE "(migrations?|schemas?|models)/"; then
+        return 0
+    fi
+
+    return 1
+}
+
+# Exit if not a schema file
+if ! is_schema_file "$FILE_PATH"; then
+    exit 0
+fi
+
+# Read the file content (if it exists and is readable)
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+FILE_CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+
+if [[ -z "$FILE_CONTENT" ]]; then
+    exit 0
+fi
+
+# Detect breaking changes
+BREAKING_CHANGES=()
+
+# Check for DROP COLUMN
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+COLUMN"; then
+    BREAKING_CHANGES+=("DROP COLUMN detected - may break existing queries")
+fi
+
+# Check for DROP TABLE
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+TABLE"; then
+    BREAKING_CHANGES+=("DROP TABLE detected - data loss risk")
+fi
+
+# Check for DROP INDEX
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+INDEX"; then
+    BREAKING_CHANGES+=("DROP INDEX detected - may impact query performance")
+fi
+
+# Check for ALTER TYPE / MODIFY COLUMN type changes
+if echo "$FILE_CONTENT" | grep -qiE "ALTER[[:space:]]+.*(TYPE|COLUMN.*TYPE)"; then
+    BREAKING_CHANGES+=("Column type change detected - may cause data truncation")
+fi
+
+if echo "$FILE_CONTENT" | grep -qiE "MODIFY[[:space:]]+COLUMN"; then
+    BREAKING_CHANGES+=("MODIFY COLUMN detected - verify data compatibility")
+fi
+
+# Check for adding NOT NULL to existing column
+if echo "$FILE_CONTENT" | grep -qiE "ALTER[[:space:]]+.*SET[[:space:]]+NOT[[:space:]]+NULL"; then
+    BREAKING_CHANGES+=("Adding NOT NULL constraint - existing NULL values will fail")
+fi
+
+if echo "$FILE_CONTENT" | grep -qiE "ADD[[:space:]]+.*NOT[[:space:]]+NULL[^[:space:]]*[[:space:]]+DEFAULT"; then
+    # Adding NOT NULL with DEFAULT is usually safe - don't warn
+    :
+elif echo "$FILE_CONTENT" | grep -qiE "ADD[[:space:]]+.*NOT[[:space:]]+NULL"; then
+    BREAKING_CHANGES+=("Adding NOT NULL column without DEFAULT - INSERT may fail")
+fi
+
+# Check for RENAME TABLE/COLUMN
+if echo "$FILE_CONTENT" | grep -qiE "RENAME[[:space:]]+(TABLE|COLUMN|TO)"; then
+    BREAKING_CHANGES+=("RENAME detected - update all references")
+fi
+
+# Check for removing from Django/SQLAlchemy models (Python files)
+if [[ "$FILE_PATH" == *.py ]]; then
+    if echo "$FILE_CONTENT" | grep -qE "^-[[:space:]]*[a-z_]+[[:space:]]*=.*Field\("; then
+        BREAKING_CHANGES+=("Model field removal detected in Python ORM")
+    fi
+fi
+
+# Check for Prisma schema changes
+if [[ "$FILE_PATH" == *schema.prisma ]]; then
+    if echo "$FILE_CONTENT" | grep -qE "@relation.*onDelete.*Cascade"; then
+        BREAKING_CHANGES+=("Cascade delete detected - verify data safety")
+    fi
+fi
+
+# Output warnings if any breaking changes detected
+if [[ ${#BREAKING_CHANGES[@]} -gt 0 ]]; then
+    echo ""
+    echo "$PREFIX WARNING: Potential breaking schema changes in $(basename "$FILE_PATH")"
+    echo "$PREFIX ============================================"
+    for change in "${BREAKING_CHANGES[@]}"; do
+        echo "$PREFIX   - $change"
+    done
+    echo "$PREFIX ============================================"
+    echo "$PREFIX Review before deploying to production"
+    echo ""
+fi
+
+# Always exit 0 - non-blocking
+exit 0

plugins/git-flow/hooks/branch-check.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# git-flow branch name validation hook
+# Validates branch names follow the convention: <type>/<description>
+# Command hook - guaranteed predictable behavior
+
+# Read tool input from stdin (JSON format)
+INPUT=$(cat)
+
+# Extract command from JSON input
+# The Bash tool sends {"command": "..."} format
+COMMAND=$(echo "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no command found, exit silently (allow)
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Check if this is a branch creation command
+# Patterns: git checkout -b, git branch (without -d/-D), git switch -c/-C
+IS_BRANCH_CREATE=false
+BRANCH_NAME=""
+
+# git checkout -b <branch>
+if echo "$COMMAND" | grep -qE 'git\s+checkout\s+(-b|--branch)\s+'; then
+    IS_BRANCH_CREATE=true
+    BRANCH_NAME=$(echo "$COMMAND" | sed -n 's/.*git\s\+checkout\s\+\(-b\|--branch\)\s\+\([^ ]*\).*/\2/p')
+fi
+
+# git switch -c/-C <branch>
+if echo "$COMMAND" | grep -qE 'git\s+switch\s+(-c|-C|--create|--force-create)\s+'; then
+    IS_BRANCH_CREATE=true
+    BRANCH_NAME=$(echo "$COMMAND" | sed -n 's/.*git\s\+switch\s\+\(-c\|-C\|--create\|--force-create\)\s\+\([^ ]*\).*/\2/p')
+fi
+
+# git branch <name> (without -d/-D/-m/-M which are delete/rename)
+if echo "$COMMAND" | grep -qE 'git\s+branch\s+[^-]' && ! echo "$COMMAND" | grep -qE 'git\s+branch\s+(-d|-D|-m|-M|--delete|--move|--list|--show-current)'; then
+    IS_BRANCH_CREATE=true
+    BRANCH_NAME=$(echo "$COMMAND" | sed -n 's/.*git\s\+branch\s\+\([^ -][^ ]*\).*/\1/p')
+fi
+
+# If not a branch creation command, exit silently (allow)
+if [ "$IS_BRANCH_CREATE" = false ]; then
+    exit 0
+fi
+
+# If we couldn't extract the branch name, exit silently (allow)
+if [ -z "$BRANCH_NAME" ]; then
+    exit 0
+fi
+
+# Remove any quotes from branch name
+BRANCH_NAME=$(echo "$BRANCH_NAME" | tr -d '"' | tr -d "'")
+
+# Skip validation for special branches
+case "$BRANCH_NAME" in
+    main|master|develop|development|staging|release|hotfix)
+        exit 0
+        ;;
+esac
+
+# Allowed branch types
+VALID_TYPES="feat|fix|chore|docs|refactor|test|perf|debug"
+
+# Validate branch name format: <type>/<description>
+# Description: lowercase letters, numbers, hyphens only, max 50 chars total
+if ! echo "$BRANCH_NAME" | grep -qE "^($VALID_TYPES)/[a-z0-9][a-z0-9-]*$"; then
+    echo ""
+    echo "[git-flow] Branch name validation failed"
+    echo ""
+    echo "Branch: $BRANCH_NAME"
+    echo ""
+    echo "Expected format: <type>/<description>"
+    echo ""
+    echo "Valid types: feat, fix, chore, docs, refactor, test, perf, debug"
+    echo ""
+    echo "Description rules:"
+    echo "  - Lowercase letters, numbers, and hyphens only"
+    echo "  - Must start with letter or number"
+    echo "  - No spaces or special characters"
+    echo ""
+    echo "Examples:"
+    echo "  feat/add-user-auth"
+    echo "  fix/login-timeout"
+    echo "  chore/update-deps"
+    echo "  docs/api-reference"
+    echo ""
+    exit 1
+fi
+
+# Check total length (max 50 chars)
+if [ ${#BRANCH_NAME} -gt 50 ]; then
+    echo ""
+    echo "[git-flow] Branch name too long"
+    echo ""
+    echo "Branch: $BRANCH_NAME (${#BRANCH_NAME} chars)"
+    echo "Maximum: 50 characters"
+    echo ""
+    exit 1
+fi
+
+# Valid branch name
+exit 0

plugins/git-flow/hooks/commit-msg-check.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# git-flow commit message validation hook
+# Validates git commit messages follow conventional commit format
+# PreToolUse hook for Bash commands - type: command
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Use Python to properly parse JSON and extract the command
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('command',''))" 2>/dev/null)
+
+# If no command or python failed, allow through
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Check if it is a git commit command with -m flag
+if ! echo "$COMMAND" | grep -qE 'git\s+commit.*-m'; then
+    # Not a git commit with -m, allow through
+    exit 0
+fi
+
+# Extract commit message - handle various quoting styles
+# Try double quotes first
+COMMIT_MSG=$(echo "$COMMAND" | sed -n 's/.*-m[[:space:]]*"\([^"]*\)".*/\1/p')
+# If empty, try single quotes
+if [ -z "$COMMIT_MSG" ]; then
+    COMMIT_MSG=$(echo "$COMMAND" | sed -n "s/.*-m[[:space:]]*'\\([^']*\\)'.*/\\1/p")
+fi
+# If still empty, try HEREDOC pattern
+if [ -z "$COMMIT_MSG" ]; then
+    if echo "$COMMAND" | grep -qE -- '-m[[:space:]]+"\$\(cat <<'; then
+        # HEREDOC pattern - too complex to parse, allow through
+        exit 0
+    fi
+fi
+
+# If no message extracted, allow through
+if [ -z "$COMMIT_MSG" ]; then
+    exit 0
+fi
+
+# Validate conventional commit format
+# Format: <type>(<scope>): <description>
+# or: <type>: <description>
+# Valid types: feat, fix, docs, style, refactor, perf, test, chore, build, ci
+
+VALID_TYPES="feat|fix|docs|style|refactor|perf|test|chore|build|ci"
+
+# Check if message matches conventional commit format
+if echo "$COMMIT_MSG" | grep -qE "^($VALID_TYPES)(\([a-zA-Z0-9_-]+\))?:[[:space:]]+.+"; then
+    # Valid format
+    exit 0
+fi
+
+# Invalid format - output warning
+echo "[git-flow] WARNING: Commit message does not follow conventional commit format"
+echo ""
+echo "Expected format: <type>(<scope>): <description>"
+echo "  or: <type>: <description>"
+echo ""
+echo "Valid types: feat, fix, docs, style, refactor, perf, test, chore, build, ci"
+echo ""
+echo "Examples:"
+echo "  feat(auth): add password reset functionality"
+echo "  fix: resolve login timeout issue"
+echo "  docs(readme): update installation instructions"
+echo ""
+echo "Your message: $COMMIT_MSG"
+echo ""
+echo "To proceed anyway, use /commit command which auto-generates valid messages."
+
+# Exit with non-zero to block
+exit 1

plugins/git-flow/hooks/hooks.json

@@ -0,0 +1,19 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/branch-check.sh"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/commit-msg-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}