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

> Set up automated Git validation hooks for commits and pushes in Claude-Code-Game-Studios. This system validates design documents, enforces code quality, and runs tests before merging.

- Repository: [Donchitos/Claude-Code-Game-Studios](https://github.com/Donchitos/Claude-Code-Game-Studios)
- Tags: how-to-guide
- Published: 2026-04-16

---

**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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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:

```bash

# 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:

```bash
#!/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.pre-commit-config.yaml) in your repository root:

```yaml
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:

```bash
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:

```bash
#!/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:

```bash
#!/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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.