klaudiush: Instructions file for Claude Code

GitHub Copilot Instructions

This file provides guidance to GitHub Copilot when working with code in this repository.

Project Overview

klaudiush is a validation dispatcher for Claude Code hooks. It intercepts tool invocations (PreToolUse events) and validates commands before execution, enforcing git workflow standards and commit message conventions.

Commands

Build

# Development build (no signoff validation)
mise run build

# Production build (validates signoff matches git config)
mise run build:prod

# Install to ~/.claude/hooks/dispatcher
mise run install

Testing

# Run all tests
mise run test

# Unit tests only
mise run test:unit

# Integration tests only
mise run test:integration

Linting

# Lint and auto-fix
mise run check
mise run lint:fix

# Lint only
mise run lint

Development

# Format code
mise run fmt

# Clean build artifacts
mise run clean

# Update dependencies
mise run deps

# Run all verification (fmt + lint + test)
mise run verify

Before Committing Code:

Always run mise run lint and mise run test to ensure code quality and test coverage.

Architecture

Core Flow

1. CLI Entry (cmd/klaudiush/main.go): Receives JSON from stdin, parses --hook-type flag
2. JSON Parser (internal/parser/json.go): Converts JSON to hook.Context
3. Dispatcher (internal/dispatcher/dispatcher.go): Orchestrates validation
4. Registry (internal/validator/registry.go): Matches validators to context using predicates
5. Validators: Execute validation logic, return Result (Pass/Fail/Warn)

Hook Context

The hook.Context struct (pkg/hook/context.go) represents tool invocations:

• EventType: PreToolUse, PostToolUse, Notification
• ToolName: Bash, Write, Edit, Grep, etc.
• ToolInput: Command, FilePath, Content, etc.

Validator System

Predicate-based Registration (internal/validator/registry.go):

registry.Register(
    validator,
    validator.And(
        validator.EventTypeIs(hook.PreToolUse),
        validator.ToolTypeIs(hook.Bash),
        validator.CommandContains("git commit"),
    ),
)