feat(hooks): add support for custom hooks

Author: amondnet

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

@@ -31,7 +31,8 @@ rewrite_paths() {
   sed -E \
     -e 's@(/?)memory/@.specify/memory/@g' \
     -e 's@(/?)scripts/@.specify/scripts/@g' \
-    -e 's@(/?)templates/@.specify/templates/@g'
+    -e 's@(/?)templates/@.specify/templates/@g' \
+    -e 's@(/?)hooks/@.specify/hooks/@g'
 }
 
 generate_commands() {
@@ -110,6 +111,7 @@ build_variant() {
   fi
 
   [[ -d templates ]] && { mkdir -p "$SPEC_DIR/templates"; find templates -type f -not -path "templates/commands/*" -exec cp --parents {} "$SPEC_DIR"/ \; ; echo "Copied templates -> .specify/templates"; }
+  [[ -d hooks ]] && { cp -r hooks "$SPEC_DIR/"; echo "Copied hooks -> .specify"; }
   # Inject variant into plan-template.md within .specify/templates if present
   local plan_tpl="$base_dir/.specify/templates/plan-template.md"
   if [[ -f "$plan_tpl" ]]; then

hooks/README.md

@@ -0,0 +1,190 @@
+# Specify Hooks
+
+This directory contains Git-style hook script samples that customize the `/specify` command workflow. All hooks are optional and follow Git's naming conventions for familiar, intuitive usage.
+
+## Hook Activation
+
+Hooks are provided as `.sample` files and must be activated by removing the `.sample` extension:
+
+**Unix/Linux/macOS:**
+```bash
+# Activate bash hook (example: prepare-feature-num)
+cp .specify/hooks/prepare-feature-num.sample .specify/hooks/prepare-feature-num
+chmod +x .specify/hooks/prepare-feature-num
+```
+
+**Windows PowerShell:**
+```powershell
+# Activate PowerShell hook
+Copy-Item .specify/hooks/prepare-feature-num.ps1.sample .specify/hooks/prepare-feature-num.ps1
+```
+
+**Cross-platform support:** The system automatically detects and uses the appropriate hook format (`.ps1` for Windows, executable scripts for Unix).
+
+## Available Hooks (Git-Style Naming)
+
+### `pre-specify` - Pre-processing Hook
+- **When**: Before the entire specify workflow begins
+- **Purpose**: Validation, setup, or preprocessing tasks
+- **Arguments**: `$1` = feature description
+- **Exit codes**: Non-zero exit codes show warnings but don't stop execution
+
+**Example uses:**
+- Validate feature description format and length
+- Check prerequisites or dependencies
+- Set up external resources or authenticate
+
+### `prepare-feature-num` - Feature Number Preparation Hook
+- **When**: Before auto-incrementing feature number (similar to Git's `prepare-commit-msg`)
+- **Purpose**: Provide custom feature numbering from external sources
+- **Arguments**: `$1` = feature description
+- **Output**: Integer feature number (stdout)
+- **Fallback**: If hook fails or outputs nothing, auto-increment is used
+
+**Example uses:**
+- Fetch feature number from external spec server
+- Create GitHub issue and use issue number
+- Implement custom numbering schemes
+
+### `post-checkout` - Post-Checkout Hook
+- **When**: After branch creation and checkout (matches Git's `post-checkout`)
+- **Purpose**: Setup tasks after branch creation but before spec writing
+- **Arguments**: `$1` = feature description
+- **Environment**: `BRANCH_NAME`, `SPEC_FILE`, `FEATURE_NUM` are available
+- **Exit codes**: Non-zero exit codes show warnings but don't stop execution
+
+**Example uses:**
+- Initialize additional project files
+- Set up branch-specific configurations
+- Create directory structures
+- Send branch creation notifications
+
+### `post-specify` - Post-Specification Hook
+- **When**: After spec file is completely written (true post-specify)
+- **Purpose**: Final integration tasks and notifications
+- **Arguments**: `$1` = feature description
+- **Environment**: `BRANCH_NAME`, `SPEC_FILE`, `FEATURE_NUM` are available
+- **Exit codes**: Non-zero exit codes show warnings but don't stop execution
+
+**Example uses:**
+- Create GitHub issues linking to completed specs
+- Send completion notifications
+- Trigger CI/CD pipelines for spec review
+- Update external tracking systems
+
+## Hook Examples
+
+### Custom Feature Numbering from Server
+
+**Bash version:**
+```bash
+#!/bin/bash
+# .specify/hooks/prepare-feature-num
+FEATURE_DESC="$1"
+FEATURE_NUMBER=$(curl -s "$SPEC_SERVER/api/next-number")
+echo "$FEATURE_NUMBER"
+```
+
+**PowerShell version:**
+```powershell
+#!/usr/bin/env pwsh
+# .specify/hooks/prepare-feature-num.ps1
+param([string]$FeatureDescription)
+$featureNumber = Invoke-RestMethod -Uri "$env:SPEC_SERVER/api/next-number"
+Write-Output $featureNumber
+```
+
+### GitHub Issue for Feature Number
+
+**Bash version:**
+```bash
+#!/bin/bash
+# .specify/hooks/prepare-feature-num
+FEATURE_DESC="$1"
+ISSUE_URL=$(gh issue create --title "Spec: $FEATURE_DESC" --body "Specification development")
+ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -o '[0-9]*$')
+echo "$ISSUE_NUMBER"
+```
+
+**PowerShell version:**
+```powershell
+#!/usr/bin/env pwsh
+# .specify/hooks/prepare-feature-num.ps1
+param([string]$FeatureDescription)
+$issueUrl = gh issue create --title "Spec: $FeatureDescription" --body "Specification development"
+$issueNumber = [regex]::Match($issueUrl, '\d+$').Value
+Write-Output $issueNumber
+```
+
+### Post-Checkout Setup
+
+**Bash version:**
+```bash
+#!/bin/bash
+# .specify/hooks/post-checkout
+FEATURE_DESC="$1"
+# Create additional project directories
+mkdir -p "docs/$BRANCH_NAME"
+# Set up branch-specific configuration
+echo "Branch $BRANCH_NAME created for: $FEATURE_DESC" > "docs/$BRANCH_NAME/info.txt"
+```
+
+### Post-Specification Notification
+
+**Bash version:**
+```bash
+#!/bin/bash
+# .specify/hooks/post-specify
+FEATURE_DESC="$1"
+# Create completion issue
+gh issue create --title "Spec Complete: $FEATURE_DESC" --body "Specification ready for review: $SPEC_FILE"
+# Send notification
+echo "Specification $FEATURE_NUM completed: $SPEC_FILE" | mail -s "Spec Ready" team@company.com
+```
+
+## Technical Notes
+
+### Platform-Specific Behavior
+- **Unix/Linux/macOS**: Hooks must be executable (`chmod +x`). System looks for exact hook name.
+- **Windows**: PowerShell hooks use `.ps1` extension. No execute permission needed.
+- **Cross-platform**: System automatically detects and uses appropriate hook format.
+
+### Hook Execution
+- Hooks are called with the feature description as the first argument
+- The `feature-num` hook should output only the number to stdout
+- The `post-specify` hook has access to environment variables set by the create script
+- Failed hooks generate warnings but don't stop the specification process
+- Non-existent or non-executable hook files are safely ignored
+
+### Available Hook Formats
+- `hook-name` - Bash/shell script (Unix/Linux/macOS)
+- `hook-name.ps1` - PowerShell script (Windows/cross-platform)
+
+### Hook Execution Order
+1. `pre-specify` - Workflow validation and setup
+2. `prepare-feature-num` - Custom feature numbering (optional)
+3. **Script execution** - Branch/directory creation
+4. `post-checkout` - Post-branch setup tasks
+5. **Spec writing** - Template processing and content generation
+6. `post-specify` - Completion notifications and final tasks
+
+## Customization
+
+**To activate and customize hooks:**
+
+1. **Copy the sample**: Remove `.sample` from the appropriate hook file
+2. **Make executable** (Unix only): `chmod +x .specify/hooks/hook-name`
+3. **Edit the hook**: Customize the logic for your needs
+4. **Test**: Run the hook manually with test data
+
+**Example activation:**
+```bash
+# Unix/Linux/macOS - Activate prepare-feature-num hook
+cp .specify/hooks/prepare-feature-num.sample .specify/hooks/prepare-feature-num
+chmod +x .specify/hooks/prepare-feature-num
+
+# Windows PowerShell - Activate prepare-feature-num hook
+Copy-Item .specify/hooks/prepare-feature-num.ps1.sample .specify/hooks/prepare-feature-num.ps1
+```
+
+The Git-style naming provides familiar patterns for developers already using Git hooks, making the system more intuitive and easier to understand.

hooks/post-checkout.ps1.sample

@@ -0,0 +1,21 @@
+#!/usr/bin/env pwsh
+# Post-specify hook: Runs after feature branch and directory creation
+# Arguments: $args[0] = feature description
+# Environment: $env:BRANCH_NAME, $env:SPEC_FILE, $env:FEATURE_NUM available
+
+param(
+    [Parameter(Position=0)]
+    [string]$FeatureDescription
+)
+
+# Example: Create GitHub issue
+# if (Get-Command gh -ErrorAction SilentlyContinue) {
+#     gh issue create --title "Spec: $FeatureDescription" --body "Branch: $env:BRANCH_NAME, Spec: $env:SPEC_FILE"
+# }
+
+# Example: Send notification
+# $message = "Feature $env:FEATURE_NUM created: $env:BRANCH_NAME"
+# Send-MailMessage -To "team@company.com" -Subject "New Spec" -Body $message -SmtpServer "smtp.company.com"
+
+# Default: Do nothing
+exit 0

hooks/post-checkout.sample

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Post-specify hook: Runs after feature branch and directory creation
+# Arguments: $1 = feature description
+# Environment: BRANCH_NAME, SPEC_FILE, FEATURE_NUM available
+
+# Example: Create GitHub issue
+# if command -v gh >/dev/null 2>&1; then
+#     gh issue create --title "Spec: $1" --body "Branch: $BRANCH_NAME, Spec: $SPEC_FILE"
+# fi
+
+# Example: Send notification
+# echo "Feature $FEATURE_NUM created: $BRANCH_NAME" | mail -s "New Spec" team@company.com
+
+# Default: Do nothing
+exit 0

hooks/post-specify.ps1.sample

@@ -0,0 +1,29 @@
+#!/usr/bin/env pwsh
+# Post-specify hook: Runs after spec file is written and completed
+# Arguments: $args[0] = feature description
+# Environment: $env:BRANCH_NAME, $env:SPEC_FILE, $env:FEATURE_NUM available
+
+param(
+    [Parameter(Position=0)]
+    [string]$FeatureDescription
+)
+
+# Example: Create GitHub issue linking to completed spec
+# if (Get-Command gh -ErrorAction SilentlyContinue) {
+#     gh issue create --title "Spec Complete: $FeatureDescription" --body "Specification completed: $env:SPEC_FILE on branch $env:BRANCH_NAME"
+# }
+
+# Example: Send completion notification
+# $message = "Specification $env:FEATURE_NUM completed: $env:SPEC_FILE"
+# Send-MailMessage -To "team@company.com" -Subject "Spec Ready for Review" -Body $message -SmtpServer "smtp.company.com"
+
+# Example: Trigger CI/CD pipeline
+# $body = @{
+#     event = "spec_completed"
+#     branch = $env:BRANCH_NAME
+#     spec = $env:SPEC_FILE
+# } | ConvertTo-Json
+# Invoke-RestMethod -Uri $env:CI_WEBHOOK_URL -Method Post -Body $body -ContentType "application/json"
+
+# Default: Do nothing
+exit 0

hooks/post-specify.sample

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Post-specify hook: Runs after spec file is written and completed
+# Arguments: $1 = feature description
+# Environment: BRANCH_NAME, SPEC_FILE, FEATURE_NUM available
+
+# Example: Create GitHub issue linking to completed spec
+# if command -v gh >/dev/null 2>&1; then
+#     gh issue create --title "Spec Complete: $1" --body "Specification completed: $SPEC_FILE on branch $BRANCH_NAME"
+# fi
+
+# Example: Send completion notification
+# echo "Specification $FEATURE_NUM completed: $SPEC_FILE" | mail -s "Spec Ready for Review" team@company.com
+
+# Example: Trigger CI/CD pipeline
+# curl -X POST "$CI_WEBHOOK_URL" -d '{"event":"spec_completed","branch":"'$BRANCH_NAME'","spec":"'$SPEC_FILE'"}'
+
+# Default: Do nothing
+exit 0

hooks/pre-specify.ps1.sample

@@ -0,0 +1,18 @@
+#!/usr/bin/env pwsh
+# Pre-specify hook: Runs before feature creation
+# Arguments: $args[0] = feature description
+# Customize this script to add pre-processing logic
+
+param(
+    [Parameter(Position=0)]
+    [string]$FeatureDescription
+)
+
+# Example: Validate feature description
+# if ($FeatureDescription.Length -lt 10) {
+#     Write-Error "Error: Feature description too short"
+#     exit 1
+# }
+
+# Default: Do nothing
+exit 0

hooks/pre-specify.sample

@@ -0,0 +1,13 @@
+#!/bin/bash
+# Pre-specify hook: Runs before feature creation
+# Arguments: $1 = feature description
+# Customize this script to add pre-processing logic
+
+# Example: Validate feature description
+# if [[ ${#1} -lt 10 ]]; then
+#     echo "Error: Feature description too short" >&2
+#     exit 1
+# fi
+
+# Default: Do nothing
+exit 0

hooks/prepare-feature-num.ps1.sample

@@ -0,0 +1,23 @@
+#!/usr/bin/env pwsh
+# Feature-num hook: Override auto-generated feature number
+# Arguments: $args[0] = feature description
+# Output: Custom feature number (integer)
+
+param(
+    [Parameter(Position=0)]
+    [string]$FeatureDescription
+)
+
+# Example 1: Get from server
+# $featureNumber = Invoke-RestMethod -Uri "$env:SPEC_SERVER/api/next-number"
+# Write-Output $featureNumber
+
+# Example 2: Use GitHub issue number
+# if (Get-Command gh -ErrorAction SilentlyContinue) {
+#     $issueUrl = gh issue create --title "Spec: $FeatureDescription" --body "Specification development"
+#     $issueNumber = [regex]::Match($issueUrl, '\d+$').Value
+#     Write-Output $issueNumber
+# }
+
+# Default: Let script auto-increment (output nothing)
+exit 0

hooks/prepare-feature-num.sample

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Feature-num hook: Override auto-generated feature number
+# Arguments: $1 = feature description
+# Output: Custom feature number (integer)
+
+# Example 1: Get from server
+# FEATURE_NUMBER=$(curl -s "$SPEC_SERVER/api/next-number")
+# echo "$FEATURE_NUMBER"
+
+# Example 2: Use GitHub issue number
+# ISSUE_URL=$(gh issue create --title "Spec: $1" --body "Specification development")
+# ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -o '[0-9]*$')
+# echo "$ISSUE_NUMBER"
+
+# Default: Let script auto-increment (output nothing)
+exit 0