claudetools/.claude/HOOKS.md

# Git Hooks Configuration

## Overview

Git hooks automatically send notifications to the `dev-alerts` coordination channel when feature specifications are created or significant commits are made to main branches.

## Installed Hooks

### post-commit (Main Repo)

**Location:** `.git/hooks/post-commit`

**Triggers:**
- **Feature Spec Creation:** When a commit includes new `docs/specs/SPEC-NNN-*.md` files
- **Build Events:** When commits with conventional commit prefixes (`spec:`, `feat:`, `fix:`, `build:`) are made to `main` branch

**Actions:**
- Extracts SPEC number, priority, effort, and overview from spec file
- Sends coordination message to `dev-alerts` channel
- Includes commit hash, author, branch, and affected files

**Message Format (Feature Spec):**
```
Subject: [ProjectName] Feature Spec: SPEC-NNN [Feature Name]
Body:
  - SPEC number and name
  - Priority and effort estimate
  - Overview excerpt
  - Commit hash and author
  - Link to spec file
```

**Message Format (Build Event):**
```
Subject: [ProjectName] Build: [commit type] on main
Body:
  - Commit hash and type
  - Files changed count
  - Branch and author
  - Full commit message
```

### post-commit (GuruConnect Submodule)

**Location:** `.git/modules/projects/msp-tools/guru-connect/hooks/post-commit`

**Triggers:** Same as main repo
**Project Key:** `guruconnect`
**Project Name:** GuruConnect

### post-commit (GuruRMM Submodule)

**Location:** `.git/modules/projects/msp-tools/guru-rmm/hooks/post-commit`

**Status:** To be created when submodule is initialized
**Project Key:** `gururmm`
**Project Name:** GuruRMM

## Setup

### Install Hooks Manually

```bash
# Main repo
cp .claude/hooks/post-commit.template .git/hooks/post-commit
chmod +x .git/hooks/post-commit

# GuruConnect submodule
cp .claude/hooks/post-commit.template .git/modules/projects/msp-tools/guru-connect/hooks/post-commit
chmod +x .git/modules/projects/msp-tools/guru-connect/hooks/post-commit

# GuruRMM submodule (when initialized)
cp .claude/hooks/post-commit.template .git/modules/projects/msp-tools/guru-rmm/hooks/post-commit
chmod +x .git/modules/projects/msp-tools/guru-rmm/hooks/post-commit
```

### Verify Hook Installation

```bash
# Check if hook exists and is executable
ls -l .git/hooks/post-commit
ls -l .git/modules/projects/msp-tools/guru-connect/hooks/post-commit

# Test manually (run from repo root after a commit)
.git/hooks/post-commit
```

## Coordination API Integration

Hooks send messages to the coordination API at `http://172.16.3.30:8001/api/coord/messages` with:

- **from_session:** `$(hostname)/claude-main`
- **to_session:** `dev-alerts`
- **project_key:** `guruconnect`, `gururmm`, or `claudetools`
- **subject:** Auto-generated based on event type
- **body:** Formatted notification with commit details

## Message Recipients

Messages sent to `dev-alerts` can be queried by any session:

```bash
# Check unread dev-alerts messages
curl -s "http://172.16.3.30:8001/api/coord/messages?to_session=dev-alerts&unread_only=true"

# Check all dev-alerts messages for a project
curl -s "http://172.16.3.30:8001/api/coord/messages?to_session=dev-alerts&project_key=guruconnect"
```

## Troubleshooting

### Hook Not Firing

1. **Check executable permission:**
   ```bash
   chmod +x .git/hooks/post-commit
   ```

2. **Test manually:**
   ```bash
   .git/hooks/post-commit
   ```

3. **Check coordination API:**
   ```bash
   curl -s http://172.16.3.30:8001/api/coord/status
   ```

### Debug Hook Execution

Temporarily add debug output to hook:

```bash
#!/bin/bash
set -x  # Enable debug mode
# ... rest of hook code ...
```

Then check git output after commit.

## Customization

### Add Custom Event Types

Edit the hook and add new patterns to detect:

```bash
# Example: Detect documentation commits
if echo "$COMMIT_MSG" | grep -qE '^docs:.*API'; then
    # Send custom dev-alerts message
fi
```

### Change Alert Channel

Replace `dev-alerts` with a different channel name:

```bash
curl -s -X POST http://172.16.3.30:8001/api/coord/messages \
  -H "Content-Type: application/json" \
  -d "{
    \"from_session\": \"$SESSION_ID\",
    \"to_session\": \"build-notifications\",  # Changed from dev-alerts
    ...
  }"
```

## Maintenance

### Disable Hooks Temporarily

```bash
# Rename to disable
mv .git/hooks/post-commit .git/hooks/post-commit.disabled

# Re-enable
mv .git/hooks/post-commit.disabled .git/hooks/post-commit
```

### Update All Hooks

When the hook logic changes, update all installations:

```bash
# Update template
vim .claude/hooks/post-commit.template

# Reinstall to all repos
cp .claude/hooks/post-commit.template .git/hooks/post-commit
cp .claude/hooks/post-commit.template .git/modules/projects/msp-tools/guru-connect/hooks/post-commit
cp .claude/hooks/post-commit.template .git/modules/projects/msp-tools/guru-rmm/hooks/post-commit
```

---

**Last Updated:** 2026-05-31