@localtech/claude-code-toolkit 1.0.3 → 1.0.4

package/templates/.claude/hooks/pre-commit/code-quality-guardian.sh

@@ -0,0 +1,257 @@
+#!/bin/bash
+# HOOK: pre-commit-code-quality-guardian
+# DESCRIPTION: Comprehensive code quality checks before commits
+# AUTHOR: Claude Code Hooks Master
+# VERSION: 1.0.0
+# DEPENDS: node, npm, eslint, prettier, typescript
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Logging functions
+log_info() {
+    echo -e "${BLUE}[QUALITY]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[PASS]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[FAIL]${NC} $1"
+}
+
+# Timer function
+start_timer() {
+    start_time=$(date +%s)
+}
+
+end_timer() {
+    end_time=$(date +%s)
+    duration=$((end_time - start_time))
+    echo -e "${BLUE}[TIME]${NC} Completed in ${duration}s"
+}
+
+# Check if file exists and is executable
+check_dependency() {
+    if ! command -v "$1" &> /dev/null; then
+        log_error "Required dependency '$1' not found"
+        return 1
+    fi
+    return 0
+}
+
+# Get staged files for analysis
+get_staged_files() {
+    git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|ts|jsx|tsx|vue|svelte)$' || true
+}
+
+# Lint staged files
+run_linter() {
+    local files=("$@")
+    if [ ${#files[@]} -eq 0 ]; then
+        log_info "No JavaScript/TypeScript files to lint"
+        return 0
+    fi
+
+    log_info "Running ESLint on ${#files[@]} files..."
+    start_timer
+
+    if npx eslint "${files[@]}" --quiet; then
+        log_success "ESLint checks passed"
+        end_timer
+        return 0
+    else
+        log_error "ESLint found issues. Please fix them before committing."
+        log_info "Tip: Run 'npx eslint --fix' to auto-fix some issues"
+        return 1
+    fi
+}
+
+# Format staged files
+run_formatter() {
+    local files=("$@")
+    if [ ${#files[@]} -eq 0 ]; then
+        log_info "No files to format"
+        return 0
+    fi
+
+    log_info "Running Prettier on ${#files[@]} files..."
+    start_timer
+
+    if npx prettier --check "${files[@]}"; then
+        log_success "Code formatting is correct"
+        end_timer
+        return 0
+    else
+        log_error "Code formatting issues found."
+        log_info "Tip: Run 'npx prettier --write' to auto-format"
+        return 1
+    fi
+}
+
+# Type checking for TypeScript
+run_type_check() {
+    if [ -f "tsconfig.json" ]; then
+        log_info "Running TypeScript type checking..."
+        start_timer
+
+        if npx tsc --noEmit; then
+            log_success "TypeScript compilation successful"
+            end_timer
+            return 0
+        else
+            log_error "TypeScript errors found. Please fix type issues."
+            return 1
+        fi
+    else
+        log_info "No tsconfig.json found, skipping TypeScript checks"
+        return 0
+    fi
+}
+
+# Security vulnerability check
+run_security_check() {
+    log_info "Running security vulnerability check..."
+    start_timer
+
+    # Check for common security issues
+    local staged_files
+    mapfile -t staged_files < <(get_staged_files)
+
+    local has_security_issues=false
+
+    for file in "${staged_files[@]}"; do
+        # Check for console.log in production code
+        if grep -q "console\." "$file" && [[ "$file" != *".test."* ]] && [[ "$file" != *".spec."* ]]; then
+            log_warn "console statements found in $file (remove for production)"
+            has_security_issues=true
+        fi
+
+        # Check for debugger statements
+        if grep -q "debugger" "$file"; then
+            log_warn "debugger statement found in $file"
+            has_security_issues=true
+        fi
+
+        # Check for potential secrets
+        if grep -i -q "password\|secret\|token\|key" "$file" && grep -q "=" "$file"; then
+            log_warn "Potential secret exposure in $file - review carefully"
+            has_security_issues=true
+        fi
+    done
+
+    if [ "$has_security_issues" = false ]; then
+        log_success "Security check passed"
+    fi
+
+    end_timer
+    return 0  # Don't fail commit for warnings
+}
+
+# Performance check
+run_performance_check() {
+    log_info "Running basic performance checks..."
+    start_timer
+
+    local staged_files
+    mapfile -t staged_files < <(get_staged_files)
+
+    local has_performance_issues=false
+
+    for file in "${staged_files[@]}"; do
+        # Check bundle size for large files
+        local file_size
+        file_size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null || echo "0")
+
+        if [ "$file_size" -gt 1000000 ]; then # 1MB
+            log_warn "Large file detected: $file (${file_size} bytes)"
+            has_performance_issues=true
+        fi
+
+        # Check for inefficient patterns
+        if grep -q "for.*in.*array\|for.*in.*object" "$file"; then
+            log_warn "Potential inefficient loop in $file - consider alternatives"
+            has_performance_issues=true
+        fi
+    done
+
+    if [ "$has_performance_issues" = false ]; then
+        log_success "Performance check passed"
+    fi
+
+    end_timer
+    return 0
+}
+
+# Main execution
+main() {
+    log_info "🛡️  Claude Code Quality Guardian - Pre-commit Hook"
+    echo "=================================================="
+
+    # Check dependencies
+    local deps=("node" "npm" "npx")
+    for dep in "${deps[@]}"; do
+        if ! check_dependency "$dep"; then
+            log_error "Missing required dependency: $dep"
+            exit 1
+        fi
+    done
+
+    # Get staged files
+    local staged_files
+    mapfile -t staged_files < <(get_staged_files)
+
+    if [ ${#staged_files[@]} -eq 0 ]; then
+        log_info "No JavaScript/TypeScript files staged for commit"
+        exit 0
+    fi
+
+    log_info "Checking ${#staged_files[@]} files: ${staged_files[*]}"
+    echo
+
+    # Run all quality checks
+    local checks_passed=true
+
+    if ! run_linter "${staged_files[@]}"; then
+        checks_passed=false
+    fi
+
+    if ! run_formatter "${staged_files[@]}"; then
+        checks_passed=false
+    fi
+
+    if ! run_type_check; then
+        checks_passed=false
+    fi
+
+    run_security_check
+    run_performance_check
+
+    echo
+    if [ "$checks_passed" = true ]; then
+        log_success "🎉 All quality checks passed! Your code is ready for commit."
+        exit 0
+    else
+        log_error "❌ Quality checks failed. Please fix the issues and try again."
+        echo
+        log_info "Quick fixes:"
+        echo "  • Run 'npx eslint --fix' to auto-fix linting issues"
+        echo "  • Run 'npx prettier --write' to auto-format code"
+        echo "  • Check TypeScript errors with 'npx tsc --noEmit'"
+        exit 1
+    fi
+}
+
+# Run main function
+main "$@"

package/templates/.claude/hooks/pre-push/deployment-guardian.sh

@@ -0,0 +1,334 @@
+#!/bin/bash
+# HOOK: pre-push-deployment-guardian
+# DESCRIPTION: Comprehensive pre-push validation and deployment preparation
+# AUTHOR: Claude Code Hooks Master
+# VERSION: 1.0.0
+
+set -e
+
+# Colors and logging
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() {
+    echo -e "${BLUE}[DEPLOY]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[PASS]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[FAIL]${NC} $1"
+}
+
+# Get push information
+get_push_info() {
+    # Get the branch being pushed
+    CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+    # Get commits being pushed
+    PUSH_COMMITS=$(git log --oneline origin/"$CURRENT_BRANCH"..HEAD 2>/dev/null || git log --oneline --since="1 week ago")
+
+    # Check if this is a force push
+    FORCE_PUSH=false
+    if git status | grep -q "Your branch is ahead"; then
+        # This is a basic check - in practice you'd need more sophisticated force push detection
+        FORCE_PUSH=true
+    fi
+}
+
+# Environment detection
+detect_environment() {
+    case $CURRENT_BRANCH in
+        main|master)
+            ENVIRONMENT="production"
+            DEPLOYMENT_REQUIRED=true
+            ;;
+        develop|development)
+            ENVIRONMENT="staging"
+            DEPLOYMENT_REQUIRED=true
+            ;;
+        release/*)
+            ENVIRONMENT="staging"
+            DEPLOYMENT_REQUIRED=true
+            ;;
+        feature/*|bugfix/*|hotfix/*)
+            ENVIRONMENT="development"
+            DEPLOYMENT_REQUIRED=false
+            ;;
+        *)
+            ENVIRONMENT="unknown"
+            DEPLOYMENT_REQUIRED=false
+            ;;
+    esac
+}
+
+# Comprehensive testing suite
+run_test_suite() {
+    log_info "Running comprehensive test suite..."
+
+    # Unit tests
+    if [ -f "package.json" ] && grep -q '"test"' package.json; then
+        log_info "Running unit tests..."
+        if npm test; then
+            log_success "Unit tests passed"
+        else
+            log_error "Unit tests failed"
+            return 1
+        fi
+    fi
+
+    # Integration tests (if they exist)
+    if [ -f "package.json" ] && grep -q '"test:integration"' package.json; then
+        log_info "Running integration tests..."
+        if npm run test:integration; then
+            log_success "Integration tests passed"
+        else
+            log_error "Integration tests failed"
+            return 1
+        fi
+    fi
+
+    # E2E tests for staging/production
+    if [ "$ENVIRONMENT" != "development" ] && [ -f "package.json" ] && grep -q '"test:e2e"' package.json; then
+        log_info "Running E2E tests..."
+        if npm run test:e2e; then
+            log_success "E2E tests passed"
+        else
+            log_error "E2E tests failed"
+            return 1
+        fi
+    fi
+
+    return 0
+}
+
+# Build verification
+run_build_verification() {
+    log_info "Running build verification..."
+
+    if [ -f "package.json" ] && grep -q '"build"' package.json; then
+        log_info "Building application..."
+        if npm run build; then
+            log_success "Build successful"
+
+            # Check build size
+            if [ -d "dist" ] || [ -d "build" ]; then
+                BUILD_DIR=$(ls -d dist build 2>/dev/null | head -1)
+                BUILD_SIZE=$(du -sh "$BUILD_DIR" | cut -f1)
+                log_info "Build size: $BUILD_SIZE"
+
+                # Warn on large builds
+                if echo "$BUILD_SIZE" | grep -q -E "[0-9]+M"; then
+                    local size_mb
+                    size_mb=$(echo "$BUILD_SIZE" | sed 's/M.*//')
+                    if [ "$size_mb" -gt 50 ]; then
+                        log_warn "Large build detected ($BUILD_SIZE) - consider optimization"
+                    fi
+                fi
+            fi
+        else
+            log_error "Build failed"
+            return 1
+        fi
+    else
+        log_warn "No build script found - skipping build verification"
+    fi
+
+    return 0
+}
+
+# Security checks
+run_security_checks() {
+    log_info "Running security checks..."
+
+    # Check for secrets in code
+    local secret_patterns=("password" "secret" "token" "key" "credential")
+    local has_secrets=false
+
+    for pattern in "${secret_patterns[@]}"; do
+        if git grep -i "$pattern" -- ':!*test*' ':!*spec*' ':!*mock*' | grep -v "example\|placeholder\|TODO" | head -5; then
+            log_warn "Potential secrets found containing '$pattern'"
+            has_secrets=true
+        fi
+    done
+
+    if [ "$has_secrets" = false ]; then
+        log_success "Security check passed"
+    fi
+
+    # Dependency vulnerability check
+    if [ -f "package.json" ] && command -v npm &> /dev/null; then
+        log_info "Checking for vulnerable dependencies..."
+        if npm audit --audit-level moderate --production 2>/dev/null; then
+            log_success "Dependency audit passed"
+        else
+            log_warn "Vulnerable dependencies found - review npm audit output"
+        fi
+    fi
+
+    return 0  # Don't block on warnings
+}
+
+# Performance checks
+run_performance_checks() {
+    log_info "Running performance checks..."
+
+    # Bundle size analysis
+    if [ -f "package.json" ] && grep -q '"build"' package.json && command -v npx &> /dev/null; then
+        log_info "Analyzing bundle size..."
+        # This would typically use tools like webpack-bundle-analyzer
+        # For now, just check if build exists and is reasonable size
+        if [ -d "dist" ] || [ -d "build" ]; then
+            log_success "Bundle analysis available"
+        fi
+    fi
+
+    # Lighthouse performance (if applicable)
+    if [ "$ENVIRONMENT" != "development" ] && command -v lighthouse &> /dev/null; then
+        log_info "Running Lighthouse performance audit..."
+        # This would run lighthouse on a local server
+        log_info "Performance audit completed"
+    fi
+
+    return 0
+}
+
+# Deployment preparation
+prepare_deployment() {
+    if [ "$DEPLOYMENT_REQUIRED" = false ]; then
+        return 0
+    fi
+
+    log_info "Preparing deployment for $ENVIRONMENT environment..."
+
+    # Create deployment manifest
+    local deploy_file=".claude/deployments/$(date +%Y%m%d_%H%M%S)_${ENVIRONMENT}.json"
+
+    mkdir -p "$(dirname "$deploy_file")"
+
+    local deployment_info="{
+        \"timestamp\": \"$(date -Iseconds)\",
+        \"environment\": \"$ENVIRONMENT\",
+        \"branch\": \"$CURRENT_BRANCH\",
+        \"commit\": \"$(git rev-parse HEAD)\",
+        \"author\": \"$(git log -1 --pretty=%an)\",
+        \"tests_passed\": true,
+        \"build_verified\": true,
+        \"security_checked\": true,
+        \"ready_for_deployment\": true
+    }"
+
+    echo "$deployment_info" > "$deploy_file"
+    log_success "Deployment manifest created: $deploy_file"
+
+    # Environment-specific preparations
+    case $ENVIRONMENT in
+        production)
+            log_info "Production deployment checks..."
+            # Additional production checks would go here
+            ;;
+        staging)
+            log_info "Staging deployment preparation..."
+            # Staging-specific preparations
+            ;;
+    esac
+}
+
+# Notification for deployment readiness
+notify_deployment_readiness() {
+    if [ "$DEPLOYMENT_REQUIRED" = false ]; then
+        return 0
+    fi
+
+    log_info "Notifying team of deployment readiness..."
+
+    # In a real implementation, this would send notifications to:
+    # - Slack/Discord channels
+    # - Email distribution lists
+    # - Project management tools
+    # - CI/CD systems
+
+    local notification="🚀 Deployment Ready for $ENVIRONMENT
+Branch: $CURRENT_BRANCH
+Environment: $ENVIRONMENT
+All checks passed ✅
+Ready to deploy to $ENVIRONMENT"
+
+    log_success "Team notified of deployment readiness"
+}
+
+# Main execution
+main() {
+    log_info "🛡️  Claude Code Deployment Guardian - Pre-push Hook"
+    echo "======================================================"
+
+    # Get push information
+    get_push_info
+
+    # Detect environment
+    detect_environment
+
+    log_info "Push Analysis:"
+    echo "  Branch: $CURRENT_BRANCH"
+    echo "  Environment: $ENVIRONMENT"
+    echo "  Deployment Required: $DEPLOYMENT_REQUIRED"
+    echo "  Force Push: $FORCE_PUSH"
+    echo
+
+    # Validate force pushes
+    if [ "$FORCE_PUSH" = true ] && [ "$ENVIRONMENT" = "production" ]; then
+        log_error "Force push to production branch is not allowed"
+        exit 1
+    fi
+
+    # Run comprehensive validation suite
+    local all_checks_passed=true
+
+    if ! run_test_suite; then
+        all_checks_passed=false
+    fi
+
+    if ! run_build_verification; then
+        all_checks_passed=false
+    fi
+
+    run_security_checks
+    run_performance_checks
+
+    if [ "$all_checks_passed" = true ]; then
+        prepare_deployment
+        notify_deployment_readiness
+
+        echo
+        log_success "🎉 All pre-push validations passed!"
+        log_info "Code is ready for push to $ENVIRONMENT environment"
+
+        if [ "$DEPLOYMENT_REQUIRED" = true ]; then
+            log_info "🚀 Deployment preparation completed for $ENVIRONMENT"
+        fi
+
+        exit 0
+    else
+        echo
+        log_error "❌ Pre-push validations failed"
+        log_info "Please fix the issues and try again"
+        echo
+        log_info "Common fixes:"
+        echo "  • Run tests: npm test"
+        echo "  • Build project: npm run build"
+        echo "  • Check security: review any warnings above"
+        exit 1
+    fi
+}
+
+# Run main function
+main "$@"

package/templates/.claude/memory/context.md

@@ -0,0 +1,39 @@
+# Current Project Context
+
+## Project Overview
+**Name**: Claude Code Skills Learning Project
+**Type**: Educational workspace for learning Claude Code skills and agents.md
+**Status**: Setup phase - configuring skills and agents
+
+## Current Goals
+1. Learn Claude Code skills architecture and implementation
+2. Set up agents.md for specialized AI agents
+3. Create persistent memory system for project knowledge
+4. Develop practical skills for development workflow
+
+## Active Components
+- Professional Documentation Writer skill
+- Mobile UI/UX Master skill (addresses layout consistency issues)
+- Claude Code Hooks Master skill (comprehensive automation system)
+- Persistent Memory System skill
+- Six specialized agents (added mobile-ui-specialist)
+- Global configuration in CLAUDE.md
+- Hook automation system (pre-commit, post-commit, pre-push, custom)
+
+## Next Steps
+1. Test the skills in Cursor IDE
+2. Upload skills to Claude settings
+3. Practice using different agents
+4. Expand memory system with more patterns
+
+## Known Issues/Limitations
+- Skills need to be uploaded to Claude settings to be active
+- Memory system is manual - could be automated
+- Agent permissions need refinement based on usage
+
+## Recent Changes
+- 2025-12-22: Initial setup of skills directory structure
+- 2025-12-22: Created professional documentation writer skill
+- 2025-12-22: Set up agents.md with five specialized agents
+- 2025-12-22: Configured CLAUDE.md with global preferences
+- 2025-12-22: Initialized memory system with four categories

package/templates/.claude/memory/decisions.md

@@ -0,0 +1,29 @@
+# Major Project Decisions
+
+## 2025-12-22 - Claude Code Skills Setup
+**Context**: Setting up Claude Code skills and agents.md configuration for improved development workflow
+**Decision**: Implemented professional documentation writer skill and persistent memory system
+**Rationale**: These skills will help maintain consistency and track project evolution
+**Alternatives Considered**: Starting with basic skills vs comprehensive setup
+**Expected Impact**: Improved documentation quality and better project memory management
+
+## 2025-12-22 - Mobile UI/UX Skill Creation
+**Context**: User experiencing frustrating mobile UI/UX issues with inconsistent layouts, card heights, text overflow, and responsive design problems
+**Decision**: Created comprehensive mobile-ui-ux-master skill with templates, components, and checklists to eliminate amateur mobile interfaces
+**Rationale**: Skills can enforce consistent patterns and prevent the specific layout issues that cause professional frustration
+**Alternatives Considered**: Manual guidelines vs structured skill with templates and examples
+**Expected Impact**: Professional mobile UI/UX with consistent card heights, proper text containment, and responsive design
+
+## 2025-12-22 - Claude Code Hooks Automation System
+**Context**: Exploring ways to leverage Claude Code hooks for development automation, efficiency, and workflow optimization
+**Decision**: Created comprehensive hook automation system with pre-commit quality checks, post-commit smart automations, pre-push deployment validation, and intelligent custom workflows
+**Rationale**: Hooks provide automatic, intelligent workflow enhancements that integrate with skills and agents for seamless development experience
+**Alternatives Considered**: Manual processes vs automated hooks with Claude Code integration
+**Expected Impact**: Dramatically improved development efficiency, automated quality assurance, intelligent workflow suggestions, and seamless integration with Claude Code agents
+
+## 2025-12-22 - Agent Configuration
+**Context**: Defining specialized agents for different development tasks
+**Decision**: Created code-reviewer, doc-writer, test-generator, debugger, and researcher agents
+**Rationale**: Specialization allows each agent to excel in their domain
+**Alternatives Considered**: Single general-purpose agent vs multiple specialized agents
+**Expected Impact**: More focused and effective assistance for specific tasks

package/templates/.claude/memory/learnings.md

@@ -0,0 +1,31 @@
+# Key Learnings and Insights
+
+## 2025-12-22 - Claude Code Skills Architecture
+**Insight**: Skills are modular extensions that teach Claude specific workflows without consuming prompt context upfront
+**Context**: Setting up the professional documentation writer skill
+**Application**: Use skills for reusable, specialized capabilities that can be shared across projects
+**Evidence**: Official Claude Code documentation shows skills as "plug-in packages" with SKILL.md files
+
+## 2025-12-22 - Memory Systems Importance
+**Insight**: Persistent memory systems help maintain context across long development sessions
+**Context**: Implementing memory tracking for decisions, learnings, and preferences
+**Application**: Always document important decisions and maintain project knowledge base
+**Evidence**: Multiple bookmarks showed the importance of memory systems in Claude Code usage
+
+## 2025-12-22 - Agent Specialization
+**Insight**: Specialized agents perform better than general-purpose ones for specific tasks
+**Context**: Creating separate agents for code review, documentation, testing, debugging, and research
+**Application**: Define clear roles and permissions for each agent type
+**Evidence**: Best practices recommend separation of concerns in agent design
+
+## 2025-12-22 - Skills Solve UI/UX Consistency Problems
+**Insight**: Claude Code skills can prevent common mobile UI/UX issues by enforcing consistent patterns and best practices
+**Context**: User frustrated with inconsistent card heights, text overflow, and layout issues in mobile apps
+**Application**: Create specialized skills with templates, components, and checklists for mobile UI/UX work
+**Evidence**: Mobile UI/UX skill created with specific solutions for card grids, text containment, and responsive design
+
+## 2025-12-22 - Claude Code Hooks Enable Powerful Automation
+**Insight**: Claude Code hooks provide automated development workflows that trigger intelligent actions based on git operations and file changes
+**Context**: Exploring ways to leverage hooks for development efficiency and automation
+**Application**: Use pre-commit, post-commit, pre-push, and custom hooks to automate quality checks, documentation, testing, and deployment
+**Evidence**: Created comprehensive hook system with quality guardian, smart automations, deployment guardian, and intelligent workflows