How to Set Up Automated Validation Hooks for Git Commits and Pushes in Claude-Code-Game-Studios

The Claude-Code-Game-Studios repository implements a three-tier Bash-based Git hook system that validates design documents, enforces code quality standards, and runs build and test gates before code reaches shared branches.

Setting up automated validation hooks for git commits and pushes ensures that game design documents remain consistent, source code meets quality standards, and failing builds never reach protected branches. The Donchitos/Claude-Code-Game-Studios repository provides a complete reference implementation using native Git hooks written in Bash.

Understanding the Three-Tier Hook Architecture

The automated validation system uses three distinct hooks that trigger at different stages of the Git workflow. Each hook resides in .claude/docs/hooks-reference/ and targets specific validation concerns.

pre-commit-design-check

The pre-commit-design-check hook runs before any commit that modifies files in design/ or assets/data/. It validates that Game Design Documents (GDDs) contain required sections and that data files contain valid JSON.

According to the source code in .claude/docs/hooks-reference/pre-commit-design-check.md, the hook checks for five mandatory GDD sections: Overview, Detailed, Edge Cases, Dependencies, and Acceptance Criteria. For data files, it uses Python's json.tool module to validate syntax.

pre-commit-code-quality

The pre-commit-code-quality hook executes before commits that modify files under src/. It enforces code quality standards without blocking commits for minor issues (warnings) while preventing obvious anti-patterns.

As implemented in .claude/docs/hooks-reference/pre-commit-code-quality.md, this hook detects hard-coded gameplay values, flags TODO and FIXME comments missing assignees, and optionally runs language-specific linters. It can also execute unit tests for changed code modules when configured.

pre-push-test-gate

The pre-push-test-gate hook represents the final quality barrier before code reaches remote repositories. It runs before any push and implements mandatory gates for develop and main branches.

The source in .claude/docs/hooks-reference/pre-push-test-gate.md shows this hook performs a full build (adaptable to Make, .NET, Cargo, or other toolchains), executes unit tests, and for protected branches (develop and main), runs integration tests, smoke tests, and performance baseline checks.

Installing the Automated Validation Hooks

You can install these hooks manually or using the pre-commit framework for version-controlled automation.

Manual Installation

Copy the hook scripts from the reference directory to your local .git/hooks folder and make them executable:

# Copy design check hook

cp .claude/docs/hooks-reference/pre-commit-design-check.md .git/hooks/pre-commit-design-check

# Copy code quality hook (append or combine with pre-commit)

cp .claude/docs/hooks-reference/pre-commit-code-quality.md .git/hooks/pre-commit-code-quality

# Copy push gate hook

cp .claude/docs/hooks-reference/pre-push-test-gate.md .git/hooks/pre-push

# Make executable

chmod +x .git/hooks/pre-commit-design-check .git/hooks/pre-commit-code-quality .git/hooks/pre-push

If you need both pre-commit hooks to run, create a master pre-commit script that sources both:

#!/bin/bash

# .git/hooks/pre-commit

.claude/docs/hooks-reference/pre-commit-design-check.md
.claude/docs/hooks-reference/pre-commit-code-quality.md

Using the Pre-Commit Framework

For version-controlled hook management, use the pre-commit framework. Create a .pre-commit-config.yaml in your repository root:

repos:
  - repo: local
    hooks:
      - id: design-check
        name: Design Document Validation
        entry: bash .claude/docs/hooks-reference/pre-commit-design-check.md
        language: system
        files: ^(design/|assets/data/).*$
      - id: code-quality
        name: Code Quality Check
        entry: bash .claude/docs/hooks-reference/pre-commit-code-quality.md
        language: system
        files: ^src/.*$

Install with:

pip install pre-commit
pre-commit install

Hook Implementation Details

The validation logic in Claude-Code-Game-Studios uses standard Git plumbing commands and shell scripting for portability.

Design Document Validation

The pre-commit-design-check hook uses git diff --cached --name-only to detect staged changes in monitored directories:

#!/bin/bash
DESIGN_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^design/')
DATA_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^assets/data/')
EXIT_CODE=0

if [ -n "$DESIGN_FILES" ]; then
  for file in $DESIGN_FILES; do
    if [[ "$file" == design/gdd/* && "$file" == *.md ]]; then
      for section in "Overview" "Detailed" "Edge Cases" "Dependencies" "Acceptance Criteria"; do
        if ! grep -qi "$section" "$file"; then
          echo "ERROR: $file missing required section: $section"
          EXIT_CODE=1
        fi
      done
    fi
  done
fi

if [ -n "$DATA_FILES" ]; then
  for file in $DATA_FILES; do
    if [[ "$file" == *.json ]]; then
      python -m json.tool "$file" > /dev/null 2>&1 || {
        echo "ERROR: $file is not valid JSON"
        EXIT_CODE=1
      }
    fi
  done
fi

exit $EXIT_CODE

Pre-Push Test Gate

The pre-push-test-gate receives remote and URL arguments, detects the current branch, and implements conditional logic for protected branches:

#!/bin/bash
REMOTE="$1"
URL="$2"
PROTECTED_BRANCHES="develop main"
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

FULL_GATE=false
for branch in $PROTECTED_BRANCHES; do
  [ "$CURRENT_BRANCH" = "$branch" ] && FULL_GATE=true && break
done

echo "=== Pre-Push Quality Gate ==="

make build || { echo "Build failed"; exit 1; }
echo "Build: PASS"

pytest -q tests/unit/ || { echo "Unit tests failed"; exit 1; }
echo "Unit tests: PASS"

if $FULL_GATE; then
  pytest -q tests/integration/ || { echo "Integration tests failed"; exit 1; }
  pytest -q tests/playtest/smoke/   || { echo "Smoke tests failed"; exit 1; }
  python tools/ci/perf_check.py    || { echo "Performance regression"; exit 1; }
fi

echo "=== All gates passed ==="
exit 0

Summary

Setting up automated validation hooks for git commits and pushes in Claude-Code-Game-Studios involves three Bash-based scripts that enforce design consistency, code quality, and build integrity:

• pre-commit-design-check validates GDD sections and JSON syntax in design/ and assets/data/ directories
• pre-commit-code-quality detects anti-patterns in src/ and optionally runs linters or unit tests
• pre-push-test-gate executes build verification and conditional integration, smoke, and performance tests for develop and main branches

Install these hooks by copying the scripts from .claude/docs/hooks-reference/ to .git/hooks/ and making them executable, or use the pre-commit framework for version-controlled automation.

Frequently Asked Questions

How do I bypass the pre-commit hooks in an emergency?

You can bypass the commit-time hooks using git commit --no-verify or the shorter git commit -n. However, the pre-push-test-gate in Claude-Code-Game-Studios runs critical build and test validation that should not be skipped for develop or main branches. If you must bypass, ensure you run the tests manually before opening a pull request.

Can I customize the build command in the pre-push hook?

Yes. The pre-push-test-gate script uses a generic make build command by default, but you can adapt this to your specific toolchain. Edit the build line in .claude/docs/hooks-reference/pre-push-test-gate.md to use dotnet build, cargo build, npm run build, or any other build command before copying the hook to .git/hooks/.

Why does the design check hook require specific GDD sections?

The pre-commit-design-check enforces the "Overview", "Detailed", "Edge Cases", "Dependencies", and "Acceptance Criteria" sections to ensure game design documents follow the standardized format defined in the Claude-Code-Game-Studios architecture. This consistency allows automated agents and team members to parse design intent reliably and prevents incomplete specifications from entering the repository.

How do I add the hooks to a team member's repository automatically?

To ensure every team member has the hooks installed, use the pre-commit framework rather than manual copying. Create a .pre-commit-config.yaml file in the repository root that points to the hook scripts in .claude/docs/hooks-reference/. Team members install the hooks by running pre-commit install after cloning. This keeps hook definitions version-controlled and automatically updates them when the repository changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}