# project-hook-setup

> Use when setting up project-specific hooks for Claude Code enforcement. Load during INIT state when .claude/hooks/ is missing, or when creating new project. Installs 5 hooks that read from .claude/config/project.json (tests, health, dependencies).

- Author: ingpoc
- Repository: ingpoc/agent-harness
- Version: 20251230153013
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/ingpoc/agent-harness
- Web: https://mule.run/skillshub/@@ingpoc/agent-harness~project-hook-setup:20251230153013

---

---
name: project-hook-setup
description: "Use when setting up project-specific hooks for Claude Code enforcement. Load during INIT state when .claude/hooks/ is missing, or when creating new project. Installs 5 hooks that read from .claude/config/project.json (tests, health, dependencies)."
keywords: hooks, project, setup, enforcement, testing, health-check, dependencies
---

# Project Hook Setup

Per-project setup for Claude Code hooks. These hooks read from `.claude/config/project.json` for project-specific settings.

## Purpose

Installs 5 project-specific hooks that enforce:
- Test verification before marking tested
- File existence before marking complete
- Health checks for API projects
- Dependency validation
- Session entry protocol

## When to Use

| Situation | Action |
|-----------|--------|
| New project | Run during INIT |
| .claude/hooks/ missing | Run setup |
| Project config changed | Re-run setup |
| Adding dependencies | Update config, re-run |

## Quick Check

```bash
# Check if project hooks exist
ls .claude/hooks/

# Check if config exists
cat .claude/config/project.json
```

## Interactive Config

Setup prompts for project configuration:

| Setting | Description | Example |
|---------|-------------|---------|
| Project type | Framework used | `fastapi`, `django`, `node` |
| Dev server port | Local development port | `8000` |
| Health check | Command to verify server | `curl -sf http://localhost:8000/health` |
| Test command | How to run tests | `pytest` |
| Required env | Environment variables needed | `DATABASE_URL`, `API_KEY` |
| Required services | Services to be running | `redis://localhost:6379` |

## Setup Steps

### 1. Install Hooks

```bash
.skills/project-hook-setup/scripts/setup-project-hooks.sh
```

This:
- Prompts for project config
- Creates `.claude/config/project.json`
- Copies 5 hook templates to `.claude/hooks/`
- Sets executable permissions

### 2. Verify Installation

```bash
.skills/project-hook-setup/scripts/verify-project-hooks.sh
```

## Hooks Installed

| Hook | Purpose | Reads From |
|------|---------|------------|
| `verify-tests.py` | Run tests before tested | project.json → test_command |
| `verify-files-exist.py` | Check files before complete | feature-list.json |
| `verify-health.py` | Check server health | project.json → health_check |
| `require-dependencies.py` | Validate env, services | project.json |
| `session-entry.sh` | Session entry protocol | project.json |

## Exit Criteria (Code Verified)

```bash
# Config exists with required fields
[ -f ".claude/config/project.json" ]
jq -e '.project_type' .claude/config/project.json >/dev/null
jq -e '.health_check' .claude/config/project.json >/dev/null
jq -e '.test_command' .claude/config/project.json >/dev/null

# Hooks exist and executable
[ -d ".claude/hooks" ]
[ -x ".claude/hooks/verify-tests.py" ]
[ -x ".claude/hooks/verify-files-exist.py" ]
[ -x ".claude/hooks/verify-health.py" ]
[ -x ".claude/hooks/require-dependencies.py" ]
[ -x ".claude/hooks/session-entry.sh" ]

# Verify script passes
.skills/project-hook-setup/scripts/verify-project-hooks.sh
```

## Scripts

| Script | Purpose |
|--------|---------|
| `setup-project-hooks.sh` | Main setup (config + hooks) |
| `prompt-project-config.sh` | Interactive config creation |
| `verify-project-hooks.sh` | Verify all installed |
| `install-hooks.sh` | Copy templates to .claude/hooks/ |

## Project Config Schema

`.claude/config/project.json`:

```json
{
  "project_type": "fastapi|django|node|python|other",
  "dev_server_port": 8000,
  "health_check": "curl -sf http://localhost:8000/health",
  "test_command": "pytest",
  "required_env": ["DATABASE_URL", "API_KEY"],
  "required_services": ["redis://localhost:6379"]
}
```

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Config missing | Run `setup-project-hooks.sh` to create |
| Hook can't read config | Check JSON syntax, verify required fields |
| Tests not found | Update test_command in project.json |
| Health check fails | Server not running or wrong port |
| Permission denied | Run: `chmod +x .claude/hooks/*` |

## Integration

This skill is called by the `initializer` skill during INIT state:

```markdown
5. Setup hooks:
   - Check: ~/.claude/hooks/verify-state-transition.py exists (global)
   - Check: .claude/hooks/verify-tests.py exists (project)
   - If missing, load respective setup skill
```

## Next Steps

After project hooks: Continue with feature breakdown and implementation.