@paulduvall/claude-dev-toolkit 0.0.1-alpha.2 → 0.0.1-alpha.4

package/templates/hybrid-hook-config.yaml

@@ -0,0 +1,133 @@
+# Hybrid Hook Configuration for Claude Code
+# 
+# This configuration demonstrates the hybrid approach: lightweight trigger scripts
+# that delegate complex logic to AI subagents. This approach provides the best
+# balance of immediate response and intelligent analysis.
+#
+# Place relevant sections in your Claude Code settings.json file.
+
+##################################
+# Claude Code Settings.json Configuration
+##################################
+
+# Copy sections below into your ~/.claude/settings.json file:
+
+hooks_configuration:
+  PreToolUse:
+    - matcher: "Edit|Write|MultiEdit"
+      hooks:
+        - command: "~/.claude/hooks/pre-write-security.sh"
+          blocking: true
+          description: "Security analysis via security-auditor subagent"
+          timeout: 10000
+        
+  PostToolUse:
+    - matcher: "Edit|Write|MultiEdit" 
+      hooks:
+        - command: "~/.claude/hooks/file-logger.sh"
+          blocking: false
+          description: "Log file modifications"
+
+  OnError:
+    - hooks:
+        - command: "~/.claude/hooks/on-error-debug.sh"
+          blocking: false
+          description: "Automatic debugging via debug-specialist subagent"
+          
+  custom:
+    pre-commit:
+      command: "~/.claude/hooks/pre-commit-quality.sh"
+      description: "Quality checks via style-enforcer subagent"
+      blocking: true
+      
+    manual-security:
+      command: "~/.claude/hooks/subagent-trigger-simple.sh security-auditor manual"
+      description: "Manual security audit"
+
+##################################
+# Trigger Script to Subagent Mapping
+##################################
+# Reference for which trigger scripts delegate to which subagents:
+
+trigger_mappings:
+  pre-write-security.sh:
+    delegates_to: "security-auditor"
+    purpose: "Scan for security vulnerabilities before file modifications"
+    context_includes: ["tool", "file", "user", "timestamp"]
+    
+  pre-commit-quality.sh:  
+    delegates_to: "style-enforcer"
+    purpose: "Code quality validation before git commits"
+    context_includes: ["staged_files", "git_info", "file_types"]
+    
+  on-error-debug.sh:
+    delegates_to: "debug-specialist" 
+    purpose: "Automatic debugging assistance when errors occur"
+    context_includes: ["error_info", "system_context", "diagnostics"]
+    
+  subagent-trigger-simple.sh:
+    delegates_to: "any (specified as argument)"
+    purpose: "General-purpose lightweight subagent trigger"
+    context_includes: ["subagent", "event", "environment", "project"]
+
+##################################  
+# Available Subagents for Delegation
+##################################
+# These subagents can be invoked by the trigger scripts:
+
+available_subagents:
+  security-auditor:
+    specialization: "Security vulnerability detection and prevention"
+    best_for: ["credential_exposure", "injection_attacks", "access_control"]
+    trigger_events: ["pre_write", "pre_commit", "manual"]
+    
+  style-enforcer:
+    specialization: "Code quality, formatting, and style consistency"  
+    best_for: ["formatting", "imports", "documentation", "best_practices"]
+    trigger_events: ["pre_commit", "post_write", "manual"]
+    
+  debug-specialist:
+    specialization: "Error analysis and troubleshooting"
+    best_for: ["error_analysis", "root_cause", "performance_issues"]
+    trigger_events: ["on_error", "manual"]
+    
+  test-writer:
+    specialization: "Test case generation and validation"
+    best_for: ["test_coverage", "test_generation", "mocking"]
+    trigger_events: ["post_write", "pre_test", "manual"]
+
+##################################
+# Usage Examples  
+##################################
+
+# Manual subagent invocation:
+manual_usage:
+  - "~/.claude/hooks/subagent-trigger-simple.sh security-auditor pre_write"
+  - "~/.claude/hooks/subagent-trigger-simple.sh style-enforcer pre_commit 'Check Python files'"
+  - "~/.claude/hooks/subagent-trigger-simple.sh debug-specialist on_error 'ImportError'"
+
+# Event-driven automatic invocation:
+automatic_usage:
+  - "Edit/Write operations automatically trigger security analysis"  
+  - "Git operations can trigger quality checks"
+  - "Errors automatically engage debugging assistance"
+
+##################################
+# Migration from Complex to Hybrid
+##################################
+
+migration_benefits:
+  before: "253-line complex bash orchestration script"
+  after: "4 lightweight trigger scripts (30-100 lines each)"
+  improvements:
+    - "Simplified maintenance and debugging"
+    - "AI-driven complex logic instead of bash complexity"
+    - "Better error handling and user feedback"
+    - "Modular trigger scripts for specific use cases"
+    - "Preserved shared utilities in hooks/lib/"
+
+# To migrate:
+# 1. Replace complex hooks with appropriate trigger scripts
+# 2. Update Claude Code settings.json with new hook commands  
+# 3. Test triggers with manual invocation
+# 4. Verify subagent delegation works correctly

package/templates/security-focused-settings.json

@@ -0,0 +1,62 @@
+{
+  "// Security-focused Claude Code settings.json template": "Copy to ~/.claude/settings.json",
+  "// Includes security hooks and enhanced governance": "",
+  
+  "allowedTools": [
+    "Edit",
+    "Bash",
+    "Read",
+    "Write",
+    "MultiEdit"
+  ],
+  
+  "// Trust and onboarding settings": "",
+  "hasTrustDialogAccepted": true,
+  "hasCompletedProjectOnboarding": true,
+  
+  "// Performance optimization": "",
+  "parallelTasksCount": 3,
+  
+  "// Security hooks configuration": "",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/prevent-credential-exposure.sh",
+            "blocking": true,
+            "timeout": 10000
+          }
+        ]
+      }
+    ]
+  },
+  
+  "// Security-focused environment variables": "",
+  "env": {
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "true",
+    "BASH_DEFAULT_TIMEOUT_MS": "120000",
+    "SECURITY_WEBHOOK_URL": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
+    "CLAUDE_SECURITY_OVERRIDE": "false"
+  },
+  
+  "// Restrictive permissions for security": "",
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(python -m *)",
+      "Bash(git *)",
+      "Edit(*)",
+      "Read(*)",
+      "Write(*)"
+    ],
+    "deny": [
+      "Bash(curl *)",
+      "Bash(wget *)",
+      "Bash(ssh *)",
+      "Bash(sudo *)"
+    ]
+  }
+}

package/templates/subagent-hooks.yaml

@@ -0,0 +1,188 @@
+# Claude Code Subagent-Hook Event Mapping Configuration
+# 
+# This file defines which subagents should be automatically invoked
+# during specific Claude Code events. Place this file at:
+# ~/.claude/subagent-hooks.yaml
+#
+# Format:
+#   event_name:
+#     - subagent-name
+#     - another-subagent
+#
+# Available events:
+#   - pre_write: Before any file write/edit operation
+#   - post_write: After successful file write/edit
+#   - pre_commit: Before git commit operations
+#   - post_commit: After successful git commit
+#   - pre_test: Before running tests
+#   - post_test: After test execution
+#   - on_error: When an error occurs
+#   - security_check: Security validation events
+#   - code_review: Code review triggers
+#   - deployment: Deployment-related events
+
+# File modification events
+pre_write:
+  - security-auditor        # Check for security issues before writing
+  - style-enforcer          # Ensure code style compliance
+  - license-compliance-guardian  # Verify license headers
+
+post_write:
+  - documentation-curator   # Update docs after code changes
+  - test-writer            # Generate/update tests for new code
+
+# Git workflow events  
+pre_commit:
+  - trunk-guardian         # Ensure branch policies are followed
+  - security-auditor       # Final security check before commit
+  - contract-tester        # Verify API contracts maintained
+
+post_commit:
+  - audit-trail-verifier   # Log changes for audit trail
+  - change-scoper         # Analyze change impact
+
+# Testing events
+pre_test:
+  - test-writer           # Ensure adequate test coverage
+  - environment-guardian  # Validate test environment
+
+post_test:
+  - performance-guardian  # Analyze performance results
+  - observability-engineer # Check monitoring coverage
+
+on_test_failure:
+  - debug-specialist      # Diagnose test failures
+  - test-writer          # Suggest test fixes
+
+# Build and deployment events
+pre_build:
+  - dependency-steward    # Check dependency versions
+  - sbom-provenance      # Generate software bill of materials
+
+pre_deployment:
+  - deployment-strategist # Plan deployment approach
+  - environment-guardian  # Validate target environment
+  - rollback-first-responder # Prepare rollback plan
+
+post_deployment:
+  - observability-engineer # Verify monitoring active
+  - performance-guardian   # Check performance metrics
+
+# Error handling events
+on_error:
+  - debug-specialist      # Analyze and diagnose errors
+  - rollback-first-responder # Prepare recovery plan
+
+on_security_violation:
+  - security-auditor      # Deep security analysis
+  - audit-trail-verifier  # Document violation
+
+# Code review events
+code_review:
+  - code-review-assistant # Automated review suggestions
+  - requirements-reviewer # Check requirements alignment
+  - api-guardian         # Verify API compatibility
+
+# Continuous improvement events
+daily_analysis:
+  - data-steward         # Data quality check
+  - performance-guardian # Performance trending
+  - dependency-steward   # Dependency updates
+
+weekly_review:
+  - product-owner-proxy  # Business alignment check
+  - workflow-coordinator # Process optimization
+
+# CI/CD pipeline events
+pipeline_failure:
+  - ci-pipeline-curator  # Diagnose pipeline issues
+  - debug-specialist     # Investigate failures
+
+pipeline_success:
+  - continuous-release-orchestrator # Plan next release
+  - audit-trail-verifier # Document successful build
+
+# Custom event examples (add your own)
+custom_security_scan:
+  - security-auditor
+  - license-compliance-guardian
+  - sbom-provenance
+
+custom_performance_check:
+  - performance-guardian
+  - observability-engineer
+  - debug-specialist
+
+# Priority configurations (optional)
+# Define execution order and blocking behavior
+priorities:
+  security-auditor:
+    priority: 1        # Execute first
+    blocking: true     # Block operation if issues found
+  
+  style-enforcer:
+    priority: 2
+    blocking: false    # Non-blocking, just warnings
+  
+  test-writer:
+    priority: 3
+    blocking: false
+  
+  documentation-curator:
+    priority: 4
+    blocking: false
+
+# Subagent configuration overrides (optional)
+# Override default subagent settings for specific events
+overrides:
+  pre_deployment:
+    deployment-strategist:
+      timeout: 300    # 5 minutes for deployment planning
+      tools: "Read, Grep, Glob, Bash"  # Restricted tools
+    
+    environment-guardian:
+      timeout: 120
+      require_approval: true  # Human approval needed
+
+  on_error:
+    debug-specialist:
+      timeout: 600    # 10 minutes for debugging
+      tools: "all"     # Full tool access for debugging
+
+# Event conditions (optional)
+# Define conditions for event triggering
+conditions:
+  pre_write:
+    file_patterns:
+      - "*.py"        # Only Python files
+      - "*.js"        # Only JavaScript files
+      - "*.ts"        # Only TypeScript files
+    
+    exclude_patterns:
+      - "*.test.*"    # Skip test files
+      - "*.spec.*"    # Skip spec files
+      - "__pycache__/*" # Skip cache directories
+
+  code_review:
+    branch_patterns:
+      - "feature/*"   # Feature branches
+      - "hotfix/*"    # Hotfix branches
+    
+    exclude_branches:
+      - "main"        # Skip main branch
+      - "develop"     # Skip develop branch
+
+# Notification settings (optional)
+notifications:
+  on_blocking_event:
+    log_level: "error"
+    alert_user: true
+  
+  on_security_violation:
+    log_level: "critical"
+    alert_user: true
+    notify_webhook: "${SECURITY_WEBHOOK_URL}"
+  
+  on_success:
+    log_level: "info"
+    alert_user: false