claude-git-hooks 2.9.1 → 2.11.0

package/README.md

@@ -1,848 +1,318 @@
-# Pre-commit Hook con Claude CLI
-
-🚀 **Transforma tu flujo de desarrollo con IA**: análisis de código instantáneo, mensajes de commit automáticos y generación de PRs perfectas. Claude revisa tu código antes de cada commit, detecta issues críticos con análisis estructurado, y genera toda la documentación que necesitas. ¿Lo mejor? Se ejecuta localmente sin contaminar tu CI/CD.
-
-## ✨ Novedad v2.7.1 - Improved Reliability
-
-**Nuevo v2.7.1**: Sistema de reintentos automáticos para errores transitorios de Claude API. Cuando Claude devuelve "Execution error" (típicamente por rate limiting), el sistema ahora reintenta automáticamente después de 2 segundos.
-
-## ✨ Novedad v2.0.0 - Ahora Cross-Platform
-
-**¡Nueva arquitectura!** Migración completa a Node.js con ES6 modules para soporte más universal:
-
-- ✅ **Windows** - Git en Bash y Powershell
-- ✅ **WSL** - Subsistema de Linux
-- ✅ **Linux** - Funcionamiento nativo
-- ✅ **Worktrees** - Compatible con git worktrees en cualquier entorno
-- ✅ **IDEs** - Compatible con git manager de IntelliJ and VSCode -> mensaje de commit "auto" committea (y pushea si se quiere) con mensaje automático. Si el commit tiene problemas, se bloquea.
-
-## 🎯 Características principales
-
-- 🔍 **Análisis de código pre-commit**: Detecta issues críticos antes de que lleguen al repo
-- 💬 **Mensajes de commit automáticos**: Escribe "auto" y Claude genera el mensaje con task-id (Jira, GitHub, Linear)
-- 📋 **Generación de PRs**: Análisis de diff y metadata automática con un comando
-- 🔗 **Creación de PRs en GitHub**: Claude genera metadata, Octokit crea el PR (determinista) - v2.5.0+
-- 🎯 **Presets por tech-stack**: 6 configuraciones optimizadas (backend, frontend, fullstack, database, ai, default) - v2.3.0+
-- 🚀 **Parallel Analysis**: Multiple Claude CLI processes analyzing file batches simultaneously (v2.2.0+)
-- 🔄 **Auto-actualización**: Se mantiene actualizado automáticamente
-- 🌍 **Cross-platform**: Windows, WSL, macOS, Linux sin configuración especial
-- ♻️ **Reintentos automáticos**: Recuperación automática de errores transitorios de API (v2.7.1+)
-
-## 📋 CHEATSHEET
-
-### 🚀 Comandos Frecuentes
-
-```bash
-# Commit rápido sin análisis + mensaje automático
-git commit --no-verify -m "auto"
-
-# Analizar diferencias con origin de la rama actual
-claude-hooks analyze-diff
-
-# Analizar diferencias para PR (comparar con origin/develop)
-claude-hooks analyze-diff develop
-
-# Crear PR en GitHub con metadata automática (v2.5.0+)
-claude-hooks create-pr develop
-
-# Configurar token de GitHub para PRs (v2.5.0+)
-claude-hooks setup-github
-
-# Reinstalar durante desarrollo (después de npm link)
-claude-hooks install --force --skip-auth
-
-# Listar presets
-claude-hooks presets
-
-# Seleccionar preset
-claude-hooks --set-preset <name>
-
-# Mostrar preset actual
-claude-hooks preset current
-
-# Activar modo debug
-claude-hooks --debug true
-
-# Ver estado de debug
-claude-hooks --debug status
-
-# Ver estadísticas de telemetría (v2.9.0+, habilitada por defecto)
-claude-hooks telemetry show
+# Claude Git Hooks
 
-# Limpiar datos de telemetría (v2.9.0+)
-claude-hooks telemetry clear
-```
+AI-powered git hooks for automatic commit messages, code analysis, and PR creation.
 
-### 📦 Instalación y Gestión
+## Requirements
 
-✨ **v2.0.0+**: Funciona terminales WSL y Bash.
+- Node.js >=16.9.0
+- Git
+- Claude CLI (authenticated)
 
-Se debe instalar el paquete globalmente, para luego gestionarlo localmente en cada repositorio.
+## Quick Start
 
 ```bash
-# Instalar globalmente (desde cualquier terminal)
 npm install -g claude-git-hooks
-
-# Luego en cada proyecto
-cd /tu/proyecto
+cd your-project
 claude-hooks install
-
-# Actualizar a última versión
-claude-hooks update
-
-# Desinstalar hooks
-claude-hooks uninstall
-
-# Ver estado actual
-claude-hooks status
-
-# Desactivar temporalmente
-claude-hooks disable
-
-# Reactivar hooks
-claude-hooks enable
 ```
 
-### 💻 Flujos de Commit
-
-```bash
-# Commit con análisis de código
-git commit -m "feat: nueva funcionalidad"
+## Usage
 
-# Generar mensaje automático con task-id (v2.5.0+)
-# Branch: feature/IX-123-add-auth → detecta IX-123
-git commit -m "auto"
-# Resultado: [IX-123] feat: add user authentication
+### Auto Commit Message
 
-# Branch: feature/471459f-test → NO detecta (hash, no task-id)
+```bash
 git commit -m "auto"
-# Resultado: feat: add test feature (sin task-id)
-
-# Saltar análisis (emergencias)
-git commit --no-verify -m "hotfix: corrección urgente"
-
-# Modificar último commit
-git commit --amend
+# Claude generates message from branch name + changes
+# Format: [TASK-ID] type: description
+# Example: branch feature/IX-123-auth → [IX-123] feat: add authentication
 ```
 
-## 🚀 Quick Setup: GitHub PR Creation
-
-Para usar `create-pr` necesitas configurar autenticación con GitHub:
-
-### 1. Ejecuta el setup wizard
+### Create PR
 
 ```bash
-claude-hooks setup-github
+claude-hooks create-pr develop
+# Automatically pushes branch if unpublished (with confirmation)
+# Analyzes diff, generates title/description, creates PR on GitHub
 ```
 
-El comando verificará tu token o te guiará a configurarlo.
-
-### 2. Opciones de configuración del token
+**Auto-push feature (v2.11.0):**
+- Detects unpublished branches or unpushed commits
+- Shows commit preview before pushing
+- Prompts for confirmation (configurable)
+- Handles diverged branches gracefully
 
-**Opción A - Settings local (recomendado):**
+### GitHub Token Setup
 
 ```bash
-# Crear .claude/settings.local.json
-cat > .claude/settings.local.json << 'EOF'
-{
-  "githubToken": "ghp_tu_token_aqui"
-}
-EOF
+claude-hooks setup-github  # Shows status and configuration options
 ```
 
-**Opción B - Variable de entorno:**
-
-```bash
-export GITHUB_TOKEN="ghp_tu_token_aqui"
-# o
-export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_tu_token_aqui"
+**Option 1 - Settings file (recommended):**
+```json
+// .claude/settings.local.json (gitignored)
+{ "githubToken": "ghp_..." }
 ```
 
-**Opción C - Claude Desktop config** (auto-detectado si existe)
-
-### 3. Crear GitHub token
-
-1. Ir a https://github.com/settings/tokens
-2. "Generate new token (classic)"
-3. Scopes requeridos: **repo** (all) + **read:org**
-4. Copiar token (empieza con `ghp_`)
-
-### 4. Configurar reviewers y labels (opcional)
-
+**Option 2 - Environment variable:**
 ```bash
-# Ver .claude/config_example/ para más ejemplos
-cat > .claude/config.json << 'EOF'
-{
-  "version": "2.8.0",
-  "preset": "backend",
-  "overrides": {
-    "github": {
-      "pr": {
-        "defaultBase": "develop",
-        "reviewers": ["tu-usuario-github", "teammate"],
-        "labelRules": {
-          "backend": ["backend", "java"],
-          "frontend": ["frontend", "react"]
-        }
-      }
-    }
-  }
-}
-EOF
+export GITHUB_TOKEN="ghp_..."
 ```
 
-**Nota:** Los reviewers también se detectan automáticamente desde CODEOWNERS si existe.
+Create token at https://github.com/settings/tokens with scopes: `repo`, `read:org`
 
-### 5. Crear tu primer PR
+### Analyze Diff (without creating PR)
 
 ```bash
-git checkout -b feature/mi-feature
-# ... hacer cambios ...
-git add .
-git commit -m "feat: nueva funcionalidad"
-git push -u origin feature/mi-feature
-
-# Crear PR
-claude-hooks create-pr develop
+claude-hooks analyze-diff develop
+# Generates PR metadata without creating
 ```
 
-**Arquitectura:** Claude analiza el diff y genera metadata (título, descripción, reviewers, labels) → Octokit crea el PR de forma determinista.
-
-Ver `templates/config.github.example.json` para configuración avanzada (reviewer rules por path, custom labels, etc.).
-
----
-
-## 📆 Próximos Desarrollos
-
-Toda idea es bienvenida, aunque parezca espantosa. Si hay bugs, incluirlos también. Dónde? en https://github.com/mscope-S-L/git-hooks/issues/new.
-
-### 🔧 Configuración Avanzada (v2.8.0+)
+### Disable/Enable Hooks
 
 ```bash
-# Configuración vía .claude/config.json (v2.8.0+)
-.claude/
-├── config.json                      # Configuración principal (formato simplificado)
-├── config_example/                  # Ejemplos de configuración
-│   ├── config.example.json          # Configuración básica
-│   └── config.advanced.example.json # Parámetros avanzados
-└── prompts/                         # Templates de prompts (v2.8.0+)
-    ├── CLAUDE_PRE_COMMIT.md         # Criterios de análisis
-    └── CLAUDE_ANALYSIS_PROMPT.md    # Template del prompt
-
-# Ejemplo de config.json v2.8.0 (formato simplificado)
-cat > .claude/config.json << 'EOF'
-{
-  "version": "2.8.0",
-  "preset": "backend",
-  "overrides": {
-    "github": {
-      "pr": {
-        "defaultBase": "main",
-        "reviewers": ["tech-lead"]
-      }
-    },
-    "subagents": {
-      "batchSize": 2
-    }
-  }
-}
-EOF
-
-# Para configuración avanzada, consultar:
-# .claude/config_example/config.advanced.example.json
-
-# Personalizar patrón de task-id
-# Default: 1-3 letras + separador + 3-5 dígitos
-# Ejemplos válidos: ABC-12345, IX-123, DE 4567
-# No detecta: 471459f (hash), ABCD-123 (4 letras), IX-12 (2 dígitos)
+claude-hooks disable [pre-commit|prepare-commit-msg]
+claude-hooks enable [pre-commit|prepare-commit-msg]
 ```
 
-#### 🎯 Presets Disponibles
-
-| Preset        | Extensiones de Archivo                                                     | Caso de Uso       | Tech Stack                   |
-| ------------- | -------------------------------------------------------------------------- | ----------------- | ---------------------------- |
-| **backend**   | `.java`, `.xml`, `.yml`, `.yaml`                                           | APIs Spring Boot  | Spring Boot, JPA, SQL Server |
-| **frontend**  | `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss`, `.html`                     | Apps React        | React, Redux, Material-UI    |
-| **fullstack** | Todos backend + frontend                                                   | Apps full-stack   | Spring Boot + React          |
-| **database**  | `.sql`                                                                     | Scripts de BD     | SQL Server, T-SQL            |
-| **ai**        | `.js`, `.json`, `.md`, `.sh`                                               | Herramientas CLI  | Node.js, Claude API          |
-| **default**   | `.js`, `.sh`, `.py`, `.rb`, `.pl`, `.sql`, `.yaml`, `.json`, `.xml`, `.md` | Propósito general | Lenguajes mixtos             |
-
----
-
-#### 🔍 Qué Verifica Cada Preset
-
-**Backend (Spring Boot + SQL Server)**
-
-- ✅ Diseño de API REST y métodos HTTP
-- ✅ Entidades JPA y repositorios
-- ✅ Seguridad (OWASP Top 10)
-- ✅ Prevención de inyección SQL
-- ✅ Gestión de transacciones
-- ✅ Mapeos DTO
-- ✅ Mejores prácticas Spring Security
-
-**Frontend (React + Material-UI)**
-
-- ✅ Mejores prácticas de hooks React
-- ✅ Diseño de componentes y reusabilidad
-- ✅ Patrones de gestión de estado
-- ✅ Prevención XSS
-- ✅ Optimización de rendimiento
-- ✅ Accesibilidad (a11y)
-- ✅ Error boundaries
-
-**Fullstack (Spring Boot + React)**
-
-- ✅ **Consistencia de contrato API** (prioridad)
-- ✅ Flujo de datos (BD → API → UI)
-- ✅ Autenticación entre capas
-- ✅ Consistencia en manejo de errores
-- ✅ Todas las verificaciones backend
-- ✅ Todas las verificaciones frontend
-
-**Database (SQL Server)**
-
-- ✅ Riesgos de inyección SQL
-- ✅ UPDATE/DELETE sin WHERE
-- ✅ Índices faltantes
-- ✅ Rendimiento de consultas
-- ✅ Manejo de transacciones
-- ✅ Restricciones de integridad de datos
-
-**AI (Node.js + Claude)**
-
-- ✅ Mejores prácticas Claude API
-- ✅ Calidad de ingeniería de prompts
-- ✅ Experiencia de usuario CLI
-- ✅ Seguridad de operaciones Git
-- ✅ Compatibilidad multiplataforma
-- ✅ Protección de API key
-
-**Default (Propósito general)**
-
-- ✅ Fundamentos de calidad de código
-- ✅ Fundamentos de seguridad
-- ✅ Manejo de errores
-- ✅ Mejores prácticas por lenguaje
-- ✅ Mantenibilidad
-
----
-
-##### ⚙️ Prioridad de Configuración
-
-```
-defaults (lib/config.js)
-  ↓
-user config (.claude/config.json)  ← General preferences
-  ↓
-preset config (.claude/presets/{name}/config.json)  ← MÁXIMA PRIORIDAD (tech-stack specific)
-```
-
-**Rationale**: User sets general preferences, preset provides tech-stack-specific overrides.
-
-**Nota v2.2.0+:** Variables de entorno ya NO son soportadas. Usar `.claude/config.json` en su lugar.
-
-### 🎯 Casos de Uso Específicos
+### Uninstall
 
 ```bash
-# Desarrollo local de claude-hooks
-cd /path/to/claude-git-hooks
-npm link
-cd /path/to/your-project
-claude-hooks install --force --skip-auth
-
-# Preparar PR hacia develop
-git checkout -b feature/nueva-funcionalidad
-# ... hacer cambios ...
-git add .
-git commit -m "feat: implementar nueva funcionalidad"
-claude-hooks analyze-diff develop  # Genera título, descripción y tests
-
-# Resolver issues bloqueantes
-git commit -m "fix: resolver issues"
-# Si falla, ver claude_resolution_prompt.md generado
-# Copiar contenido y pegar en Claude para obtener solución
+claude-hooks uninstall
 ```
 
-### ⚡ Tips y Trucos
-
-1. **Mensaje automático**: Usa `"auto"` como mensaje para que Claude lo genere con task-id automático
-2. **Task-ID pattern**: Default 1-3 letras + separador + 3-5 dígitos (ABC-12345, IX-123). Configurable en `.claude/config_example/config.advanced.example.json`
-3. **Skip auth**: Usa `--skip-auth` en CI/CD o desarrollo local
-4. **Force install**: Usa `--force` para reinstalar sin confirmación
-5. **Debug**: Activa con `claude-hooks --debug true`
-6. **Archivos grandes**: Se omiten automáticamente archivos > 1MB (hardcoded desde v2.8.0)
-7. **Límite de archivos**: Máximo 20 archivos por commit (hardcoded desde v2.8.0)
-
-### 🚀 Parallel Analysis (Enabled by default desde v2.8.0)
-
-**When analyzing 3+ files**, parallel execution runs multiple Claude CLI processes simultaneously for faster analysis.
-
-**Configuración automática (hardcoded):**
-- ✅ **Enabled**: `true` (siempre activo)
-- ⚡ **Model**: `haiku` (rápido y económico)
-- 📦 **BatchSize**: `3` files per batch (puede overridearse)
-
-**Customizar batch size (opcional):**
+### Presets
 
 ```bash
-# En .claude/config.json v2.8.0
-{
-  "version": "2.8.0",
-  "preset": "backend",
-  "overrides": {
-    "subagents": {
-      "batchSize": 2
-    }
-  }
-}
-```
-
-**Model options (solo en config avanzado):**
-
-- `haiku` - Fast & cheap (default)
-- `sonnet` - Balanced quality/speed
-- `opus` - Maximum quality (slower)
-
-**How batching works:**
-
-- Files are split into batches of size `batchSize`
-- Each batch runs in a separate Claude CLI process
-- All batches execute in parallel (true OS-level parallelism)
-- Results are consolidated automatically
-
-**Examples with 4 files:**
-
-- `batchSize: 1` → 4 parallel Claude processes (1 file each) - **fastest**
-- `batchSize: 2` → 2 parallel Claude processes (2 files each) - **balanced**
-- `batchSize: 4` → 1 process (all files) - no parallelization
-
-**Speed improvement:**
-
-- Sequential: 60s per file × 4 = 240s total
-- Parallel (batch=1): max(60s) = 60s total ✅ **4x faster**
-
-**Console output:**
-
+claude-hooks presets              # List available
+claude-hooks --set-preset backend # Set preset
+claude-hooks preset current       # Show current
 ```
-🚀 PARALLEL EXECUTION: 4 Claude processes
-  ⚡ Launching batch 1/4...
-  ⚡ Launching batch 2/4...
-  ⚡ Launching batch 3/4...
-  ⚡ Launching batch 4/4...
-  ⏳ Waiting for all batches to complete...
-
-✅ PARALLEL EXECUTION COMPLETE: 4 results in 62.5s
-```
-
-**Best for:** Large commits (3+ files), refactoring, multi-file features
-
-### 🎨 Personalización y Customización
-
-**Archivos clave para modificar:**
 
-- `.claude/config.json` - Configuración principal (v2.8.0+)
-- `.claude/prompts/CLAUDE_PRE_COMMIT.md` - Criterios (backend/frontend/data/db)
-- `.claude/prompts/CLAUDE_ANALYSIS_PROMPT.md` - Template del prompt
+| Preset | Extensions | Focus |
+|--------|------------|-------|
+| backend | .java, .xml, .yml, .yaml | Spring Boot, JPA, OWASP |
+| frontend | .js, .jsx, .ts, .tsx, .css, .scss, .html | React, XSS, a11y |
+| fullstack | all above | API contract consistency |
+| database | .sql | SQL injection, indexes |
+| ai | .js, .json, .md, .sh | Node.js, Claude API |
+| default | multiple | General quality |
 
-**Crear o modificar presets personalizados:**
+### Skip Analysis
 
 ```bash
-# Ver guía completa de customización
-cat templates/CUSTOMIZATION_GUIDE.md
-
-# O en GitHub
-# https://github.com/pablorovito/claude-git-hooks/blob/main/templates/CUSTOMIZATION_GUIDE.md
+git commit --no-verify -m "message"
 ```
 
-**Ejemplo:**
+### Debug Mode
 
 ```bash
-vim .claude/prompts/CLAUDE_PRE_COMMIT.md  # Agregar reglas API REST/Spring Boot
+claude-hooks --debug true|false|status
 ```
 
-## 🔧 Configuración Previa Importante
-
-### Requisitos del Sistema
-
-✨ **v2.0.0+**: Los hooks funcionan en cualquier terminal donde tengas:
-
-- **Node.js** >= 16.9.0
-- **Git** configurado
-- **Claude CLI** instalado y autenticado
-
-🆕 **v2.6.0+**: Totalmente compatible con Node.js 24
-
-### Credenciales Git
-
-Si es tu primera vez configurando git en esta terminal, configura tus credenciales:
+### Telemetry
 
 ```bash
-git config --global user.name "Tu Nombre"
-git config --global user.email "tu.email@ejemplo.com"
-
-# Si usas credential helper (opcional)
-git config --global credential.helper store
+claude-hooks telemetry show   # View statistics
+claude-hooks telemetry clear  # Clear data
 ```
 
-## 🚀 Instalación
-
-✨ **v2.0.0+**: Instalación cross-platform. Funciona en PowerShell, CMD, WSL, macOS Terminal, Linux shell.
+### Other Commands
 
 ```bash
-# Instalar el paquete globalmente
-npm install -g claude-git-hooks
-
-# En cualquier repositorio, instalar los hooks
-cd tu-proyecto
-claude-hooks install
+claude-hooks status   # Show hook status
+claude-hooks update   # Update to latest version
+claude-hooks --help   # Full command reference
 ```
 
-El comando `claude-hooks install` incluye:
-
-- ✅ Verificación completa de dependencias del sistema (Node.js, Git, Claude CLI)
-- ✅ Verificación de autenticación Claude con entretenimiento (omitible con `--skip-auth`)
-- ✅ Instalación de hooks con arquitectura bash wrapper + Node.js
-- ✅ Instalación de archivos de pautas y templates
-- ✅ Actualización automática de .gitignore con archivos de Claude
-
-**Nuevo en v2.0.0 - Soporte Cross-Platform:**
-
-Auto-detecta plataforma, convierte CRLF→LF en install, busca Claude en WSL (Windows), instala bash wrappers que convierten rutas C:\ a /c/
-
-**Opciones de instalación:**
-
-- `--force`: Reinstala aunque los hooks ya existan
-- `--skip-auth`: Omite la verificación de autenticación de Claude (útil para CI/CD)
-
-## 📁 Gestión de Archivos
-
-### Archivos creados durante la instalación
-
-El comando `claude-hooks install` crea los siguientes archivos y directorios:
-
-1. **`.git/hooks/pre-commit`** - Hook de análisis de código
-2. **`.git/hooks/prepare-commit-msg`** - Hook de generación de mensajes
-3. **`.git/hooks/check-version.sh`** - Script de verificación de versión
-4. **`.claude/`** - Directorio para archivos de configuración
-    - `CLAUDE_PRE_COMMIT.md` - Criterios de evaluación de calidad
-    - `CLAUDE_ANALYSIS_PROMPT.md` - Template de prompt para análisis
-    - `CLAUDE_RESOLUTION_PROMPT.md` - Template para prompt de resolución AI
-
-### Actualización automática de .gitignore
+---
 
-Durante la instalación, Claude Hooks actualiza automáticamente tu `.gitignore` para incluir:
+## Architecture Reference (AI Context)
+
+### Design Philosophy
+
+**Modular, decoupled, reusable code.** Each component has a single responsibility and can be tested/modified independently.
+
+### Directory Map
+
+| Path | Purpose | Key Exports |
+|------|---------|-------------|
+| `bin/claude-hooks` | **Thin CLI router** - argument parsing, command dispatch | - |
+| `lib/commands/` | **Command modules** - one file per CLI command | See table below |
+| `lib/config.js` | **Config system** - load/merge configuration | `getConfig()` |
+| `lib/hooks/` | **Git hook logic** - Node.js implementations | `pre-commit.js`, `prepare-commit-msg.js` |
+| `lib/utils/` | **Reusable utilities** - shared across commands | See table below |
+| `templates/` | **Static assets** - bash wrappers, prompts, presets | Copied during install |
+
+### Command Modules (`lib/commands/`)
+
+| Module | Purpose | Key Exports |
+|--------|---------|-------------|
+| `helpers.js` | **Shared CLI utilities** - colors, output, platform detection | `colors`, `error()`, `success()`, `info()`, `checkGitRepo()`, `Entertainment` |
+| `install.js` | **Installation logic** - dependencies, hooks, templates | `runInstall()`, `extractLegacySettings()` |
+| `hooks.js` | **Hook management** - enable, disable, status, uninstall | `runEnable()`, `runDisable()`, `runStatus()`, `runUninstall()` |
+| `analyze-diff.js` | **Diff analysis** - generate PR metadata from git diff | `runAnalyzeDiff()` |
+| `create-pr.js` | **PR creation** - full workflow via Octokit | `runCreatePr()` |
+| `setup-github.js` | **Token setup** - interactive GitHub configuration | `runSetupGitHub()` |
+| `presets.js` | **Preset management** - list, set, show current | `runShowPresets()`, `runSetPreset()`, `runCurrentPreset()` |
+| `update.js` | **Self-update** - check and install latest version | `runUpdate()` |
+| `migrate-config.js` | **Config migration** - legacy to v2.8.0 format | `runMigrateConfig()` |
+| `debug.js` | **Debug toggle** - enable/disable verbose logging | `runSetDebug()` |
+| `telemetry-cmd.js` | **Telemetry commands** - show/clear statistics | `runShowTelemetry()`, `runClearTelemetry()` |
+| `help.js` | **Help display** - usage information | `runShowHelp()`, `runShowVersion()` |
+
+### Utility Modules (`lib/utils/`)
+
+| Module | Purpose | Key Exports |
+|--------|---------|-------------|
+| `claude-client.js` | **Claude CLI wrapper** - spawn, retry, parallel execution | `analyzeCode()`, `analyzeCodeParallel()`, `executeClaudeWithRetry()` |
+| `prompt-builder.js` | **Prompt construction** - load templates, replace variables | `buildAnalysisPrompt()`, `loadPrompt()` |
+| `git-operations.js` | **Git abstractions** - staged files, diff, repo root | `getStagedFiles()`, `getDiff()`, `getRepoRoot()` |
+| `github-api.js` | **Octokit integration** - PR creation, token validation | `createPullRequest()`, `validateToken()`, `saveGitHubToken()` |
+| `github-client.js` | **GitHub helpers** - CODEOWNERS parsing, reviewers | `getReviewersForFiles()`, `parseGitHubRepo()` |
+| `preset-loader.js` | **Preset system** - load tech-stack configurations | `loadPreset()`, `listPresets()` |
+| `task-id.js` | **Task ID extraction** - Jira, GitHub, Linear patterns | `getOrPromptTaskId()`, `formatWithTaskId()` |
+| `resolution-prompt.js` | **Issue resolution** - AI-friendly fix prompts | `generateResolutionPrompt()` |
+| `logger.js` | **Logging system** - centralized output with debug mode | `info()`, `warning()`, `error()`, `debug()` |
+| `interactive-ui.js` | **CLI UI components** - previews, prompts, spinners | `showPRPreview()`, `promptConfirmation()`, `promptMenu()` |
+| `telemetry.js` | **Local telemetry** - track JSON parsing, retries | `recordEvent()`, `displayStatistics()` |
+
+### Execution Flow
+
+#### Pre-commit Hook
 
-```gitignore
-# Claude Git Hooks
-.claude/
 ```
-
-Esto asegura que:
-
-- Los archivos de configuración de Claude específicos del proyecto no se suban al repositorio
-- Los archivos de debug temporales se ignoren
-- Cada desarrollador pueda tener sus propias preferencias de análisis
-
-Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas se agregarán al final solo si no están presentes.
-
-## 🎯 Funcionamiento
-
-### Hook pre-commit (Análisis de código)
-
-1. **Intercepta cada intento de commit**
-2. **Extrae y filtra archivos modificados**:
-    - Solo analiza: Java, XML, properties, yml, yaml
-    - Omite archivos mayores a 1MB
-    - Límite de 30 archivos por commit
-3. **Construye prompt inteligente**:
-    - Usa template de prompt desde `.claude/prompts/CLAUDE_ANALYSIS_PROMPT*.md`
-    - Lee las pautas desde `.claude/prompts/CLAUDE_PRE_COMMIT*.md`
-    - Incluye el diff completo para archivos nuevos
-    - Muestra solo cambios para archivos existentes
-4. **Envía a Claude CLI para revisión**
-5. **Procesa respuesta JSON estructurada**:
-    - blockingIssues siempre como objetos con localización precisa
-    - verifica `QUALITY_GATE`, muestra métricas y issues por severidad
-6. **Decisión final**:
-    - Si hay problemas críticos → genera prompt AI de resolución y bloquea commit
-    - Si todo está bien → commit procede
-7. **Generación de Prompt de Resolución AI** (opcional): Cuando se detectan problemas críticos:
-
-- Se genera automáticamente un archivo `claude_resolution_prompt.md`
-- Contiene información estructurada y AI-friendly de todos los issues
-- Incluye localización precisa (archivo, línea, método)
-- Puede copiarse a otra instancia de Claude para resolución automática
-
-### Hook prepare-commit-msg (Generación automática de mensajes)
-
-1. **Se activa cuando el mensaje es**:
-    - `"auto"`
-2. **Analiza los cambios del staging area**:
-    - Lista archivos modificados con estadísticas
-    - Incluye diffs completos para archivos < 1MB
-3. **Genera mensaje en formato Conventional Commits**:
-    - Determina tipo: feat, fix, docs, style, refactor, test, chore
-    - Crea título conciso y descriptivo
-    - Añade body con detalles si es necesario
-4. **Manejo de errores**:
-    - Si falla la generación → cancela el commit completamente
-    - No usa mensajes genéricos de fallback
-
-### Características adicionales
-
-- **Generación de información para Pull Requests**: `claude-hooks analyze-diff [branch]` para comparar rama local con rama origin, propone nombre para rama actual, título y detalles para pull request, da tips para verificar trabajo. Si se especifica branch, compara con origin/branch. Si no, compara con origin de la rama actual. Este comando genera automáticamente:
-    - 📝 Título de PR conciso (máx. 72 caracteres)
-    - 📄 Descripción detallada con markdown
-    - 🌿 Nombre de rama sugerido (formato: tipo/descripcion)
-    - 📋 Tipo de cambio (feature/fix/refactor/docs/test/chore)
-    - ⚠️ Indicador de breaking changes
-    - 🧪 Notas de testing recomendado
-    - 📝 Archivo `.claude-pr-analysis.json`
-- **Creación de PRs en GitHub (v2.5.0+)**: `claude-hooks create-pr [branch]` crea pull requests directamente en GitHub vía MCP. Extrae task-id de branch, genera metadata con Claude, detecta reviewers desde CODEOWNERS o config, aplica labels por preset, y muestra preview interactivo antes de crear
-- **Auto-actualización**: Verificación automática de versiones antes de cada commit con prompt interactivo para actualizar
-- **Comando update**: `claude-hooks update` para actualizar manualmente a la última versión
-- **Modo debug**: `claude-hooks --debug true` activa logging detallado para troubleshooting
-- **Análisis de PR**: Nuevo comando `analyze-diff` para generar información de Pull Requests
-- **Validación de dependencias**: Verifica que Claude CLI esté autenticado antes de ejecutar
-
-### Desactivar/Activar hooks
-
-```bash
-# Desactivar todos los hooks
-claude-hooks disable
-
-# Desactivar un hook específico
-claude-hooks disable pre-commit
-claude-hooks disable prepare-commit-msg
-
-# Habilitar todos los hooks
-claude-hooks enable
-
-# Habilitar un hook específico
-claude-hooks enable pre-commit
-claude-hooks enable prepare-commit-msg
-
-# Ver estado actual
-claude-hooks status
+git commit → templates/pre-commit (bash wrapper)
+  → lib/hooks/pre-commit.js
+  → getStagedFiles() → filter by preset extensions
+  → buildAnalysisPrompt() → analyzeCode() or analyzeCodeParallel()
+  → parse JSON response → exit 0 (pass) or exit 1 (block)
+  → if blocked: generates claude_resolution_prompt.md
 ```
 
-## ⚙️ Configuración
-
-### Scripts
-
-✨ **v2.0.0+**: Configuración en archivos Node.js dentro de `lib/hooks/`.
-
-En `lib/hooks/pre-commit.js`:
-
-- **`MAX_FILE_SIZE`**: Tamaño máximo de archivo a analizar (default: 1MB)
-- **`MAX_FILES`**: Número máximo de archivos por commit (default: 30)
-- **`ALLOWED_EXTENSIONS`**: Extensiones permitidas (default: .java, .xml, .properties, .yml, .yaml)
-
-En `lib/hooks/prepare-commit-msg.js`:
-
-- **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 1MB)
-
-### Pautas de Evaluación
-
-- **`CLAUDE_PRE_COMMIT.md`** - Criterios de evaluación de calidad
-
-### Templates de Prompts
-
-- **`CLAUDE_ANALYSIS_PROMPT.md`** - Estructura del prompt de análisis
-- **`CLAUDE_RESOLUTION_PROMPT.md`** - Template para generar prompts de resolución
-
-Todos estos archivos son personalizables y específicos de tu proyecto. Puedes:
-
-- Modificar los criterios de evaluación según estándares del equipo
-- Ajustar la estructura de los prompts para obtener respuestas más precisas
-- Personalizar el formato de salida del prompt de resolución
-
-## 🐛 Troubleshooting
+#### Commit Message Generation
 
-No hay... esto es la perfección hecha código.
-
-## 🔧 Desarrollo y Contribución
-
-### Estructura del Proyecto
-
-✨ **v2.0.0+**: Nueva arquitectura modular con ES6 modules.
-
-```
-claude-git-hooks/
-├── bin/
-│   └── claude-hooks                          # CLI principal (ES6 modules)
-├── lib/                                      # 🆕 Código Node.js modular
-│   ├── config.js                             # Configuración centralizada con merge
-│   ├── hooks/
-│   │   ├── pre-commit.js                     # Hook de análisis (Node.js)
-│   │   └── prepare-commit-msg.js             # Hook de mensajes (Node.js)
-│   └── utils/
-│       ├── logger.js                         # Sistema de logging centralizado
-│       ├── git-operations.js                 # Operaciones git abstractas
-│       ├── file-utils.js                     # Utilidades de sistema de archivos
-│       ├── claude-client.js                  # Cliente Claude CLI
-│       ├── prompt-builder.js                 # Constructor de prompts
-│       ├── resolution-prompt.js              # Generador de resolution prompts
-│       ├── preset-loader.js                  # Cargador de presets
-│       ├── installation-diagnostics.js       # Diagnósticos de instalación
-│       ├── claude-diagnostics.js             # Diagnósticos de errores Claude CLI
-│       ├── github-api.js                     # 🆕 Integración Octokit (determinista)
-│       ├── github-client.js                  # Cliente GitHub (CODEOWNERS, reviewers)
-│       ├── task-id.js                        # Extracción task-id (Jira, GitHub, Linear)
-│       ├── interactive-ui.js                 # UI interactiva CLI (preview, prompts)
-│       └── mcp-setup.js                      # Setup y detección MCP
-├── templates/
-│   ├── pre-commit                            # Bash wrapper (llama a lib/hooks/pre-commit.js)
-│   ├── prepare-commit-msg                    # Bash wrapper (llama a lib/hooks/prepare-commit-msg.js)
-│   ├── check-version.sh                      # Script de verificación de versión
-│   ├── CLAUDE_PRE_COMMIT.md            # Criterios de evaluación
-│   ├── CLAUDE_ANALYSIS_PROMPT.md       # Template de prompt para análisis
-│   ├── CLAUDE_RESOLUTION_PROMPT.md           # Template para resolución de issues
-│   ├── ANALYZE_DIFF.md                       # Template para análisis de diff (PR metadata)
-│   ├── CREATE_GITHUB_PR.md                   # Template para creación de PR
-│   ├── config.github.example.json            # 🆕 Ejemplo configuración GitHub
-│   └── settings.local.example.json           # 🆕 Ejemplo token local (gitignored)
-├── test/                                     # 🆕 Tests unitarios con Jest
-│   └── unit/
-│       └── logger.test.js                    # Tests del logger
-├── .claude/                                  # Directorio de configuración local (gitignore)
-│   └── settings.local.json                   # Configuración local del usuario
-├── jest.config.js                            # 🆕 Configuración Jest para ES6
-├── .eslintrc.json                            # 🆕 Configuración ESLint
-├── .prettierrc.json                          # 🆕 Configuración Prettier
-├── package.json                              # Configuración NPM (type: "module")
-├── package-lock.json                         # Lock file de NPM
-├── README.md                                 # Este archivo
-├── CHANGELOG.md                              # Historial de versiones
-└── .gitignore                                # Archivos ignorados por git
 ```
-
-### 🔌 Utility Modules Reference
-
-**Purpose**: Reusable modules for extending claude-hooks or building similar tools
-
-#### Core Utilities
-
-| Module                            | Purpose                               | Key Exports                                       | Usage Context                                  |
-| --------------------------------- | ------------------------------------- | ------------------------------------------------- | ---------------------------------------------- |
-| **`config.js`**                   | Centralized configuration management  | `getConfig()`, `defaults`                         | Priority merging: defaults < user < preset     |
-| **`logger.js`**                   | Structured logging with debug support | `info()`, `warning()`, `error()`, `debug()`       | Console output with context tracking           |
-| **`git-operations.js`**           | Git command abstractions              | `getRepoRoot()`, `getStagedFiles()`, `getDiff()`  | Safe git operations with error handling        |
-| **`file-utils.js`**               | File system operations                | `ensureDir()`, `writeFile()`                      | Repo-root-relative path handling               |
-| **`claude-client.js`**            | Claude CLI integration                | `analyzeCode()`, `analyzeCodeParallel()`          | Prompt execution with timeout/retry            |
-| **`prompt-builder.js`**           | Template-based prompts                | `buildAnalysisPrompt()`, `loadTemplate()`         | Dynamic prompt construction from .md files     |
-| **`preset-loader.js`**            | Preset system                         | `loadPreset()`, `listPresets()`, `loadTemplate()` | Metadata, config, template loading             |
-| **`resolution-prompt.js`**        | Issue resolution prompts              | `generateResolutionPrompt()`                      | AI-friendly error remediation prompts          |
-| **`installation-diagnostics.js`** | Installation error diagnostics        | `formatError()`, `getInstallationDiagnostics()`   | Installation error formatting with remediation |
-| **`claude-diagnostics.js`**       | Claude CLI error diagnostics          | `detectClaudeError()`, `formatClaudeError()`      | Rate limit, auth, network error detection      |
-| **`github-api.js`**               | Octokit GitHub integration            | `createPullRequest()`, `readCodeowners()`         | Deterministic PR creation, token resolution    |
-| **`github-client.js`**            | GitHub operations                     | `getReviewersForFiles()`, `parseGitHubRepo()`     | CODEOWNERS parsing, reviewer detection         |
-| **`task-id.js`**                  | Task ID extraction                    | `getOrPromptTaskId()`, `formatWithTaskId()`       | Jira, GitHub, Linear task-id extraction        |
-| **`interactive-ui.js`**           | Interactive CLI components            | `showPRPreview()`, `promptConfirmation()`         | Terminal UI helpers (spinners, menus)          |
-| **`mcp-setup.js`**                | MCP detection and setup               | `findGitHubTokenInDesktopConfig()`                | Claude Desktop config token resolution         |
-
-#### Using Utilities in Other Claude Instances
-
-**Example: Check installation health**
-
-```javascript
-import { formatError } from './lib/utils/installation-diagnostics.js';
-
-try {
-    // ... operation that may fail
-} catch (error) {
-    console.error(formatError('Operation failed', ['Additional context line']));
-    process.exit(1);
-}
+git commit -m "auto" → templates/prepare-commit-msg (bash wrapper)
+  → lib/hooks/prepare-commit-msg.js
+  → extract task-id from branch name
+  → generate message via Claude
+  → write to COMMIT_EDITMSG
 ```
 
-**Example: Load configuration**
+#### PR Creation
 
-```javascript
-import { getConfig } from './lib/config.js';
-
-const config = await getConfig();
-const maxFiles = config.analysis.maxFiles;
 ```
-
-**Example: Execute git operations**
-
-```javascript
-import { getRepoRoot, getStagedFiles } from './lib/utils/git-operations.js';
-
-const repoRoot = getRepoRoot();
-const files = getStagedFiles({ extensions: ['.js', '.ts'] });
+claude-hooks create-pr → bin/claude-hooks (router)
+  → lib/commands/create-pr.js
+  → validateToken() (github-api.js)
+  → parseGitHubRepo() (github-client.js)
+  → getReviewersForFiles() (CODEOWNERS + config)
+  → executeClaudeWithRetry() (metadata generation)
+  → createPullRequest() (Octokit API)
 ```
 
-**Example: Build custom prompts**
-
-```javascript
-import { buildAnalysisPrompt } from './lib/utils/prompt-builder.js';
+### Config Priority
 
-const prompt = await buildAnalysisPrompt({
-    templateName: 'CUSTOM_PROMPT.md',
-    files: filesData,
-    metadata: { REPO_NAME: 'my-repo' }
-});
+```
+defaults (lib/config.js)
+  < user config (.claude/config.json)
+  < preset config (.claude/presets/{name}/)
 ```
 
-**Note**: All utilities follow single-responsibility principle and include JSDoc documentation inline.
-
-### Configuración del Entorno de Desarrollo
-
-```bash
-# 1. Clonar el repositorio
-git clone https://github.com/pablorovito/claude-git-hooks.git
-cd claude-git-hooks
-
-# 2. Instalar dependencias (si las hubiera)
-npm install
+Preset always wins - tech-stack specific has priority over user preferences.
 
-# 3. Enlazar para desarrollo local
-npm link
+### Config Format (v2.8.0)
 
-# 4. Probar en un repositorio de prueba
-cd /path/to/test-repo
-claude-hooks install
+```json
+{
+  "version": "2.8.0",
+  "preset": "backend",
+  "overrides": {
+    "github": {
+      "pr": {
+        "defaultBase": "develop",
+        "reviewers": ["user"],
+        "autoPush": true,        // Auto-push unpublished branches (v2.11.0)
+        "pushConfirm": true,     // Prompt before push (v2.11.0)
+        "showCommits": true,     // Show commit preview (v2.11.0)
+        "verifyRemote": true     // Verify remote exists (v2.11.0)
+      }
+    },
+    "subagents": { "batchSize": 2 }
+  }
+}
 ```
 
-### Workflow de Desarrollo
+### Key Patterns
 
-#### 1. Modificar Hooks
+- **Factory**: `preset-loader.js` - dynamic config per tech-stack
+- **Template Method**: `prompt-builder.js` - prompts from .md templates
+- **Strategy**: `claude-client.js` - sequential vs parallel analysis
+- **Adapter**: `git-operations.js` - git commands to JS functions
+- **Command**: `lib/commands/*.js` - one module per CLI command
 
-✨ **v2.0.0+**: La lógica de los hooks está en `lib/hooks/`:
+### Modification Guide
 
-- `lib/hooks/pre-commit.js` - Lógica de análisis de código (Node.js ES6)
-- `lib/hooks/prepare-commit-msg.js` - Lógica de generación de mensajes (Node.js ES6)
-- `templates/pre-commit` - Bash wrapper que llama al script Node.js
-- `templates/prepare-commit-msg` - Bash wrapper que llama al script Node.js
+| To change... | Edit... |
+|--------------|---------|
+| CLI argument parsing | `bin/claude-hooks` |
+| Install workflow | `lib/commands/install.js` |
+| PR creation flow | `lib/commands/create-pr.js` |
+| Analysis logic | `lib/hooks/pre-commit.js` |
+| Message generation | `lib/hooks/prepare-commit-msg.js` |
+| Prompt templates | `templates/*.md` or `.claude/prompts/*.md` |
+| Preset definitions | `templates/presets/{name}/` |
+| Config defaults | `lib/config.js` |
+| GitHub integration | `lib/utils/github-api.js` |
+| Claude CLI calls | `lib/utils/claude-client.js` |
 
-#### 2. Probar Localmente
+### File Structure
 
-```bash
-# Después de modificar archivos, repo de claude-hooks
-npm link
-
-# En un repo de prueba
-claude-hooks install --force  # Fuerza reinstalación, luego probar lo que se desee
+```
+claude-git-hooks/
+├── bin/claude-hooks              # Thin CLI router - dispatch to commands
+├── lib/
+│   ├── config.js                 # Config system - load and merge
+│   ├── commands/                 # Command modules - one per CLI command
+│   │   ├── helpers.js            # Shared utilities - colors, output
+│   │   ├── install.js            # Install command - hooks, templates
+│   │   ├── hooks.js              # Hook management - enable/disable
+│   │   ├── analyze-diff.js       # Diff analysis - PR metadata
+│   │   ├── create-pr.js          # PR creation - Octokit workflow
+│   │   ├── setup-github.js       # Token setup - interactive config
+│   │   ├── presets.js            # Preset commands - list/set
+│   │   ├── update.js             # Self-update - npm latest
+│   │   ├── migrate-config.js     # Migration - legacy to v2.8.0
+│   │   ├── debug.js              # Debug mode - toggle verbose
+│   │   ├── telemetry-cmd.js      # Telemetry - show/clear stats
+│   │   └── help.js               # Help display - usage info
+│   ├── hooks/                    # Git hooks - Node.js logic
+│   │   ├── pre-commit.js         # Pre-commit analysis
+│   │   └── prepare-commit-msg.js # Message generation
+│   └── utils/                    # Reusable modules - shared logic
+├── templates/
+│   ├── pre-commit                # Bash wrapper - invokes Node.js
+│   ├── prepare-commit-msg        # Bash wrapper - invokes Node.js
+│   ├── *.md                      # Prompt templates
+│   └── presets/                  # Preset configurations
+└── test/unit/                    # Jest tests
 ```
 
-#### 3. Actualizar Documentación
+### Parallel Analysis (3+ files)
 
-- `README.md` - Documentación principal
-- `CHANGELOG.md` - Documentación principal
-- `README-NPM.md` - Para usuarios de NPM
+Files split into batches, each batch runs in separate Claude CLI process:
+- `batchSize: 1` → Maximum parallelism (1 file per process)
+- `batchSize: 2` → Balanced (2 files per process)
+- Results consolidated automatically
 
-#### 4. Versioning y Publicación
+### Hardcoded Defaults (v2.8.0)
 
-```bash
-# Actualizar versión
-npm version patch  # 1.0.0 -> 1.0.1
-npm version minor  # 1.0.0 -> 1.1.0
-npm version major  # 1.0.0 -> 2.0.0
+- Max file size: 1MB
+- Max files per commit: 20
+- Parallel analysis: enabled
+- Parallel model: haiku
+- Parallel batch size: 3
 
-# Publicar nueva versión
-npm publish
-```
+---
+
+More information: https://github.com/mscope-S-L/git-hooks