@localtech/claude-code-toolkit 1.0.3 → 1.0.5

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

package/templates/.claude/memory/patterns.md

@@ -0,0 +1,72 @@
+# Common Patterns and Solutions
+
+## Error Handling Pattern
+```
+try {
+  // Operation that might fail
+  const result = await riskyOperation();
+  return result;
+} catch (error) {
+  // Log error with context
+  console.error(`Operation failed: ${error.message}`, { context: additionalData });
+  // Return safe default or re-throw
+  throw new Error(`Operation failed: ${error.message}`);
+}
+```
+
+## API Response Pattern
+```
+interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  timestamp: string;
+}
+
+function createResponse<T>(data: T): ApiResponse<T> {
+  return {
+    success: true,
+    data,
+    timestamp: new Date().toISOString()
+  };
+}
+```
+
+## Component Structure Pattern
+```
+interface ComponentProps {
+  // Define props interface
+}
+
+export function ComponentName({ prop1, prop2 }: ComponentProps) {
+  // Early returns for edge cases
+  if (!prop1) return null;
+
+  // Main component logic
+  return (
+    <div>
+      {/* Component JSX */}
+    </div>
+  );
+}
+```
+
+## Testing Pattern
+```
+describe('ComponentName', () => {
+  it('should render correctly with valid props', () => {
+    // Arrange
+    const props = { /* test props */ };
+
+    // Act
+    render(<ComponentName {...props} />);
+
+    // Assert
+    expect(screen.getByText('expected text')).toBeInTheDocument();
+  });
+
+  it('should handle error states gracefully', () => {
+    // Test error scenarios
+  });
+});
+```

package/templates/.claude/memory/preferences.md

@@ -0,0 +1,23 @@
+# User Preferences and Working Styles
+
+## Development Environment
+**IDE**: Cursor IDE with Claude Code extension
+**Theme**: Dark mode preferred
+**Font**: Monospace, 14pt for code readability
+
+## Code Style Preferences
+**Language**: TypeScript preferred over JavaScript for new projects
+**Architecture**: Functional programming principles where appropriate
+**Naming**: camelCase for variables/functions, PascalCase for classes/types
+**Documentation**: JSDoc/TSDoc for public APIs, inline comments for complex logic
+
+## Communication Style
+**Feedback**: Prefer specific, actionable feedback with examples
+**Documentation**: Professional yet approachable tone
+**Decision Making**: Prefer data-driven decisions with clear rationale
+
+## Tool Preferences
+**Version Control**: Git with conventional commits
+**Testing**: Jest/Vitest with >80% coverage target
+**Linting**: ESLint with TypeScript rules
+**Package Management**: Prefer npm for stability, yarn/pnpm for performance