feat(hooks): add support for custom hooks #345

amondnet · 2025-09-18T17:06:30Z

Add Git-Style Hook System for Specify Command

Implements a comprehensive hook system for the /specify command that allows users to customize the specification creation workflow with Git-style naming conventions.

Addresses Issue

Closes #343 - Add feature number override functionality with hook system
#83
#344

Features Added

Git-Style Hook System

pre-specify - Pre-workflow validation and setup
prepare-feature-num - Custom feature numbering (replaces auto-increment)
post-checkout - Post-branch creation tasks
post-specify - Post-specification completion tasks

Cross-Platform Support

Bash hooks (.sample) for Unix/Linux/macOS
PowerShell hooks (.ps1.sample) for Windows
Automatic platform detection and execution

Key Capabilities

Feature Number Override: Custom numbering from external servers or GitHub issues
Workflow Customization: Pre/post hooks for validation and integration
Sample-Based Activation: Safe defaults with opt-in hook activation

📁 File Structure

hooks/
├── README.md # Comprehensive documentation
├── pre-specify.sample # Bash pre-workflow hook
├── pre-specify.ps1.sample # PowerShell pre-workflow hook├── prepare-feature-num.sample # Bash feature numbering hook
├── prepare-feature-num.ps1.sample # PowerShell feature numbering hook
├── post-checkout.sample # Bash post-branch hook
├── post-checkout.ps1.sample # PowerShell post-branch hook
├── post-specify.sample # Bash post-completion hook
└── post-specify.ps1.sample # PowerShell post-completion hook

Technical Implementation

Script Enhancements

Added --feature-num NUMBER parameter to bash script
Added -FeatureNum NUMBER parameter to PowerShell script
Backward compatible with existing functionality

CLI Integration

Updated ensure_executable_scripts() to handle hooks
Sample files excluded from permission setting
Cross-platform permission management

Release Process

Updated create-release-packages.sh to include hooks directory
Hooks distributed in all release packages
Path rewriting for .specify/hooks/ structure

Template Updates

Modified templates/commands/specify.md with hook execution steps
Detailed cross-platform hook calling instructions
Clear execution order and error handling

Hook Execution Flow

pre-specify → Validation
prepare-feature-num → Custom numbering (optional)
Branch/directory creation
post-checkout → Post-branch setup
Spec file writing
post-specify → Completion tasks

Usage Examples

Custom Feature Numbering

# Create GitHub issue and use issue number
ISSUE_URL=$(gh issue create --title "Spec: $1" --body "Development")
echo $(echo "$ISSUE_URL" | grep -o '[0-9]*$')

# Notify team when spec is complete
gh issue create --title "Spec Complete: $1" --body "Ready for review: $SPEC_FILE"

Documentation

Comprehensive hooks/README.md with examples
Git-style naming explanation and rationale
Platform-specific activation instructions
Hook execution order and timing details

Backward Compatibility

Existing /specify workflows unchanged when no hooks active
Sample files provide safe defaults
No breaking changes to current functionality

Future Enhancements

This establishes the foundation for extending hooks to /plan and /tasks commands in future PRs.

Copilot

Pull Request Overview

This PR adds comprehensive hook support to the specify CLI tool, allowing users to customize the specification workflow with pre-processing, feature number generation, and post-processing hooks.

Introduces Git-style hook system with four hook types: pre-specify, prepare-feature-num, post-checkout, and post-specify
Adds hook execution logic to the specify command workflow with cross-platform support
Updates script permissions handling to include hooks alongside existing script management

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
templates/commands/specify.md	Updates workflow to integrate hook execution at appropriate stages
src/specify_cli/init.py	Extends script permission handling to include hooks in the .specify/hooks directory
scripts/powershell/create-new-feature.ps1	Adds --FeatureNum parameter support for custom feature numbering
scripts/bash/create-new-feature.sh	Adds --feature-num parameter support for custom feature numbering
hooks/*.sample	Provides sample hook implementations for all four hook types in both bash and PowerShell
hooks/README.md	Comprehensive documentation for hook system usage and examples
.github/workflows/scripts/create-release-packages.sh	Updates release packaging to include hooks directory

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

hooks/post-checkout.sample

hooks/post-checkout.ps1.sample

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/specify_cli/__init__.py

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

scripts/bash/create-new-feature.sh

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

scripts/bash/create-new-feature.sh

src/specify_cli/__init__.py

templates/commands/specify.md

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

templates/commands/specify.md

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

scripts/powershell/create-new-feature.ps1

src/specify_cli/__init__.py

amondnet · 2025-09-19T17:50:42Z

@localden Thanks for the feedback! I've addressed your comments with the following changes:

Changes Made

Simplified hook execution

Removed OS detection (Windows/Linux distinction)
Each package now executes only its script type's hooks
Introduced {HOOK_EXT} placeholder (ps: .ps1, sh: empty string)

Removed environment variable export

Eliminated redundant Step 4 for environment variable setup
Script already handles these internally

Selective hook sample inclusion

sh packages: Include only bash hook samples (.sample files)
ps packages: Include only PowerShell hook samples (.ps1.sample files)
Reduces package size and prevents confusion

Regarding OS Detection

You're absolutely right about LLMs being unreliable at OS detection. I've kept the current approach (script type determined at build time) while simplifying so each package only handles its own script type.

If runtime OS detection becomes necessary, we should handle it in a separate PR.

Let me know if you have any additional feedback!

… script github#345 (comment)

…e_scripts github#345 (comment)

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/specify_cli/__init__.py

templates/commands/specify.md

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/specify_cli/__init__.py

scripts/bash/create-new-feature.sh

.github/workflows/scripts/create-release-packages.sh

github#345 (comment)

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

templates/commands/specify.md

scripts/bash/create-new-feature.sh

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

scripts/powershell/create-new-feature.ps1:1

Add tests for -FeatureNum to cover: accepted values (e.g., 1 -> 001, 42 -> 042), validation failures (0, 1000), and that the auto-increment path is used when the parameter is omitted.

#!/usr/bin/env pwsh

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/specify_cli/__init__.py

.github/workflows/scripts/create-release-packages.sh

hooks/README.md

Co-authored-by: Copilot <[email protected]>

…ditional arguments

Co-authored-by: Copilot <[email protected]>

…ctive hook copying

… script github#345 (comment)

…e_scripts github#345 (comment)

Co-authored-by: Copilot <[email protected]>

github#345 (comment)

Co-authored-by: Copilot <[email protected]>

Copilot

Pull Request Overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

templates/commands/specify.md

amondnet requested a review from localden as a code owner September 18, 2025 17:06

Copilot AI review requested due to automatic review settings September 18, 2025 17:06