Claude Code Hooks

Comprehensive hook system for automated validation, project-aware guidance, and KISS principle enforcement across all Zeron development.

Overview

Claude Code hooks are shell scripts that run automatically before or after tool use (file edits, bash commands, agent spawning). They provide:

• Real-time validation - Catch issues before they happen
• Project-aware guidance - Context-specific reminders for OrderDay vs Zeron
• KISS enforcement - Prevent over-engineering in hobby projects
• Multi-agent coordination - Workspace-aware hints for builder/QA/architect agents
• Security validation - Special checks for security-sensitive operations

Hook Configuration Location

Hooks are configured in Claude Code settings:

~/.claude/settings.json

Hook Types

PreToolUse Hooks

Run before a tool executes. Used for:

• Validation that can prevent execution
• Warnings and reminders before changes
• KISS principle enforcement

PostToolUse Hooks

Run after a tool completes. Used for:

• Type checking after edits
• Git operation validation
• Prisma client regeneration

Implemented Hooks

1. KISS Principle Enforcement (PreToolUse - Edit/Write)

Purpose: Prevent over-engineering in hobby projects

Triggers:

• Before editing/writing TypeScript, JavaScript, Python, or Bash files

Checks:

• Abstraction limits: Max 1 interface/abstract class per 150 lines
• Async complexity: Warning if 10+ async operations
• Generic overuse: Warning if 5+ generic types
• Enterprise patterns: Blocks Singleton, Observer, CQRS, Event Sourcing, etc.
• File size: Warning if >500 lines
• Function size: Warning if >50 lines
• Mock data: Detects fake/test data patterns

Example Output:

🚨 KISS VIOLATION - TOO ABSTRACT!
   5 abstractions in only 200 lines
   Hobby Project Rule: Max 1 abstraction per 150 lines
   SIMPLIFY THIS NOW!

🏭 ENTERPRISE PATTERN ALERT!
   This is a HOBBY PROJECT!
   Delete this pattern and use something simple

Philosophy:

• 30-minute prototype max
• Real problem, simplest solution
• No mock data or fallbacks (fail honestly)
• Concrete types over generics

2. Project-Aware File Edit Validation (PostToolUse - Edit/Write)

Purpose: Context-specific guidance based on project and workspace

Triggers:

• After editing/writing code files

Project Detection:

• OrderDay: /orderday/ in path
• Zeron: /zeron/ in path

Workspace Detection (Multi-Agent):

• zeron-builder/ → Builder workspace
• zeron-qa-security/ → QA/Security workspace
• zeron-architect/ → Architect workspace
• zeron-devops/ → DevOps workspace
• zeron-tech-debt/ → Tech Debt workspace

Checks:

TypeScript Type Checking:

🔍 Running TypeScript type check for orderday...
npm run type-check (in correct project directory)

Widget Protection (Zeron Feedback Service):

🛡️ CRITICAL Widget Safety Checklist:
   ❌ DO NOT replace with simple iframe loader
   ✅ Must maintain 600+ lines of AI chat code
   ✅ Keep ZeronWidget, MessageBubble, FeedbackInput classes

Security Branch Detection:

🔐 Security Branch Active: security/xss-fix
   ⚠️  Editing security test file - ensure tests pass
   Run: node test-xss-injection.js to validate

TODO Detection:

🚧 Found 3 TODO/FIXME items
widget.js:45: // TODO: Add error handling

Prisma Client Regeneration:

• Auto-regenerates when @prisma/client imports detected

3. Pre-Edit Project Validation (PreToolUse - Edit/Write)

Purpose: Warn before editing with project-specific context

OrderDay-Specific Warnings:

• Feature flag reminders for new components
• Multi-tenant safety for API routes
• Prisma decimal type reminders

Zeron-Specific Warnings:

• ZONE branch scope reminders
• Widget protection warnings
• Learning Service integration checks
• AI Conversation Service requirements
• Multi-tenant database safety

Example Output:

👷 Builder Workspace - Focus on implementation

🎯 Working on PROJ-123 - Stay within scope

🔒 Multi-Tenant Checklist:
   □ organizationId field added?
   □ projectId field where appropriate?
   □ RLS maintained?

4. Git Operations Validation (PostToolUse - Bash)

Purpose: Validate git commits and pushes

Triggers:

• After git commit commands
• After git push commands

Checks:

Branch Protection:

❌ Direct commits to main not allowed - use staging branch

Security Branch Validation:

🔐 Committing to security branch: security/session-fix
   Ensure all security tests pass:
   • Run: node test-xss-injection.js
   • Run: node test-session-fix.js
   • Run: node redteam-attack-suite.js

Type Check Before Commit:

• Runs npm run type-check for project
• Blocks commit if type errors detected

Deployment Warnings:

🚀 This will deploy to preview.orderday.co via Vercel

5. Orchestrator Launch Detection (PostToolUse - Task)

Purpose: Ensure orchestrator agents have required context

Triggers:

• When spawning orchestrator-type agents with Task tool

Required Elements:

• Read CLAUDE.md instruction
• Read settings.json instruction
• Sub-agent launching instructions
• KISS principle reminder

Example Output:

🚫 ORCHESTRATOR LAUNCH BLOCKED!

Missing required elements:
   ❌ Missing: Read CLAUDE.md instruction
   ❌ Missing: Sub-agent launching instructions

📋 USE THE TEMPLATE FROM CLAUDE.md:
   Section: 'Orchestrator Agent Template'

6. Pre-Bash Validation

Purpose: Provide guidance before running bash commands

Special Detections:

Redis Operations:

📮 Redis Operation Detected
   💡 Tip: For orchestrator tasks, use:
      docker exec zeron-redis-upstream redis-cli

Docker Operations:

🐳 Docker Operation
   Required containers:
   • zeron-redis-upstream (orchestrator)
   • zeron-neo4j (graph database)

Statsig CLI:

📊 Statsig CLI Tips:
   • List flags: npm run flags:list
   • Check flag: npm run flags:check <name>

Database Operations:

🗄️ Database Operation Reminders:
   ✓ agent_conversations table must exist
   ✓ Seed data: default-org, default-project, anonymous user

Hook Matchers

File Path Matchers

Edit/MultiEdit/Write - Matches file edit operations Bash - Matches bash command execution Task - Matches agent spawning

Pattern Matching

Hooks use grep patterns to detect specific scenarios:

• security/ - Security branches
• widget.js - Critical production files
• schema.prisma - Database schema files
• api/ - API route files

Environment Variables Available to Hooks

PreToolUse - Edit/Write:

• $FILE_PATH - Path to file being edited
• $TOOL_NAME - Name of tool (Edit, Write, MultiEdit)

PostToolUse - Edit/Write:

• $FILE_PATH - Path to file edited
• $TOOL_NAME - Name of tool used

PreToolUse/PostToolUse - Bash:

• $COMMAND - Bash command being executed
• $PWD - Current working directory

PreToolUse/PostToolUse - Task:

• $SUBAGENT_TYPE - Type of agent being launched
• $PROMPT - Prompt being sent to agent

Custom Hook Development

Adding a New Hook

1. Edit ~/.claude/settings.json

2. Add to PreToolUse or PostToolUse array:

{
  "matcher": "Edit|Write",
  "hooks": [
    {
      "type": "command",
      "command": "#!/bin/bash\n# Your hook script here\necho \"File: $FILE_PATH\"",
      "timeout": 5
    }
  ]
}

3. Test with file edit or bash command

Hook Best Practices

Performance:

• Keep timeouts short (5-10 seconds max)
• Cache expensive operations (/tmp/claude_cache_$$)
• Use grep -q for fast pattern matching

User Experience:

• Use emoji for visual categorization (🚨 errors, 💡 tips, ✅ success)
• Provide actionable guidance, not just warnings
• Show relevant commands to fix issues

Project Awareness:

• Detect project via path patterns
• Provide context-specific guidance
• Use different rules for OrderDay vs Zeron

Security:

• Never expose secrets in hook output
• Validate security-sensitive operations
• Warn about production deployments

Hook Output Examples

Successful Validation

👷 Builder Workspace - Focus on implementation
🔍 Running TypeScript type check for zeron...
✅ Orchestrator prompt includes all required elements

Warnings

⚠️  WARNING: Sub-agent prompt missing CLAUDE.md!
   Should include: 'Read /path/to/project/CLAUDE.md'

📏 FILE TOO LARGE!
   650 lines - this should be split up

Errors (Non-Blocking)

❌ Type errors detected - commit blocked
❌ CRITICAL: ZeronWidget class missing from widget.js!

Disabling Hooks

Temporarily disable all hooks:

# Edit settings.json, comment out hooks section

Disable specific hook:

• Remove from PreToolUse or PostToolUse array in settings.json

Override for specific command:

• Hooks cannot be overridden per-command
• Must disable in settings.json

Troubleshooting

Hook Not Running

Check:

1. Verify hook is in ~/.claude/settings.json
2. Ensure matcher pattern matches tool name
3. Check timeout isn't too short
4. Verify bash script is valid (bash -n script.sh)

Hook Errors

Common Issues:

• Permission denied: Check script has execute permissions
• Command not found: Use absolute paths for commands
• Timeout: Increase timeout value or optimize script

Hook Output Not Showing

Solutions:

• Check stdout/stderr in hook script
• Verify echo statements are present
• Ensure script exits with code 0 (success)

Integration with Conductor

The hook system complements Conductor's automated development:

Conductor (orchestration):

• Spawns agents for Jira tickets
• Manages agent lifecycle
• Validates checklists

Hooks (validation):

• Provide real-time guidance to agents
• Enforce KISS principles
• Project-specific validation
• Prevent common mistakes

Together they form a comprehensive development automation system with built-in quality gates.

Future Enhancements

Planned Hook Features:

• Pre-commit lint enforcement
• Automatic code formatting
• Security vulnerability scanning
• Dependency update warnings
• Cost estimation for API changes

Integration Ideas:

• Hook results logged to Conductor metrics
• Failed hooks trigger Conductor alerts
• Hook output stored in validation reports

---

Related:

• Conductor Development Guide
• KISS Principles
• Multi-Agent Workflow