Global Hook Setup Skill

Global Hook Setup

One-time setup for global Claude Code hooks. These hooks work across all projects.

Purpose

Installs 8 project-agnostic hooks that enforce DESIGN-v2 determinism:

State machine integrity
Git hygiene
Learning layer (outcome tracking)
Session checkpoints

When to Use

| Situation | Action | | --------- | ------ | | First time setup | Run full setup | | ~/.claude/hooks/ missing | Run full setup | | After updating hooks | Re-run setup | | Manual verification | Run verify script |

Quick Check

# Check if global hooks exist
ls ~/.claude/hooks/

Expected output:

verify-state-transition.py
require-commit-before-tested.py
require-outcome-update.py
link-feature-to-trace.py
markdownlint-fix.sh
remind-decision-trace.sh
session-end.sh
feature-commit.sh

Setup Steps

1. Install Hooks

~/.claude/skills/global-hook-setup/scripts/setup-global-hooks.sh

This creates:

~/.claude/hooks/ directory
8 hook files
Executable permissions (chmod +x)

2. Verify Installation

~/.claude/skills/global-hook-setup/scripts/verify-global-hooks.sh

Hooks Installed

| Hook | Event | Purpose | Blocks? | | ---- | ----- | ------- | ------- | | verify-state-transition.py | PreToolUse | Valid state transitions only | Yes | | require-commit-before-tested.py | PreToolUse | Git clean before tested | Yes | | require-outcome-update.py | PreToolUse | Update trace outcome | Yes | | link-feature-to-trace.py | PostToolUse | Auto-link features | No | | markdownlint-fix.sh | PostToolUse | Auto-fix .md linting | No | | remind-decision-trace.sh | SessionEnd | Remind to log decisions | No | | session-end.sh | SessionEnd | Checkpoint commit | No | | feature-commit.sh | CLI utility | Feature commit helper | N/A |

Note: feature-commit.sh is a CLI utility (not a hook). Use: ~/.claude/hooks/feature-commit.sh <feature-id> [message]

Settings.json Configuration

Setup script configures ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "python3 ~/.claude/hooks/verify-state-transition.py"},
          {"type": "command", "command": "python3 ~/.claude/hooks/require-commit-before-tested.py"},
          {"type": "command", "command": "python3 ~/.claude/hooks/require-outcome-update.py"}
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "python3 ~/.claude/hooks/link-feature-to-trace.py"},
          {"type": "command", "command": "/bin/bash ~/.claude/hooks/markdownlint-fix.sh"}
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {"type": "command", "command": "/bin/bash ~/.claude/hooks/session-end.sh"},
          {"type": "command", "command": "/bin/bash ~/.claude/hooks/remind-decision-trace.sh"}
        ]
      }
    ]
  }
}

Exit Criteria (Code Verified)

# Directory exists
[ -d ~/.claude/hooks ]

# All hooks exist and executable
[ -x ~/.claude/hooks/verify-state-transition.py ]
[ -x ~/.claude/hooks/require-commit-before-tested.py ]
[ -x ~/.claude/hooks/require-outcome-update.py ]
[ -x ~/.claude/hooks/link-feature-to-trace.py ]
[ -x ~/.claude/hooks/markdownlint-fix.sh ]
[ -x ~/.claude/hooks/remind-decision-trace.sh ]
[ -x ~/.claude/hooks/session-end.sh ]
[ -x ~/.claude/hooks/feature-commit.sh ]

# Verify script passes
~/.claude/skills/global-hook-setup/scripts/verify-global-hooks.sh

Scripts

| Script | Purpose | | ------ | ------- | | setup-global-hooks.sh | Main setup (install + configure + validate) | | configure-settings.py | Configure settings.json with hook entries | | validate-settings.py | Validate hooks configured in settings.json | | verify-global-hooks.sh | Verify hook files exist | | install-hooks.sh | Copy from templates |

Troubleshooting

| Problem | Solution | | ------- | -------- | | Hooks not found | Re-run setup script | | Permission denied | Run: chmod +x ~/.claude/hooks/* | | Verification fails | Check hook syntax, ensure python3 available | | Already exists | Setup is idempotent, safe to re-run |

Next Steps

After global hooks: Set up project-specific hooks with project-hook-setup skill.

Agent Skills: Global Hook Setup

Skill Files