docs: Create comprehensive hook development guide

Overview

Create a comprehensive guide for developing, testing, and contributing new pre-commit hooks to this repository.

Purpose

Provide clear documentation to help contributors:

• Understand hook architecture and standards
• Develop new hooks following best practices
• Test hooks thoroughly
• Submit quality contributions

Content Requirements

1. Hook Development Basics

• What are pre-commit hooks?
• Repository structure overview
• Naming conventions
• File organization

2. Writing Hooks

• Shell script best practices
• Error handling patterns
• Input/output standards
• Exit codes and their meanings
• Dependency management

3. Security Guidelines

• Input validation
• Safe file operations
• Avoiding command injection
• Secret handling
• Permission requirements

4. Testing Hooks

• Using the bats framework
• Writing effective tests
• Mocking external commands
• Coverage requirements
• CI integration

5. Contributing Process

• Fork and clone workflow
• Branch naming conventions
• Commit message format
• PR requirements
• Review process

6. Examples

• Simple hook example
• Complex hook with dependencies
• Multi-file processing hook
• Language-specific hook

7. Common Patterns

• File filtering
• Parallel processing
• Progress reporting
• Configuration handling
• Cross-platform compatibility

8. Troubleshooting

• Common errors
• Debugging techniques
• Performance optimization
• Platform-specific issues

Deliverables

• CONTRIBUTING.md enhancement
• docs/HOOK_DEVELOPMENT.md guide
• Example hook template
• Test template
• Quick reference card

Success Criteria

• Clear, comprehensive documentation
• Practical examples
• Reduced barrier to contribution
• Consistent hook quality
• Faster PR reviews

Related

• #26 - CI/CD implementation
• #27 - Test coverage
• Current CONTRIBUTING.md needs update