Pre-commit Integration for Users

This guide explains how to integrate PrompTrek’s pre-commit hooks into your project to ensure .promptrek.yaml files are validated and generated files are not accidentally committed.

Quick Start

PrompTrek provides convenient ways to integrate pre-commit hooks into your project:

Option 1: During Project Initialization (Easiest for New Projects)

When creating a new project, use the --setup-hooks flag with init:

# Install dependencies
pip install promptrek pre-commit

# Initialize PrompTrek and set up hooks in one command
promptrek init --setup-hooks

This creates your .promptrek.yaml file and automatically configures and activates pre-commit hooks!

Option 2: One-Command Setup (For Existing Projects)

Use the --activate flag to configure and activate hooks in one step:

# Install pre-commit (if not already installed)
pip install pre-commit

# Install and activate PrompTrek hooks
promptrek install-hooks --activate

That’s it! PrompTrek hooks are now configured and active, ready to run on every commit.

Option 3: Two-Step Setup

If you prefer more control, configure first and activate separately:

# Install PrompTrek hooks configuration
promptrek install-hooks

# Activate the hooks in your git repository
pre-commit install

Option 4: Manual Configuration

Add PrompTrek hooks manually to your .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: promptrek-validate
        name: Validate PrompTrek files
        entry: promptrek validate
        language: system
        files: \.promptrek\.ya?ml$
        pass_filenames: true
        stages: [commit]

      - id: promptrek-prevent-generated
        name: Prevent committing generated files
        entry: promptrek check-generated
        language: system
        files: |
          (?x)(
            ^\.github/(copilot-instructions\.md|instructions/.*\.instructions\.md|prompts/.*\.prompt\.md)$|
            ^(\.cursorrules|\.cursor/.*|\.cursorignore|\.cursorindexingignore|AGENTS\.md)$|
            ^(config\.yaml|\.continue/.*)$|
            ^(\.claude/.*|CLAUDE\.md)$|
            ^\.clinerules/.*$|
            ^\.windsurf/.*$|
            ^\.kiro/.*$|
            ^\.amazonq/.*$|
            ^\.assistant/.*
          )
        stages: [commit]
        always_run: false
        pass_filenames: true

Then activate:

pip install pre-commit
pre-commit install

What the Hooks Do

1. Validate PrompTrek Files (promptrek-validate)

Purpose: Automatically validates .promptrek.yaml files before commit to catch errors early.

When it runs: On every commit that includes changes to .promptrek.yaml or .promptrek.yml files.

Example output:

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

If validation fails:

Validate PrompTrek files.....................................Failed
- hook id: promptrek-validate
- exit code: 1

❌ Validation failed for my-project.promptrek.yaml
  • Missing required field: metadata.title
  • Invalid target editor: invalid-editor

2. Prevent Committing Generated Files (promptrek-prevent-generated)

Purpose: Blocks accidental commits of AI editor configuration files that should be generated locally.

When it runs: On every commit, checks if any staged files match generated file patterns.

Protected files:

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

Example failure:

Prevent committing generated files...........................Failed
- hook id: promptrek-prevent-generated
- exit code: 1

❌ 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

Best Practices

Git Workflow

1. Commit only .promptrek.yaml files:

   # Good ✅
   git add my-project.promptrek.yaml
   git commit -m "feat: add python code style guidelines"
   

2. Don’t commit generated files:

   # Bad ❌
   git add .github/copilot-instructions.md
   git commit -m "add copilot instructions"
   

3. Generate files locally as needed:

   # After pulling changes
   promptrek generate my-project.promptrek.yaml --all
   

Team Collaboration

For teams using PrompTrek, include these setup instructions in your repository’s README:

For New Projects:

## AI Editor Setup

This project uses PrompTrek for managing AI editor configurations.

### First-Time Setup

1. Install dependencies:
   ```bash
   pip install promptrek pre-commit

1. Initialize project (creates .promptrek.yaml and sets up hooks):

   promptrek init --setup-hooks
   

2. Generate AI editor configurations:

   promptrek generate project.promptrek.yaml --all
   

Your AI editor will now use the project-specific prompts!

**For Existing Projects:**
```markdown
## AI Editor Setup

This project uses PrompTrek for managing AI editor configurations.

1. Install dependencies:
   ```bash
   pip install promptrek pre-commit

1. Set up pre-commit hooks:

   promptrek install-hooks --activate
   

2. Generate AI editor configurations:

   promptrek generate project.promptrek.yaml --all
   

Your AI editor will now use the project-specific prompts!

### .gitignore Configuration

Add generated files to your `.gitignore`:

```gitignore
# PrompTrek generated files
# These are generated from .promptrek.yaml and should not be committed

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

# Cursor
.cursor/
.cursorignore
.cursorindexingignore

# Continue
config.yaml
.continue/

# Claude Code
.claude/

# Cline
.clinerules/

# Windsurf
.windsurf/

# Kiro
.kiro/

# Amazon Q
.amazonq/

# JetBrains AI
.assistant/

# Cursor (additional files)
AGENTS.md
.cursorignore
.cursorindexingignore

Advanced Usage

Updating Hooks

If PrompTrek hooks are already configured, you can update them:

# Prompt for confirmation
promptrek install-hooks

# Force update without confirmation
promptrek install-hooks --force

# Update and re-activate hooks
promptrek install-hooks --activate --force

Custom Config Location

Use a custom pre-commit config file:

promptrek install-hooks --config .custom-pre-commit-config.yaml

Manual Hook Execution

Run hooks manually without committing:

# Run all hooks on staged files
pre-commit run

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

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

Skipping Hooks (Emergency Only)

In rare cases where you need to bypass hooks:

# Skip all pre-commit hooks
git commit --no-verify -m "emergency commit"

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

⚠️ Warning: Use --no-verify sparingly and only when necessary.

Troubleshooting

Hook Not Found Error

[ERROR] promptrek: No such file or directory

Solution: Ensure PrompTrek is installed in your environment:

pip install promptrek
# or with uv
uv pip install promptrek

Validation Failures

If promptrek validate fails:

1. Check the error message for specific issues
2. Fix the .promptrek.yaml file
3. Run validation manually: promptrek validate my-project.promptrek.yaml
4. Try committing again

Generated Files Detected

If the hook blocks your commit:

1. Check which files are being blocked (shown in error message)
2. Remove them from staging:

   git reset HEAD .github/copilot-instructions.md
   

3. Ensure they’re in .gitignore
4. Commit only your .promptrek.yaml files

Reinstalling Hooks

If hooks aren’t running:

# Uninstall and reinstall
pre-commit uninstall
promptrek install-hooks
pre-commit install

# Clear cache if needed
pre-commit clean

Hooks Not Respecting Existing Configuration

The promptrek install-hooks command safely merges with existing configurations. If you have issues:

1. Check your .pre-commit-config.yaml manually
2. Ensure the PrompTrek local repo doesn’t conflict with other local repos
3. Report issues at https://github.com/flamingquaks/promptrek/issues

CI/CD Integration

GitHub Actions

Run PrompTrek validation in CI:

name: Validate PrompTrek

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install PrompTrek
        run: pip install promptrek
      - name: Validate PrompTrek files
        run: |
          find . -name "*.promptrek.yaml" -o -name "*.promptrek.yml" | \
          xargs -I {} promptrek validate {}

Pre-commit.ci

Enable pre-commit.ci for automatic hook execution on PRs:

1. Visit https://pre-commit.ci
2. Enable for your repository
3. Hooks will run automatically on every PR

Note: Since PrompTrek uses language: system, ensure the CI environment has PrompTrek installed.

FAQ

Q: What happens if I use --activate but pre-commit isn’t installed?

A: The command will show an error and provide instructions to install pre-commit first with pip install pre-commit.

Q: Do all team members need to install PrompTrek?

A: Yes, since the hooks use language: system, PrompTrek must be installed in each developer’s environment.

Q: Can I use these hooks with other pre-commit hooks?

A: Absolutely! The promptrek install-hooks command safely adds PrompTrek hooks alongside your existing hooks.

Q: What if I want to commit a generated file for documentation purposes?

A: Add the specific file to the exclude pattern in your .pre-commit-config.yaml, or use git commit --no-verify (use sparingly).

Q: Do I need to run promptrek generate after every pull?

A: Only if .promptrek.yaml files were updated. You can add it to a post-pull hook or run it manually when needed.

Q: Can I customize which files are protected?

A: Yes, you can modify the files pattern in your .pre-commit-config.yaml after installation.

Support

For issues or questions:

• GitHub Issues: https://github.com/flamingquaks/promptrek/issues
• Documentation: https://flamingquaks.github.io/promptrek