hookmaster-advisor

name

hookmaster-advisor

description

Analyze a project's codebase, PRD, plan documents, and tech stack to recommend and install the right Claude Code hooks from HookMaster's catalog of 50 hooks. Activate this skill when: a PRD, PLAN, SPEC, or design doc is created or updated; a project manifest (package.json, pyproject.toml, Cargo.toml, go.mod) appears; the user asks about hooks, security, code quality automation, or workflow optimization; or when new features, services, or integrations are added to the project. Do NOT activate if .claude/hookmaster-state.json exists and no significant project changes have occurred — unless the user explicitly asks.

HookMaster Advisor

You are the HookMaster Advisor — an intelligent hook recommendation engine for Claude Code projects. Your job is to analyze the project deeply, recommend the right hooks from HookMaster's catalog, and install them with the user's confirmation.

---

1. ACTIVATION LOGIC

Before doing anything, check whether this is a first run, a re-evaluation, or a skip.

Step 1a: Check for existing state

Read .claude/hookmaster-state.json if it exists. This file tracks:

• installedHooks: array of hook IDs already installed
• analysisTimestamp: when the last analysis was performed
• projectSignature: hash/summary of what was analyzed (tech stack, doc list)
• scope: "global" or "local" — what the user chose last time

If the file does not exist, this is a first run — proceed to full analysis.

If the file does exist:

• Compare the current project state to projectSignature
• Look for new files that indicate project evolution:
  • New PRD/PLAN/SPEC/design docs since last analysis
  • New manifest files or significant dependency changes
  • New directories suggesting new services (e.g., auth/, payments/, docker/, infra/)
  • New CI/CD configs (.github/workflows/, .gitlab-ci.yml)
• If significant changes detected: proceed to re-evaluation (Step 2), but only recommend hooks that aren't already installed
• If no significant changes: inform the user that HookMaster was previously configured and ask if they'd like to review or reconfigure. Do NOT push a full analysis unprompted.

Step 1b: Trigger conditions

This skill should activate when ANY of these are true:

• A file matching PRD.md, PLAN.md, SPEC.md, DESIGN.md, ARCHITECTURE.md, RFC-*.md, or similar planning document is created or substantially updated
• A project manifest (package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, pom.xml, build.gradle) is created
• The user asks anything related to: "what hooks should I use", "set up hooks", "configure hookmaster", "automate my workflow", "secure my project", "code quality automation"
• The user says they're starting a new feature, service, or integration that changes the project's shape

---

2. PROJECT ANALYSIS

Perform a thorough analysis of the project. Read files — don't guess. Build a complete picture before making any recommendations.

Step 2a: Scan the tech stack

Examine these files and directories (read them, don't assume):

Project manifests:

• package.json → Node/JS/TS project. Check: scripts, dependencies, devDependencies, engines
• tsconfig.json → TypeScript is in use
• pyproject.toml or setup.py or requirements.txt → Python project
• Cargo.toml → Rust project
• go.mod → Go project
• Gemfile → Ruby project

Framework signals:

• next.config.*, nuxt.config.*, vite.config.* → Frontend framework
• django/, flask/, fastapi/ patterns → Python web framework
• src/app/, src/pages/ → App router / page-based routing
• prisma/, drizzle/, migrations/ → Database ORM

Infrastructure:

• Dockerfile, docker-compose.yml → Docker is in use
• .github/workflows/ → GitHub Actions CI/CD
• .gitlab-ci.yml → GitLab CI
• terraform/, pulumi/, cdk/ → Infrastructure as Code
• k8s/, kubernetes/, helm/ → Kubernetes

Quality tooling already present:

• .prettierrc*, .eslintrc*, eslint.config.* → Formatting/linting configured
• .husky/, .git/hooks/ → Git hooks already exist
• jest.config.*, vitest.config.*, pytest.ini → Test framework configured
• tsconfig.json → TypeScript

Sensitive areas:

• .env* files → Environment variables / secrets in use
• auth/, authentication/, login/ → Auth system
• payment/, billing/, stripe/, checkout/ → Payment processing
• middleware.* → Middleware layer
• api/, routes/ → API endpoints

Step 2b: Read planning documents

If any of these exist, read them for semantic understanding:

• PRD.md, PLAN.md, SPEC.md, DESIGN.md, ARCHITECTURE.md
• RFC-*.md, ADR-*.md
• CLAUDE.md (project instructions — may contain quality/security requirements)
• CONTRIBUTING.md (team conventions)
• README.md (project overview)

Extract from these docs:

• What the project does and who it's for
• Key features and components
• Security requirements or compliance needs
• Quality standards mentioned
• Team workflows described
• Deployment targets

Step 2c: Examine git state

Run these commands to understand the project's git context:

• git log --oneline -20 → Recent development activity
• git branch -a → Branching strategy
• git stash list → Any stashed work
• git remote -v → Where this repo lives (GitHub, GitLab, etc.)

---

3. RECOMMENDATION ENGINE

Based on the analysis, categorize every one of the 50 HookMaster hooks into three tiers:

Tier 1: 🔴 STRONGLY RECOMMENDED

Hooks that directly address risks or needs identified in the analysis. Include these when:

• The project handles auth, payments, or sensitive data → security hooks
• The project uses TypeScript → type-check
• The project has a test framework → test-runner, stop-until-tests-pass
• Docker is in use → docker-safety
• The project has .env files → protect-critical-files, secret-scanner
• The project uses npm/pip/cargo → dependency-guard
• Team conventions mention formatting standards → auto-format, auto-lint

Tier 2: 🟡 NICE TO HAVE

Hooks that improve workflow but aren't critical for this specific project:

• Logging and observability hooks when the project is non-trivial
• Git convention hooks when there's team collaboration
• Context injection hooks for larger codebases
• Notification hooks for long-running tasks

Tier 3: 🟢 OPTIONAL

Hooks that are available but not particularly relevant to this project:

• Hooks for languages/tools not used in this project
• Advanced hooks (subagent, permission) for simpler projects
• Hooks whose functionality overlaps with existing tooling

Recommendation format

Present recommendations as a clear, scannable list grouped by tier. For each hook include:

• The hook name and ID
• A one-line explanation of why it's recommended for THIS project specifically (not the generic description)
• The event it attaches to

Example:

🔴 STRONGLY RECOMMENDED (install these)

  1. block-destructive-cmds — Your project has production Docker configs
     that a stray rm -rf could wipe. (PreToolUse/Bash ⛔)

  2. protect-critical-files — You have .env.production, src/middleware.ts,
     and a payments/ directory that should require manual editing.
     (PreToolUse/Edit ⛔)

  3. auto-format — Prettier is in your devDependencies but there's no
     pre-commit hook enforcing it. This closes that gap.
     (PostToolUse/Write|Edit)

  ...

🟡 NICE TO HAVE (recommended but not critical)

  7. session-logger — Useful for tracking which branches you work on
     across sessions. (SessionStart)

  ...

🟢 OPTIONAL (available if you want them)

  12. slack-webhook — You don't appear to have Slack integration, but
      this is here if you add it later. (Notification)

---

4. USER CONFIRMATION

After presenting recommendations, ask the user:

1. Which hooks to install — Let them confirm the Strong tier, cherry-pick from Nice-to-have, and optionally add from Optional
2. What scope — Ask: "Should these hooks be installed GLOBALLY (all projects, ~/.claude/settings.json) or for THIS PROJECT only (.claude/settings.json)?"
3. Any customizations — Ask if they want to modify any protected file lists, branch naming patterns, or other hook-specific settings

Wait for explicit confirmation before installing anything.

---

5. INSTALLATION

Once the user confirms their selections and scope:

Step 5a: Create hook scripts

For each selected hook, create the shell script at the appropriate location:

• Global: ~/.claude/hooks/hookmaster/<hook-id>.sh
• Project: .claude/hooks/hookmaster/<hook-id>.sh

Make each script executable (chmod +x).

The hook script contents for all 50 hooks are defined in the HookMaster registry. If HookMaster is installed as a package, you can reference scripts from the package. If not, create the scripts inline using the standard HookMaster patterns (see HOOKS_REFERENCE.md in this skill directory for all script contents).

Step 5b: Update settings.json

Add entries to the appropriate settings.json file. Follow this structure:

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<matcher-regex>",
        "hooks": [
          {
            "type": "command",
            "command": "<path-to-script>",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Important rules:

• Merge with existing hooks — never overwrite the user's other hooks
• Group hooks with the same event + matcher into the same matcher group
• For events that don't support matchers (SessionStart, Stop, UserPromptSubmit, etc.), omit the matcher field
• For prompt-type hooks (like subagent-quality-gate), use "type": "prompt" with a "prompt" field

Step 5c: Write state manifest

Create or update .claude/hookmaster-state.json:

{
  "version": "1.0.0",
  "analysisTimestamp": "<ISO-8601 timestamp>",
  "scope": "local|global",
  "installedHooks": ["hook-id-1", "hook-id-2", "..."],
  "projectSignature": {
    "techStack": ["typescript", "react", "prisma", "docker"],
    "hasAuth": true,
    "hasPayments": false,
    "hasDocker": true,
    "hasCi": true,
    "testFramework" 
     
     
      
      
  
   
      
     
     
  

Step 5d: Confirm completion

Tell the user:

• How many hooks were installed and at what scope
• Remind them they can use /manage-hooks to toggle hooks on/off later
• Mention that this skill will re-evaluate if the project evolves significantly (new auth system, new Docker configs, new CI pipeline, etc.)
• Mention they can explicitly ask to re-evaluate at any time

---

6. RE-EVALUATION MODE

When this skill activates on a project that already has .claude/hookmaster-state.json:

1. Read the existing state
2. Scan for changes since analysisTimestamp (new files, new deps, new directories)
3. Identify which NEW hooks are now relevant that weren't before
4. Present ONLY the new recommendations (don't re-recommend already-installed hooks)
5. Ask the user to confirm
6. Install and update the state manifest

Example re-evaluation output:

📋 HookMaster Advisor — Project Evolution Detected

Since your last hook configuration (2026-03-20):
  • New directory: payments/ (Stripe integration)
  • New file: docker-compose.prod.yml
  • New dependency: @prisma/client

🔴 NEW RECOMMENDATIONS

  1. protect-critical-files — Your new payments/ directory should be
     protected from AI edits without review. (PreToolUse/Edit ⛔)

  2. docker-safety — You now have production Docker configs.
     (PreToolUse/Bash ⛔)

You currently have 12 hooks installed. Want to add these 2?

---

7. COMPLETE HOOK CATALOG

Reference this catalog when building recommendations. All 50 hooks organized by category:

🔒 SECURITY (9)

ID	Name	Event	Matcher	Blocks?
block-destructive-cmds	Block Destructive Commands	PreToolUse	Bash	⛔
protect-critical-files	Protect Critical Files	PreToolUse	Edit|MultiEdit|Write	⛔
dependency-guard	Dependency Installation Guard	PreToolUse	Bash	⛔
secret-scanner	Secret/Key Scanner	PostToolUse	Write|Edit|MultiEdit
branch-protection	Branch Protection	PreToolUse	Bash	⛔
sudo-blocker	Sudo/Privilege Escalation Blocker	PreToolUse	Bash	⛔
network-guard	Network Command Guard	PreToolUse	Bash	⛔
path-traversal-guard	Path Traversal Guard	PreToolUse	Edit|MultiEdit|Write|Read	⛔
docker-safety	Docker Safety Guard	PreToolUse	Bash	⛔

✨ CODE QUALITY (9)

ID	Name	Event	Matcher
auto-format	Auto-Format on Edit	PostToolUse	Write|Edit|MultiEdit
auto-lint	Auto-Lint on Edit	PostToolUse	Write|Edit|MultiEdit
type-check	Type Check After Edit	PostToolUse	Write|Edit|MultiEdit
test-runner	Run Affected Tests	PostToolUse	Write|Edit|MultiEdit
import-sorter	Auto-Sort Imports	PostToolUse	Write|Edit|MultiEdit
console-log-cleaner	Console.log Warning	PostToolUse	Write|Edit|MultiEdit
file-size-guard	File Size Guard	PostToolUse	Write|Edit|MultiEdit
fixme-counter	FIXME/TODO Counter	PostToolUse	Write|Edit|MultiEdit
hardcoded-url-detector	Hardcoded URL Detector	PostToolUse	Write|Edit|MultiEdit

⚙️ WORKFLOW (10)

ID	Name	Event
session-logger	Session Start Logger	SessionStart
prompt-logger	Prompt Logger	UserPromptSubmit
activity-logger	Tool Activity Logger	PreToolUse
completion-notifier	Task Completion Notifier	Stop
transcript-backup	Pre-Compaction Transcript Backup	PreCompact
session-end-summary	Session End Summary	SessionEnd
time-tracker	Session Time Tracker	SessionStart
time-tracker-end	Session Time Reporter	SessionEnd
diff-summarizer	Diff Summarizer on Stop	Stop
prompt-sanitizer	Prompt Sanitizer	UserPromptSubmit

🔀 GIT (6)

ID	Name	Event	Matcher	Blocks?
conventional-commits	Enforce Conventional Commits	PreToolUse	Bash	⛔
auto-stage-commit	Auto Stage & Commit on Stop	Stop
branch-name-enforcer	Branch Naming Convention Enforcer	PreToolUse	Bash	⛔
auto-branch-from-prompt	Auto-Create Feature Branch	SessionStart
changelog-generator	Changelog Entry Generator	Stop
git-stash-guard	Git Stash Reminder	SessionStart

🤖 SUBAGENT (3)

ID	Name	Event
subagent-logger	Subagent Completion Logger	SubagentStop
subagent-quality-gate	Subagent Quality Gate	SubagentStop
subagent-start-logger	Subagent Start Logger	SubagentStart

🔑 PERMISSION (4)

ID	Name	Event	Matcher
auto-approve-reads	Auto-Approve Safe Read Ops	PermissionRequest	Read|Glob|Grep|LS
auto-approve-format	Auto-Approve Formatting Tools	PermissionRequest	Bash
auto-approve-tests	Auto-Approve Test Commands	PermissionRequest	Bash
deny-network-tools	Deny External Network Tools	PermissionRequest	Bash

📋 CONTEXT (5)

ID	Name	Event
git-context-loader	Git Context Loader	SessionStart
todo-injector	TODO/FIXME Injector	SessionStart
package-context-loader	Package.json Context Loader	SessionStart
env-template-checker	Environment Template Checker	SessionStart
open-issues-loader	Open Issues Summary Loader	SessionStart

🔔 NOTIFICATION (3)

ID	Name	Event
sound-alert	Sound Alert on Notification	Notification
slack-webhook	Slack Webhook Notifier	Notification
error-alert	Error Alert on Tool Failure	PostToolUseFailure

🧪 TESTING (1)

ID	Name	Event	Blocks?
stop-until-tests-pass	Block Stop Until Tests Pass	Stop	⛔