---
description: Create a SmartStack hook extension project
argument-hint: <name> [trigger] [description]
---

# Create Hook Extension

Scaffold a complete SmartStack **hook** extension project.

## What is a Hook?

A hook is a validation/action trigger:
- Runs automatically at specific points (pre-commit, pre-merge, etc.)
- Can block operations if issues detected
- Defined in markdown with detection patterns
- Integrates with GitFlow workflow

## Arguments

Parse from `$ARGUMENTS`:
- **name** (required): Hook name in kebab-case
- **trigger** (optional): pre-commit | pre-merge | pre-push | post-commit
- **description** (optional): What the hook validates

## Project Structure

```
smartstack-{name}/
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── README.md
├── .gitignore
├── src/
│   └── index.ts
└── templates/
    └── hooks/
        └── {name}.md          # Hook template
```

## Generated Hook Template

```markdown
---
description: {description}
trigger: {trigger}
blocking: true
---

# {PascalCaseName} Hook

{description}

## Purpose

This hook validates [what it validates] before allowing [the action].

## Trigger Points

| Trigger | When | Blocking |
|---------|------|----------|
| pre-commit | Before git commit | Yes |
| pre-merge | Before branch merge | Yes |
| pre-push | Before git push | Yes |
| post-commit | After git commit | No |

Current trigger: **{trigger}**

## Detection Patterns

### BLOCKING Patterns

These patterns will **prevent** the operation:

| Pattern | File Types | Risk Level | Reason |
|---------|-----------|------------|--------|
| `PATTERN_ONE` | *.ts, *.js | Critical | Description |
| `PATTERN_TWO` | *.sql | High | Description |
| `PATTERN_THREE` | * | Medium | Description |

### WARNING Patterns

These patterns will **warn** but allow:

| Pattern | File Types | Reason |
|---------|-----------|--------|
| `WARN_PATTERN` | *.ts | Description |

## Detection Script

```bash
#!/bin/bash
# {PascalCaseName} Hook
# {description}

set -e

echo "🔍 Running {name} check..."

# Configuration
BLOCKING_PATTERNS=(
  "PATTERN_ONE"
  "PATTERN_TWO"
)

WARNING_PATTERNS=(
  "WARN_PATTERN"
)

FILE_TYPES="*.ts *.js *.tsx *.jsx"

FOUND_BLOCKING=0
FOUND_WARNING=0

# Check blocking patterns
for pattern in "${BLOCKING_PATTERNS[@]}"; do
  if grep -rn "$pattern" --include="$FILE_TYPES" . 2>/dev/null; then
    echo "❌ BLOCKING: Found '$pattern'"
    FOUND_BLOCKING=$((FOUND_BLOCKING + 1))
  fi
done

# Check warning patterns
for pattern in "${WARNING_PATTERNS[@]}"; do
  if grep -rn "$pattern" --include="$FILE_TYPES" . 2>/dev/null; then
    echo "⚠️  WARNING: Found '$pattern'"
    FOUND_WARNING=$((FOUND_WARNING + 1))
  fi
done

# Results
if [ $FOUND_BLOCKING -gt 0 ]; then
  echo ""
  echo "╔═══════════════════════════════════════════╗"
  echo "║  ❌ HOOK BLOCKED: $FOUND_BLOCKING issues found  ║"
  echo "╚═══════════════════════════════════════════╝"
  echo ""
  echo "Fix the issues above or bypass with:"
  echo "  SKIP_{NAME_UPPER}_HOOK=1 git commit -m 'message'"
  exit 1
fi

if [ $FOUND_WARNING -gt 0 ]; then
  echo ""
  echo "⚠️  $FOUND_WARNING warnings found (non-blocking)"
fi

echo "✅ Hook PASSED"
exit 0
```

## Integration

### With GitFlow

In `/gitflow:3-commit`, this hook runs automatically:

1. User initiates commit
2. Hook executes detection script
3. If blocking patterns found → commit rejected
4. User must fix or explicitly bypass

### Manual Execution

```bash
# Run hook manually
./.claude/hooks/{name}.sh

# Check specific files
./.claude/hooks/{name}.sh src/specific-file.ts
```

## Bypass (Emergency Only)

```bash
# Use with extreme caution!
SKIP_{NAME_UPPER}_HOOK=1 git commit -m "message"

# Or in environment
export SKIP_{NAME_UPPER}_HOOK=1
```

**WARNING**: Bypassing should be documented and justified.

## Logging

All detections logged to:
`~/.claude/gitflow/logs/{name}.json`

```json
{
  "timestamp": "2024-01-15T10:30:00Z",
  "hook": "{name}",
  "trigger": "{trigger}",
  "result": "blocked|passed|warning",
  "blocking_issues": [],
  "warnings": [],
  "branch": "feature/xxx",
  "user": "username"
}
```

## Customization

Edit patterns in the hook file:
- Add new blocking patterns
- Adjust file type filters
- Customize error messages

## Priority

Security > Correctness > Speed
```

## Trigger Options

| Trigger | Use Case |
|---------|----------|
| `pre-commit` | Validate before local commit |
| `pre-merge` | Validate before branch merge |
| `pre-push` | Validate before pushing to remote |
| `post-commit` | Log/notify after commit |

## Workflow

1. Parse arguments (name, trigger, description)
2. Validate name format
3. Create project directory
4. Generate hook template with proper trigger
5. Display success message

---

User: $ARGUMENTS
