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

package/hooks/subagent-trigger.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Claude Code Hook: Subagent Event Trigger
+# 
+# Purpose: Bridge between Claude Code hooks and subagents, enabling event-driven subagent execution
+# Usage: subagent-trigger.sh [OPTIONS] <subagent-name> [event-type] [additional-context]
+#        subagent-trigger.sh [OPTIONS] --event <event-type>
+# Trigger: Can be used in PreToolUse, PostToolUse, or custom hook configurations
+#
+# This hook enables automatic invocation of specialized subagents based on
+# specific events, ensuring the right expertise is applied at the right time.
+
+##################################
+# Module Loading
+##################################
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/lib"
+
+# Source all required modules in dependency order
+source "$LIB_DIR/config-constants.sh"
+source "$LIB_DIR/file-utils.sh" 
+source "$LIB_DIR/error-handler.sh"
+source "$LIB_DIR/argument-parser.sh"
+source "$LIB_DIR/subagent-discovery.sh"
+source "$LIB_DIR/subagent-validator.sh"
+source "$LIB_DIR/context-manager.sh"
+source "$LIB_DIR/execution-engine.sh"
+
+##################################
+# Initialization
+##################################
+initialize_all_modules() {
+    log_debug "Initializing all modules"
+    
+    initialize_error_handling || {
+        echo "FATAL: Error handling initialization failed" >&2
+        exit $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_argument_parser || {
+        log_error "Argument parser initialization failed"
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_subagent_discovery || {
+        log_error "Subagent discovery initialization failed"  
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_subagent_validator || {
+        log_error "Subagent validator initialization failed"
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_context_manager || {
+        log_error "Context manager initialization failed"
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    initialize_execution_engine || {
+        log_error "Execution engine initialization failed"
+        return $EXIT_GENERAL_ERROR
+    }
+    
+    log_debug "All modules initialized successfully"
+    return $EXIT_SUCCESS
+}
+
+##################################
+# Core Workflow Functions
+##################################
+execute_single_subagent() {
+    local subagent_name="$1"
+    local event_type="$2"
+    local additional_context="$3"
+    
+    log_info "Executing single subagent: $subagent_name for event: $event_type"
+    
+    # Find the subagent file
+    local subagent_file
+    if ! subagent_file=$(find_subagent "$subagent_name"); then
+        handle_missing_subagent "$subagent_name"
+        return $EXIT_SUBAGENT_NOT_FOUND
+    fi
+    
+    log_debug "Found subagent file: $subagent_file"
+    
+    # Validate the subagent
+    if ! validate_subagent_file "$subagent_file" "strict"; then
+        handle_validation_failure "$subagent_name" "file validation failed"
+        return $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Create context file
+    if ! create_context_file "$subagent_name" "$event_type"; then
+        log_error "Failed to create context file"
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    local context_file
+    context_file=$(get_context_file)
+    
+    # Gather context information
+    if ! gather_complete_context "$event_type" "$subagent_name" "$additional_context" "false"; then
+        log_error "Failed to gather context"
+        cleanup_context_file
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    # Write context to file
+    if ! write_context_to_file "$context_file"; then
+        log_error "Failed to write context to file"
+        cleanup_context_file
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    # Determine execution mode and timeout
+    local execution_mode timeout
+    execution_mode=$(determine_execution_mode "$event_type" "$(get_parsed_execution_mode)")
+    timeout=$(get_timeout_for_execution "$event_type" "$subagent_name")
+    
+    # Check for dry run mode
+    if is_dry_run; then
+        execution_mode="dry-run"
+    fi
+    
+    # Execute the subagent
+    local execution_result
+    if ! execute_subagent "$subagent_file" "$context_file" "$execution_mode" "$timeout"; then
+        log_error "Subagent execution failed: $subagent_name"
+        cleanup_context_file
+        return $EXIT_EXECUTION_FAILED
+    fi
+    
+    # Clean up context file
+    cleanup_context_file
+    
+    log_info "Single subagent execution completed successfully: $subagent_name"
+    return $EXIT_SUCCESS
+}
+
+execute_event_based_subagents() {
+    local event_type="$1"
+    local additional_context="$2"
+    
+    log_info "Executing event-based subagents for event: $event_type"
+    
+    # Create shared context file for all subagents
+    if ! create_context_file "event-$event_type" "$event_type"; then
+        log_error "Failed to create context file for event execution"
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    local context_file
+    context_file=$(get_context_file)
+    
+    # Gather context information
+    if ! gather_complete_context "$event_type" "event-based" "$additional_context" "false"; then
+        log_error "Failed to gather context for event execution"
+        cleanup_context_file
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    # Write context to file
+    if ! write_context_to_file "$context_file"; then
+        log_error "Failed to write context to file for event execution"
+        cleanup_context_file  
+        return $EXIT_GENERAL_ERROR
+    fi
+    
+    # Determine execution mode
+    local execution_mode
+    execution_mode=$(determine_execution_mode "$event_type" "$(get_parsed_execution_mode)")
+    
+    # Execute all subagents for this event
+    local execution_result
+    if ! execute_multiple_subagents "$event_type" "$context_file" "$execution_mode"; then
+        log_error "Event-based subagent execution failed for event: $event_type"
+        cleanup_context_file
+        return $EXIT_EXECUTION_FAILED
+    fi
+    
+    # Clean up context file
+    cleanup_context_file
+    
+    log_info "Event-based subagent execution completed successfully: $event_type"
+    return $EXIT_SUCCESS
+}
+
+##################################
+# Main Hook Logic
+##################################
+main() {
+    # Initialize all modules
+    if ! initialize_all_modules; then
+        echo "FATAL: Module initialization failed" >&2
+        exit $EXIT_GENERAL_ERROR
+    fi
+    
+    # Parse arguments
+    if ! parse_arguments "$@"; then
+        # Error messages already logged by parser
+        safe_exit $EXIT_VALIDATION_FAILED
+    fi
+    
+    # Handle help request
+    if is_help_requested; then
+        show_usage
+        safe_exit $EXIT_SUCCESS
+    fi
+    
+    # Log parsed arguments in debug mode
+    if is_debug_mode; then
+        log_parsed_arguments
+    fi
+    
+    # Get execution parameters
+    local subagent_name event_type additional_context execution_mode
+    subagent_name=$(get_parsed_subagent_name)
+    event_type=$(get_parsed_event_type)
+    additional_context=$(get_parsed_additional_context)
+    execution_mode=$(get_parsed_execution_mode)
+    
+    log_info "Starting subagent hook execution"
+    log_info "Mode: $execution_mode, Event: $event_type"
+    
+    # Execute based on mode
+    local exit_code
+    case "$execution_mode" in
+        "event-based")
+            execute_event_based_subagents "$event_type" "$additional_context"
+            exit_code=$?
+            ;;
+        *)
+            execute_single_subagent "$subagent_name" "$event_type" "$additional_context"
+            exit_code=$?
+            ;;
+    esac
+    
+    if [[ $exit_code -eq $EXIT_SUCCESS ]]; then
+        log_info "Subagent hook completed successfully"
+    else
+        log_error "Subagent hook failed with exit code: $exit_code"
+    fi
+    
+    safe_exit $exit_code
+}
+
+##################################
+# Execute Main Function
+##################################
+main "$@"

package/lib/hook-installer-core.js

@@ -320,9 +320,9 @@ class HookInstaller {
      */
     _getPackageVersion() {
         try {
-            return require('../package.json').version || '0.0.1-alpha.1';
+            return require('../package.json').version || '0.0.1-alpha.2';
         } catch (error) {
-            return '0.0.1-alpha.1';
+            return '0.0.1-alpha.2';
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paulduvall/claude-dev-toolkit",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.1-alpha.4",
   "description": "Custom commands toolkit for Claude Code - streamline your development workflow",
   "author": "Paul Duvall",
   "license": "MIT",
@@ -42,6 +42,8 @@
     "test:subagents": "node tests/test_subagents_command.js",
     "test:subagents-async": "node tests/test_subagents_async.js",
     "test:config": "node tests/test_config_command.js",
+    "test:ux-quick-start": "node tests/test_ux_quick_start_guide.js",
+    "test:npm-completeness": "node tests/test_npm_package_completeness.js",
     "test:install": "scripts/publishing/test-package-install.sh",
     "test:manual": "scripts/publishing/manual-test-suite.sh",
     "publish:local": "scripts/publishing/setup-local-registry.sh",

package/templates/README.md

@@ -0,0 +1,100 @@
+# Claude Code Settings Templates
+
+This directory contains example `settings.json` configurations for different use cases.
+
+## Templates Available
+
+### 1. `basic-settings.json`
+**Use case**: Simple development setup
+**Features**:
+- Basic tool permissions for custom commands
+- API key helper configuration
+- Standard performance settings
+- Minimal environment variables
+
+**To use**:
+```bash
+cp templates/basic-settings.json ~/.claude/settings.json
+```
+
+### 2. `security-focused-settings.json` 
+**Use case**: Security-conscious development
+**Features**:
+- All basic features plus:
+- Security hooks enabled (credential exposure prevention)
+- Restrictive tool permissions
+- Security environment variables
+- Slack/Teams webhook integration for alerts
+
+**Prerequisites**: Install security hooks first
+```bash
+cp hooks/prevent-credential-exposure.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/prevent-credential-exposure.sh
+```
+
+**To use**:
+```bash
+cp templates/security-focused-settings.json ~/.claude/settings.json
+# Edit SECURITY_WEBHOOK_URL to your actual webhook
+```
+
+### 3. `comprehensive-settings.json`
+**Use case**: Comprehensive development with full governance
+**Features**:
+- All security features plus:
+- Comprehensive audit logging
+- Comprehensive permissions
+- MCP server integration
+- Enhanced performance settings
+- Full monitoring and compliance
+
+**Prerequisites**: 
+- Install all security hooks
+- Docker Desktop running (for MCP servers)
+- Configure organizational webhooks
+
+**To use**:
+```bash
+cp templates/comprehensive-settings.json ~/.claude/settings.json
+# Configure webhooks and organizational settings
+```
+
+## Configuration Notes
+
+### Settings Hierarchy
+Settings are applied in this order (later overrides earlier):
+1. User settings: `~/.claude/settings.json`
+2. Project settings: `.claude/settings.json` 
+3. Local settings: `.claude/settings.local.json`
+
+### Security Considerations
+- Always review webhook URLs before using
+- Set appropriate file permissions: `chmod 600 ~/.claude/settings.json`
+- Store sensitive settings in environment variables, not directly in JSON
+- Use `.claude/settings.local.json` for personal settings in team projects
+
+### Customization
+These templates are starting points. Customize based on your needs:
+- Add/remove allowed tools
+- Adjust timeout values
+- Configure additional hooks
+- Set team-specific environment variables
+
+### Validation
+Use the validation script to check your configuration:
+```bash
+./validate-commands.sh --check-settings
+```
+
+## Troubleshooting
+
+### Common Issues
+1. **Commands not working**: Check `allowedTools` array includes required tools
+2. **Hooks not running**: Verify executable permissions and file paths
+3. **Timeouts**: Increase timeout values for slow operations
+4. **Permissions errors**: Check file permissions on settings.json and hooks
+
+### Getting Help
+- Run `./verify-setup.sh` to diagnose issues
+- Check Claude Code logs: `~/.claude/logs/`
+- Review the main README.md troubleshooting section

package/templates/basic-settings.json

@@ -0,0 +1,30 @@
+{
+  "// Basic Claude Code settings.json template": "Copy to ~/.claude/settings.json",
+  "// This provides minimal configuration for custom commands to work": "",
+  
+  "allowedTools": [
+    "Edit",
+    "Bash",
+    "Read",
+    "Write"
+  ],
+  
+  "// Basic hooks configuration": "",
+  "hooks": {
+    "PreToolUse": [],
+    "PostToolUse": []
+  },
+  
+  "// Trust and onboarding settings": "",
+  "hasTrustDialogAccepted": true,
+  "hasCompletedProjectOnboarding": true,
+  
+  "// Performance optimization": "",
+  "parallelTasksCount": 3,
+  
+  "// Optional: Environment variables": "",
+  "env": {
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "true",
+    "BASH_DEFAULT_TIMEOUT_MS": "120000"
+  }
+}

package/templates/comprehensive-settings.json

@@ -0,0 +1,206 @@
+{
+  "// Comprehensive Claude Code settings.json template": "Copy to ~/.claude/settings.json",
+  "// Full comprehensive setup with hooks, governance, and monitoring": "",
+  
+  "allowedTools": [
+    "Edit",
+    "Bash",
+    "Read",
+    "Write",
+    "MultiEdit",
+    "Glob",
+    "Grep",
+    "LS",
+    "Task",
+    "WebFetch",
+    "WebSearch",
+    "NotebookEdit",
+    "BashOutput",
+    "KillBash"
+  ],
+  
+  "// Comprehensive tools configuration": "",
+  "tools": {
+    "bash": {
+      "defaultTimeout": 300000,
+      "maxParallelCommands": 3
+    },
+    "edit": {
+      "autoBackup": true,
+      "validateChanges": true
+    },
+    "web": {
+      "allowedDomains": ["github.com", "docs.anthropic.com", "stackoverflow.com"],
+      "timeout": 30000
+    }
+  },
+  
+  "// Trust and onboarding settings": "",
+  "hasTrustDialogAccepted": true,
+  "hasCompletedProjectOnboarding": true,
+  
+  "// Performance optimization for comprehensive setup": "",
+  "parallelTasksCount": 5,
+  
+  "// Comprehensive security hooks with subagent integration": "",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/prevent-credential-exposure.sh",
+            "blocking": true,
+            "timeout": 10000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command", 
+            "command": "~/.claude/hooks/audit-bash-commands.sh",
+            "blocking": false,
+            "timeout": 5000
+          }
+        ],
+        "// Subagent integration for security events": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-trigger.sh security-auditor pre_write",
+            "blocking": true,
+            "timeout": 10000
+          },
+          {
+            "type": "command", 
+            "command": "~/.claude/hooks/subagent-trigger.sh style-enforcer pre_write",
+            "blocking": false,
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(git commit*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-trigger.sh trunk-guardian pre_commit",
+            "blocking": true,
+            "timeout": 10000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(*test*|*spec*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-trigger.sh test-writer pre_test",
+            "blocking": false,
+            "timeout": 8000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/log-all-operations.sh", 
+            "blocking": false,
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-trigger.sh documentation-curator post_write",
+            "blocking": false,
+            "timeout": 8000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash(*test*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-trigger.sh performance-guardian post_test",
+            "blocking": false,
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "// Custom error handling hooks with subagents": "",
+    "OnError": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-trigger.sh debug-specialist on_error",
+            "blocking": false,
+            "timeout": 15000
+          },
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/subagent-trigger.sh rollback-first-responder on_error",
+            "blocking": false,
+            "timeout": 10000
+          }
+        ]
+      }
+    ]
+  },
+  
+  "// Comprehensive environment variables": "",
+  "env": {
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "true",
+    "BASH_DEFAULT_TIMEOUT_MS": "300000",
+    "MCP_TIMEOUT": "60000",
+    "SECURITY_WEBHOOK_URL": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
+    "CLAUDE_SECURITY_OVERRIDE": "false",
+    "ANTHROPIC_LOG": "info",
+    "CLAUDE_CODE_ENABLE_TELEMETRY": "0"
+  },
+  
+  "// Comprehensive permissions": "",
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Bash(python -m *)",
+      "Bash(git *)",
+      "Bash(docker *)",
+      "Bash(kubectl *)",
+      "Bash(terraform *)",
+      "Edit(*)",
+      "Read(*)",
+      "Write(*)",
+      "MultiEdit(*)"
+    ],
+    "deny": [
+      "Bash(curl *://*/admin*)",
+      "Bash(wget *://*/admin*)",
+      "Bash(ssh *prod*)",
+      "Bash(sudo *)",
+      "Bash(rm -rf *)",
+      "Bash(*production*)"
+    ]
+  },
+  
+  "// MCP servers for comprehensive features": "",
+  "mcpServers": {
+    "puppeteer": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "--init", "-e", "DOCKER_CONTAINER=true", "mcp/puppeteer"]
+    }
+  }
+}