Agent skill

setting-up-git-hooks

Configures git hooks for automated testing, linting, and quality enforcement. Use when initializing projects, establishing quality gates, or preventing commit/push errors.

View SKILL.md on GitHub Repository
Stars 3
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/bacchus-labs/wrangler/tree/main/skills/setting-up-git-hooks

SKILL.md

Setup Git Hooks

Purpose

This skill sets up Git hooks to automatically enforce testing and code quality standards before commits and pushes. It supports two installation patterns:

  • Pattern A (Default): Hooks installed directly to .git/hooks/ with configuration in .wrangler/config/hooks-config.json
  • Pattern B: Version-controlled hooks in .wrangler/config/git-hooks/ with install script for team synchronization

When to Use

  • Setting up a new project with test enforcement
  • Adding hooks to an existing project
  • Migrating from other hook managers (Husky, pre-commit)
  • Configuring CI-like checks locally

Setup Workflow

Phase 1: Environment Verification

Step 1: Verify Git Repository

bash
# Check if we're in a git repository
git rev-parse --show-toplevel

# Check existing hooks
ls -la .git/hooks/ 2>/dev/null | head -10

# Check for existing wrangler hooks config
[ -f .wrangler/config/hooks-config.json ] && echo "Existing config found" || echo "No existing config"

If not in a git repository, inform user and exit.

Step 2: Check for Existing Hook Managers

bash
# Check for Husky
[ -d .husky ] && echo "Husky detected" || true
[ -f package.json ] && grep -q '"husky"' package.json && echo "Husky in package.json" || true

# Check for pre-commit framework
[ -f .pre-commit-config.yaml ] && echo "pre-commit framework detected" || true

# Check for existing custom hooks
for hook in pre-commit pre-push commit-msg; do
    [ -f .git/hooks/$hook ] && echo "Existing $hook hook found" || true
done

If existing hook manager found, ask user how to proceed:

  • Migrate from existing (backup and replace)
  • Skip setup (user will handle manually)
  • Continue anyway (may conflict)

Phase 2: Project Detection

Special Case: Empty Project or No Tests Detected

If the skill detects an empty project or no test framework:

Detection criteria:

  • No package.json, pyproject.toml, go.mod, Cargo.toml, etc.
  • No test files found (.test., _test., tests/ directory)
  • No test scripts in package.json

Graceful handling:

  1. Populate TESTING.md with placeholder content:

    TESTING.md should already exist from governance initialization. Update status section:

    markdown
    **Status:** No tests configured yet

    If TESTING.md doesn't exist, create it from initializing-governance template first.

  2. Create stub hooks-config.json:

    json
    {
  "version": "1.0.0",
  "createdAt": "2026-01-21T...",
  "testCommand": "",
  "note": "No tests detected. Run /wrangler:updating-git-hooks after adding tests.",
  "protectedBranches": ["main", "master", "feature/*", "fix/*"],
  "skipDocsOnlyChanges": true,
  "docsPatterns": ["*.md", "docs/**/*", ".wrangler/memos/**/*"],
  "bypassEnvVar": "WRANGLER_SKIP_HOOKS",
  "setupComplete": false
}

    Note: File should be created at .wrangler/config/hooks-config.json

  3. Install bypass-only hooks:

    • Hooks check setupComplete flag in config
    • If false, log message and exit 0 (allow all commits/pushes)
    • If true, run normal test enforcement

  4. Inform user:

    Git hooks installed (inactive - no tests detected)

Hooks are installed but will not enforce testing until you:
1. Add tests to your project
2. Run: /wrangler:updating-git-hooks

Created:
- .wrangler/TESTING.md (placeholder)
- .wrangler/config/hooks-config.json (stub configuration)
- .git/hooks/pre-commit (bypass mode)
- .git/hooks/pre-push (bypass mode)

Why this works:

  • No broken setup (hooks exist but don't fail)
  • Clear messaging about what to do next
  • Easy to activate later
  • TESTING.md always exists (no orphaned references)

Step 3: Detect Project Type

Use Bash to identify project language/framework:

bash
# JavaScript/TypeScript
[ -f package.json ] && echo "javascript"

# Python
[ -f setup.py ] || [ -f pyproject.toml ] || [ -f requirements.txt ] && echo "python"

# Go
[ -f go.mod ] && echo "go"

# Rust
[ -f Cargo.toml ] && echo "rust"

# Java
[ -f pom.xml ] || [ -f build.gradle ] && echo "java"

Step 4: Detect Existing Test/Format/Lint Commands

For JavaScript projects:

bash
# Read package.json scripts
cat package.json | grep -E '"(test|lint|format)"' || true

For Python projects:

bash
# Check for common test runners
[ -f pytest.ini ] || [ -f pyproject.toml ] && grep -q pytest pyproject.toml && echo "pytest"
[ -f setup.cfg ] && grep -q flake8 setup.cfg && echo "flake8"

For Go projects:

bash
# Go has standard commands
echo "go test ./..."
echo "go fmt ./..."

Phase 3: Interactive Configuration

Step 5: Ask User for Configuration

Use multiple AskUserQuestion calls to gather configuration:

Question 1: Installation Pattern

typescript
AskUserQuestion({
  questions: [{
    question: "Which hook installation pattern would you prefer?",
    header: "Installation Pattern",
    options: [
      {
        label: "Pattern A: Direct installation (Recommended)",
        description: "Hooks in .git/hooks/, config in .wrangler/config/hooks-config.json"
      },
      {
        label: "Pattern B: Version-controlled",
        description: "Hooks in .wrangler/config/git-hooks/, install script for team sync"
      }
    ],
    multiSelect: false
  }]
})

Question 2: Test Command

typescript
// Show detected commands as suggestions
AskUserQuestion({
  questions: [{
    question: "What command runs your full test suite?",
    header: "Test Command",
    options: [
      { label: "[detected command]", description: "Detected from project files" },
      { label: "Custom command", description: "I'll specify my own" }
    ],
    multiSelect: false
  }]
})

If "Custom command" selected, ask user to type the command.

Question 3: Unit Test Command (Optional)

typescript
AskUserQuestion({
  questions: [{
    question: "Do you have a separate command for fast unit tests? (for pre-commit)",
    header: "Unit Tests",
    options: [
      { label: "Same as full tests", description: "Use full test command" },
      { label: "[suggested fast command]", description: "Faster subset of tests" },
      { label: "Custom command", description: "I'll specify my own" },
      { label: "Skip unit tests", description: "Don't run tests in pre-commit" }
    ],
    multiSelect: false
  }]
})

Question 4: Format Command (Optional)

typescript
AskUserQuestion({
  questions: [{
    question: "What command formats your code? (auto-fix and re-stage)",
    header: "Formatter",
    options: [
      { label: "[detected command]", description: "Detected from project files" },
      { label: "Custom command", description: "I'll specify my own" },
      { label: "Skip formatting", description: "Don't auto-format in pre-commit" }
    ],
    multiSelect: false
  }]
})

Question 5: Lint Command (Optional)

typescript
AskUserQuestion({
  questions: [{
    question: "What command lints your code?",
    header: "Linter",
    options: [
      { label: "[detected command]", description: "Detected from project files" },
      { label: "Custom command", description: "I'll specify my own" },
      { label: "Skip linting", description: "Don't lint in pre-commit" }
    ],
    multiSelect: false
  }]
})

Question 6: Protected Branches

typescript
AskUserQuestion({
  questions: [{
    question: "Which branches should require full tests before push?",
    header: "Protected Branches",
    options: [
      { label: "Default (main, master, develop, release/*, hotfix/*)", description: "Standard Git Flow branches" },
      { label: "Just main/master", description: "Only primary branches" },
      { label: "Custom patterns", description: "I'll specify my own" }
    ],
    multiSelect: false
  }]
})

Question 7: Commit Message Validation (Optional)

typescript
AskUserQuestion({
  questions: [{
    question: "Enable commit message format validation?",
    header: "Commit Messages",
    options: [
      { label: "Yes - Conventional Commits", description: "feat:, fix:, docs:, etc." },
      { label: "No", description: "Allow any commit message format" }
    ],
    multiSelect: false
  }]
})

Phase 4: Configuration Generation

Step 6: Generate hooks-config.json

Create the configuration file with user's answers:

bash
mkdir -p .wrangler/config

Use Write tool to create .wrangler/config/hooks-config.json:

json
{
  "$schema": "https://wrangler.dev/schemas/hooks-config.json",
  "version": "1.0.0",
  "createdAt": "[ISO timestamp]",
  "projectType": "[detected type]",
  "testCommand": "[user's test command]",
  "unitTestCommand": "[user's unit test command or null]",
  "formatCommand": "[user's format command or null]",
  "lintCommand": "[user's lint command or null]",
  "protectedBranches": ["main", "master", "develop", "release/*", "hotfix/*"],
  "skipDocsOnlyChanges": true,
  "docsPatterns": ["*.md", "*.txt", "*.rst", "docs/*", "README*", "LICENSE*", "CHANGELOG*"],
  "enableCommitMsgValidation": [true/false],
  "bypassEnvVar": "WRANGLER_SKIP_HOOKS",
  "pattern": "[A or B]"
}

Phase 5: Hook Installation

Step 7: Install Hooks (Pattern A)

If Pattern A selected:

bash
# Backup existing hooks
if [ -f .git/hooks/pre-commit ] || [ -f .git/hooks/pre-push ]; then
    mkdir -p .git/hooks.backup
    cp .git/hooks/pre-commit .git/hooks.backup/ 2>/dev/null || true
    cp .git/hooks/pre-push .git/hooks.backup/ 2>/dev/null || true
    cp .git/hooks/commit-msg .git/hooks.backup/ 2>/dev/null || true
    echo "Existing hooks backed up to .git/hooks.backup/"
fi

Use Read tool to read template files from wrangler skills directory:

  • skills/setting-up-git-hooks/templates/pre-commit.template.sh
  • skills/setting-up-git-hooks/templates/pre-push.template.sh
  • skills/setting-up-git-hooks/templates/commit-msg.template.sh (if enabled)

Use string replacement to substitute placeholders:

  • {{TEST_COMMAND}} -> user's test command
  • {{UNIT_TEST_COMMAND}} -> user's unit test command
  • {{FORMAT_COMMAND}} -> user's format command
  • {{LINT_COMMAND}} -> user's lint command
  • {{PROTECTED_BRANCHES}} -> user's protected branches
  • {{DOCS_PATTERNS}} -> docs patterns

Use Write tool to save hooks to .git/hooks/:

  • .git/hooks/pre-commit
  • .git/hooks/pre-push
  • .git/hooks/commit-msg (if enabled)

Make hooks executable:

bash
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push
[ -f .git/hooks/commit-msg ] && chmod +x .git/hooks/commit-msg

Step 8: Install Hooks (Pattern B)

If Pattern B selected:

bash
# Create version-controlled hooks directory
mkdir -p .wrangler/config/git-hooks

Use Write tool to save hooks to .wrangler/config/git-hooks/:

  • .wrangler/config/git-hooks/pre-commit
  • .wrangler/config/git-hooks/pre-push
  • .wrangler/config/git-hooks/commit-msg (if enabled)

Use Write tool to create install script at scripts/install-hooks.sh: (Copy from skills/setting-up-git-hooks/templates/install-hooks.sh)

Make files executable:

bash
chmod +x .wrangler/config/git-hooks/pre-commit
chmod +x .wrangler/config/git-hooks/pre-push
[ -f .wrangler/config/git-hooks/commit-msg ] && chmod +x .wrangler/config/git-hooks/commit-msg
chmod +x scripts/install-hooks.sh

Run install script:

bash
./scripts/install-hooks.sh

Phase 6: Documentation Installation

Step 9: Install PR Template

Create PR template in user's project:

bash
mkdir -p .github

Create PR template (git hooks specific):

  • .github/pull_request_template.md (copy from skills/setting-up-git-hooks/templates/pull_request_template.md)

Note on other templates: Security checklist and Definition of Done templates remain in their skill directories:

  • Security checklist: skills/initializing-governance/templates/SECURITY_CHECKLIST.md
  • Definition of Done: skills/initializing-governance/templates/DEFINITION_OF_DONE.md

These are referenced directly from skills, not copied to project directories.

Step 10: Populate TESTING.md

TESTING.md is created by initializing-governance skill. This step populates it with git hooks configuration.

If .wrangler/TESTING.md doesn't exist (governance not initialized), create it from initializing-governance template with user's configuration:

bash
# Copy template from initializing-governance
cp skills/initializing-governance/templates/TESTING.md .wrangler/TESTING.md

Then populate all placeholders with detected/configured values.

Phase 7: Verification and Summary

Step 11: Verify Installation

bash
# Verify hooks are installed and executable
echo "=== Hook Installation Verification ==="
for hook in pre-commit pre-push commit-msg; do
    if [ -f .git/hooks/$hook ]; then
        if [ -x .git/hooks/$hook ]; then
            echo "[OK] $hook installed and executable"
        else
            echo "[WARN] $hook installed but not executable"
        fi
    else
        echo "[SKIP] $hook not installed"
    fi
done

# Verify config file

## References

For detailed information, see:

- `references/detailed-guide.md` - Complete workflow details, examples, and troubleshooting

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

bacchus-labs/wrangler

locating-code

Finds specific code elements (functions, classes, patterns) using multiple search strategies. Use when searching for implementations, dependencies, or code requiring modification.

3 1
Explore
bacchus-labs/wrangler

using-wrangler

Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Skill tool before announcing usage, following brainstorming before coding, and creating TodoWrite todos for checklists

3 1
Explore
bacchus-labs/wrangler

creating-issues

For use when a new issue/task has been identified and needs to be formally captured using the Wrangler MCP issue management system. Use this skill to create new issues via the issues_create MCP tool with appropriate metadata and structured content.

3 1
Explore
bacchus-labs/wrangler

validating-roadmaps

Validates roadmap completeness, phase coherence, and alignment with constitution. Use when creating roadmaps, reviewing planning documents, or ensuring strategic consistency.

3 1
Explore
bacchus-labs/wrangler

refreshing-metrics

Auto-updates status metrics across governance documents from MCP issue counts. Use when governance metrics are stale or after significant issue status changes requiring documentation refresh.

3 1
Explore
bacchus-labs/wrangler

updating-git-hooks

Updates existing git hook configurations for new requirements or tool changes. Use when hook requirements change, adding new quality checks, or modifying test commands.

3 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results