@paulduvall/claude-dev-toolkit 0.0.1-alpha.1 → 0.0.1-alpha.10

package/commands/active/xrefactor.md

@@ -0,0 +1,198 @@
+---
+description: Interactive refactoring assistant based on Martin Fowler's catalog and project-specific rules for code smell detection
+tags: [refactoring, code-smells, quality, patterns, analysis]
+---
+
+Analyze code for refactoring opportunities based on the arguments provided in $ARGUMENTS.
+
+## Usage Examples
+
+**Basic refactoring analysis:**
+```
+/xrefactor
+```
+
+**Detect code smells:**
+```
+/xrefactor --smell
+```
+
+**Find duplicate code:**
+```
+/xrefactor --duplicates
+```
+
+**Help and options:**
+```
+/xrefactor --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+First, examine the project structure for Python files to analyze:
+!find . -name "*.py" -type f | grep -v __pycache__ | head -20
+!ls -la src/ app/ lib/ 2>/dev/null || echo "No standard Python directories found"
+!python --version 2>/dev/null || echo "Python not available"
+
+Based on $ARGUMENTS, perform the appropriate refactoring analysis:
+
+## 1. Code Smell Detection
+
+If analyzing code smells (--smell, --analyze, --detect):
+!find . -name "*.py" | xargs wc -l | sort -nr | head -10
+!python -c "import ast; print('AST analysis available')" 2>/dev/null || echo "Python AST not available"
+!grep -r "def " . --include="*.py" | wc -l
+!grep -r "class " . --include="*.py" | wc -l
+
+Detect common code smells:
+- Long methods and large classes
+- Duplicate code patterns
+- Complex conditional logic
+- Missing error handling
+- Hardcoded configuration values
+
+## 2. Bloater Detection
+
+If detecting bloaters (--bloaters, --long-methods, --large-classes):
+!python -c "
+import ast
+import os
+for root, dirs, files in os.walk('.'):
+    for file in files:
+        if file.endswith('.py'):
+            filepath = os.path.join(root, file)
+            try:
+                with open(filepath, 'r') as f:
+                    tree = ast.parse(f.read())
+                    for node in ast.walk(tree):
+                        if isinstance(node, ast.FunctionDef):
+                            if hasattr(node, 'end_lineno') and node.end_lineno - node.lineno > 20:
+                                print(f'Long method: {node.name} in {filepath} ({node.end_lineno - node.lineno} lines)')
+            except: pass
+" 2>/dev/null || echo "Python AST analysis not available"
+
+Analyze bloater patterns:
+- Methods longer than 20-30 lines
+- Classes with more than 200 lines
+- Parameter lists with more than 3-4 parameters
+- Data classes with too many fields
+- Large conditional expressions
+
+## 3. Change Preventer Detection
+
+If detecting change preventers (--change-preventers, --coupling):
+!grep -r "import " . --include="*.py" | wc -l
+!python -c "
+import ast
+import os
+for root, dirs, files in os.walk('.'):
+    for file in files:
+        if file.endswith('.py'):
+            filepath = os.path.join(root, file)
+            try:
+                with open(filepath, 'r') as f:
+                    content = f.read()
+                    if content.count('if ') > 10:
+                        print(f'High conditional complexity in {filepath}')
+            except: pass
+" 2>/dev/null
+
+Identify change preventers:
+- Divergent change patterns
+- Shotgun surgery indicators
+- Parallel inheritance hierarchies
+- Refused bequest patterns
+- Alternative classes with different interfaces
+
+## 4. Dispensable Code Detection
+
+If detecting dispensables (--dispensables, --dead-code, --duplicates):
+!grep -r "TODO\|FIXME\|XXX" . --include="*.py" | wc -l
+!find . -name "*.py" -exec grep -l "^#.*unused\|^#.*deprecated" {} \; | wc -l
+!python -c "
+import ast
+import os
+from collections import defaultdict
+
+class_methods = defaultdict(list)
+for root, dirs, files in os.walk('.'):
+    for file in files:
+        if file.endswith('.py'):
+            filepath = os.path.join(root, file)
+            try:
+                with open(filepath, 'r') as f:
+                    tree = ast.parse(f.read())
+                    for node in ast.walk(tree):
+                        if isinstance(node, ast.ClassDef):
+                            methods = [n.name for n in node.body if isinstance(n, ast.FunctionDef)]
+                            if len(methods) < 2:
+                                print(f'Potential lazy class: {node.name} in {filepath}')
+            except: pass
+" 2>/dev/null
+
+Find dispensable code:
+- Dead code and unused variables
+- Duplicate code blocks
+- Lazy classes with minimal functionality
+- Data classes without behavior
+- Comments and temporary fields
+
+## 5. Coupler Detection
+
+If detecting couplers (--couplers, --dependencies):
+!find . -name "*.py" | xargs grep -l "\.[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_]" | head -10
+!python -c "
+import ast
+import os
+for root, dirs, files in os.walk('.'):
+    for file in files:
+        if file.endswith('.py'):
+            filepath = os.path.join(root, file)
+            try:
+                with open(filepath, 'r') as f:
+                    content = f.read()
+                    # Look for feature envy patterns (lots of method calls on other objects)
+                    if content.count('.') > len(content.split('\n')) * 0.3:
+                        print(f'Potential feature envy in {filepath}')
+            except: pass
+" 2>/dev/null
+
+Detect coupling issues:
+- Feature envy patterns
+- Inappropriate intimacy between classes
+- Message chains and law of Demeter violations
+- Middle man classes
+- Temporary field usage
+
+Think step by step about refactoring opportunities and provide:
+
+1. **Code Smell Analysis**:
+   - Identified code smells and their severity
+   - Location and context of problematic code
+   - Impact assessment on maintainability
+   - Priority ranking for refactoring
+
+2. **Refactoring Strategy**:
+   - Recommended refactoring techniques
+   - Step-by-step refactoring approach
+   - Risk assessment and mitigation
+   - Testing strategy during refactoring
+
+3. **Implementation Plan**:
+   - Prioritized refactoring tasks
+   - Dependencies between refactoring steps
+   - Timeline and effort estimation
+   - Team coordination requirements
+
+4. **Quality Improvements**:
+   - Expected code quality improvements
+   - Maintainability and readability gains
+   - Performance impact assessment
+   - Long-term technical debt reduction
+
+Generate comprehensive refactoring analysis with smell detection, improvement recommendations, implementation guidance, and quality metrics.
+
+If no specific operation is provided, perform comprehensive code smell detection and recommend refactoring priorities based on Martin Fowler's refactoring catalog and current code analysis.

package/commands/active/xrelease.md

@@ -0,0 +1,142 @@
+---
+description: Comprehensive release management with planning, coordination, deployment automation, and monitoring
+tags: [release, deployment, planning, coordination, automation, monitoring, rollback]
+---
+
+Manage comprehensive release operations based on the arguments provided in $ARGUMENTS.
+
+## Usage Examples
+
+**Basic release analysis:**
+```
+/xrelease
+```
+
+**Plan release:**
+```
+/xrelease --plan
+```
+
+**Deploy release:**
+```
+/xrelease --deploy
+```
+
+**Help and options:**
+```
+/xrelease --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+First, examine the project release environment and status:
+!git tag --sort=-version:refname | head -10 2>/dev/null || echo "No git tags found"
+!git log --oneline -10 2>/dev/null || echo "No git repository found"
+!find . -name "CHANGELOG*" -o -name "RELEASE*" | head -3
+!ls -la package.json setup.py pyproject.toml 2>/dev/null || echo "No version files found"
+
+Based on $ARGUMENTS, perform the appropriate release operation:
+
+## 1. Release Planning and Preparation
+
+If planning release (--plan):
+!git log --since="$(git describe --tags --abbrev=0 2>/dev/null)..HEAD" --oneline | wc -l 2>/dev/null || echo "No previous releases"
+!find . -name "*.md" | xargs grep -l "BREAKING" | head -3 2>/dev/null || echo "No breaking changes documented"
+!git diff --name-only HEAD~10..HEAD | head -10 2>/dev/null
+
+Create comprehensive release plan:
+- Analyze changes since last release
+- Identify breaking changes and dependencies
+- Assess release readiness criteria
+- Generate release timeline and milestones
+- Coordinate stakeholder approvals
+
+## 2. Release Notes and Documentation
+
+If generating release notes (--notes):
+!git log --since="$(git describe --tags --abbrev=0 2>/dev/null)" --pretty=format:"%h %s" 2>/dev/null | head -20
+!find . -name "CHANGELOG*" | head -1
+!git log --grep="feat\|fix\|BREAKING" --oneline --since="$(git describe --tags --abbrev=0 2>/dev/null)" 2>/dev/null | head -10
+
+Generate release documentation:
+- Extract commit messages and categorize changes
+- Identify features, fixes, and breaking changes
+- Create formatted changelog entries
+- Generate migration guides for breaking changes
+- Prepare stakeholder communications
+
+## 3. Deployment and Delivery
+
+If deploying release (--deploy):
+!docker --version 2>/dev/null || echo "Docker not available"
+!kubectl version --client 2>/dev/null || echo "Kubernetes not available"
+!find . -name "Dockerfile" -o -name "docker-compose.yml" | head -3
+
+Execute release deployment:
+- Validate deployment environment
+- Execute deployment strategy (blue-green, canary, rolling)
+- Monitor deployment progress and health
+- Coordinate feature flag rollouts
+- Validate deployment success criteria
+
+## 4. Rollback and Recovery
+
+If executing rollback (--rollback):
+!git tag --sort=-version:refname | head -5
+!docker images --format "table {{.Repository}}:{{.Tag}}" 2>/dev/null | head -5
+!kubectl get deployments 2>/dev/null || echo "No Kubernetes deployments"
+
+Execute rollback procedures:
+- Identify target rollback version
+- Validate rollback compatibility
+- Execute rollback deployment
+- Verify system stability post-rollback
+- Document rollback reasons and lessons
+
+## 5. Quality Gates and Validation
+
+If validating release (--validate, --gate):
+!python -m pytest --tb=short 2>/dev/null || npm test 2>/dev/null || echo "No tests configured"
+!find . -name "*security*" -o -name "*audit*" | head -3
+!git log --grep="security\|vulnerability" --oneline | head -5
+
+Validate release quality:
+- Execute comprehensive test suites
+- Run security scans and audits
+- Check compliance requirements
+- Validate performance benchmarks
+- Ensure documentation completeness
+
+Think step by step about release management requirements and provide:
+
+1. **Release Planning Assessment**:
+   - Current release readiness status
+   - Change analysis and impact assessment
+   - Dependency validation and coordination
+   - Risk evaluation and mitigation strategies
+
+2. **Documentation and Communication**:
+   - Release notes generation from commits
+   - Breaking change identification and documentation
+   - Stakeholder communication planning
+   - Migration guide preparation
+
+3. **Deployment Strategy**:
+   - Deployment method selection and validation
+   - Environment readiness verification
+   - Rollback plan preparation
+   - Monitoring and health check configuration
+
+4. **Quality Assurance**:
+   - Quality gate validation
+   - Security and compliance verification
+   - Performance benchmark validation
+   - Post-release monitoring setup
+
+Generate comprehensive release management with automated planning, coordinated deployment, quality validation, and monitoring integration.
+
+If no specific operation is provided, analyze current release status and recommend next steps based on project state and release readiness criteria.
+

package/commands/active/xsecurity.md

@@ -0,0 +1,92 @@
+---
+description: Run security scans with smart defaults (scans all areas if no arguments)
+tags: [security, vulnerabilities, scanning]
+---
+
+# Security Analysis
+
+Perform comprehensive security scanning with intelligent defaults. No parameters needed for basic usage.
+
+## Usage Examples
+
+**Basic usage (runs all security checks):**
+```
+/xsecurity
+```
+
+**Quick secret scan:**
+```
+/xsecurity secrets
+```
+
+**Dependency vulnerability check:**
+```
+/xsecurity deps
+```
+
+**Help and options:**
+```
+/xsecurity help
+/xsecurity --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+Start by detecting project type and available security tools:
+!ls -la | grep -E "(package.json|requirements.txt|go.mod|Gemfile|pom.xml|composer.json)"
+
+Determine scan scope based on $ARGUMENTS (default to comprehensive scan):
+
+**Mode 1: Comprehensive Scan (no arguments or "all")**
+If $ARGUMENTS is empty or contains "all":
+
+Run complete security analysis:
+1. **Secret Detection**: Scan for exposed credentials and API keys
+2. **Dependency Check**: Check for known vulnerable dependencies  
+3. **Code Analysis**: Look for common security anti-patterns
+4. **Configuration Review**: Check for insecure settings
+
+!git grep -i -E "(api[_-]?key|secret|password|token)" --no-index 2>/dev/null | grep -v -E "(test|spec|mock|example)" | head -10 || echo "✓ No secrets found in code"
+!pip-audit 2>/dev/null || npm audit --audit-level=high 2>/dev/null || echo "Dependency scan: install pip-audit or npm for dependency checks"
+!grep -r -E "(eval\(|exec\(|system\()" . --include="*.py" --include="*.js" 2>/dev/null | head -5 || echo "✓ No dangerous code patterns found"
+
+**Mode 2: Secret Scan Only (argument: "secrets")**
+If $ARGUMENTS contains "secrets":
+!git grep -i -E "(api[_-]?key|secret|password|token|credential)" --no-index 2>/dev/null | grep -v -E "(test|spec|mock|example)" | head -15
+!git log -p --all -S"api_key" --pickaxe-all 2>/dev/null | grep -E "^\+.*api_key" | head -5 || echo "✓ No secrets in git history"
+
+Focus on credential exposure:
+- Scan current files for hardcoded secrets
+- Check git history for accidentally committed credentials
+- Identify potential credential leaks
+- Provide immediate remediation steps
+
+**Mode 3: Dependency Check (argument: "deps")**
+If $ARGUMENTS contains "deps":
+!pip-audit --format=json 2>/dev/null || npm audit --json 2>/dev/null || echo "Checking dependencies..."
+
+Analyze dependency vulnerabilities:
+- Check for known security issues in dependencies
+- Identify outdated packages with vulnerabilities
+- Suggest version updates and fixes
+- Report critical vs non-critical issues
+
+## Security Analysis Results
+
+Think step by step about the security findings and provide:
+
+1. **Security Status**: Overall security posture assessment
+2. **Critical Issues**: Problems requiring immediate attention 
+3. **Recommended Actions**: Priority-ordered fix list
+4. **Prevention Tips**: How to avoid similar issues
+
+Generate a clear security report showing:
+- 🔴 Critical vulnerabilities (fix immediately)
+- 🟡 Important issues (fix soon)
+- ✅ Areas that look secure
+- 🛡️ Recommended security improvements
+
+Keep output focused on actionable findings rather than overwhelming technical details. Provide specific file locations and concrete remediation steps for any issues found.

package/commands/active/xspec.md

@@ -0,0 +1,174 @@
+---
+description: Machine-readable specifications with unique identifiers and authority levels for precise AI code generation
+tags: [specifications, traceability, ai-generation, coverage, requirements, authority]
+---
+
+Manage SpecDriven AI specifications based on the arguments provided in $ARGUMENTS.
+
+## Usage Examples
+
+**Basic specification analysis:**
+```
+/xspec
+```
+
+**Read specifications:**
+```
+/xspec --read
+```
+
+**Create new specification:**
+```
+/xspec --new "Add contact form"
+```
+
+**Help and options:**
+```
+/xspec --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+First, verify SpecDriven AI project structure:
+!ls -la specs/ 2>/dev/null || echo "No specs directory found"
+!find specs/specifications/ -name "*.md" 2>/dev/null | head -5 || echo "No specifications found"
+!find specs/tests/ -name "*.py" 2>/dev/null | head -5 || echo "No tests found"
+
+Based on $ARGUMENTS, perform the appropriate specification operation:
+
+## 1. Specification Reading and Discovery
+
+If reading specifications (--read, --find):
+!grep -r "#{#" specs/specifications/ | head -10 2>/dev/null || echo "No specification IDs found"
+!find specs/specifications/ -name "*.md" -exec grep -l "authority=" {} \; 2>/dev/null | head -5
+
+Read and analyze specifications:
+- Parse specification IDs and authority levels
+- Extract requirement descriptions and criteria
+- Identify implementation dependencies
+- Display specification content and metadata
+- Cross-reference related specifications
+
+## 2. Traceability Analysis
+
+If tracing specifications (--trace):
+!grep -r "$spec_id" specs/tests/ 2>/dev/null || echo "No tests found for specification"
+!grep -r "$spec_id" . --exclude-dir=specs --exclude-dir=.git 2>/dev/null | head -5
+
+Analyze specification traceability:
+- Find tests implementing the specification
+- Locate code referencing specification ID
+- Map requirement-to-implementation relationships
+- Validate traceability completeness
+- Generate traceability reports
+
+## 3. Specification Validation
+
+If validating specifications (--validate, --machine-readable):
+!grep -r "#{#[a-z]{3}[0-9][a-z] authority=" specs/specifications/ 2>/dev/null || echo "Invalid specification format"
+!find specs/specifications/ -name "*.md" -exec grep -E "authority=(system|platform|developer)" {} \; | wc -l
+
+Validate specification compliance:
+- Check ID format (3 letters + 1 digit + 1 letter)
+- Verify authority levels (system/platform/developer)
+- Validate specification structure
+- Ensure machine-readable format compliance
+- Report format violations
+
+## 4. Specification Creation
+
+If creating new specifications (--new):
+!find specs/specifications/ -name "*.md" -exec grep -o "#{#[a-z]*[0-9][a-z]" {} \; | sort | tail -5
+!mkdir -p specs/specifications specs/tests
+
+Create new specification with proper format:
+- Generate unique specification ID
+- Apply appropriate authority level
+- Create specification template
+- Include acceptance criteria
+- Add traceability placeholders
+
+## 5. Coverage Analysis
+
+If analyzing coverage (--coverage, --dual-coverage):
+!grep -r "#{#" specs/specifications/ | wc -l
+!grep -r "#{#" specs/tests/ | wc -l
+!python -m pytest --cov=. --cov-report=term-missing specs/tests/ 2>/dev/null || echo "Code coverage not available"
+
+Analyze dual coverage metrics:
+- Specification coverage (tests exist for requirements)
+- Code coverage (tests execute relevant code)
+- Traceability coverage (links maintained)
+- Gap analysis and recommendations
+- Coverage trend reporting
+
+## 6. AI Code Generation
+
+If generating from specifications (--generate-test, --ai-implement):
+@specs/specifications/$spec_file 2>/dev/null || echo "Specification file not found"
+!find specs/tests/ -name "*test*" | grep "$component" | head -3
+
+Generate AI implementation:
+- Extract requirements from specification
+- Generate test cases covering all criteria
+- Create minimal implementation code
+- Ensure specification traceability
+- Validate generated code compliance
+
+## 7. Authority Management
+
+If filtering by authority (--authority):
+!grep -r "authority=$authority_level" specs/specifications/ 2>/dev/null || echo "No specifications with authority level found"
+
+Manage specification authority:
+- system: Critical system requirements (highest priority)
+- platform: Infrastructure/framework requirements
+- developer: Application/feature requirements (lowest priority)
+- Authority-based filtering and prioritization
+- Compliance validation by authority level
+
+## 8. Gap Analysis
+
+If identifying gaps (--gaps):
+!find specs/specifications/ -name "*.md" -exec grep -o "#{#[a-z]{3}[0-9][a-z]" {} \; | sort | uniq > /tmp/spec_ids
+!find specs/tests/ -name "*.py" -exec grep -o "#{#[a-z]{3}[0-9][a-z]" {} \; | sort | uniq > /tmp/test_ids || touch /tmp/test_ids
+
+Identify specification gaps:
+- Specifications without corresponding tests
+- Tests without specification references
+- Missing implementation coverage
+- Broken traceability links
+- Prioritized gap remediation
+
+Think step by step about specification management and provide:
+
+1. **Specification Analysis**:
+   - Current specification inventory
+   - Authority level distribution
+   - Format compliance status
+   - Coverage metrics and gaps
+
+2. **Traceability Assessment**:
+   - Requirement-to-test mapping completeness
+   - Implementation traceability status
+   - Broken or missing links
+   - Cross-reference validation
+
+3. **Quality Metrics**:
+   - Specification coverage percentage
+   - Code coverage achieved by tests
+   - Authority level compliance
+   - Format standardization status
+
+4. **Improvement Recommendations**:
+   - Missing specifications to create
+   - Tests requiring implementation
+   - Traceability links to establish
+   - Coverage improvement opportunities
+
+Generate comprehensive specification management report with dual coverage analysis, traceability validation, and actionable recommendations for improving SpecDriven AI development practices.
+
+If no specific operation is provided, analyze current specification state and suggest priorities for improvement.