claude-git-hooks 2.17.2 → 2.18.0

package/CLAUDE.md

@@ -0,0 +1,820 @@
+# Repository Context
+
+## Purpose
+
+`claude-git-hooks` is an intelligent Git hooks system that integrates Claude CLI to automate code analysis, commit message generation, and PR creation. It functions as a pre-commit code quality tool (for pre-commit code quality checks) that blocks commits with critical issues and assists throughout the development workflow.
+
+**Main use cases:**
+
+1. **Pre-commit analysis**: Detects security issues, bugs, and code smells before each commit (blocks on CRITICAL/BLOCKER only)
+2. **Interactive analysis**: `claude-hooks analyze` - review all issues (INFO to BLOCKER) interactively before committing
+3. **Automatic messages**: Write `git commit -m "auto"` and Claude generates the message in Conventional Commits format with task-id extracted from branch
+4. **PR analysis**: `claude-hooks analyze-diff [branch]` generates title, description, and test plan for PRs
+5. **PR creation**: `claude-hooks create-pr [branch]` creates the PR on GitHub with automatic metadata (reviewers from CODEOWNERS, labels by preset)
+
+## Architecture
+
+### Technology Stack
+
+- **Runtime**: Node.js >=16.9.0 (compatible up to 24+)
+- **Module type**: ES6 modules (`"type": "module"` in package.json)
+- **Main dependencies**:
+    - `@octokit/rest`: GitHub client for PR creation (v2.5.0+)
+- **Dev dependencies**: Jest, ESLint, Prettier
+- **Distribution**: NPM global package (`npm install -g claude-git-hooks`)
+
+### Design Philosophy
+
+**Modular, decoupled, reusable code.** Each component has a single responsibility:
+
+- **bin/claude-hooks**: Thin CLI router - only argument parsing and command dispatch
+- **lib/commands/**: Command modules - one file per CLI command, self-contained logic
+- **lib/hooks/**: Git hook logic - Node.js implementations invoked by bash wrappers
+- **lib/utils/**: Reusable utilities - shared across commands, no CLI dependencies
+- **templates/**: Static assets - copied during installation, user-customizable
+
+This separation enables:
+
+- **Testability**: Each module can be unit tested independently
+- **Maintainability**: Changes to one command don't risk breaking others
+- **Discoverability**: Find code by filename matching command name
+- **Extensibility**: Add new commands by creating new module files
+
+### Directory Structure
+
+```
+claude-git-hooks/
+├── bin/
+│   └── claude-hooks                  # Thin CLI router - argument parsing, command dispatch
+├── lib/
+│   ├── config.js                     # Config system - load/merge with priority
+│   ├── commands/                     # Command modules - one file per CLI command
+│   │   ├── helpers.js                # Shared CLI utilities - colors, output, platform
+│   │   ├── install.js                # Install command - dependencies, hooks, templates
+│   │   ├── hooks.js                  # Hook management - enable, disable, status, uninstall
+│   │   ├── analyze-diff.js           # Diff analysis - generate PR metadata from git diff
+│   │   ├── create-pr.js              # PR creation - full Octokit workflow
+│   │   ├── setup-github.js           # Token setup - interactive GitHub configuration
+│   │   ├── presets.js                # Preset management - list, set, show current
+│   │   ├── update.js                 # Self-update - check and install latest version
+│   │   ├── migrate-config.js         # Config migration - legacy to v2.8.0 format
+│   │   ├── debug.js                  # Debug toggle - enable/disable verbose logging
+│   │   ├── telemetry-cmd.js          # Telemetry commands - show/clear statistics
+│   │   ├── bump-version.js           # Version management - bump with commit, CHANGELOG and tags
+│   │   ├── generate-changelog.js     # CHANGELOG generation - standalone command
+│   │   └── help.js                   # Help, AI help, and report-issue commands
+│   ├── hooks/                        # Git hooks - Node.js implementations
+│   │   ├── pre-commit.js             # Pre-commit analysis - code quality gate
+│   │   └── prepare-commit-msg.js     # Message generation - auto commit messages
+│   └── utils/                        # Reusable modules - shared logic
+│       ├── analysis-engine.js        # Shared analysis logic - file data, orchestration, results (v2.13.0)
+│       ├── claude-client.js          # Claude CLI wrapper - spawn, retry, parallel
+│       ├── prompt-builder.js         # Prompt construction - load templates, replace vars
+│       ├── git-operations.js         # Git abstractions - staged files, diff, repo root, push, commit
+│       ├── file-utils.js             # File operations - repo-relative paths
+│       ├── logger.js                 # Logging system - centralized output, debug mode
+│       ├── preset-loader.js          # Preset system - load tech-stack configurations
+│       ├── pr-metadata-engine.js     # PR metadata generation - branch context, diff reduction, metadata (v2.14.0)
+│       ├── github-api.js             # Octokit integration - PR creation, token validation
+│       ├── github-client.js          # GitHub helpers - CODEOWNERS parsing, reviewers
+│       ├── task-id.js                # Task ID extraction - Jira, GitHub, Linear patterns
+│       ├── interactive-ui.js         # CLI UI components - previews, prompts, spinners
+│       ├── resolution-prompt.js      # Issue resolution - AI-friendly fix prompts
+│       ├── installation-diagnostics.js # Installation diagnostics - error context
+│       ├── claude-diagnostics.js     # Claude errors - rate limit, auth, formatting
+│       ├── which-command.js          # Executable resolution - cross-platform paths
+│       ├── sanitize.js               # Input sanitization - shell safety
+│       ├── telemetry.js              # Local telemetry - track JSON parsing, retries
+│       ├── version-manager.js        # Version detection - parse, increment, validate, per-file targets (v2.12.0)
+│       ├── git-tag-manager.js        # Git tag operations - create, list, compare, push, isSemverTag (v2.12.0)
+│       └── changelog-generator.js    # CHANGELOG generation - Claude-powered analysis (v2.12.0)
+├── templates/                        # Static assets - copied during install
+│   ├── pre-commit                    # Bash wrapper - invokes lib/hooks/pre-commit.js
+│   ├── prepare-commit-msg            # Bash wrapper - invokes lib/hooks/prepare-commit-msg.js
+│   ├── check-version.sh              # Version check - auto-update prompt
+│   ├── CLAUDE_PRE_COMMIT.md          # Analysis criteria - evaluation guidelines
+│   ├── CLAUDE_ANALYSIS_PROMPT.md     # Analysis prompt - code review template
+│   ├── CLAUDE_RESOLUTION_PROMPT.md   # Resolution prompt - issue fix template
+│   ├── ANALYZE_DIFF.md               # PR analysis - diff review template
+│   ├── GENERATE_CHANGELOG.md         # CHANGELOG generation - commit analysis template (v2.12.0)
+│   ├── HELP_QUERY.md                 # AI help - question answering with NEED_MORE_CONTEXT protocol (v2.18.0)
+│   ├── HELP_REPORT_ISSUE.md          # Report issue - question generation from templates (v2.18.0)
+│   ├── HELP_COMPOSE_ISSUE.md         # Report issue - issue body composition from answers (v2.18.0)
+│   ├── config.example.json           # Config example - minimal setup
+│   ├── config.advanced.example.json  # Config advanced - all options documented
+│   ├── settings.local.example.json   # Local settings - token storage template
+│   └── CUSTOMIZATION_GUIDE.md        # Customization - preset creation guide
+└── test/                             # Tests - Jest with ES6 modules
+    └── unit/
+        └── *.test.js
+```
+
+### Execution Architecture
+
+**1. Git Hooks (bash wrappers → Node.js)**
+
+```
+.git/hooks/pre-commit (bash)
+  ↓
+node lib/hooks/pre-commit.js
+  ↓ (reads config + preset)
+lib/config.js → merges: defaults < user config < preset config
+  ↓ (gets staged files)
+lib/utils/git-operations.js → getStagedFiles()
+  ↓ (filters by preset extensions + size)
+lib/utils/file-operations.js → filterFiles()
+  ↓ (builds file data + runs analysis)
+lib/utils/analysis-engine.js → buildFilesData(), runAnalysis()
+  ↓ (orchestrates parallel/sequential Claude CLI calls)
+lib/utils/claude-client.js → analyzeCode() or analyzeCodeParallel()
+  ↓ (displays results)
+lib/utils/analysis-engine.js → displayResults()
+  ↓ (if blocking issues found)
+lib/utils/resolution-prompt.js → generates claude_resolution_prompt.md
+  ↓
+exit 1 (blocks commit) or exit 0 (allows commit)
+```
+
+**2. Configuration System (priorities)**
+
+```
+defaults (lib/config.js)
+  ↓ overridden by
+user config (.claude/config.json)
+  ↓ overridden by
+preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
+```
+
+**Rationale**: User configures general preferences, preset provides tech-stack-specific overrides.
+
+**Config format (v2.8.0):**
+
+```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 }
+    }
+}
+```
+
+**Hardcoded defaults (v2.8.0):**
+
+| Parameter            | Value   | Notes                        |
+| -------------------- | ------- | ---------------------------- |
+| Max file size        | 1MB     | Files larger are skipped     |
+| Max files per commit | 20      | Excess files trigger warning |
+| Parallel analysis    | enabled | Always on for 3+ files       |
+| Parallel model       | haiku   | Fast, cost-effective         |
+| Parallel batch size  | 3       | Files per Claude process     |
+| Analysis timeout     | 300s    | Per-batch timeout            |
+| Commit msg timeout   | 300s    | Message generation timeout   |
+| PR metadata timeout  | 180s    | Engine default (reads config)|
+
+**3. Presets System**
+
+| Preset      | Extensions                                                                 | Stack                    | Key Verifications                                   |
+| ----------- | -------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------- |
+| `backend`   | `.java`, `.xml`, `.yml`, `.yaml`                                           | Spring Boot + SQL Server | REST API, JPA, OWASP Top 10, SQL injection          |
+| `frontend`  | `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss`, `.html`                     | React + Material-UI      | Hooks, XSS, a11y, performance                       |
+| `fullstack` | backend + frontend                                                         | Spring Boot + React      | **API contract consistency** (priority)             |
+| `database`  | `.sql`                                                                     | SQL Server               | SQL injection, UPDATE/DELETE without WHERE, indexes |
+| `ai`        | `.js`, `.json`, `.md`, `.sh`                                               | Node.js + Claude API     | Prompts, API key security, cross-platform           |
+| `default`   | `.js`, `.sh`, `.py`, `.rb`, `.pl`, `.sql`, `.yaml`, `.json`, `.xml`, `.md` | Multiple                 | Quality and security fundamentals                   |
+
+**4. Parallel Analysis (v2.2.0+)**
+
+When 3+ files are present, the system divides into batches and executes multiple `claude` CLI processes in parallel:
+
+```
+4 files + batchSize=2
+  ↓
+Batch 1: [file1, file2] → claude CLI process #1 (parallel)
+Batch 2: [file3, file4] → claude CLI process #2 (parallel)
+  ↓
+Wait for both → consolidate results
+```
+
+- **Configuration**: `.claude/config.json` → `subagents.batchSize`, `subagents.model` (haiku/sonnet/opus)
+- **Speed-up**: ~4x faster with batch=1 (1 file per process)
+
+### Key Module Exports
+
+**Command Modules (`lib/commands/`):**
+
+| Module                  | Purpose                   | Key Exports                                                                   |
+| ----------------------- | ------------------------- | ----------------------------------------------------------------------------- |
+| `helpers.js`            | Shared CLI utilities      | `colors`, `error()`, `success()`, `info()`, `checkGitRepo()`, `getGitHooksPath()`, `Entertainment` |
+| `install.js`            | Installation logic        | `runInstall()`, `extractLegacySettings()`                                     |
+| `hooks.js`              | Hook management           | `runEnable()`, `runDisable()`, `runStatus()`, `runUninstall()`                |
+| `analyze.js`            | Interactive code analysis | `runAnalyze()`                                                                |
+| `analyze-diff.js`       | Diff analysis             | `runAnalyzeDiff()`                                                            |
+| `create-pr.js`          | PR creation               | `runCreatePr()`                                                               |
+| `bump-version.js`       | Version management        | `runBumpVersion()`                                                            |
+| `generate-changelog.js` | CHANGELOG generation      | `runGenerateChangelog()`                                                      |
+| `setup-github.js`       | Token setup               | `runSetupGitHub()`                                                            |
+| `presets.js`            | Preset management         | `runShowPresets()`, `runSetPreset()`, `runCurrentPreset()`                    |
+| `update.js`             | Self-update               | `runUpdate()`                                                                 |
+| `migrate-config.js`     | Config migration          | `runMigrateConfig()`                                                          |
+| `debug.js`              | Debug toggle              | `runSetDebug()`                                                               |
+| `telemetry-cmd.js`      | Telemetry commands        | `runShowTelemetry()`, `runClearTelemetry()`                                   |
+| `help.js`               | Help, AI help, report-issue | `runShowHelp()`, `showStaticHelp()`, `runShowVersion()`                     |
+
+**Utility Modules (`lib/utils/`):**
+
+| Module                   | Purpose               | Key Exports                                                                                                                                                                    |
+| ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `lib/config.js`          | Config system         | `getConfig()`                                                                                                                                                                  |
+| `analysis-engine.js`     | Shared analysis logic | `buildFileData()`, `buildFilesData()`, `runAnalysis()`, `consolidateResults()`, `hasBlockingIssues()`, `hasAnyIssues()`, `displayResults()`, `displayIssueSummary()` (v2.13.0) |
+| `claude-client.js`       | Claude CLI wrapper    | `analyzeCode()`, `analyzeCodeParallel()`, `executeClaudeWithRetry()`                                                                                                           |
+| `prompt-builder.js`      | Prompt construction   | `buildAnalysisPrompt()`, `loadPrompt()`                                                                                                                                        |
+| `git-operations.js`      | Git abstractions      | `getStagedFiles()`, `getUnstagedFiles()`, `getAllTrackedFiles()`, `getDiff()`, `getRepoRoot()`, `getBranchPushStatus()`, `pushBranch()`, `createCommit()`, `fetchRemote()`, `branchExists()`, `getRemoteBranches()`, `resolveBaseBranch()`, `getChangedFilesBetweenRefs()`, `getDiffBetweenRefs()`, `getCommitsBetweenRefs()` |
+| `pr-metadata-engine.js`  | PR metadata generation | `getBranchContext()`, `buildDiffPayload()`, `generatePRMetadata()`, `analyzeBranchForPR()` (v2.14.0) |
+| `git-tag-manager.js`     | Git tag operations    | `createTag()`, `pushTags()`, `getLocalTags()`, `getRemoteTags()`, `compareLocalAndRemoteTags()`, `tagExists()` (v2.12.0)                                                       |
+| `version-manager.js`     | Version management    | `discoverVersionFiles()`, `getDiscoveryResult()`, `readVersionFromFile()`, `writeVersionToFile()`, `updateVersionFiles()`, `modifySuffix()`, `incrementVersion()`, `parseVersion()`, `validateVersionFormat()`, `compareVersions()`, `validateVersionAlignment()` (v2.15.5)                             |
+| `changelog-generator.js` | CHANGELOG generation  | `generateChangelogEntry()`, `updateChangelogFile()`, `getLastFinalVersionTag()`, `getCommitsSinceTag()` (v2.12.0)                                                              |
+| `github-api.js`          | Octokit integration   | `createPullRequest()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()`                                                |
+| `github-client.js`       | GitHub helpers        | `getReviewersForFiles()`, `parseGitHubRepo()`                                                                                                                                  |
+| `preset-loader.js`       | Preset system         | `loadPreset()`, `listPresets()`                                                                                                                                                |
+| `task-id.js`             | Task ID extraction    | `getOrPromptTaskId()`, `formatWithTaskId()`                                                                                                                                    |
+| `logger.js`              | Logging system        | `info()`, `warning()`, `error()`, `debug()`                                                                                                                                    |
+| `resolution-prompt.js`   | Issue resolution      | `generateResolutionPrompt()`                                                                                                                                                   |
+| `interactive-ui.js`      | CLI UI components     | `showPRPreview()`, `promptConfirmation()`, `promptMenu()`, `promptToggleList()`, `promptEditField()`, `promptUserConfirmation()`                                                                                          |
+| `telemetry.js`           | Local telemetry       | `recordEvent()`, `displayStatistics()`                                                                                                                                         |
+
+### Design Patterns
+
+1. **Command Pattern**: `lib/commands/*.js` - each CLI command is a self-contained module
+2. **Factory Pattern**: `preset-loader.js` loads configurations dynamically per tech-stack
+3. **Template Method**: `prompt-builder.js` builds prompts from markdown templates
+4. **Strategy Pattern**: `claude-client.js` selects between sequential or parallel analysis
+5. **Adapter Pattern**: `git-operations.js` abstracts git commands into JS functions
+6. **Singleton Pattern**: `config.js` loads configuration once per execution
+
+### Key Data Flows
+
+**Flow 1: Pre-commit with blocking**
+
+```
+git commit
+  → hook reads staged files
+  → filters by preset extensions
+  → builds prompt with diff
+  → Claude analyzes → detects SQL injection (CRITICAL)
+  → generates resolution prompt
+  → exit 1 → COMMIT BLOCKED
+```
+
+**Flow 1.5: Interactive analysis command (v2.13.0)**
+
+```
+claude-hooks analyze
+  → runs outside git hook context (stdin works)
+  → getStagedFiles() → buildFilesData() → runAnalysis()
+  → displayIssueSummary() → shows all severity levels (or "No issues found")
+  → promptUserConfirmation() → interactive menu:
+    → [y] Continue - executes createCommit('auto', { noVerify: true })
+    → [n] Abort - generates resolution prompt
+    → [v] View - shows detailed issues → returns to menu
+  → on continue: git commit -m "auto" --no-verify
+    → prepare-commit-msg hook generates message via Claude
+    → commit created with auto-generated message
+```
+
+**Flow 2: Commit with automatic message**
+
+```
+git commit -m "auto"
+  → hook extracts task-id from branch (feature/IX-123-add-auth)
+  → Claude generates message → "[IX-123] feat: add user authentication"
+  → writes to .git/COMMIT_EDITMSG
+  → commit proceeds with generated message
+```
+
+**Flow 3: Analyze diff (v2.14.0)**
+
+```
+claude-hooks analyze-diff develop
+  → lib/commands/analyze-diff.js (thin wrapper)
+  → analyzeBranchForPR() (pr-metadata-engine.js)
+    → fetchRemote() → resolveBaseBranch() (suggests similar branches if not found)
+    → getChangedFilesBetweenRefs() → getCommitsBetweenRefs()
+    → buildDiffPayload() → tiered reduction (context → proportional → stat-only)
+    → executeClaudeWithRetry() → parses PRMetadata
+  → formats metadata to console
+  → saves to .claude/out/pr-analysis.json
+```
+
+**Flow 4: PR creation (with auto-push v2.11.0, engine v2.14.0)**
+
+```
+claude-hooks create-pr develop
+  → checks branch push status (unpublished/unpushed commits)
+  → shows commit preview → prompts for confirmation
+  → pushes branch to remote (if needed)
+  → reads CODEOWNERS → detects reviewers
+  → reads config → applies label rules per preset
+  → analyzeBranchForPR() (pr-metadata-engine.js) → generates metadata
+  → interactive preview → user confirms
+  → Octokit creates PR on GitHub
+```
+
+**Flow 5: Version bump with per-file editing (v2.16.0)**
+
+```
+claude-hooks bump-version patch --interactive
+  → validatePrerequisites() → clean working directory, valid branch, remote
+  → discoverVersionFiles() → recursive scan (max 3 levels)
+  → displayDiscoveryTable() → shows all discovered files with versions
+  → promptFileSelection() → interactive menu:
+    → [a] Update all files - all files get same newVersion
+    → [s] Select files - toggle list to pick subset
+    → [e] Edit per file - promptEditField() per file:
+      → user enters custom version per file (Enter keeps calculated version)
+      → validateVersionFormat() → rejects invalid entries
+      → stores file.targetVersion on each descriptor
+    → [c] Cancel
+  → incrementVersion() / modifySuffix() → calculates newVersion (used for tag + commit)
+  → updateVersionFiles() → uses file.targetVersion || newVersion per file
+  → createTag(newVersion) → tag reflects primary release version
+  → commit message uses newVersion
+```
+
+**Per-file version design**: `VersionFileDescriptor` gains an optional `targetVersion` property at runtime, set only by option 'e'. When present, `updateVersionFiles()` writes `targetVersion` instead of the global `newVersion`. The tag and commit message always use the calculated `newVersion`.
+
+## Code Conventions
+
+### General Style
+
+- **Format**: Prettier (config in `.prettierrc.json`)
+- **Linting**: ESLint 8.57.0 (config in `.eslintrc.json`)
+- **Indentation**: 4 spaces
+- **Quotes**: Single quotes (strings), double quotes (HTML/imports)
+- **Semicolons**: Required
+
+### Naming
+
+- **Files**: `kebab-case.js` (e.g., `claude-client.js`, `git-operations.js`)
+- **Functions**: `camelCase()` (e.g., `getStagedFiles()`, `buildAnalysisPrompt()`)
+- **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_FILE_SIZE`, `ALLOWED_EXTENSIONS`)
+- **Classes**: Not applicable (no classes, only exported functions)
+- **Private variables**: `_` prefix (e.g., `_internalHelper()`)
+
+### Exports
+
+**Preferred pattern - Named exports:**
+
+```javascript
+// lib/utils/example.js
+export function doSomething() { ... }
+export function doOtherThing() { ... }
+
+// consumer
+import { doSomething, doOtherThing } from './utils/example.js';
+```
+
+**Avoid default exports** (except in `bin/claude-hooks` per CLI convention).
+
+### Error Handling
+
+**Standard pattern:**
+
+```javascript
+import { error } from './utils/logger.js';
+
+try {
+    const result = dangerousOperation();
+    return result;
+} catch (err) {
+    error(`Failed to perform operation: ${err.message}`);
+    process.exit(1); // In hooks and CLI commands
+    // or throw err; // In library functions
+}
+```
+
+**Specific errors:**
+
+- Git operations → `execSync()` with try-catch, log and exit
+- Claude CLI → retry logic in `claude-client.js`, configurable timeout
+- GitHub API → catch `@octokit/request-error`, user-friendly formatting
+
+### Logging
+
+```javascript
+import { info, warning, error, debug } from './utils/logger.js';
+
+info('✅ Operation completed'); // User-facing messages
+warning('⚠️ Non-blocking issue detected'); // Warnings
+error('❌ Critical failure'); // Errors
+debug('Detailed diagnostic info'); // Only shown when debug=true
+```
+
+**Debug mode**: Activate with `claude-hooks --debug true` or in `.claude/config.json`.
+
+### Async/Await
+
+**Prefer async/await over callbacks:**
+
+```javascript
+// ✅ GOOD
+async function analyzeCode(prompt) {
+    const result = await spawnClaude(prompt);
+    return result;
+}
+
+// ❌ BAD
+function analyzeCode(prompt, callback) {
+    spawnClaude(prompt, callback);
+}
+```
+
+### Reusable Modules
+
+All modules in `lib/utils/` must:
+
+1. Export pure functions (no global side effects)
+2. Include inline JSDoc documentation
+3. Accept configuration via parameters (no globals)
+4. Return structured results (objects or arrays)
+5. Log with `logger.js` (no direct `console.log`)
+
+## Workflow
+
+### Branching Strategy
+
+This repository follows **simplified GitHub Flow**:
+
+- **Main branch**: `main` (protected)
+- **Feature branches**: `feature/issue-description` or `feature/TASK-ID-description`
+- **Fix branches**: `fix/issue-description`
+- **Hotfix branches**: `hotfix/urgent-description`
+
+**Rules:**
+
+1. All changes require PR to `main`
+2. No direct commits to `main`
+3. PRs require review (auto-merge NOT allowed)
+
+### Development Process
+
+**1. Initial setup (first time)**
+
+```bash
+git clone https://github.com/mscope-S-L/git-hooks.git
+cd git-hooks
+npm install
+npm link  # Install globally as symlink for development
+```
+
+**2. Create feature branch**
+
+```bash
+git checkout -b feature/new-functionality
+# or with task-id: feature/IX-123-new-functionality
+```
+
+**3. Iterative development**
+
+```bash
+# Make changes...
+npm run lint        # Check linting
+npm run test        # Run tests
+git add .
+git commit -m "feat: add new functionality"
+# Hooks execute automatically
+```
+
+**4. Local testing**
+
+Test changes in a test repository:
+
+```bash
+# In test repo
+cd /path/to/test-repo
+claude-hooks install --force --skip-auth  # Reinstall from symlink
+git commit -m "test"  # Test hook
+```
+
+**5. Create PR**
+
+```bash
+git push -u origin feature/new-functionality
+claude-hooks analyze-diff main  # Generate PR metadata
+# or directly:
+claude-hooks create-pr main  # Create PR on GitHub (if MCP configured)
+```
+
+### CI/CD
+
+**Currently**: No automated CI/CD (GitHub Actions pending).
+
+**Manual verifications before merge:**
+
+1. `npm run lint` → passes
+2. `npm run test` → all tests pass
+3. Manual testing in test repo
+4. Peer code review
+5. CHANGELOG.md updated
+
+### Versioning
+
+We follow **Semantic Versioning** (MAJOR.MINOR.PATCH):
+
+- **MAJOR**: Breaking changes (e.g., 1.x → 2.0 with ES6 migration)
+- **MINOR**: New features without breaking changes (e.g., 2.2 → 2.3 with presets)
+- **PATCH**: Bug fixes (e.g., 2.6.0 → 2.6.1 with spawn ENOENT fix)
+
+**Update version:**
+
+```bash
+npm version patch  # 2.6.1 → 2.6.2
+npm version minor  # 2.6.1 → 2.7.0
+npm version major  # 2.6.1 → 3.0.0
+```
+
+**Publish to NPM:**
+
+```bash
+npm publish
+```
+
+### Conventional Commits
+
+Format: `<type>(<scope>): <subject>`
+
+**Types:**
+
+- `feat`: New functionality
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting (no logic change)
+- `refactor`: Refactoring without functional change
+- `test`: Add or modify tests
+- `chore`: Maintenance (deps, config)
+- `perf`: Performance improvements
+
+**Optional scopes:**
+
+- `hooks`: Changes in pre-commit or prepare-commit-msg
+- `presets`: Preset system
+- `github`: GitHub integration
+- `cli`: Main CLI commands
+- `config`: Configuration system
+- `windows`: Windows-specific fixes
+
+**Examples:**
+
+```
+feat(presets): add database preset for SQL analysis
+fix(windows): resolve spawn ENOENT with .cmd files
+docs: update CLAUDE.md with architecture details
+chore(deps): upgrade @octokit/rest to v21
+```
+
+## Useful Commands
+
+### Development
+
+```bash
+# Installation and setup
+npm install                           # Install dependencies
+npm link                              # Install globally as symlink
+npm unlink                            # Uninstall global symlink
+
+# Testing
+npm test                              # Run all tests (Jest)
+npm run test:watch                    # Tests in watch mode
+npm run test:coverage                 # Coverage report
+
+# Linting and formatting
+npm run lint                          # Check ESLint
+npm run lint:fix                      # Auto-fix ESLint issues
+npm run format                        # Format with Prettier
+
+# Versioning
+npm version patch|minor|major         # Bump version
+npm publish                           # Publish to NPM
+```
+
+### Package CLI
+
+```bash
+# Hook installation in a repo
+claude-hooks install                  # Interactive installation
+claude-hooks install --force          # Reinstall without confirmation
+claude-hooks install --skip-auth      # Skip Claude verification
+
+# Hook management
+claude-hooks status                   # View current status
+claude-hooks enable [hook]            # Enable all or specific hook
+claude-hooks disable [hook]           # Disable all or specific hook
+claude-hooks uninstall                # Completely uninstall
+
+# Presets
+claude-hooks presets                  # List available presets
+claude-hooks --set-preset backend     # Change preset
+claude-hooks preset current           # View current preset
+
+# Analysis and PRs
+claude-hooks analyze-diff [branch]    # Analyze diff for PR
+claude-hooks create-pr [branch]       # Create PR on GitHub
+claude-hooks setup-github             # Configure GitHub token
+
+# Version management
+claude-hooks bump-version patch       # Bump version (commits, tags locally)
+claude-hooks bump-version minor --suffix SNAPSHOT  # With suffix
+claude-hooks bump-version major --update-changelog # With CHANGELOG
+claude-hooks bump-version patch --push             # Push tag immediately
+claude-hooks bump-version patch --no-commit        # Manual workflow
+claude-hooks bump-version patch --interactive      # Force file selection menu
+claude-hooks generate-changelog       # Generate CHANGELOG only
+
+# Help and issue reporting
+claude-hooks help "how do presets work?"  # AI-powered help (uses CLAUDE.md)
+claude-hooks help --report-issue          # Interactive issue creation
+
+# Debugging
+claude-hooks --debug true             # Enable debug mode
+claude-hooks --debug false            # Disable debug mode
+claude-hooks --debug status           # View debug status
+
+# Auto-update
+claude-hooks update                   # Update to latest version
+```
+
+### Git with Active Hooks
+
+```bash
+# Normal commit with analysis
+git commit -m "feat: new functionality"
+
+# Commit with automatic message
+git commit -m "auto"  # Claude generates the message
+
+# Skip analysis (emergencies)
+git commit --no-verify -m "hotfix: urgent"
+
+# Amend last commit
+git commit --amend
+```
+
+### Local Testing in Test Repo
+
+```bash
+# Initial setup
+cd /path/to/test-repo
+claude-hooks install --force --skip-auth
+
+# After changes in claude-hooks
+# (npm link is already active, no need to reinstall)
+cd /path/to/test-repo
+git add test.txt
+git commit -m "test: validate changes"
+# Hooks use local version automatically
+```
+
+## Testing
+
+### Test Framework
+
+- **Framework**: Jest with ES6 modules (`--experimental-vm-modules`)
+- **Location**: `test/unit/*.test.js`
+- **Naming**: `{module-name}.test.js` matches `lib/utils/{module-name}.js`
+- **Run**: `npm test` (all), `npm run test:watch` (watch mode)
+
+### Test Patterns
+
+```javascript
+// test/unit/example.test.js
+import { functionToTest } from '../../lib/utils/example.js';
+
+describe('functionToTest', () => {
+    it('should handle normal input', () => {
+        const result = functionToTest('input');
+        expect(result).toBe('expected');
+    });
+
+    it('should throw on invalid input', () => {
+        expect(() => functionToTest(null)).toThrow('Invalid input');
+    });
+});
+```
+
+### Mocking
+
+```javascript
+// Mock child_process for git/claude commands
+import { jest } from '@jest/globals';
+import { execSync } from 'child_process';
+
+jest.mock('child_process');
+execSync.mockReturnValue('mocked output');
+```
+
+### Coverage
+
+No enforced threshold. Focus on critical paths:
+
+- `claude-client.js` - Claude CLI interaction
+- `git-operations.js` - Git command abstraction
+- `config.js` - Configuration merging
+
+## Restrictions
+
+### What Claude should NOT do in this repository
+
+1. **DO NOT add interactive prompts to git hooks**
+    - Git hooks run with stdin redirected from `/dev/null`
+    - Readline-based prompts cannot read user input in hook context
+    - Works in IDE integrations (VSCode, IntelliJ) but breaks in terminal
+    - **Solution**: Use `claude-hooks analyze` command instead (runs outside hook context)
+    - **Rationale**: Discovered through manual testing in Issue #20
+
+2. **DO NOT modify bash wrappers without corresponding Node.js changes**
+    - `templates/pre-commit` and `templates/prepare-commit-msg` are wrappers
+    - Real logic is in `lib/hooks/*.js`
+    - Changes to bash should be minimal (only Node.js invocation)
+
+3. **DO NOT use `shell: true` in `spawn()` calls**
+    - Deprecated in Node.js 24 (DEP0190)
+    - Use `which-command.js` to resolve executable paths
+    - **Exception**: Windows with `.cmd`/`.bat` requires `cmd.exe /c` wrapper
+
+4. **DO NOT modify config priority order**
+    - Maintain: defaults < user config < preset config
+    - Preset always wins (tech-stack specific has priority over user preferences)
+
+5. **DO NOT create duplicate config files**
+    - Single `.claude/config.json` per repo
+    - Presets live in `.claude/presets/{name}/`
+    - Do not create `.env` or similar files for configuration
+
+6. **DO NOT make breaking changes without MAJOR version bump**
+    - Changes in config.json structure → MAJOR
+    - Changes in CLI arguments → MAJOR
+    - Changes in template format → MINOR if backward compatible, otherwise MAJOR
+
+7. **DO NOT hardcode absolute paths**
+    - Use `getRepoRoot()` from `git-operations.js`
+    - All paths relative to repo root
+    - Exception: paths in `PATH` resolved with `which-command.js`
+
+8. **DO NOT use `console.log` directly**
+    - Always use `logger.js`: `info()`, `warning()`, `error()`, `debug()`
+    - Enables centralized output control and debug mode
+
+9. **DO NOT execute Claude CLI without timeout**
+    - Always configure timeout (default: 150s analysis, 180s commit msg)
+    - Timeout configurable in `.claude/config.json`
+
+10. **DO NOT ignore platform-specific issues**
+    - Test changes on Windows, Linux, and macOS
+    - Path separators: use `path.join()` (no hardcoded `/`)
+    - Line endings: templates use LF, convert on install if needed
+
+11. **DO NOT commit secrets**
+    - `.claude/settings.local.json` is in `.gitignore`
+    - GitHub tokens should go in settings.local or env vars
+    - Never in `.claude/config.json` (tracked)
+
+12. **DO NOT modify project `.gitignore` without consultation**
+    - `.claude/` is ignored by design (user-specific)
+    - `node_modules/` obvious
+    - New entries must be justified
+
+13. **DO NOT add dependencies without validation**
+    - Only 1 runtime dependency currently: `@octokit/rest`
+    - New deps must be justified (no built-in alternative?)
+    - Dev deps are OK if they improve DX (testing, linting)
+
+14. **DO NOT perform git operations add, commit, push unless asked to**
+    - Git flow associated with normal development must be left to human user
+
+### Technical Limitations
+
+1. **Node.js versions**: >=16.9.0 required (ES6 module features)
+2. **Claude CLI**: Must be installed and authenticated externally
+3. **Git**: Requires initialized repo (doesn't work outside git repos)
+4. **Parallel analysis**: Minimum 3 files to activate
+5. **File size**: Default max 1MB per file (configurable)
+6. **Max files**: Default 30 files per commit (configurable)
+7. **GitHub API**: Rate limits apply (5000 req/hour authenticated)
+
+### Security Considerations
+
+1. **Input sanitization**: Use `sanitize.js` for user inputs in shell commands
+2. **Token storage**: GitHub tokens in settings.local (gitignored) or env vars, NEVER tracked
+3. **Shell injection**: Avoid `shell: true`, use arrays in spawn()
+4. **Path traversal**: Validate relative paths before file operations
+5. **Secrets in diffs**: Hook should NOT prevent commits with secrets (user responsibility)