feat: Add BYO (Bring Your Own) prompt instruction feature

[eonist]

Overview

This PR introduces a new --byo (Bring Your Own) flag that allows users to provide custom prompt instructions from a file, enabling teams and individuals to define their own commit message rules and conventions.

Motivation

While diffsense provides excellent built-in prompt styles (default, verbose, minimal), different teams have unique commit message conventions, style guides, and requirements. This feature allows users to:

• Define team-specific commit message formats (e.g., conventional commits)
• Enforce organizational standards and best practices
• Add custom type prefixes, scopes, or structure requirements
• Include project-specific guidelines without modifying the tool

Changes

1. Updated resources/diffsense.sh

New --byo flag support

• Accepts both --byo <file> and --byo=<file> syntax
• Expands ~ to home directory for convenience
• Validates file existence before loading

New load_byo_prompt() function

• Dedicated helper to load custom prompt instructions from file
• Proper error handling when file doesn't exist
• Returns empty string gracefully when no BYO file is specified

Updated parse_args() function

• Refactored to use proper while loop with shift for robust argument parsing
• Added --help handling within the parser
• Supports mixed argument order (e.g., --byo "file.md" --gpt --verbose)

Enhanced prompt composition in diffsense() main function

• Combines base prompt with BYO instructions using clear separator: "Additional instructions:"
• Validates combined prompt size before truncation
• Provides detailed error messages when prompt exceeds available space:
  • Shows available character space
  • Shows model character limit
  • Shows actual prompt size
  • Requires minimum 500 chars for diff content

Updated help text

• Documents the new --byo <file> option
• Includes usage examples
• Notes that large prompts reduce available diff space

2. Added cstm_cmt_msg_rules.md

A comprehensive example template that users can use as a starting point for their own custom rules:

• Format guidelines: Subject line structure, body format, tense usage
• Conventional commit types: feat, fix, refactor, perf, docs, test, chore, style
• Content guidelines: Specificity, scoping, ticket references
• Good/bad examples: Helps AI understand expected output quality
• Output format: Plain text constraint (no markdown formatting)

This template is intentionally concise (~250 words) to leave plenty of room for diff content while demonstrating best practices.

Technical Details

Character Budget Management

The existing truncate_diff() function already accounts for prompt length using ${#prompt}. This PR enhances this by:

1. Pre-validation: Checks combined prompt size before processing
2. Minimum threshold: Ensures at least 500 chars available for diff
3. Clear errors: Shows exact character counts when validation fails

Prompt Combination Strategy

When --byo is used:

<base_prompt>

Additional instructions:
<byo_prompt_content>

This approach:

• Preserves the base prompt structure and formatting rules
• Clearly separates custom instructions for the AI
• Allows custom rules to complement (not replace) base behavior

Usage Examples

# Use custom team rules
diffsense --byo "~/cstm_cmt_msg_rules.md"

# Combine with AI model selection
diffsense --byo "~/team_rules.md" --gpt

# Use with all options
diffsense --verbose --byo "./project-rules.md" --pcc --nopopup

# Alternative syntax
diffsense --byo="~/rules.md" --minimal

Testing Recommendations

1. Basic functionality: Test --byo with various file paths
2. Tilde expansion: Verify ~/file.md works correctly
3. Error cases:
   • Non-existent file
   • Very large prompt file (>5000 chars)
   • Missing file path argument
4. Integration: Test with different AI models and message styles
5. Edge cases: Empty files, files with special characters

Breaking Changes

None. This is a purely additive feature. All existing functionality remains unchanged.

Future Enhancements

Potential improvements for future PRs:

• Support for multiple BYO files (compose from several sources)
• Built-in library of popular convention templates
• Validation/linting of custom prompt files
• Interactive prompt builder CLI

Checklist

• Added --byo flag support
• Created load_byo_prompt() helper function
• Updated argument parsing with proper while loop
• Added prompt size validation
• Updated help documentation
• Created example template file
• Maintained backward compatibility
• Preserved existing character budget logic

[eonist]

One detail: --verbose and --byo should not be possible to provide together