# new-hook

> Scaffold a new hook registration. Keywords: hook, event, scaffolding.

- Author: willyu1007
- Repository: willyu1007/AI_First_Template
- Version: 20251224182030
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/willyu1007/AI_First_Template
- Web: https://mule.run/skillshub/@@willyu1007/AI_First_Template~new-hook:20251224182030

---

---
name: new-hook
description: "Scaffold a new hook registration. Keywords: hook, event, scaffolding."
---
# Scaffold: New Hook Registration

This document is an entrypoint for hook scaffolding. The step-by-step flow is in
/.system/skills/ssot/repo/scaffolding/new-hook/SKILL.md.

---

## 1. Purpose & Scope

**Purpose**: Register a new hook that responds to lifecycle events (PromptSubmit, PreAbilityCreate, PreAbilityCall, PostAbilityCall, SessionStop).

**Scope**:
- Creates hook registration in `/.system/hooks/`
- Validates handler references
- Optionally creates handler implementation placeholder

**Out of scope**:
- Implementing the actual handler logic
- Modifying existing hooks
- Runtime hook execution (handled by Hook Runner)

---

## 2. Inputs & Preconditions

### Required Inputs

| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | string | Unique hook identifier (e.g., `ability_usage_tracker`) |
| `event_type` | enum | Lifecycle event: `PromptSubmit`, `PreAbilityCreate`, `PreAbilityCall`, `PostAbilityCall`, `SessionStop` |
| `enabled` | boolean | Whether hook is active |
| `blocking` | boolean | Whether hook blocks execution |
| `handler.kind` | enum | Handler type: `script`, `function` |
| `handler.command` | string | Handler command or function reference |

### Optional Inputs

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `summary` | string | "" | One-line description of what this hook does (max 200 chars) |
| `match` | object | {} | Selective execution conditions (ability_pattern, scope_pattern) |
| `order` | integer | 100 | Execution order (lower = earlier) |

### Preconditions

1. Phase 4 registry tooling is available (`scripts/devops/registry/hooks.py`)
2. `id` does not already exist in hook registry
3. Handler reference is valid or will be created
4. Hook file naming matches `id` (`<id>.yaml`)

---

## 3. Step-by-Step Flow (AI + Human)

See /.system/skills/ssot/repo/scaffolding/new-hook/SKILL.md.

---

## 4. Tools & Scripts

| Tool | Purpose |
|------|---------|
| `scripts/devops/scaffold/new_hook.py` | Orchestrator script |
| `scripts/devops/registry/hooks.py` | Hook validation |

---

## 5. Outputs & Side Effects

### Files Created

```
/.system/hooks/<id>.yaml                    # Hook registration
/.system/hooks/implementations/<id>.py      # Handler placeholder (optional)
```

### Hook Registration Structure

```yaml
id: ability_usage_tracker
event_type: PostAbilityCall
enabled: true
blocking: false
handler:
  kind: script
  command: scripts/hooks/<hook_id>.py
summary: Track ability usage for analytics
order: 100
match:
  ability_pattern: ".*"
```

---

## 6. Safety & Rollback

### Safety Measures

- `--dry-run` always available for preview
- Human approval required before execution
- Schema validation on hook registration
- Consistency checks via `hooks.py --check`

### Rollback Procedure

If registration fails or needs reverting:

1. Delete the hook file:
   ```bash
   rm /.system/hooks/<id>.yaml
   ```
2. Optionally delete the handler placeholder:
   ```bash
   rm /.system/hooks/implementations/<id>.py
   ```
3. Verify with:
   ```bash
   python scripts/devops/registry/hooks.py --check
   ```

---

## 7. Event Type Reference

| Event Type | When Triggered | Typical Use |
|------------|----------------|-------------|
| `PromptSubmit` | User submits prompt | Routing hints, intent normalization |
| `PreAbilityCreate` | Before task.create | Preflight validation, policy checks |
| `PreAbilityCall` | Before task.run | Guardrails, approval gates |
| `PostAbilityCall` | After task execution | Logging, analytics, cleanup |
| `SessionStop` | Session ends | Summary generation, state persistence |

---

## 8. Related Documents

- `/.system/skills/ssot/repo/architecture-core-mechanisms/hook-lifecycle/SKILL.md` - Hook lifecycle workflow
- `/.system/hooks/AGENTS.md` - Hook infrastructure strategy
- `/.system/registry/schemas/hook.schema.yaml` - Hook schema
- `/.system/registry/schemas/V1_CORE.md` - V1-core required fields