添加 claude code game studios 到项目

.claude/hooks/detect-gaps.sh

@@ -0,0 +1,155 @@
+#!/bin/bash
+# Hook: detect-gaps.sh
+# Event: SessionStart
+# Purpose: Detect missing documentation when code/prototypes exist
+# Cross-platform: Windows Git Bash compatible (uses grep -E, not -P)
+
+# Exit on error for debugging (but don't fail the session)
+set +e
+
+echo "=== Checking for Documentation Gaps ==="
+
+# --- Check 0: Fresh project detection (suggests /start) ---
+FRESH_PROJECT=true
+
+# Check if engine is configured
+if [ -f ".claude/docs/technical-preferences.md" ]; then
+  ENGINE_LINE=$(grep -E "^\- \*\*Engine\*\*:" .claude/docs/technical-preferences.md 2>/dev/null)
+  if [ -n "$ENGINE_LINE" ] && ! echo "$ENGINE_LINE" | grep -q "TO BE CONFIGURED" 2>/dev/null; then
+    FRESH_PROJECT=false
+  fi
+fi
+
+# Check if game concept exists
+if [ -f "design/gdd/game-concept.md" ]; then
+  FRESH_PROJECT=false
+fi
+
+# Check if source code exists
+if [ -d "src" ]; then
+  SRC_CHECK=$(find src -type f \( -name "*.gd" -o -name "*.cs" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o -name "*.hpp" -o -name "*.rs" -o -name "*.py" -o -name "*.js" -o -name "*.ts" \) 2>/dev/null | head -1)
+  if [ -n "$SRC_CHECK" ]; then
+    FRESH_PROJECT=false
+  fi
+fi
+
+if [ "$FRESH_PROJECT" = true ]; then
+  echo ""
+  echo "🚀 NEW PROJECT: No engine configured, no game concept, no source code."
+  echo "   This looks like a fresh start! Run: /start"
+  echo ""
+  echo "💡 To get a comprehensive project analysis, run: /project-stage-detect"
+  echo "==================================="
+  exit 0
+fi
+
+# --- Check 1: Substantial codebase but sparse design docs ---
+if [ -d "src" ]; then
+  # Count source files (cross-platform, handles Windows paths)
+  SRC_FILES=$(find src -type f \( -name "*.gd" -o -name "*.cs" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o -name "*.hpp" -o -name "*.rs" -o -name "*.py" -o -name "*.js" -o -name "*.ts" \) 2>/dev/null | wc -l)
+else
+  SRC_FILES=0
+fi
+
+if [ -d "design/gdd" ]; then
+  DESIGN_FILES=$(find design/gdd -type f -name "*.md" 2>/dev/null | wc -l)
+else
+  DESIGN_FILES=0
+fi
+
+# Normalize whitespace from wc output
+SRC_FILES=$(echo "$SRC_FILES" | tr -d ' ')
+DESIGN_FILES=$(echo "$DESIGN_FILES" | tr -d ' ')
+
+if [ "$SRC_FILES" -gt 50 ] && [ "$DESIGN_FILES" -lt 5 ]; then
+  echo "⚠️  GAP: Substantial codebase ($SRC_FILES source files) but sparse design docs ($DESIGN_FILES files)"
+  echo "    Suggested action: /reverse-document design src/[system]"
+  echo "    Or run: /project-stage-detect to get full analysis"
+fi
+
+# --- Check 2: Prototypes without documentation ---
+if [ -d "prototypes" ]; then
+  PROTOTYPE_DIRS=$(find prototypes -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+  UNDOCUMENTED_PROTOS=()
+
+  if [ -n "$PROTOTYPE_DIRS" ]; then
+    while IFS= read -r proto_dir; do
+      # Normalize path separators for Windows
+      proto_dir=$(echo "$proto_dir" | sed 's|\\|/|g')
+
+      # Check for README.md or CONCEPT.md
+      if [ ! -f "${proto_dir}/README.md" ] && [ ! -f "${proto_dir}/CONCEPT.md" ]; then
+        proto_name=$(basename "$proto_dir")
+        UNDOCUMENTED_PROTOS+=("$proto_name")
+      fi
+    done <<< "$PROTOTYPE_DIRS"
+
+    if [ ${#UNDOCUMENTED_PROTOS[@]} -gt 0 ]; then
+      echo "⚠️  GAP: ${#UNDOCUMENTED_PROTOS[@]} undocumented prototype(s) found:"
+      for proto in "${UNDOCUMENTED_PROTOS[@]}"; do
+        echo "    - prototypes/$proto/ (no README or CONCEPT doc)"
+      done
+      echo "    Suggested action: /reverse-document concept prototypes/[name]"
+    fi
+  fi
+fi
+
+# --- Check 3: Core systems without architecture docs ---
+if [ -d "src/core" ] || [ -d "src/engine" ]; then
+  if [ ! -d "docs/architecture" ]; then
+    echo "⚠️  GAP: Core engine/systems exist but no docs/architecture/ directory"
+    echo "    Suggested action: Create docs/architecture/ and run /architecture-decision"
+  else
+    ADR_COUNT=$(find docs/architecture -type f -name "*.md" 2>/dev/null | wc -l)
+    ADR_COUNT=$(echo "$ADR_COUNT" | tr -d ' ')
+
+    if [ "$ADR_COUNT" -lt 3 ]; then
+      echo "⚠️  GAP: Core systems exist but only $ADR_COUNT ADR(s) documented"
+      echo "    Suggested action: /reverse-document architecture src/core/[system]"
+    fi
+  fi
+fi
+
+# --- Check 4: Gameplay systems without design docs ---
+if [ -d "src/gameplay" ]; then
+  # Find major gameplay subdirectories (those with 5+ files)
+  GAMEPLAY_SYSTEMS=$(find src/gameplay -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+  if [ -n "$GAMEPLAY_SYSTEMS" ]; then
+    while IFS= read -r system_dir; do
+      system_dir=$(echo "$system_dir" | sed 's|\\|/|g')
+      system_name=$(basename "$system_dir")
+      file_count=$(find "$system_dir" -type f 2>/dev/null | wc -l)
+      file_count=$(echo "$file_count" | tr -d ' ')
+
+      # If system has 5+ files, check for corresponding design doc
+      if [ "$file_count" -ge 5 ]; then
+        # Check for design doc (allow variations: combat-system.md, combat.md)
+        design_doc_1="design/gdd/${system_name}-system.md"
+        design_doc_2="design/gdd/${system_name}.md"
+
+        if [ ! -f "$design_doc_1" ] && [ ! -f "$design_doc_2" ]; then
+          echo "⚠️  GAP: Gameplay system 'src/gameplay/$system_name/' ($file_count files) has no design doc"
+          echo "    Expected: design/gdd/${system_name}-system.md or design/gdd/${system_name}.md"
+          echo "    Suggested action: /reverse-document design src/gameplay/$system_name"
+        fi
+      fi
+    done <<< "$GAMEPLAY_SYSTEMS"
+  fi
+fi
+
+# --- Check 5: Production planning ---
+if [ "$SRC_FILES" -gt 100 ]; then
+  # For projects with substantial code, check for production planning
+  if [ ! -d "production/sprints" ] && [ ! -d "production/milestones" ]; then
+    echo "⚠️  GAP: Large codebase ($SRC_FILES files) but no production planning found"
+    echo "    Suggested action: /sprint-plan or create production/ directory"
+  fi
+fi
+
+# --- Summary ---
+echo ""
+echo "💡 To get a comprehensive project analysis, run: /project-stage-detect"
+echo "==================================="
+
+exit 0

.claude/hooks/log-agent-stop.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Claude Code SubagentStop hook: Log agent completion for audit trail
+# Tracks when agents finish and their outcome
+#
+# Input schema (SubagentStop) — per Claude Code hooks reference:
+# { "session_id": "...", "agent_id": "agent-abc123", "agent_type": "Explore",
+#   "agent_transcript_path": "...", "last_assistant_message": "...", ... }
+#
+# The agent name is in `agent_type`, NOT `agent_name`. Reading `.agent_name`
+# returns null on every invocation, so the fallback "unknown" is always used
+# and the audit trail captures nothing useful.
+
+INPUT=$(cat)
+
+# Parse agent name -- use jq if available, fall back to grep
+if command -v jq >/dev/null 2>&1; then
+    AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_type // "unknown"' 2>/dev/null)
+else
+    AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_type"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"agent_type"[[:space:]]*:[[:space:]]*"//;s/"$//')
+    [ -z "$AGENT_NAME" ] && AGENT_NAME="unknown"
+fi
+
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+SESSION_LOG_DIR="production/session-logs"
+
+mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
+
+echo "$TIMESTAMP | Agent completed: $AGENT_NAME" >> "$SESSION_LOG_DIR/agent-audit.log" 2>/dev/null
+
+exit 0

.claude/hooks/log-agent.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Claude Code SubagentStart hook: Log agent invocations for audit trail
+# Tracks which agents are being used and when
+#
+# Input schema (SubagentStart) — per Claude Code hooks reference:
+# { "session_id": "...", "agent_id": "agent-abc123", "agent_type": "Explore", ... }
+#
+# The agent name is in `agent_type`, NOT `agent_name`. Reading `.agent_name`
+# returns null on every invocation, so the fallback "unknown" is always used
+# and the audit trail captures nothing useful.
+
+INPUT=$(cat)
+
+# Parse agent name -- use jq if available, fall back to grep
+if command -v jq >/dev/null 2>&1; then
+    AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_type // "unknown"' 2>/dev/null)
+else
+    AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_type"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"agent_type"[[:space:]]*:[[:space:]]*"//;s/"$//')
+    [ -z "$AGENT_NAME" ] && AGENT_NAME="unknown"
+fi
+
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+SESSION_LOG_DIR="production/session-logs"
+
+mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
+
+echo "$TIMESTAMP | Agent invoked: $AGENT_NAME" >> "$SESSION_LOG_DIR/agent-audit.log" 2>/dev/null
+
+exit 0

.claude/hooks/notify.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Notification hook — fires when Claude Code sends a notification
+# Shows a Windows toast via PowerShell
+
+# Read notification JSON from stdin
+INPUT=$(cat)
+
+# Extract message — try jq first, fall back to grep
+if command -v jq &>/dev/null; then
+  MESSAGE=$(echo "$INPUT" | jq -r '.message // empty' 2>/dev/null)
+fi
+if [ -z "$MESSAGE" ]; then
+  MESSAGE=$(echo "$INPUT" | grep -oE '"message":"[^"]*"' | sed 's/"message":"//;s/"//')
+fi
+if [ -z "$MESSAGE" ]; then
+  MESSAGE="Claude Code needs your attention"
+fi
+
+# Sanitize message for PowerShell string embedding (escape single quotes)
+MESSAGE_SAFE=$(echo "$MESSAGE" | sed "s/'/''/g" | head -c 200)
+
+# Show Windows balloon tip notification (works on all Windows 10/11 without extra modules)
+powershell.exe -NonInteractive -WindowStyle Hidden -Command "
+  Add-Type -AssemblyName System.Windows.Forms
+  \$notify = New-Object System.Windows.Forms.NotifyIcon
+  \$notify.Icon = [System.Drawing.SystemIcons]::Information
+  \$notify.BalloonTipTitle = 'Claude Code'
+  \$notify.BalloonTipText = '$MESSAGE_SAFE'
+  \$notify.Visible = \$true
+  \$notify.ShowBalloonTip(5000)
+  Start-Sleep -Seconds 6
+  \$notify.Dispose()
+" 2>/dev/null &
+
+echo "Notification: $MESSAGE_SAFE"

.claude/hooks/post-compact.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# post-compact.sh — fires after conversation compaction
+# Reminds Claude to restore session state from the file-backed checkpoint.
+
+ACTIVE="production/session-state/active.md"
+
+echo "=== Context Restored After Compaction ==="
+
+if [ -f "$ACTIVE" ]; then
+  SIZE=$(wc -l < "$ACTIVE" 2>/dev/null || echo "?")
+  echo "Session state file exists: $ACTIVE ($SIZE lines)"
+  echo "IMPORTANT: Read this file now to restore your working context."
+  echo "It contains: current task, decisions made, files in progress, open questions."
+else
+  echo "No session state file found at $ACTIVE"
+  echo "If you were mid-task, check production/session-logs/ for the last session audit."
+fi
+
+echo "========================================="

.claude/hooks/pre-compact.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# Claude Code PreCompact hook: Dump session state before context compression
+# This output appears in the conversation right before compaction, ensuring
+# critical state survives the summarization process.
+
+echo "=== SESSION STATE BEFORE COMPACTION ==="
+echo "Timestamp: $(date)"
+
+# --- Active session state file ---
+STATE_FILE="production/session-state/active.md"
+if [ -f "$STATE_FILE" ]; then
+    echo ""
+    echo "## Active Session State (from $STATE_FILE)"
+    STATE_LINES=$(wc -l < "$STATE_FILE" 2>/dev/null | tr -d ' ')
+    if [ "$STATE_LINES" -gt 100 ] 2>/dev/null; then
+        head -n 100 "$STATE_FILE"
+        echo "... (truncated — $STATE_LINES total lines, showing first 100)"
+    else
+        cat "$STATE_FILE"
+    fi
+else
+    echo ""
+    echo "## No active session state file found"
+    echo "Consider maintaining production/session-state/active.md for better recovery."
+fi
+
+# --- Files modified this session (unstaged + staged + untracked) ---
+echo ""
+echo "## Files Modified (git working tree)"
+
+CHANGED=$(git diff --name-only 2>/dev/null)
+STAGED=$(git diff --staged --name-only 2>/dev/null)
+UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null)
+
+if [ -n "$CHANGED" ]; then
+    echo "Unstaged changes:"
+    echo "$CHANGED" | while read -r f; do echo "  - $f"; done
+fi
+if [ -n "$STAGED" ]; then
+    echo "Staged changes:"
+    echo "$STAGED" | while read -r f; do echo "  - $f"; done
+fi
+if [ -n "$UNTRACKED" ]; then
+    echo "New untracked files:"
+    echo "$UNTRACKED" | while read -r f; do echo "  - $f"; done
+fi
+if [ -z "$CHANGED" ] && [ -z "$STAGED" ] && [ -z "$UNTRACKED" ]; then
+    echo "  (no uncommitted changes)"
+fi
+
+# --- Work-in-progress design docs ---
+echo ""
+echo "## Design Docs — Work In Progress"
+
+WIP_FOUND=false
+for f in design/gdd/*.md; do
+    [ -f "$f" ] || continue
+    INCOMPLETE=$(grep -n -E "TODO|WIP|PLACEHOLDER|\[TO BE|\[TBD\]" "$f" 2>/dev/null)
+    if [ -n "$INCOMPLETE" ]; then
+        WIP_FOUND=true
+        echo "  $f:"
+        echo "$INCOMPLETE" | while read -r line; do echo "    $line"; done
+    fi
+done
+
+if [ "$WIP_FOUND" = false ]; then
+    echo "  (no WIP markers found in design docs)"
+fi
+
+# --- Log compaction event ---
+SESSION_LOG_DIR="production/session-logs"
+mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
+echo "Context compaction occurred at $(date)." \
+    >> "$SESSION_LOG_DIR/compaction-log.txt" 2>/dev/null
+
+echo ""
+echo "## Recovery Instructions"
+echo "After compaction, read $STATE_FILE to recover full working context."
+echo "Then read any files listed above that are being actively worked on."
+echo "=== END SESSION STATE ==="
+
+exit 0

.claude/hooks/session-start.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Claude Code SessionStart hook: Load project context at session start
+# Outputs context information that Claude sees when a session begins
+#
+# Input schema (SessionStart): No stdin input
+
+echo "=== Claude Code Game Studios — Session Context ==="
+
+# Current branch
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+if [ -n "$BRANCH" ]; then
+    echo "Branch: $BRANCH"
+
+    # Recent commits
+    echo ""
+    echo "Recent commits:"
+    git log --oneline -5 2>/dev/null | while read -r line; do
+        echo "  $line"
+    done
+fi
+
+# Current sprint (find most recent sprint file)
+LATEST_SPRINT=$(ls -t production/sprints/sprint-*.md 2>/dev/null | head -1)
+if [ -n "$LATEST_SPRINT" ]; then
+    echo ""
+    echo "Active sprint: $(basename "$LATEST_SPRINT" .md)"
+fi
+
+# Current milestone
+LATEST_MILESTONE=$(ls -t production/milestones/*.md 2>/dev/null | head -1)
+if [ -n "$LATEST_MILESTONE" ]; then
+    echo "Active milestone: $(basename "$LATEST_MILESTONE" .md)"
+fi
+
+# Open bug count
+BUG_COUNT=0
+for dir in tests/playtest production; do
+    if [ -d "$dir" ]; then
+        count=$(find "$dir" -name "BUG-*.md" 2>/dev/null | wc -l)
+        BUG_COUNT=$((BUG_COUNT + count))
+    fi
+done
+if [ "$BUG_COUNT" -gt 0 ]; then
+    echo "Open bugs: $BUG_COUNT"
+fi
+
+# Code health quick check
+if [ -d "src" ]; then
+    TODO_COUNT=$(grep -r "TODO" src/ 2>/dev/null | wc -l)
+    FIXME_COUNT=$(grep -r "FIXME" src/ 2>/dev/null | wc -l)
+    if [ "$TODO_COUNT" -gt 0 ] || [ "$FIXME_COUNT" -gt 0 ]; then
+        echo ""
+        echo "Code health: ${TODO_COUNT} TODOs, ${FIXME_COUNT} FIXMEs in src/"
+    fi
+fi
+
+# --- Active session state recovery ---
+STATE_FILE="production/session-state/active.md"
+if [ -f "$STATE_FILE" ]; then
+    echo ""
+    echo "=== ACTIVE SESSION STATE DETECTED ==="
+    echo "A previous session left state at: $STATE_FILE"
+    echo "Read this file to recover context and continue where you left off."
+    echo ""
+    echo "Quick summary (last 20 lines):"
+    tail -20 "$STATE_FILE" 2>/dev/null
+    TOTAL_LINES=$(wc -l < "$STATE_FILE" 2>/dev/null)
+    if [ "$TOTAL_LINES" -gt 20 ]; then
+        echo "  ... ($TOTAL_LINES total lines — read the full file to continue)"
+    fi
+    echo "=== END SESSION STATE PREVIEW ==="
+fi
+
+echo "==================================="
+exit 0

.claude/hooks/session-stop.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Claude Code Stop hook: Log session summary when Claude finishes
+# Records what was worked on for audit trail and sprint tracking
+
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+SESSION_LOG_DIR="production/session-logs"
+
+mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
+
+# Log recent git activity from this session (check up to 8 hours for long sessions)
+RECENT_COMMITS=$(git log --oneline --since="8 hours ago" 2>/dev/null)
+MODIFIED_FILES=$(git diff --name-only 2>/dev/null)
+
+# --- Archive active session state on shutdown (do NOT delete) ---
+# active.md persists across clean exits so multi-session recovery works.
+# It is only valid to delete active.md manually or when explicitly superseded.
+STATE_FILE="production/session-state/active.md"
+if [ -f "$STATE_FILE" ]; then
+    {
+        echo "## Archived Session State: $TIMESTAMP"
+        cat "$STATE_FILE"
+        echo "---"
+        echo ""
+    } >> "$SESSION_LOG_DIR/session-log.md" 2>/dev/null
+fi
+
+if [ -n "$RECENT_COMMITS" ] || [ -n "$MODIFIED_FILES" ]; then
+    {
+        echo "## Session End: $TIMESTAMP"
+        if [ -n "$RECENT_COMMITS" ]; then
+            echo "### Commits"
+            echo "$RECENT_COMMITS"
+        fi
+        if [ -n "$MODIFIED_FILES" ]; then
+            echo "### Uncommitted Changes"
+            echo "$MODIFIED_FILES"
+        fi
+        echo "---"
+        echo ""
+    } >> "$SESSION_LOG_DIR/session-log.md" 2>/dev/null
+fi
+
+exit 0

.claude/hooks/validate-assets.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Claude Code PostToolUse hook: Validates asset files after Write/Edit
+# Checks naming conventions for files in assets/ directory
+#
+# Exit behavior:
+#   exit 0 = success or advisory warnings only (non-blocking)
+#   exit 1 = blocking error (build-breaking issues: invalid JSON, missing required fields)
+#
+# Input schema (PostToolUse for Write/Edit):
+# { "tool_name": "Write", "tool_input": { "file_path": "assets/data/foo.json", "content": "..." } }
+
+INPUT=$(cat)
+
+# Parse file path -- use jq if available, fall back to grep
+if command -v jq >/dev/null 2>&1; then
+    FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+else
+    FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')
+fi
+
+# Normalize path separators (Windows backslash to forward slash)
+FILE_PATH=$(echo "$FILE_PATH" | sed 's|\\|/|g')
+
+# Only check files in assets/
+if ! echo "$FILE_PATH" | grep -qE '(^|/)assets/'; then
+    exit 0
+fi
+
+FILENAME=$(basename "$FILE_PATH")
+WARNINGS=""   # Style/convention issues -- exit 0 with advisory message
+ERRORS=""     # Build-breaking issues -- exit 1 to block the operation
+
+# ADVISORY: Check naming convention (lowercase with underscores only)
+# Naming issues are style violations -- warn but do not block
+# Uses grep -E (POSIX) not grep -P (Perl) for Windows Git Bash compatibility
+if echo "$FILENAME" | grep -qE '[A-Z[:space:]-]'; then
+    WARNINGS="$WARNINGS\n  NAMING: $FILE_PATH must be lowercase with underscores (got: $FILENAME)"
+fi
+
+# BLOCKING: Check JSON validity for data files
+# Invalid JSON will break runtime loading -- this is a build-breaking error
+if echo "$FILE_PATH" | grep -qE '(^|/)assets/data/.*\.json$'; then
+    if [ -f "$FILE_PATH" ]; then
+        # Find a working Python command
+        PYTHON_CMD=""
+        for cmd in python python3 py; do
+            if command -v "$cmd" >/dev/null 2>&1; then
+                PYTHON_CMD="$cmd"
+                break
+            fi
+        done
+
+        if [ -n "$PYTHON_CMD" ]; then
+            if ! "$PYTHON_CMD" -m json.tool "$FILE_PATH" > /dev/null 2>&1; then
+                ERRORS="$ERRORS\n  FORMAT: $FILE_PATH is not valid JSON — fix syntax errors before continuing"
+            fi
+        fi
+    fi
+fi
+
+# Report warnings (advisory -- non-blocking)
+if [ -n "$WARNINGS" ]; then
+    echo -e "=== Asset Validation: Warnings ===$WARNINGS\n==================================\n(Warnings are advisory. Fix before final commit.)" >&2
+fi
+
+# Report errors and block if any build-breaking issues found
+if [ -n "$ERRORS" ]; then
+    echo -e "=== Asset Validation: ERRORS (Blocking) ===$ERRORS\n===========================================\nFix these errors before proceeding." >&2
+    exit 1
+fi
+
+exit 0

.claude/hooks/validate-commit.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# Claude Code PreToolUse hook: Validates git commit commands
+# Receives JSON on stdin with tool_input.command
+# Exit 0 = allow, Exit 2 = block (stderr shown to Claude)
+#
+# Input schema (PreToolUse for Bash):
+# { "tool_name": "Bash", "tool_input": { "command": "git commit -m ..." } }
+
+INPUT=$(cat)
+
+# Parse command -- use jq if available, fall back to grep
+if command -v jq >/dev/null 2>&1; then
+    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+else
+    COMMAND=$(echo "$INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"command"[[:space:]]*:[[:space:]]*"//;s/"$//')
+fi
+
+# Only process git commit commands
+if ! echo "$COMMAND" | grep -qE '^git[[:space:]]+commit'; then
+    exit 0
+fi
+
+# Get staged files
+STAGED=$(git diff --cached --name-only 2>/dev/null)
+if [ -z "$STAGED" ]; then
+    exit 0
+fi
+
+WARNINGS=""
+
+# Check design documents for required sections
+DESIGN_FILES=$(echo "$STAGED" | grep -E '^design/gdd/')
+if [ -n "$DESIGN_FILES" ]; then
+    while IFS= read -r file; do
+        if [[ "$file" == *.md ]] && [ -f "$file" ]; then
+            for section in "Overview" "Player Fantasy" "Detailed" "Formulas" "Edge Cases" "Dependencies" "Tuning Knobs" "Acceptance Criteria"; do
+                if ! grep -qi "$section" "$file"; then
+                    WARNINGS="$WARNINGS\nDESIGN: $file missing required section: $section"
+                fi
+            done
+        fi
+    done <<< "$DESIGN_FILES"
+fi
+
+# Validate JSON data files -- block invalid JSON
+DATA_FILES=$(echo "$STAGED" | grep -E '^assets/data/.*\.json$')
+if [ -n "$DATA_FILES" ]; then
+    # Find a working Python command
+    PYTHON_CMD=""
+    for cmd in python python3 py; do
+        if command -v "$cmd" >/dev/null 2>&1; then
+            PYTHON_CMD="$cmd"
+            break
+        fi
+    done
+
+    while IFS= read -r file; do
+        if [ -f "$file" ]; then
+            if [ -n "$PYTHON_CMD" ]; then
+                if ! "$PYTHON_CMD" -m json.tool "$file" > /dev/null 2>&1; then
+                    echo "BLOCKED: $file is not valid JSON" >&2
+                    exit 2
+                fi
+            else
+                echo "WARNING: Cannot validate JSON (python not found): $file" >&2
+            fi
+        fi
+    done <<< "$DATA_FILES"
+fi
+
+# Check for hardcoded gameplay values in gameplay code
+# Uses grep -E (POSIX extended) instead of grep -P (Perl) for cross-platform compatibility
+CODE_FILES=$(echo "$STAGED" | grep -E '^src/gameplay/')
+if [ -n "$CODE_FILES" ]; then
+    while IFS= read -r file; do
+        if [ -f "$file" ]; then
+            if grep -nE '(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:=][[:space:]]*[0-9]+' "$file" 2>/dev/null; then
+                WARNINGS="$WARNINGS\nCODE: $file may contain hardcoded gameplay values. Use data files."
+            fi
+        fi
+    done <<< "$CODE_FILES"
+fi
+
+# Check for TODO/FIXME without assignee -- uses grep -E instead of grep -P
+SRC_FILES=$(echo "$STAGED" | grep -E '^src/')
+if [ -n "$SRC_FILES" ]; then
+    while IFS= read -r file; do
+        if [ -f "$file" ]; then
+            if grep -nE '(TODO|FIXME|HACK)[^(]' "$file" 2>/dev/null; then
+                WARNINGS="$WARNINGS\nSTYLE: $file has TODO/FIXME without owner tag. Use TODO(name) format."
+            fi
+        fi
+    done <<< "$SRC_FILES"
+fi
+
+# Print warnings (non-blocking) and allow commit
+if [ -n "$WARNINGS" ]; then
+    echo -e "=== Commit Validation Warnings ===$WARNINGS\n================================" >&2
+fi
+
+exit 0

.claude/hooks/validate-push.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Claude Code PreToolUse hook: Validates git push commands
+# Warns on pushes to protected branches
+# Exit 0 = allow, Exit 2 = block
+#
+# Input schema (PreToolUse for Bash):
+# { "tool_name": "Bash", "tool_input": { "command": "git push origin main" } }
+
+INPUT=$(cat)
+
+# Parse command -- use jq if available, fall back to grep
+if command -v jq >/dev/null 2>&1; then
+    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+else
+    COMMAND=$(echo "$INPUT" | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"command"[[:space:]]*:[[:space:]]*"//;s/"$//')
+fi
+
+# Only process git push commands
+if ! echo "$COMMAND" | grep -qE '^git[[:space:]]+push'; then
+    exit 0
+fi
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+MATCHED_BRANCH=""
+
+# Check if pushing to a protected branch
+for branch in develop main master; do
+    if [ "$CURRENT_BRANCH" = "$branch" ]; then
+        MATCHED_BRANCH="$branch"
+        break
+    fi
+    # Also check if pushing to a protected branch explicitly (quote branch name for safety)
+    if echo "$COMMAND" | grep -qE "[[:space:]]${branch}([[:space:]]|$)"; then
+        MATCHED_BRANCH="$branch"
+        break
+    fi
+done
+
+if [ -n "$MATCHED_BRANCH" ]; then
+    echo "Push to protected branch '$MATCHED_BRANCH' detected." >&2
+    echo "Reminder: Ensure build passes, unit tests pass, and no S1/S2 bugs exist." >&2
+    # Allow the push but warn -- uncomment below to block instead:
+    # echo "BLOCKED: Run tests before pushing to $CURRENT_BRANCH" >&2
+    # exit 2
+fi
+
+exit 0

.claude/hooks/validate-skill-change.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Claude Code PostToolUse hook: Advises running skill-test after skill file changes
+# Fires when any file inside .claude/skills/ is written or edited.
+#
+# Exit behavior:
+#   exit 0 = advisory only (non-blocking)
+#
+# Input schema (PostToolUse for Write|Edit):
+# { "tool_name": "Write", "tool_input": { "file_path": "...", "content": "..." } }
+
+INPUT=$(cat)
+
+# Parse file path -- use jq if available, fall back to grep
+if command -v jq >/dev/null 2>&1; then
+    FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+else
+    FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')
+fi
+
+# Normalize path separators (Windows backslash to forward slash)
+FILE_PATH=$(echo "$FILE_PATH" | sed 's|\\|/|g')
+
+# Only act on files inside .claude/skills/
+if ! echo "$FILE_PATH" | grep -qE '(^|/)\.claude/skills/'; then
+    exit 0
+fi
+
+# Extract skill name from path (.claude/skills/[skill-name]/SKILL.md)
+SKILL_NAME=$(echo "$FILE_PATH" | grep -oE '\.claude/skills/[^/]+' | sed 's|\.claude/skills/||')
+
+if [ -z "$SKILL_NAME" ]; then
+    exit 0
+fi
+
+echo "=== Skill Modified: $SKILL_NAME ===" >&2
+echo "Run /skill-test static $SKILL_NAME to validate structural compliance." >&2
+echo "====================================" >&2
+
+exit 0