@localtech/claude-code-toolkit 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localtech/claude-code-toolkit",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Portable Claude Code toolkit with agents, skills, and hooks for professional development workflows",
   "main": "dist/index.js",
   "bin": {

package/templates/.claude/hooks/README.md

@@ -0,0 +1,342 @@
+# Claude Code Hooks Automation System
+
+This directory contains a comprehensive automation system that leverages Claude Code hooks to dramatically improve development efficiency, code quality, and workflow intelligence.
+
+## 🚀 What Are Claude Code Hooks?
+
+Hooks are automated scripts that run at specific points in your development workflow. Unlike traditional Git hooks, Claude Code hooks integrate deeply with AI agents and skills to provide intelligent, context-aware automation.
+
+## 🎯 Key Benefits
+
+### ⚡ **Development Efficiency**
+- **Automated Quality Checks**: Pre-commit hooks catch issues before they reach CI/CD
+- **Smart Automations**: Post-commit hooks handle documentation, notifications, and cleanup
+- **Deployment Safety**: Pre-push hooks validate code readiness for production
+
+### 🧠 **Intelligent Workflows**
+- **Agent Integration**: Hooks automatically trigger appropriate Claude Code agents based on changes
+- **Context Awareness**: Scripts analyze file changes to determine optimal actions
+- **Predictive Suggestions**: AI-powered recommendations for next development steps
+
+### 📊 **Quality Assurance**
+- **Consistent Standards**: Enforced coding standards and best practices
+- **Security Validation**: Automated security checks and vulnerability scanning
+- **Performance Monitoring**: Build size and performance regression detection
+
+### 🔄 **Workflow Optimization**
+- **Memory Integration**: Project learning and pattern recognition
+- **Documentation Automation**: Auto-generated docs that stay current
+- **Collaboration Enhancement**: Team notifications and coordination
+
+## 📁 Hook Structure
+
+```
+.claude/hooks/
+├── pre-commit/
+│   └── code-quality-guardian.sh    # Quality checks before commits
+├── post-commit/
+│   └── smart-automations.sh        # Intelligent post-commit actions
+├── pre-push/
+│   └── deployment-guardian.sh      # Deployment validation
+├── custom/
+│   └── intelligent-workflows.sh    # AI-powered workflow analysis
+└── hook-manager.sh                 # Central hook management
+```
+
+## 🛠️ Quick Setup
+
+### 1. Make Hooks Executable
+```bash
+# From your project root
+.claude/hooks/hook-manager.sh setup
+```
+
+### 2. Install Git Integration
+```bash
+# Install hooks into Git
+.claude/hooks/hook-manager.sh install
+```
+
+### 3. Test Everything
+```bash
+# Verify all hooks work correctly
+.claude/hooks/hook-manager.sh test
+```
+
+### 4. Check Status
+```bash
+# See hook status and available commands
+.claude/hooks/hook-manager.sh status
+```
+
+## 🎭 Hook Types & Timing
+
+### 🔍 **Pre-commit Hook** (`code-quality-guardian.sh`)
+**When**: Before code is committed to local repository
+**Purpose**: Quality assurance and consistency validation
+**Checks**:
+- ESLint/Prettier code formatting
+- TypeScript type checking
+- Security vulnerability scanning
+- Performance regression detection
+
+**Timing**: < 10 seconds (blocking - prevents bad commits)
+
+### 🤖 **Post-commit Hook** (`smart-automations.sh`)
+**When**: After successful commit to local repository
+**Purpose**: Intelligent automations and notifications
+**Actions**:
+- Documentation updates
+- Team notifications
+- Memory system updates
+- Backup creation
+
+**Timing**: < 60 seconds (background processing)
+
+### 🚀 **Pre-push Hook** (`deployment-guardian.sh`)
+**When**: Before pushing to remote repository
+**Purpose**: Deployment readiness validation
+**Validations**:
+- Comprehensive test suite execution
+- Build verification
+- Security audits
+- Environment-specific checks
+
+**Timing**: < 30 seconds (blocking - prevents broken deployments)
+
+### 🧠 **Custom Hook** (`intelligent-workflows.sh`)
+**When**: Manual execution or triggered by file changes
+**Purpose**: AI-powered workflow analysis and optimization
+**Capabilities**:
+- Change analysis and categorization
+- Agent triggering based on change types
+- Predictive development suggestions
+- Workflow optimization recommendations
+
+## 💡 Usage Examples
+
+### Automatic Quality Enforcement
+```bash
+# Try to commit code with linting errors
+git add .
+git commit -m "Add new feature"
+
+# Hook automatically runs:
+# ✅ ESLint checks
+# ✅ TypeScript compilation
+# ✅ Security scanning
+# ✅ Formatting validation
+
+# If issues found:
+# ❌ Commit blocked with helpful error messages
+# 💡 Suggestions for fixes
+```
+
+### Intelligent Post-commit Automation
+```bash
+# Commit API changes
+git commit -m "feat: add user authentication endpoint"
+
+# Hook automatically:
+# 📚 Updates API documentation
+# 🔔 Notifies team about new endpoint
+# 🧠 Adds to project memory system
+# 💾 Creates backup for high-impact changes
+```
+
+### Deployment Safety Net
+```bash
+# Push to main branch
+git push origin main
+
+# Hook validates:
+# 🧪 Runs full test suite
+# 🏗️ Verifies production build
+# 🔒 Performs security audit
+# 🌍 Checks deployment environment
+
+# Only allows push if all checks pass
+```
+
+### AI-Powered Workflow Intelligence
+```bash
+# Manual workflow analysis
+.claude/hooks/custom/intelligent-workflows.sh --manual
+
+# Analyzes recent changes and:
+# 🎯 Triggers appropriate agents (mobile-ui-specialist for UI changes)
+# 📊 Updates performance metrics
+# 🔮 Provides predictive suggestions
+# 📈 Identifies workflow optimization opportunities
+```
+
+## 🔗 Integration with Claude Code Agents
+
+Hooks automatically integrate with your specialized agents:
+
+### **File Change → Agent Triggering**
+- **UI Changes** → `mobile-ui-specialist` reviews consistency
+- **Security Files** → `code-reviewer` performs security audit
+- **API Changes** → `doc-writer` updates documentation
+- **Test Files** → `test-generator` validates coverage
+
+### **Memory System Integration**
+- **Decisions** → Architectural choices automatically logged
+- **Learnings** → Development insights captured
+- **Patterns** → Common solutions tracked
+- **Context** → Project state maintained
+
+## ⚙️ Configuration
+
+### Environment Variables
+```bash
+# Hook behavior configuration
+CLAUDE_CODE_HOOKS_DEBUG=true          # Enable debug logging
+CLAUDE_CODE_HOOKS_STRICT=true         # Fail on warnings
+CLAUDE_CODE_AUTO_BACKUP=true          # Enable automatic backups
+CLAUDE_CODE_SMART_NOTIFICATIONS=true  # Enable team notifications
+```
+
+### Hook Customization
+Each hook can be customized by editing the script files:
+- **Thresholds**: Adjust performance limits and quality standards
+- **Integrations**: Add your preferred notification services
+- **Rules**: Modify validation logic for your project needs
+
+## 📊 Monitoring & Analytics
+
+### Performance Metrics
+Hooks automatically track:
+- Execution times for each validation
+- Success/failure rates
+- Most common issues found
+- Performance trends over time
+
+### Quality Analytics
+- Code quality improvement trends
+- Most frequent validation failures
+- Team productivity metrics
+- Deployment success rates
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Hooks not running:**
+```bash
+# Check hook status
+.claude/hooks/hook-manager.sh status
+
+# Verify Git hooks are installed
+ls -la .git/hooks/
+
+# Test individual hooks
+.claude/hooks/hook-manager.sh test
+```
+
+**Slow performance:**
+- Reduce test scope for pre-commit hooks
+- Move heavy operations to post-commit
+- Cache results where possible
+- Use parallel execution for independent checks
+
+**False positives:**
+- Adjust validation rules in hook scripts
+- Add project-specific exceptions
+- Fine-tune security scanning rules
+
+## 🔧 Advanced Features
+
+### Custom Hook Creation
+Create new hooks for specific workflows:
+```bash
+# Create custom hook directory
+mkdir .claude/hooks/custom/my-workflow
+
+# Create hook script
+cat > .claude/hooks/custom/my-workflow/my-hook.sh << 'EOF'
+#!/bin/bash
+# Custom workflow hook
+echo "Running custom automation..."
+# Your automation logic here
+EOF
+
+# Make executable and test
+chmod +x .claude/hooks/custom/my-workflow/my-hook.sh
+.claude/hooks/hook-manager.sh test
+```
+
+### CI/CD Integration
+Hooks work seamlessly with CI/CD pipelines:
+- Local validation before push
+- Consistent standards across team
+- Early issue detection
+- Automated deployment preparation
+
+### Multi-environment Support
+Hooks automatically detect environment:
+- **Development**: Relaxed validation, fast feedback
+- **Staging**: Full validation, integration tests
+- **Production**: Strict validation, security audits
+
+## 📈 Performance Optimization
+
+### Hook Performance Guidelines
+- **Pre-commit**: < 10 seconds (developer experience)
+- **Pre-push**: < 30 seconds (deployment safety)
+- **Post-commit**: < 60 seconds (background tasks)
+- **Custom**: As needed (manual execution)
+
+### Optimization Techniques
+- **Caching**: Cache expensive operations
+- **Incremental Checks**: Only check changed files
+- **Parallel Execution**: Run independent validations concurrently
+- **Selective Running**: Skip irrelevant checks based on changes
+
+## 🔐 Security Considerations
+
+### Safe Hook Practices
+- **Input Validation**: Never trust user-provided data
+- **Permission Limits**: Run with minimal required permissions
+- **Network Security**: Use HTTPS for all external calls
+- **Secret Management**: Never log sensitive information
+
+### Audit Trail
+- All hook executions are logged
+- Security events are tracked
+- Performance metrics are monitored
+- Compliance with security policies
+
+## 🎯 Success Metrics
+
+### Quality Improvements
+- **Reduced Bug Rate**: Fewer issues reaching production
+- **Faster Reviews**: Automated checks catch obvious issues
+- **Consistent Code**: Enforced standards across team
+- **Better Documentation**: Auto-generated docs stay current
+
+### Efficiency Gains
+- **Faster Development**: Immediate feedback prevents rework
+- **Reduced Context Switching**: Automated notifications
+- **Better Planning**: Predictive suggestions guide development
+- **Streamlined Deployments**: Automated validation and preparation
+
+## 🚀 Getting Started
+
+1. **Setup**: Run `.claude/hooks/hook-manager.sh setup`
+2. **Install**: Run `.claude/hooks/hook-manager.sh install`
+3. **Test**: Run `.claude/hooks/hook-manager.sh test`
+4. **Customize**: Modify hooks for your project needs
+5. **Monitor**: Check performance and adjust as needed
+
+## 📞 Support
+
+For issues or questions:
+- Check hook logs: `.claude/hooks/logs/`
+- Run diagnostics: `.claude/hooks/hook-manager.sh test`
+- View status: `.claude/hooks/hook-manager.sh status`
+- Review documentation in each hook file
+
+---
+
+**🎉 Enjoy automated development workflows that make you more productive and your code more reliable!**

package/templates/.claude/hooks/custom/intelligent-workflows.sh

@@ -0,0 +1,336 @@
+#!/bin/bash
+# HOOK: custom-intelligent-workflows
+# DESCRIPTION: AI-powered workflow automation based on file changes and project context
+# AUTHOR: Claude Code Hooks Master
+# VERSION: 1.0.0
+# TRIGGER: Manual execution or integration with file watchers
+
+set -e
+
+# Colors and logging
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+PURPLE='\033[0;35m'
+NC='\033[0m'
+
+log_info() {
+    echo -e "${BLUE}[AI]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+log_ai() {
+    echo -e "${PURPLE}[🤖]${NC} $1"
+}
+
+# Analyze file changes and determine appropriate actions
+analyze_changes() {
+    log_ai "Analyzing recent file changes..."
+
+    # Get recent changes (last commit or staged files)
+    local changed_files
+    if git diff --cached --name-only | head -1 > /dev/null 2>&1; then
+        # Staged changes
+        mapfile -t changed_files < <(git diff --cached --name-only)
+    else
+        # Last commit changes
+        mapfile -t changed_files < <(git diff --name-only HEAD~1 2>/dev/null || git ls-files)
+    fi
+
+    # Categorize changes
+    local categories=("ui" "api" "config" "docs" "tests" "security" "performance")
+    declare -A change_types
+
+    for category in "${categories[@]}"; do
+        change_types[$category]=0
+    done
+
+    for file in "${changed_files[@]}"; do
+        case $file in
+            *component*|*ui/*|*screen/*|*view/*)
+                ((change_types[ui]++))
+                ;;
+            *api/*|*service/*|*endpoint/*)
+                ((change_types[api]++))
+                ;;
+            *config*|*.env*|package.json|tsconfig.json)
+                ((change_types[config]++))
+                ;;
+            *README*|*.md|docs/*)
+                ((change_types[docs]++))
+                ;;
+            *.test.*|*.spec.*|test/*)
+                ((change_types[tests]++))
+                ;;
+            *auth/*|*security/*|*encrypt*)
+                ((change_types[security]++))
+                ;;
+            *performance*|*optimize*|*cache*)
+                ((change_types[performance]++))
+                ;;
+        esac
+    done
+
+    # Determine primary change type
+    local max_changes=0
+    local primary_type="general"
+
+    for category in "${!change_types[@]}"; do
+        if [ "${change_types[$category]}" -gt "$max_changes" ]; then
+            max_changes=${change_types[$category]}
+            primary_type=$category
+        fi
+    done
+
+    echo "$primary_type"
+}
+
+# Trigger appropriate Claude Code agents based on change type
+trigger_agents() {
+    local change_type="$1"
+
+    log_ai "Triggering specialized agents for $change_type changes..."
+
+    case $change_type in
+        ui)
+            log_info "UI changes detected - triggering mobile UI specialist"
+            if command -v claude_code_run_agent &> /dev/null; then
+                claude_code_run_agent "mobile-ui-specialist" "review-ui-consistency" || true
+            fi
+            ;;
+
+        security)
+            log_info "Security changes detected - triggering code reviewer"
+            if command -v claude_code_run_agent &> /dev/null; then
+                claude_code_run_agent "code-reviewer" "security-audit" || true
+            fi
+            ;;
+
+        api)
+            log_info "API changes detected - triggering documentation agent"
+            if command -v claude_code_run_agent &> /dev/null; then
+                claude_code_run_agent "doc-writer" "update-api-docs" || true
+            fi
+            ;;
+
+        tests)
+            log_info "Test changes detected - triggering testing agent"
+            if command -v claude_code_run_agent &> /dev/null; then
+                claude_code_run_agent "test-generator" "validate-test-coverage" || true
+            fi
+            ;;
+
+        config)
+            log_info "Configuration changes detected - triggering code reviewer"
+            if command -v claude_code_run_agent &> /dev/null; then
+                claude_code_run_agent "code-reviewer" "config-review" || true
+            fi
+            ;;
+
+        docs)
+            log_info "Documentation changes detected - triggering documentation agent"
+            if command -v claude_code_run_agent &> /dev/null; then
+                claude_code_run_agent "doc-writer" "validate-docs" || true
+            fi
+            ;;
+    esac
+}
+
+# Intelligent documentation updates
+smart_docs_update() {
+    local change_type="$1"
+
+    log_ai "Analyzing documentation needs..."
+
+    case $change_type in
+        api)
+            log_info "API changes - checking if README API section needs updates"
+            # Check if API documentation is outdated
+            ;;
+
+        ui)
+            log_info "UI changes - considering component documentation updates"
+            # Check component documentation
+            ;;
+
+        config)
+            log_info "Config changes - updating configuration documentation"
+            # Update config docs
+            ;;
+    esac
+}
+
+# Performance monitoring and optimization suggestions
+performance_intelligence() {
+    log_ai "Analyzing performance implications..."
+
+    # Check for potential performance issues
+    local perf_issues=()
+
+    # Large files
+    local large_files
+    mapfile -t large_files < <(find . -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" | xargs ls -lh | awk '$5 > 500000 {print $9}' | head -3)
+    if [ ${#large_files[@]} -gt 0 ]; then
+        perf_issues+=("Large files detected: ${large_files[*]}")
+    fi
+
+    # Inefficient patterns
+    if git grep -q "for.*in.*array" -- "*.js" "*.ts" "*.jsx" "*.tsx" 2>/dev/null; then
+        perf_issues+=("Inefficient array iteration patterns found")
+    fi
+
+    # Bundle analysis (if applicable)
+    if [ -f "package.json" ] && grep -q "webpack\|parcel\|vite" package.json; then
+        perf_issues+=("Consider bundle size analysis")
+    fi
+
+    if [ ${#perf_issues[@]} -gt 0 ]; then
+        log_warn "Performance considerations:"
+        for issue in "${perf_issues[@]}"; do
+            echo "  • $issue"
+        done
+
+        # Suggest Claude Code agent
+        if command -v claude_code_run_agent &> /dev/null; then
+            claude_code_run_agent "debugger" "performance-review" || true
+        fi
+    else
+        log_success "No performance concerns detected"
+    fi
+}
+
+# Learning and memory integration
+update_project_memory() {
+    log_ai "Updating project learning memory..."
+
+    local memory_dir=".claude/memory"
+    if [ ! -d "$memory_dir" ]; then
+        log_warn "Memory system not found - skipping learning updates"
+        return 0
+    fi
+
+    # Analyze patterns in recent changes
+    local recent_patterns
+    recent_patterns=$(git log --oneline -10 | grep -o -E "(feat|fix|refactor|docs|style|test)" | sort | uniq -c | sort -nr)
+
+    if echo "$recent_patterns" | grep -q "feat"; then
+        echo "## $(date) - Feature Development Pattern" >> "$memory_dir/learnings.md"
+        echo "**Pattern**: High feature development activity detected" >> "$memory_dir/learnings.md"
+        echo "**Context**: Recent commits show active feature development" >> "$memory_dir/learnings.md"
+        echo "**Suggestion**: Consider integration testing for new features" >> "$memory_dir/learnings.md"
+        echo >> "$memory_dir/learnings.md"
+    fi
+
+    log_success "Project memory updated with recent patterns"
+}
+
+# Predictive suggestions
+predictive_suggestions() {
+    log_ai "Generating predictive development suggestions..."
+
+    local suggestions=()
+
+    # Based on current changes, predict next likely steps
+    if git diff --name-only | grep -q "component.*test"; then
+        suggestions+=("Consider adding integration tests for the new component")
+    fi
+
+    if git diff --name-only | grep -q "api.*route"; then
+        suggestions+=("Don't forget to update API documentation")
+        suggestions+=("Consider adding request/response validation")
+    fi
+
+    if git diff --name-only | grep -q "config"; then
+        suggestions+=("Test configuration changes across different environments")
+    fi
+
+    if [ ${#suggestions[@]} -gt 0 ]; then
+        log_info "🤖 Predictive suggestions for next steps:"
+        for suggestion in "${suggestions[@]}"; do
+            echo "  • $suggestion"
+        done
+    fi
+}
+
+# Workflow optimization
+optimize_workflow() {
+    log_ai "Analyzing workflow optimization opportunities..."
+
+    # Check for repeated patterns that could be automated
+    local repeated_actions
+    repeated_actions=$(git log --oneline -20 | grep -o -E "(add|update|fix|refactor)" | sort | uniq -c | awk '$1 > 3 {print $2}')
+
+    if [ -n "$repeated_actions" ]; then
+        log_info "🔄 Detected repetitive actions that could be automated:"
+        echo "$repeated_actions" | while read -r action; do
+            echo "  • Frequent '$action' operations - consider creating a custom hook"
+        done
+    fi
+
+    # Suggest improvements based on commit patterns
+    if git log --oneline -10 | grep -q "WIP\|temp\|fix.*later"; then
+        log_warn "Frequent WIP commits detected - consider feature branches"
+    fi
+
+    if git log --oneline -10 | grep -q "merge.*conflict"; then
+        log_warn "Merge conflicts detected - consider smaller, focused commits"
+    fi
+}
+
+# Main execution
+main() {
+    log_ai "🧠 Claude Code Intelligent Workflows - Custom Hook"
+    echo "======================================================"
+
+    # Analyze changes
+    local change_type
+    change_type=$(analyze_changes)
+
+    log_info "Primary change type detected: $change_type"
+    echo
+
+    # Execute intelligent automations
+    trigger_agents "$change_type"
+    smart_docs_update "$change_type"
+    performance_intelligence
+    update_project_memory
+    predictive_suggestions
+    optimize_workflow
+
+    echo
+    log_success "🎉 Intelligent workflow analysis completed!"
+    log_ai "All automations triggered based on your code changes"
+}
+
+# Allow manual execution
+if [ "${1:-}" = "--manual" ]; then
+    log_info "Manual execution requested"
+    main
+elif [ "${1:-}" = "--help" ]; then
+    echo "Intelligent Workflows Hook"
+    echo "Usage: $0 [--manual] [--help]"
+    echo ""
+    echo "This hook analyzes code changes and triggers intelligent automations:"
+    echo "  - Agent triggering based on change types"
+    echo "  - Smart documentation updates"
+    echo "  - Performance analysis"
+    echo "  - Memory system updates"
+    echo "  - Predictive suggestions"
+    echo "  - Workflow optimization"
+    exit 0
+else
+    # Auto-execution mode (would be called by file watchers or CI)
+    main
+fi