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

package/commands/experiments/xux.md

@@ -0,0 +1,171 @@
+---
+description: User experience optimization, frontend testing, and accessibility compliance with SpecDriven AI methodology integration
+tags: [ux, frontend, accessibility, performance, testing, user-journey]
+---
+
+# /xux - User Experience & Frontend
+
+## Purpose
+Optimize user experience, conduct frontend testing, and ensure accessibility compliance with SpecDriven AI methodology integration.
+
+## Usage
+
+### User Journey Testing
+```bash
+/xux --test <journey>             # Test complete user journeys and flows
+/xux --flow <scenario>            # Analyze user flow optimization
+/xux --conversion <funnel>        # Conversion funnel analysis and optimization
+/xux --personas <validation>      # Validate design against user personas
+```
+
+### Accessibility Compliance
+```bash
+/xux --accessibility <audit>      # Comprehensive accessibility audit
+/xux --wcag <level>               # WCAG compliance checking (A, AA, AAA)
+/xux --screen-reader <test>       # Screen reader compatibility testing
+/xux --contrast <validation>      # Color contrast validation
+```
+
+### Frontend Performance
+```bash
+/xux --performance <metrics>      # Frontend performance analysis
+/xux --lighthouse <audit>         # Google Lighthouse audit automation
+/xux --core-vitals <monitoring>   # Core Web Vitals monitoring
+/xux --bundle <analysis>          # JavaScript bundle analysis
+```
+
+### Visual Testing
+```bash
+/xux --regression <baseline>      # Visual regression testing
+/xux --cross-browser <matrix>     # Cross-browser compatibility testing
+/xux --responsive <breakpoints>   # Responsive design validation
+/xux --component <library>        # Component library testing
+```
+
+### User Behavior Analytics
+```bash
+/xux --analytics <tracking>       # User behavior tracking setup
+/xux --heatmaps <analysis>        # User interaction heatmap analysis
+/xux --session <recording>        # User session recording analysis
+/xux --feedback <collection>      # User feedback collection and analysis
+```
+
+### UX Optimization
+```bash
+/xux --optimization <recommendations> # UX optimization suggestions
+/xux --ab-test <experiment>           # A/B testing setup and analysis
+/xux --usability <testing>            # Usability testing procedures
+/xux --design-system <validation>     # Design system compliance checking
+```
+
+## Examples
+
+### Comprehensive Accessibility Audit
+```bash
+/xux --accessibility "full-site-audit"
+# Creates: reports/accessibility-audit-2024-01.md with WCAG compliance analysis
+```
+
+### Performance Optimization
+```bash
+/xux --performance "core-vitals-analysis"
+# Creates: reports/performance-analysis.md with optimization recommendations
+```
+
+### User Journey Validation
+```bash
+/xux --test "checkout-flow"
+# Creates: tests/user-journeys/checkout-flow/ with automated test scenarios
+```
+
+### Visual Regression Testing
+```bash
+/xux --regression "component-library-v2"
+# Creates: visual-tests/regression/ with baseline comparisons
+```
+
+## SpecDriven AI Integration
+
+### UX Specifications
+- Links UX to specifications: `{#ux1a authority=developer}`
+- Traces user requirements to implementations
+- Validates designs against user stories
+
+### Dual Coverage
+- **Feature Coverage**: All user features have UX validation
+- **Accessibility Coverage**: All interfaces meet accessibility standards
+
+### Traceability
+- Links UX tests to user story specifications
+- Traces performance issues to user experience
+- Connects analytics to user requirement validation
+
+## UX Testing Framework
+
+### User Journey Categories
+- **Critical Paths**: Core business flow testing
+- **Edge Cases**: Error handling and validation
+- **Accessibility**: Assistive technology compatibility
+- **Performance**: Loading and interaction speed
+
+### Testing Methodologies
+- **Automated Testing**: Playwright, Cypress, Selenium
+- **Visual Testing**: Percy, Chromatic, BackstopJS
+- **Performance Testing**: Lighthouse CI, WebPageTest
+- **Accessibility Testing**: axe-core, WAVE, Pa11y
+
+### Metrics & KPIs
+- **Core Web Vitals**: LCP, FID, CLS
+- **Accessibility Score**: WCAG compliance percentage
+- **User Satisfaction**: NPS, CSAT, task completion rates
+- **Conversion Metrics**: Funnel completion, abandonment rates
+
+## Design System Integration
+
+### Component Validation
+- **Visual Consistency**: Design token compliance
+- **Interaction Patterns**: Consistent behavior across components
+- **Responsive Behavior**: Breakpoint validation
+- **Accessibility Standards**: Component-level accessibility
+
+### Documentation
+- **Usage Guidelines**: Component implementation guides
+- **Accessibility Notes**: Component-specific accessibility requirements
+- **Browser Support**: Compatibility matrices
+- **Performance Impact**: Component performance characteristics
+
+## Browser & Device Support
+
+### Desktop Browsers
+- **Chrome**: Latest 2 versions + 1 previous major
+- **Firefox**: Latest 2 versions + ESR
+- **Safari**: Latest 2 versions
+- **Edge**: Latest 2 versions
+
+### Mobile Devices
+- **iOS Safari**: Latest 2 versions
+- **Chrome Mobile**: Latest 2 versions
+- **Samsung Internet**: Latest version
+- **Device Testing**: Physical device validation
+
+### Assistive Technologies
+- **Screen Readers**: NVDA, JAWS, VoiceOver
+- **Voice Control**: Dragon NaturallySpeaking
+- **Switch Navigation**: Hardware switch support
+- **High Contrast**: Windows High Contrast mode
+
+## Integration Points
+
+- **Design tools**: Figma, Sketch, Adobe XD integration
+- **Analytics platforms**: Google Analytics, Mixpanel, Amplitude
+- **Testing frameworks**: Jest, Playwright, Cypress
+- **CI/CD pipelines**: Automated testing and reporting
+- **Monitoring**: Real User Monitoring (RUM) integration
+
+## Output Formats
+
+- **Test reports**: Automated testing results and recommendations
+- **Accessibility audits**: WCAG compliance reports with remediation steps
+- **Performance reports**: Core Web Vitals analysis and optimization guides
+- **User journey maps**: Visual flow documentation with test coverage
+- **Analytics dashboards**: User behavior insights and conversion metrics

package/commands/experiments/xvalidate.md

@@ -0,0 +1,104 @@
+---
+description: Comprehensive validation ensuring project meets quality, security, and compliance standards
+tags: [validation, quality, compliance]
+---
+
+Validate the project against quality, security, and compliance standards.
+
+Parse validation options from $ARGUMENTS (--pre-commit, --pre-deploy, --quality, --security, etc.). Default to comprehensive validation if no arguments.
+
+## 1. Project Structure Check
+
+First, verify essential files exist:
+!ls -la | grep -E "(README|LICENSE|.gitignore|requirements.txt|package.json)"
+
+Check project structure:
+!find . -type f -name "*.py" -o -name "*.js" -o -name "*.ts" | wc -l
+!find . -type f -name "*test*" -o -name "*spec*" | wc -l
+
+## 2. Code Quality Validation
+
+Run linting and formatting checks:
+!python -m black --check . 2>/dev/null || echo "Black not configured"
+!python -m ruff check . 2>/dev/null || echo "Ruff not configured"
+!npm run lint 2>/dev/null || echo "No lint script configured"
+
+Check type annotations (Python):
+!python -m mypy . --ignore-missing-imports 2>/dev/null || echo "Mypy not configured"
+
+## 3. Test Coverage Validation
+
+Run tests with coverage:
+!python -m pytest --cov=. --cov-report=term-missing 2>/dev/null || npm test -- --coverage 2>/dev/null || echo "No test coverage available"
+
+## 4. Security Validation
+
+Quick security check:
+!git grep -i "password.*=" --no-index | grep -v -E "(test|spec|example)" | head -5
+!npm audit --audit-level=high 2>/dev/null || echo "No npm audit available"
+
+## 5. Documentation Validation
+
+Check documentation completeness:
+!find . -name "*.py" -exec grep -L '"""' {} \; 2>/dev/null | head -10
+!test -f README.md && echo "README.md exists" || echo "Missing README.md"
+
+## 6. Configuration Validation
+
+Check for required configuration:
+!test -f .env.example && echo ".env.example exists" || echo "Missing .env.example"
+!grep -E "TODO|FIXME|XXX" . -r --include="*.py" --include="*.js" | wc -l
+
+Think step by step about validation results and provide:
+
+1. Overall validation status (PASS/FAIL)
+2. Specific issues that need fixing
+3. Priority order for fixes
+4. Commands to fix each issue
+
+Generate validation report in this format:
+
+```
+📋 VALIDATION REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall Status: [PASS/FAIL]
+Validation Type: $ARGUMENTS
+
+✅ PASSED CHECKS (X/Y)
+────────────────────
+✓ [Check name]: [Details]
+✓ [Check name]: [Details]
+
+❌ FAILED CHECKS (X/Y)
+────────────────────
+✗ [Check name]: [Details]
+  Fix: [Specific command or action]
+  
+✗ [Check name]: [Details]
+  Fix: [Specific command or action]
+
+🔧 QUICK FIXES
+─────────────
+1. [Command to run]
+2. [Command to run]
+3. [Command to run]
+
+📊 METRICS
+─────────
+- Code Coverage: X%
+- Type Coverage: X%
+- Documentation: X%
+- Security Issues: X
+```
+
+If --fix is provided, attempt to auto-fix issues:
+!python -m black . 2>/dev/null
+!python -m ruff check --fix . 2>/dev/null
+
+For pre-deployment validation (--pre-deploy), run additional checks:
+- Performance benchmarks
+- Integration tests
+- Environment variable verification
+- Database migration status
+
+Return exit code 0 if validation passes, 1 if it fails (for CI/CD integration).

package/commands/experiments/xworkflow.md

@@ -0,0 +1,113 @@
+---
+description: Automate and optimize development workflows with configurable automation patterns
+tags: [workflow, automation, orchestration, patterns, optimization, monitoring]
+---
+
+Manage and execute development workflows based on the arguments provided in $ARGUMENTS.
+
+First, examine the current workflow configuration and environment:
+!ls -la .workflows/ 2>/dev/null || echo "No workflows directory found"
+!find . -name "*.yml" -o -name "*.yaml" | grep -E "(workflow|pipeline)" | head -5
+!git log --oneline -10 2>/dev/null || echo "No git repository found"
+
+Based on $ARGUMENTS, perform the appropriate workflow operation:
+
+## 1. Workflow Creation and Management
+
+If creating workflows (--create):
+!mkdir -p .workflows/
+!find .workflows/ -name "*.yml" | wc -l
+!ls -la .github/workflows/ 2>/dev/null || echo "No GitHub Actions workflows found"
+
+Create and configure automated workflows:
+- Analyze project structure and requirements
+- Generate workflow templates based on project type
+- Configure workflow parameters and triggers
+- Integrate with existing CI/CD systems
+- Validate workflow syntax and dependencies
+
+## 2. Workflow Execution
+
+If running workflows (--run):
+!find .workflows/ -name "$workflow_name.yml" 2>/dev/null || echo "Workflow not found"
+!git status --porcelain
+!python -c "import yaml; print('YAML parsing available')" 2>/dev/null || echo "YAML parser needed"
+
+Execute workflow with parameter substitution:
+- Parse workflow definition and parameters
+- Substitute variables and environment values
+- Execute workflow steps in sequence
+- Handle step failures and error conditions
+- Generate execution logs and reports
+
+## 3. Workflow Discovery and Listing
+
+If listing workflows (--list):
+!find .workflows/ -name "*.yml" -o -name "*.yaml" | head -10
+!grep -r "description:" .workflows/ 2>/dev/null | head -5
+!find .github/workflows/ -name "*.yml" 2>/dev/null | head -5
+
+Discover and catalog available workflows:
+- Scan workflow directories for definitions
+- Parse workflow metadata and descriptions
+- Categorize workflows by type and purpose
+- Display workflow parameters and requirements
+- Show workflow status and execution history
+
+## 4. Workflow Optimization
+
+If optimizing workflows (--optimize):
+!find .workflows/ -name "*.yml" -exec grep -l "parallel" {} \; 2>/dev/null
+!git log --since="30 days ago" --grep="workflow" --oneline | wc -l
+!ps aux | grep -E "(workflow|pipeline)" | head -5
+
+Analyze and optimize workflow performance:
+- Identify workflow bottlenecks and dependencies
+- Recommend parallelization opportunities
+- Optimize resource utilization and timing
+- Reduce workflow execution time
+- Improve workflow reliability and success rates
+
+## 5. Workflow Monitoring
+
+If monitoring workflows (--monitor):
+!find .workflows/ -name "*.log" -o -name "*execution*" | head -5
+!tail -20 .workflows/execution.log 2>/dev/null || echo "No execution log found"
+!ps aux | grep workflow | grep -v grep
+
+Monitor workflow execution and performance:
+- Track workflow execution status
+- Monitor resource usage and performance metrics
+- Alert on workflow failures or anomalies
+- Generate workflow performance reports
+- Maintain execution history and analytics
+
+Think step by step about workflow automation requirements and provide:
+
+1. **Workflow Analysis**:
+   - Current workflow inventory and status
+   - Workflow dependencies and relationships
+   - Performance metrics and bottlenecks
+   - Integration points and requirements
+
+2. **Automation Strategy**:
+   - Workflow template recommendations
+   - Parameter configuration and validation
+   - Step sequencing and parallelization
+   - Error handling and recovery procedures
+
+3. **Optimization Opportunities**:
+   - Performance improvement recommendations
+   - Resource utilization optimization
+   - Workflow consolidation possibilities
+   - Parallel execution opportunities
+
+4. **Monitoring and Maintenance**:
+   - Execution tracking and logging
+   - Performance monitoring setup
+   - Alert configuration recommendations
+   - Workflow health assessment
+
+Generate comprehensive workflow automation with template creation, execution orchestration, performance optimization, and monitoring integration.
+
+If no specific operation is provided, analyze existing workflows and recommend automation improvements based on project structure and development patterns.

package/hooks/.smellrc.example.json

@@ -0,0 +1,19 @@
+{
+  "thresholds": {
+    "max_complexity": 10,
+    "max_function_lines": 20,
+    "max_nesting_depth": 3,
+    "max_parameters": 4,
+    "max_file_lines": 300,
+    "duplicate_min_lines": 4
+  },
+  "security": {
+    "enabled": true,
+    "trojan_enabled": true
+  },
+  "suppress_files": [
+    "tests/**",
+    "*_test.py",
+    "*.generated.*"
+  ]
+}

package/hooks/README.md

@@ -0,0 +1,263 @@
+# Claude Code Hooks Collection
+
+This directory contains security and workflow hooks for Claude Code that provide enterprise-grade governance and automation.
+
+## Available Hooks
+
+### `file-logger.sh`
+**Purpose**: Simple demonstration of hook functionality without security implications.
+
+**Features**:
+- ✅ Logs file operations (Edit, Write, MultiEdit tools)
+- ✅ Shows file information (size, lines, type)
+- ✅ Non-blocking - always allows operations to proceed
+- ✅ Perfect for learning how hooks work
+
+**Configuration**:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/file-logger.sh",
+            "blocking": false,
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Log Location**: `~/.claude/logs/file-logger.log`
+
+### `prevent-credential-exposure.sh`
+**Purpose**: Prevents accidental credential exposure in AI-generated or AI-modified code.
+
+**Features**:
+- ✅ Detects 15+ credential patterns (API keys, tokens, passwords, private keys)
+- ✅ Blocks dangerous operations with detailed warnings
+- ✅ Comprehensive logging and audit trails
+- ✅ Security team notifications via webhooks
+- ✅ Emergency override capability for authorized users
+- ✅ Environment variable and URL credential detection
+
+**Configuration**:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/prevent-credential-exposure.sh",
+            "blocking": true,
+            "timeout": 10000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Environment Variables**:
+- `SECURITY_WEBHOOK_URL`: Optional Slack/Teams webhook for security alerts
+- `CLAUDE_SECURITY_OVERRIDE`: Emergency override (use with extreme caution)
+
+### Lifecycle & Event Hooks
+
+The following hooks provide logging, validation, and cleanup at various Claude Code lifecycle events. All are non-blocking and log to `~/.claude/logs/`.
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `backup-before-edit.sh` | PreToolUse (Edit/Write) | Preserves file state before modifications |
+| `audit-bash-commands.sh` | PreToolUse (Bash) | Logs shell commands for security audit trail |
+| `log-all-operations.sh` | PostToolUse (*) | Audit trail for all tool usage |
+| `validate-changes.sh` | PostToolUse (Edit/Write) | Post-edit validation of changes |
+| `handle-notifications.sh` | Notification | Security event notification logging |
+| `prompt-analysis.sh` | UserPromptSubmit | Validates prompts for security concerns |
+| `prompt-security-scan.sh` | UserPromptSubmit | Scans prompts for credential exposure risks |
+| `cleanup-on-stop.sh` | Stop | Cleans temporary state on execution stop |
+| `subagent-cleanup.sh` | SubagentStop | Cleans subagent resources on completion |
+| `session-cleanup.sh` | SessionEnd | End-of-session security cleanup |
+| `pre-compact-backup.sh` | PreCompact | Checkpoint before context compaction |
+| `session-init.sh` | SessionStart | Validates environment at session start |
+| `security-session-init.sh` | SessionStart | Enhanced security posture validation |
+
+### Quality & Workflow Hooks
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `pre-commit-quality.sh` | PreToolUse (Bash) | Code quality checks before commits |
+| `pre-commit-test-runner.sh` | PreToolUse (Bash) | Auto-detects test framework, blocks commits on failure |
+| `pre-write-security.sh` | PreToolUse (Write) | Security scan before file writes |
+| `verify-before-edit.sh` | PreToolUse (Edit/Write) | Warns about fabricated references (non-blocking) |
+| `on-error-debug.sh` | Manual invocation | Debug context capture on errors |
+| `subagent-trigger.sh` | PostToolUse (*) | Triggers subagent workflows |
+| `subagent-trigger-simple.sh` | PostToolUse (*) | Simplified subagent trigger |
+
+## Hook Installation
+
+### Option 1: Global Installation (Recommended)
+```bash
+# Copy to Claude Code hooks directory
+cp hooks/file-logger.sh ~/.claude/hooks/
+
+# Make executable
+chmod +x ~/.claude/hooks/file-logger.sh
+
+# Configure in ~/.claude/settings.json
+```
+
+### Option 2: Project-Specific Installation
+```bash
+# Use relative path in project settings
+# Add to .claude/settings.json in your project
+```
+
+## Configuration Examples
+
+### Basic Security Configuration
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/file-logger.sh",
+            "blocking": false
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Enhanced Configuration with Notifications
+```bash
+# Set webhook for security alerts
+export SECURITY_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
+
+# Add to your shell profile for persistence
+echo 'export SECURITY_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"' >> ~/.zshrc
+```
+
+## Testing the Hook
+
+### Test 1: Basic Credential Detection
+```bash
+# Create a test file with a fake API key
+echo 'API_KEY="sk-ant-1234567890abcdef"' > test-credentials.txt
+
+# Try to edit with Claude Code - should be blocked
+claude edit test-credentials.txt
+```
+
+### Test 2: Environment Variable Exposure
+```bash
+# Create a test file with environment exposure
+echo 'const apiKey = process.env.SECRET_API_KEY;' > test-env.js
+
+# Try to edit with Claude Code - should be blocked
+claude edit test-env.js
+```
+
+### Test 3: Emergency Override
+```bash
+# Enable override (use sparingly!)
+export CLAUDE_SECURITY_OVERRIDE=true
+
+# Now the operation will proceed with warnings
+claude edit test-credentials.txt
+
+# Disable override immediately after
+unset CLAUDE_SECURITY_OVERRIDE
+```
+
+## Security Patterns Detected
+
+The hook detects these credential patterns:
+- **Anthropic API Keys**: `sk-ant-...`
+- **OpenAI API Keys**: `sk-...`
+- **GitHub Tokens**: `ghp_...`, `gho_...`
+- **AWS Access Keys**: `AKIA...`
+- **Database URLs**: `postgres://user:pass@host`
+- **JWT Tokens**: `eyJ...`
+- **Private Keys**: `-----BEGIN PRIVATE KEY-----`
+- **Generic API Keys**: Pattern-based detection
+- **Environment Variable Exposure**: `process.env.SECRET_*`
+
+## Logs and Monitoring
+
+### Log Locations
+- **General Hook Logs**: `~/.claude/logs/security-hooks.log`
+- **Security Violations**: `~/.claude/logs/credential-violations.log`
+
+### Monitoring Commands
+```bash
+# View recent security events
+tail -f ~/.claude/logs/security-hooks.log
+
+# Check for violations
+cat ~/.claude/logs/credential-violations.log
+
+# Count violations by type
+grep "VIOLATION:" ~/.claude/logs/credential-violations.log | cut -d: -f3 | sort | uniq -c
+```
+
+## Best Practices
+
+1. **Always Review**: Examine the detected pattern before overriding
+2. **Use Environment Variables**: Store credentials in environment variables
+3. **Secrets Management**: Use proper secrets management systems (1Password, HashiCorp Vault, etc.)
+4. **Emergency Override**: Only use `CLAUDE_SECURITY_OVERRIDE` in genuine emergencies
+5. **Regular Audits**: Review violation logs regularly for patterns
+6. **Team Training**: Educate team on secure coding practices
+
+## Troubleshooting
+
+### Hook Not Running
+- Verify executable permissions: `ls -la ~/.claude/hooks/`
+- Check Claude Code settings: `cat ~/.claude/settings.json`
+- Review hook logs: `tail ~/.claude/logs/security-hooks.log`
+
+### False Positives
+- Review the detected pattern in logs
+- Consider if the pattern is actually a security risk
+- Use environment variables instead of hardcoded values
+- Add file to `.gitignore` if it's test data
+
+### Performance Issues
+- The hook runs quickly but can be optimized for large files
+- Consider adding file size limits if needed
+- Use async execution for non-blocking notifications
+
+## Contributing
+
+To add new credential patterns or improve detection:
+
+1. Add new patterns to the `CREDENTIAL_PATTERNS` array
+2. Test with realistic examples
+3. Update documentation
+4. Submit changes for review
+
+## Security Notice
+
+This hook is designed to prevent accidental credential exposure. It should be part of a comprehensive security strategy that includes:
+- Proper secrets management
+- Regular security training
+- Code review processes
+- Automated security scanning in CI/CD
+- Incident response procedures