Pre-commit Integration

PrompTrek includes comprehensive pre-commit hooks to ensure code quality and prevent accidental commits of generated files.

Quick Setup

# Install development dependencies (includes pre-commit)
uv sync --group dev
# or with pip: pip install -e .[dev]

# Install pre-commit hooks
uv run pre-commit install

# (Optional) Run hooks on all files
uv run pre-commit run --all-files

What the Hooks Do

1. Validate PrompTrek Files

Hook: validate-promptrek-files
Purpose: Validates .promptrek.yaml files using promptrek validate
Files: *.promptrek.yaml, *.promptrek.yml
When: Before every commit

Example output:

Validate PrompTrek files.................................................Passed

2. Prevent Committing Generated Files

Hook: prevent-generated-files
Purpose: Blocks commits of files generated by promptrek
Files: All generated AI editor configuration files
When: Before every commit

Protected file patterns:

.github/copilot-instructions.md - GitHub Copilot prompts
.cursor/, AGENTS.md, .cursorignore, .cursorindexingignore - Cursor editor
.continue/ - Continue editor configuration
.claude/ - Claude Code configuration
.clinerules/ - Cline configuration
.windsurf/ - Windsurf configuration
.kiro/ - Kiro configuration
.amazonq/ - Amazon Q configuration
.assistant/ - JetBrains AI configuration

Example failure:

❌ ERROR: Attempting to commit generated prompt files!

The following files appear to be generated by promptrek and should not be committed:
  - .github/copilot-instructions.md
  - .cursor/rules/index.mdc

💡 These files are generated from .promptrek.yaml files and should be:
   • Added to .gitignore
   • Generated locally as needed
   • Not committed to version control

To fix this:
1. Remove these files from staging: git reset HEAD <file>
2. Add them to .gitignore if not already there
3. Commit only your .promptrek.yaml source files

3. Code Quality Checks

black-check: Ensures code formatting follows black standards
isort-check: Validates import sorting
flake8-check: Checks code style and common issues

4. File Quality Checks

trailing-whitespace: Removes trailing spaces
end-of-file-fixer: Ensures files end with a newline
check-yaml: Validates YAML syntax (excludes .promptrek.yaml files)
check-merge-conflict: Detects merge conflict markers
debug-statements: Prevents committing debug statements

Generated Files and .gitignore

PrompTrek automatically ignores generated files via .gitignore:

# Generated AI Editor Configuration Files
# These files are generated by promptrek from .promptrek.yaml files
# and should not be committed to version control

# GitHub Copilot generated files
.github/copilot-instructions.md
.github/instructions/*.instructions.md
.github/prompts/*.prompt.md
.copilot/instructions.md

# Cursor generated files
.cursor/
.cursorignore
.cursorindexingignore

# Continue generated files
config.yaml
.continue/

# Claude Code generated files
.claude/

# Cline generated files
.clinerules/

# Windsurf generated files
.windsurf/

# Kiro generated files
.kiro/

# Amazon Q generated files
.amazonq/

# JetBrains AI generated files
.assistant/

# Cursor additional files
AGENTS.md
.cursorignore
.cursorindexingignore

Workflow

Normal Development

Edit your .promptrek.yaml files
Commit changes normally - hooks will validate your files

Generate editor-specific files locally as needed:

promptrek generate my-project.promptrek.yaml --all

If Hooks Fail

PrompTrek validation fails: Fix the issues in your .promptrek.yaml file
Generated files detected: Remove them from staging and ensure they’re in .gitignore
Code formatting issues: Run the formatters:
```
black src/ tests/
isort src/ tests/
```

Manual Hook Execution

# Run all hooks on staged files
uv run pre-commit run

# Run all hooks on all files
uv run pre-commit run --all-files

# Run specific hook
uv run pre-commit run validate-promptrek-files
uv run pre-commit run prevent-generated-files

# Skip hooks for a specific commit (not recommended)
git commit --no-verify -m "Emergency commit"

Configuration Files

.pre-commit-config.yaml - Pre-commit hook configuration
.yamllint - YAML linting rules for promptrek files
scripts/check_generated_files.py - Script to detect generated files

Troubleshooting

Hook Installation Issues

# Reinstall hooks
uv run pre-commit uninstall
uv run pre-commit install

# Clear cache if needed
uv run pre-commit clean

Network Issues

The configuration uses only local hooks to avoid network dependencies during commits.

Bypassing Hooks (Emergency)

# Skip pre-commit hooks (use sparingly)
git commit --no-verify -m "Emergency commit"

# Re-run hooks later
uv run pre-commit run --all-files

Integration with Make

Use the Makefile for common pre-commit operations:

# Set up development environment with hooks
make dev

# Install pre-commit hooks
make pre-commit-install

# Run all hooks
make pre-commit-run

# Update hook versions
make pre-commit-update

This ensures consistent development practices and prevents accidental commits of generated files that should remain local to each developer’s environment.