claude-git-hooks 2.13.0 → 2.14.1

package/CHANGELOG.md

@@ -5,6 +5,44 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.14.1] - 2026-02-06
+
+### 🔧 Changed
+- Improved `bump-version` command workflow - now automatically stages and commits version changes with conventional commit format before tag creation
+- Enhanced `bump-version` command flexibility - added `--no-commit` flag for manual workflows where users prefer to commit changes themselves
+- Improved error handling in `bump-version` - provides clearer guidance when staging or committing fails, with manual fallback instructions
+- Enhanced next-steps guidance in `bump-version` output - adapts instructions based on flags used (--no-commit, --no-push, --no-tag)
+
+### 🐛 Fixed
+- Fixed `bump-version` workflow inconsistency - prevented tag creation when using `--no-commit` flag, as tags should only be created after changes are committed
+- Fixed potential git history issues - version bump commits now use `--no-verify` flag to bypass pre-commit hooks and prevent circular execution
+
+### 🗑️ Removed
+- Removed redundant fallback warnings from `analyze-diff` and `create-pr` commands - warnings were unnecessary as base branch resolution now throws clear errors with suggestions instead
+
+
+## [2.14.0] - 2026-02-06
+
+### ✨ Added
+- PR metadata engine (`pr-metadata-engine.js`) - centralized module for generating PR titles, descriptions, and test plans from branch diffs with timeout resilience (#63)
+- Tiered diff reduction system - automatically truncates large diffs using context reduction, proportional budgets, and stat-only summaries to prevent timeouts
+- Extended git operations - added `fetchRemote()`, `branchExists()`, `resolveBaseBranch()`, `getChangedFilesBetweenRefs()`, `getDiffBetweenRefs()`, and `getCommitsBetweenRefs()` to `git-operations.js`
+- RFC-001 documentation - comprehensive design specification for PR metadata engine refactor with timeout resilience strategy
+
+### 🔧 Changed
+- Refactored `analyze-diff` command to use shared PR metadata engine - reduced from 262 to ~80 lines by eliminating duplicate git logic
+- Refactored `create-pr` command to use shared PR metadata engine - eliminated duplicate diff extraction logic (lines 340-420)
+- Improved timeout error handling - timeout errors now include `errorInfo` and are classified as recoverable for automatic retry with exponential backoff
+- Updated CLAUDE.md with PR metadata engine architecture, new git operations exports, and tiered diff reduction strategy
+
+### 🐛 Fixed
+- Fixed timeout failures in `analyze-diff` for large diffs - now uses tiered reduction instead of monolithic diff processing
+- Fixed inconsistent behavior between `analyze-diff` and `create-pr` commands - both now share identical analysis logic via unified engine
+
+### 🗑️ Removed
+- Removed unreliable `SUBAGENT_INSTRUCTION` text hint - replaced with deterministic tiered diff reduction for parallel processing
+
+
 ## [2.13.0] - 2026-02-05
 
 ### ✨ Added

package/README.md

@@ -110,12 +110,16 @@ claude-hooks bump-version major --update-changelog
 
 # Preview without applying
 claude-hooks bump-version patch --dry-run
+
+# Manual workflow (skip automatic commit)
+claude-hooks bump-version patch --no-commit
 ```
 
 **What it does:**
 - Detects project type (Node.js, Maven, or monorepo with both)
 - Updates `package.json` and/or `pom.xml`
 - Generates CHANGELOG entry with Claude (analyzes commits)
+- Commits changes automatically with conventional commit format
 - Creates annotated Git tag with `v` prefix (e.g., `v2.7.0`)
 - Pushes tag to remote automatically
 
@@ -253,7 +257,8 @@ claude-hooks --help   # Full command reference
 | `analysis-engine.js` | **Shared analysis logic** - file data, orchestration, results (v2.13.0) | `buildFilesData()`, `runAnalysis()`, `consolidateResults()`, `displayResults()` |
 | `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()` |
+| `git-operations.js` | **Git abstractions** - staged files, diff, branch comparison | `getStagedFiles()`, `getDiff()`, `getRepoRoot()`, `resolveBaseBranch()`, `getDiffBetweenRefs()` |
+| `pr-metadata-engine.js` | **PR metadata generation** - branch context, diff reduction (v2.14.0) | `getBranchContext()`, `buildDiffPayload()`, `generatePRMetadata()`, `analyzeBranchForPR()` |
 | `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()` |
@@ -290,16 +295,18 @@ git commit -m "auto" → templates/prepare-commit-msg (bash wrapper)
   → write to COMMIT_EDITMSG
 ```
 
-#### PR Creation
+#### PR Metadata Generation (analyze-diff / create-pr)
 
 ```
-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)
+claude-hooks analyze-diff|create-pr → bin/claude-hooks (router)
+  → lib/commands/analyze-diff.js or create-pr.js (thin wrapper)
+  → analyzeBranchForPR() (pr-metadata-engine.js)
+    → resolveBaseBranch() (git-operations.js)
+    → getDiffBetweenRefs() + getCommitsBetweenRefs()
+    → buildDiffPayload() with tiered reduction (context → proportional → stat-only)
+    → executeClaudeWithRetry() → PRMetadata
+  → analyze-diff: formats to console + saves JSON
+  → create-pr: additionally creates PR via Octokit API
 ```
 
 ### Config Priority

package/lib/commands/analyze-diff.js

@@ -3,15 +3,13 @@
  * Purpose: Analyze differences between branches and generate PR info
  */
 
-import { execSync } from 'child_process';
 import fs from 'fs';
-import { executeClaudeWithRetry, extractJSON } from '../utils/claude-client.js';
-import { loadPrompt } from '../utils/prompt-builder.js';
+import { analyzeBranchForPR } from '../utils/pr-metadata-engine.js';
 import { getConfig } from '../config.js';
+import logger from '../utils/logger.js';
 import {
     colors,
     error,
-    success,
     info,
     warning,
     checkGitRepo
@@ -27,156 +25,38 @@ export async function runAnalyzeDiff(args) {
         return;
     }
 
-    // Load configuration
+    // Enable debug mode from config
     const config = await getConfig();
-
-    const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
-
-    if (!currentBranch) {
-        error('You are not in a valid branch.');
-        return;
+    if (config.system?.debug) {
+        logger.setDebugMode(true);
     }
 
-    // Update remote references
-    execSync('git fetch', { stdio: 'ignore' });
-
-    let baseBranch, compareWith, contextDescription;
-
-    if (args[0]) {
-        // Case with argument: compare current branch vs origin/specified-branch
-        const targetBranch = args[0];
-        baseBranch = `origin/${targetBranch}`;
-        compareWith = `${baseBranch}...HEAD`;
-        contextDescription = `${currentBranch} vs ${baseBranch}`;
-
-        // Check that the origin branch exists
-        try {
-            execSync(`git rev-parse --verify ${baseBranch}`, { stdio: 'ignore' });
-        } catch (e) {
-            error(`Branch ${baseBranch} does not exist.`);
-            return;
-        }
-    } else {
-        // Case without argument: compare current branch vs origin/current-branch
-        baseBranch = `origin/${currentBranch}`;
-        compareWith = `${baseBranch}...HEAD`;
-        contextDescription = `${currentBranch} vs ${baseBranch}`;
-
-        // Check that the origin branch exists
-        try {
-            execSync(`git rev-parse --verify ${baseBranch}`, { stdio: 'ignore' });
-        } catch (e) {
-            // Try fallback to origin/develop
-            baseBranch = 'origin/develop';
-            compareWith = `${baseBranch}...HEAD`;
-            contextDescription = `${currentBranch} vs ${baseBranch} (fallback)`;
-
-            try {
-                execSync(`git rev-parse --verify ${baseBranch}`, { stdio: 'ignore' });
-                warning(`Branch origin/${currentBranch} does not exist. Using ${baseBranch} as fallback.`);
-            } catch (e2) {
-                // Try fallback to origin/main
-                baseBranch = 'origin/main';
-                compareWith = `${baseBranch}...HEAD`;
-                contextDescription = `${currentBranch} vs ${baseBranch} (fallback)`;
+    // Parse target branch from arguments
+    const targetBranch = args[0];
 
-                try {
-                    execSync(`git rev-parse --verify ${baseBranch}`, { stdio: 'ignore' });
-                    warning(`No origin/develop branch. Using ${baseBranch} as fallback.`);
-                } catch (e3) {
-                    error('Could not find a valid comparison branch (tried origin/current, origin/develop, origin/main).');
-                    return;
-                }
-            }
-        }
-    }
-
-    info(`Analyzing: ${contextDescription}...`);
+    info(targetBranch ? `Analyzing differences with ${targetBranch}...` : 'Analyzing differences...');
+    const startTime = Date.now();
 
-    // Get modified files
-    let diffFiles;
     try {
-        diffFiles = execSync(`git diff ${compareWith} --name-only`, { encoding: 'utf8' }).trim();
-
-        if (!diffFiles) {
-            // Check if there are staged or unstaged changes
-            const stagedFiles = execSync('git diff --cached --name-only', { encoding: 'utf8' }).trim();
-            const unstagedFiles = execSync('git diff --name-only', { encoding: 'utf8' }).trim();
+        // Call PR metadata engine
+        const { success: engineSuccess, result, error: engineError } = await analyzeBranchForPR(targetBranch, {
+            hook: 'analyze-diff'
+        });
 
-            if (stagedFiles || unstagedFiles) {
-                warning('No differences with remote, but you have uncommitted local changes.');
-                console.log('Staged changes:', stagedFiles || 'none');
-                console.log('Unstaged changes:', unstagedFiles || 'none');
-            } else {
-                success('✅ No differences. Your branch is synchronized.');
-            }
+        if (!engineSuccess) {
+            error(engineError || 'Failed to analyze branch');
             return;
         }
-    } catch (e) {
-        error('Error getting differences: ' + e.message);
-        return;
-    }
-
-    // Get the complete diff
-    let fullDiff, commits;
-    try {
-        fullDiff = execSync(`git diff ${compareWith}`, { encoding: 'utf8' });
-        commits = execSync(`git log ${baseBranch}..HEAD --oneline`, { encoding: 'utf8' }).trim();
-    } catch (e) {
-        error('Error getting diff or commits: ' + e.message);
-        return;
-    }
-
-    // Check if subagents should be used
-    const useSubagents = config.subagents.enabled;
-    const subagentModel = config.subagents.model;
-    let subagentBatchSize = config.subagents.batchSize;
-    // Validate batch size (must be >= 1)
-    if (subagentBatchSize < 1) {
-        subagentBatchSize = 1;
-    }
-    const subagentInstruction = useSubagents
-        ? `\n\nIMPORTANT PARALLEL PROCESSING: If analyzing 3+ files, process them in batches of ${subagentBatchSize}. For EACH batch, create that many subagents in parallel using Task tool (send single message with multiple Task calls). Each subagent analyzes one file and provides insights. After ALL batches complete, consolidate into SINGLE JSON with ONE cohesive PR title/description. Model: ${subagentModel}. Example: 4 files with BATCH_SIZE=1 → 4 sequential batches of 1 subagent each. Example: 4 files with BATCH_SIZE=3 → batch 1 has 3 parallel subagents (files 1-3), batch 2 has 1 subagent (file 4).\n`
-        : '';
-
-    // Truncate full diff if too large
-    const truncatedDiff = fullDiff.length > 50000
-        ? fullDiff.substring(0, 50000) + '\n... (truncated diff)'
-        : fullDiff;
 
-    // Load prompt from template
-    const prompt = await loadPrompt('ANALYZE_DIFF.md', {
-        CONTEXT_DESCRIPTION: contextDescription,
-        SUBAGENT_INSTRUCTION: subagentInstruction,
-        COMMITS: commits,
-        DIFF_FILES: diffFiles,
-        FULL_DIFF: truncatedDiff
-    });
-
-    info('Sending to Claude for analysis...');
-    const startTime = Date.now();
-
-    // Prepare telemetry context
-    const filesChanged = diffFiles.split('\n').length;
-    const telemetryContext = {
-        fileCount: filesChanged,
-        batchSize: filesChanged,
-        totalBatches: 1,
-        model: subagentModel || 'sonnet',
-        hook: 'analyze-diff'
-    };
-
-    try {
-        // Use cross-platform executeClaudeWithRetry from claude-client.js with telemetry
-        const response = await executeClaudeWithRetry(prompt, {
-            timeout: 180000, // 3 minutes for diff analysis
-            telemetryContext
-        });
-
-        // Extract JSON from response using claude-client utility
-        const result = extractJSON(response);
+        // Log truncation details if applicable
+        if (result.context.isTruncated) {
+            logger.debug('analyze-diff', 'Diff was truncated', result.context.truncationDetails);
+        }
 
         // Show the results
+        const contextDescription = `${result.context.currentBranch} vs ${result.context.baseBranch}`;
+        const filesChanged = result.context.filesCount;
+
         console.log('');
         console.log('════════════════════════════════════════════════════════════════');
         console.log('                      DIFFERENCES ANALYSIS                      ');
@@ -215,10 +95,15 @@ export async function runAnalyzeDiff(args) {
 
         // Save the results in a file with context
         const outputData = {
-            ...result,
+            prTitle: result.prTitle,
+            prDescription: result.prDescription,
+            suggestedBranchName: result.suggestedBranchName,
+            changeType: result.changeType,
+            breakingChanges: result.breakingChanges,
+            testingNotes: result.testingNotes,
             context: {
-                currentBranch,
-                baseBranch,
+                currentBranch: result.context.currentBranch,
+                baseBranch: result.context.baseBranch,
                 contextDescription,
                 filesChanged,
                 timestamp: new Date().toISOString()
@@ -243,13 +128,7 @@ export async function runAnalyzeDiff(args) {
 
         // Contextual suggestions
         console.log('');
-        if (!args[0] && contextDescription.includes('local changes without push')) {
-            // Case of local changes without push
-            console.log(`💡 ${colors.yellow}To create new branch with these changes:${colors.reset}`);
-            console.log(`   git checkout -b ${result.suggestedBranchName}`);
-            console.log(`   git push -u origin ${result.suggestedBranchName}`);
-        } else if (currentBranch !== result.suggestedBranchName) {
-            // Normal case of comparison between branches
+        if (result.context.currentBranch !== result.suggestedBranchName) {
             console.log(`💡 ${colors.yellow}For renaming your current branch:${colors.reset}`);
             console.log(`   git branch -m ${result.suggestedBranchName}`);
         }
@@ -257,6 +136,6 @@ export async function runAnalyzeDiff(args) {
         console.log(`💡 ${colors.yellow}Tip:${colors.reset} Use this information to create your PR on GitHub.`);
 
     } catch (e) {
-        error('Error executing Claude: ' + e.message);
+        error(`Error analyzing diff: ${e.message}`);
     }
 }

package/lib/commands/bump-version.js

@@ -8,8 +8,9 @@
  * 3. Calculate new version with optional suffix
  * 4. Update version file(s)
  * 5. [Optional] Generate and update CHANGELOG
- * 6. Create annotated Git tag
- * 7. Push tag to remote
+ * 6. Stage and commit changes (skipped with --no-commit)
+ * 7. Create annotated Git tag (skipped with --no-tag or --no-commit)
+ * 8. Push tag to remote (skipped with --no-push)
  */
 
 import { execSync } from 'child_process';
@@ -37,7 +38,9 @@ import {
     getRepoRoot,
     getCurrentBranch,
     verifyRemoteExists,
-    getRemoteName
+    getRemoteName,
+    stageFiles,
+    createCommit
 } from '../utils/git-operations.js';
 import { getConfig } from '../config.js';
 import { showInfo, showSuccess, showError, showWarning, promptConfirmation } from '../utils/interactive-ui.js';
@@ -125,7 +128,8 @@ function parseArguments(args) {
         baseBranch: 'main',
         dryRun: false,
         noTag: false,
-        noPush: false
+        noPush: false,
+        noCommit: false
     };
 
     // First argument should be bump type
@@ -158,6 +162,8 @@ function parseArguments(args) {
             parsed.noTag = true;
         } else if (arg === '--no-push') {
             parsed.noPush = true;
+        } else if (arg === '--no-commit') {
+            parsed.noCommit = true;
         }
     }
 
@@ -218,6 +224,7 @@ export async function runBumpVersion(args) {
         console.log('  --dry-run                Preview changes without applying');
         console.log('  --no-tag                 Skip Git tag creation');
         console.log('  --no-push                Create tag but don\'t push to remote');
+        console.log('  --no-commit              Skip automatic commit (manual workflow)');
         console.log('');
         console.log('Examples:');
         console.log('  claude-hooks bump-version minor --suffix SNAPSHOT');
@@ -381,58 +388,136 @@ export async function runBumpVersion(args) {
             console.log('');
         }
 
-        // Step 6: Create Git tag (if not disabled)
-        if (!options.noTag) {
-            logger.debug('bump-version', 'Step 6: Creating Git tag');
-            showInfo('Creating Git tag...');
-
-            // Check if tag already exists
-            const exists = await tagExists(tagName, 'local');
-            if (exists) {
-                showWarning(`Tag ${tagName} already exists locally`);
-                const shouldOverwrite = await promptConfirmation(
-                    'Overwrite existing tag?',
-                    false
-                );
-
-                if (!shouldOverwrite) {
-                    showInfo('Tag creation skipped');
-                    console.log('');
-                    console.log('Version files updated successfully, but tag was not created.');
-                    return;
+        // Step 6: Stage and commit changes
+        let commitCreated = false;
+
+        if (!options.noCommit) {
+            logger.debug('bump-version', 'Step 6: Staging and committing changes');
+            showInfo('Staging and committing changes...');
+
+            // Collect files to stage
+            const filesToStage = [];
+
+            // Add discovered version files
+            const paths = getDiscoveredPaths();
+            if (paths.packageJson) {
+                filesToStage.push(paths.packageJson);
+            }
+            if (paths.pomXml) {
+                filesToStage.push(paths.pomXml);
+            }
+
+            // Add CHANGELOG if it was updated
+            if (options.updateChangelog) {
+                const changelogPath = path.join(getRepoRoot(), 'CHANGELOG.md');
+                if (fs.existsSync(changelogPath)) {
+                    filesToStage.push(changelogPath);
+                }
+            }
+
+            // Stage files
+            const stageResult = stageFiles(filesToStage);
+
+            if (!stageResult.success) {
+                showError(`Failed to stage files: ${stageResult.error}`);
+                console.log('');
+                console.log('Files that should be staged:');
+                filesToStage.forEach(f => console.log(`  - ${path.relative(getRepoRoot(), f)}`));
+                console.log('');
+                console.log('You can stage and commit manually:');
+                console.log(`  git add ${filesToUpdate.join(' ')}`);
+                if (options.updateChangelog) {
+                    console.log('  git add CHANGELOG.md');
                 }
+                console.log(`  git commit -m "chore(version): bump to ${newVersion}"`);
+                process.exit(1);
             }
 
-            const tagMessage = `Release version ${newVersion}`;
-            const tagResult = createTag(newVersion, tagMessage, { force: exists });
+            showSuccess(`✓ Staged ${stageResult.stagedFiles.length} file(s)`);
 
-            if (tagResult.success) {
-                showSuccess(`✓ Tag created: ${tagName}`);
+            // Create commit
+            const commitMessage = `chore(version): bump to ${newVersion}`;
+            const commitResult = createCommit(commitMessage, { noVerify: true });
+
+            if (!commitResult.success) {
+                showError(`Failed to create commit: ${commitResult.error}`);
                 console.log('');
+                console.log('Files have been staged. You can commit manually:');
+                console.log(`  git commit -m "chore(version): bump to ${newVersion}"`);
+                process.exit(1);
+            }
 
-                // Step 7: Push tag (if not disabled)
-                if (!options.noPush) {
-                    logger.debug('bump-version', 'Step 7: Pushing tag to remote');
-                    showInfo('Pushing tag to remote...');
+            showSuccess('✓ Changes committed');
+            commitCreated = true;
+            console.log('');
+        } else {
+            showInfo('Commit skipped (--no-commit)');
+            console.log('');
+        }
 
-                    const pushResult = pushTags(null, tagName);
+        // Step 7: Create Git tag (if not disabled)
+        if (!options.noTag) {
+            logger.debug('bump-version', 'Step 7: Creating Git tag');
 
-                    if (pushResult.success) {
-                        showSuccess('✓ Tag pushed to remote');
+            // Prevent tag creation if changes not committed
+            if (options.noCommit) {
+                showWarning('Tag creation skipped: --no-commit requires manual commit before tagging');
+                console.log('');
+                console.log('After committing, you can create the tag:');
+                console.log(`  git tag -a ${tagName} -m "Release version ${newVersion}"`);
+                console.log(`  git push origin ${tagName}`);
+                console.log('');
+            } else {
+                showInfo('Creating Git tag...');
+
+                // Check if tag already exists
+                const exists = await tagExists(tagName, 'local');
+                if (exists) {
+                    showWarning(`Tag ${tagName} already exists locally`);
+                    const shouldOverwrite = await promptConfirmation(
+                        'Overwrite existing tag?',
+                        false
+                    );
+
+                    if (!shouldOverwrite) {
+                        showInfo('Tag creation skipped');
+                        console.log('');
+                        console.log('Version files updated successfully, but tag was not created.');
+                        return;
+                    }
+                }
+
+                const tagMessage = `Release version ${newVersion}`;
+                const tagResult = createTag(newVersion, tagMessage, { force: exists });
+
+                if (tagResult.success) {
+                    showSuccess(`✓ Tag created: ${tagName}`);
+                    console.log('');
+
+                    // Step 7: Push tag (if not disabled)
+                    if (!options.noPush) {
+                        logger.debug('bump-version', 'Step 7: Pushing tag to remote');
+                        showInfo('Pushing tag to remote...');
+
+                        const pushResult = pushTags(null, tagName);
+
+                        if (pushResult.success) {
+                            showSuccess('✓ Tag pushed to remote');
+                        } else {
+                            showError(`Failed to push tag: ${pushResult.error}`);
+                            console.log('');
+                            console.log('You can push the tag manually:');
+                            console.log(`  git push origin ${tagName}`);
+                        }
                     } else {
-                        showError(`Failed to push tag: ${pushResult.error}`);
+                        showInfo('Tag push skipped (--no-push)');
                         console.log('');
-                        console.log('You can push the tag manually:');
+                        console.log('To push the tag later:');
                         console.log(`  git push origin ${tagName}`);
                     }
                 } else {
-                    showInfo('Tag push skipped (--no-push)');
-                    console.log('');
-                    console.log('To push the tag later:');
-                    console.log(`  git push origin ${tagName}`);
+                    showError(`Failed to create tag: ${tagResult.error}`);
                 }
-            } else {
-                showError(`Failed to create tag: ${tagResult.error}`);
             }
         } else {
             showInfo('Tag creation skipped (--no-tag)');
@@ -448,11 +533,33 @@ export async function runBumpVersion(args) {
         console.log(`${colors.blue}New version:${colors.reset} ${newVersion}`);
         console.log(`${colors.blue}Tag:${colors.reset} ${tagName}`);
         console.log('');
-        console.log('Next steps:');
-        console.log('  1. Review the changes: git diff');
-        console.log(`  2. Commit the version bump: git add . && git commit -m "chore: bump version to ${  newVersion  }"`);
-        console.log('  3. Create PR: claude-hooks create-pr main');
-        console.log('');
+
+        // Conditional next steps
+        if (options.noCommit) {
+            console.log('Next steps:');
+            console.log('  1. Review changes: git diff');
+            console.log(`  2. Stage files: git add ${filesToUpdate.join(' ')}`);
+            if (options.updateChangelog) {
+                console.log('     git add CHANGELOG.md');
+            }
+            console.log(`  3. Commit: git commit -m "chore(version): bump to ${newVersion}"`);
+            console.log(`  4. Create tag: git tag -a ${tagName} -m "Release version ${newVersion}"`);
+            console.log(`  5. Push: git push origin $(git branch --show-current) ${tagName}`);
+            console.log('');
+        } else if (commitCreated && !options.noTag && !options.noPush) {
+            console.log('All done! Changes committed and tag pushed to remote.');
+            console.log('');
+            console.log('Next steps:');
+            console.log('  1. Create PR: claude-hooks create-pr main');
+            console.log('');
+        } else {
+            console.log('Next steps:');
+            if (commitCreated && options.noPush) {
+                console.log(`  1. Push changes: git push origin $(git branch --show-current) ${tagName}`);
+            }
+            console.log('  2. Create PR: claude-hooks create-pr main');
+            console.log('');
+        }
 
     } catch (err) {
         logger.error('bump-version', 'Version bump failed', err);