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

package/commands/active/xdebug.md

@@ -0,0 +1,130 @@
+---
+description: Interactive debugging support with error analysis and fix suggestions - integrates with Debug Specialist sub-agent for complex issues
+tags: [debugging, troubleshooting, errors, sub-agent]
+---
+
+Debug and analyze errors with root cause identification and fix suggestions. For complex debugging sessions, automatically delegates to the Debug Specialist sub-agent for persistent context and deep analysis.
+
+## Usage Examples
+
+**Analyze recent errors:**
+```
+/xdebug
+```
+
+**Debug specific error:**
+```
+/xdebug "ImportError: No module named 'requests'"
+```
+
+**Debug failing test:**
+```
+/xdebug test_user_login
+```
+
+**Help and debugging options:**
+```
+/xdebug --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+Parse the error or issue from $ARGUMENTS. If no specific error is provided, check for recent errors:
+!tail -50 *.log 2>/dev/null | grep -i "error\|exception\|failed" || echo "No recent errors in log files"
+
+**Decision Point: Quick Analysis vs Deep Debugging**
+
+Determine if this requires simple analysis or complex debugging session:
+
+**Simple/Quick Issues** (handle directly):
+- Single error messages with clear solutions
+- Common environment issues (missing dependencies, path problems)
+- Basic syntax errors
+- Simple configuration problems
+
+**Complex Issues** (delegate to Debug Specialist sub-agent):
+- Multi-step debugging requiring persistent context
+- Performance problems needing profiling
+- Intermittent issues requiring investigation over time
+- Complex stack traces with multiple potential causes
+- Issues requiring environment analysis and hypothesis testing
+
+**For Complex Issues:** Use Task tool to delegate to debug-specialist:
+```
+Use the Task tool with:
+description: "Complex debugging analysis"
+prompt: "Acting as Debug Specialist sub-agent, analyze this error: [ERROR_DETAILS]. Provide comprehensive root cause analysis, systematic troubleshooting steps, and solution validation."
+subagent_type: "debug-specialist"
+```
+
+**For Simple Issues, continue with direct analysis:**
+
+Based on the error context, perform the following debugging steps:
+
+1. **Error Classification**:
+   - Identify the error type (syntax, runtime, logic, configuration)
+   - Determine the severity and impact
+   - Check if this is a known issue pattern
+
+2. **Root Cause Analysis**:
+   - Trace the error back to its source
+   - Examine the stack trace if available
+   - Check related code sections using @<relevant_file> references
+   - Look for similar patterns in the codebase
+
+3. **Environmental Factors**:
+   - Check environment variables and configuration
+   - Verify dependencies are installed correctly
+   - Look for version mismatches
+
+4. **Test Isolation**:
+   - Identify which tests are failing
+   - Check if the error is reproducible
+   - Determine if it's environment-specific
+
+For Python errors, gather additional context:
+!python --version
+!pip list | grep -E "(package1|package2)" 2>/dev/null
+
+For JavaScript/Node errors:
+!node --version
+!npm list --depth=0 2>/dev/null
+
+Think step by step about the debugging process:
+
+1. What is the exact error message and where does it occur?
+2. What are the possible causes based on the error type?
+3. What code changes or environmental factors might have triggered this?
+4. What are the most likely solutions?
+
+Provide debugging assistance in this format:
+
+```
+🔍 DEBUG ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Error: [Error type and message]
+Location: [File:line or component]
+
+📍 ROOT CAUSE
+[Detailed explanation of why this error occurs]
+
+🔧 SUGGESTED FIX
+[Step-by-step fix with code examples]
+
+📋 VERIFICATION
+[Commands or steps to verify the fix works]
+
+💡 PREVENTION
+[How to prevent this error in the future]
+```
+
+If the error involves a specific file mentioned in the error message, examine it:
+@<error_file_path>
+
+For test failures, run relevant tests:
+!python -m pytest <test_file> -v 2>/dev/null || npm test <test_file> 2>/dev/null
+
+Provide specific, actionable debugging steps rather than generic advice.

package/commands/active/xdocs.md

@@ -0,0 +1,178 @@
+---
+description: Generate and maintain comprehensive documentation from code
+tags: [documentation, generation, maintenance]
+---
+
+Generate and maintain documentation from code, keeping it in sync with implementation.
+
+## Usage Examples
+
+**Basic documentation generation:**
+```
+/xdocs
+```
+
+**Generate API documentation:**
+```
+/xdocs --api
+```
+
+**Check documentation coverage:**
+```
+/xdocs --check
+```
+
+**Generate README:**
+```
+/xdocs --readme
+```
+
+**Help and options:**
+```
+/xdocs --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+Parse documentation options from $ARGUMENTS (--generate, --api, --readme, --check, or specific module/file).
+
+## 1. Analyze Current Documentation
+
+Check existing documentation:
+!find . -name "*.md" | grep -v node_modules | head -20
+!test -f README.md && echo "README exists" || echo "No README.md found"
+!find . -name "*.py" -exec grep -l '"""' {} \; | wc -l
+
+## 2. Generate Documentation
+
+Based on the arguments and project type, generate appropriate documentation.
+
+For Python projects, extract docstrings:
+!python -c "import ast; import os; [print(f'{f}: {len([n for n in ast.walk(ast.parse(open(f).read())) if isinstance(n, ast.FunctionDef) and ast.get_docstring(n)])} documented functions') for f in os.listdir('.') if f.endswith('.py')]" 2>/dev/null
+
+For JavaScript/TypeScript projects:
+!grep -E "^(export |const |function |class )" *.js *.ts 2>/dev/null | head -20
+
+## 3. API Documentation
+
+If --api flag is present, analyze API endpoints:
+!grep -r -E "@(app|router)\.(get|post|put|delete|patch)" . --include="*.py" 2>/dev/null | head -20
+!grep -r -E "(app|router)\.(get|post|put|delete|patch)" . --include="*.js" 2>/dev/null | head -20
+
+## 4. Check Documentation Coverage
+
+Count undocumented functions:
+!find . -name "*.py" -exec grep -E "^def |^class " {} \; | wc -l
+!find . -name "*.py" -exec grep -A1 -E "^def |^class " {} \; | grep '"""' | wc -l
+
+Think step by step about documentation needs and:
+
+1. Identify what documentation is missing
+2. Generate appropriate documentation based on code analysis
+3. Create templates for missing documentation
+4. Ensure examples are included where helpful
+
+Generate documentation in this format:
+
+For README.md:
+```markdown
+# Project Name
+
+Brief description of what this project does.
+
+## Installation
+
+```bash
+# Installation commands based on package.json or requirements.txt
+```
+
+## Usage
+
+```python
+# Example usage based on main entry points
+```
+
+## API Reference
+
+### [Function/Class Name]
+[Description from docstring or inferred from code]
+
+**Parameters:**
+- `param_name` (type): Description
+
+**Returns:**
+- type: Description
+
+**Example:**
+```python
+# Example usage
+```
+
+## Contributing
+
+See CONTRIBUTING.md for details.
+
+## License
+
+[License information]
+```
+
+For API documentation:
+```markdown
+# API Documentation
+
+## Endpoints
+
+### GET /endpoint
+Description of what this endpoint does.
+
+**Parameters:**
+- `param` (query/path/body): Description
+
+**Response:**
+```json
+{
+  "field": "example"
+}
+```
+
+**Example:**
+```bash
+curl -X GET http://localhost:8000/endpoint
+```
+```
+
+If --check flag is present, generate a documentation coverage report:
+```
+📚 DOCUMENTATION COVERAGE REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Overall Coverage: X%
+
+✅ DOCUMENTED (X/Y)
+─────────────────
+✓ module.py: X/Y functions
+✓ api.py: X/Y endpoints
+
+❌ MISSING DOCUMENTATION (X/Y)
+─────────────────────────────
+✗ utils.py: functionName (line X)
+✗ models.py: ClassName (line X)
+
+🔧 QUICK FIXES
+────────────
+1. Add docstring to functionName in utils.py
+2. Document ClassName in models.py
+3. Create API documentation for /endpoint
+
+📝 TEMPLATES TO ADD
+────────────────
+- README.md sections: Usage, Examples
+- API.md: Missing endpoint documentation
+- CONTRIBUTING.md: Development setup
+```
+
+If --generate flag with specific file, create documentation for that file.
+If --update flag, update existing documentation to match code changes.

package/commands/active/xexplore.md

@@ -0,0 +1,94 @@
+---
+description: Explore a codebase topic before making changes (read-only)
+tags: [exploration, codebase, discovery, read-only]
+---
+
+# Codebase Exploration
+
+Comprehensively search the codebase for a topic before making any changes. Read-only — no files are modified.
+
+## Usage Examples
+
+**Explore a topic:**
+```
+/xexplore authentication
+```
+
+**Explore a specific area:**
+```
+/xexplore database migrations
+```
+
+**Help and options:**
+```
+/xexplore help
+/xexplore --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+If $ARGUMENTS is empty:
+Tell the user: "Please provide a topic to explore. Example: /xexplore authentication"
+Stop and wait for input.
+
+### Step 1: Search by File Name
+
+Find files whose names match the topic:
+
+```bash
+find . -iname "*$ARGUMENTS*" ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/vendor/*" 2>/dev/null | head -30
+```
+
+### Step 2: Search by Content
+
+Grep the codebase for the topic keyword:
+- Search all source files for content matching $ARGUMENTS
+- Capture file paths and line numbers for key matches
+- Limit to first 20 matches per file to avoid flooding
+
+### Step 3: Search Configuration
+
+Check config files specifically:
+- `*.json`, `*.yaml`, `*.yml`, `*.toml`, `*.env*`, `*.ini`
+- Look for the topic in config values, keys, and comments
+
+### Step 4: Search Tests
+
+Find test files related to the topic:
+- Patterns: `*test*`, `*spec*`, `__tests__/`
+- Check both file names and file content
+
+### Step 5: Search Documentation
+
+Check docs for the topic:
+- `*.md` files, `docs/` directory, `README*`
+- Wiki or guide references
+
+### Step 6: Report
+
+Present findings in a structured inventory:
+
+```
+## Exploration Report: [topic]
+
+### Source Files (N found)
+- path/to/file.ts:42 — [matching line preview]
+
+### Tests (N found)
+- tests/path/to/test.ts:15 — [matching line preview]
+
+### Configuration (N found)
+- config/settings.json:8 — [matching line preview]
+
+### Documentation (N found)
+- docs/guide.md:23 — [matching line preview]
+```
+
+If nothing is found:
+- Tell the user: "No matches found for '[topic]'."
+- Suggest broadening the search or trying alternate terms.
+
+**Do NOT make any changes to any files. This command is read-only.**

package/commands/active/xgit.md

@@ -0,0 +1,149 @@
+---
+description: Automate git workflow - stage, commit with smart messages, and push to specified branch
+tags: [git, commit, automation, workflow, branching]
+---
+
+Automate the complete git workflow with intelligent commit message generation and branch management.
+
+## Usage Examples
+
+**Basic automated workflow:**
+```
+/xgit
+```
+
+**Push to specific branch:**
+```
+/xgit --branch feature-123
+```
+
+**Create new branch and push:**
+```
+/xgit --create-branch fix-bug
+```
+
+**Custom commit message:**
+```
+/xgit --message "Custom commit"
+```
+
+**Help and options:**
+```
+/xgit --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+First, verify this is a git repository and sync with remote:
+!git rev-parse --git-dir 2>/dev/null || echo "Not a git repository"
+!git pull 2>/dev/null || echo "Pull failed or no upstream configured"
+!git status --porcelain
+
+Parse arguments to determine branch operations and custom messages:
+Based on $ARGUMENTS, extract:
+- **Target branch**: `--branch <branch-name>` or current branch if not specified
+- **Branch creation**: `--create-branch <branch-name>` to create and switch to new branch
+- **Custom message**: `--message "<message>"` to override automatic commit message generation
+- **Force push**: `--force` to enable force push (use with caution)
+
+Check if there are any changes to commit:
+!git diff --quiet && git diff --cached --quiet && [ -z "$(git ls-files --others --exclude-standard)" ] && echo "No changes to commit" || echo "Changes detected"
+
+If no changes are found, exit. Otherwise, stage all changes:
+!git add .
+
+## Branch Management
+
+Handle branch operations based on arguments:
+
+**If creating new branch (--create-branch):**
+!git checkout -b "${TARGET_BRANCH}" 2>/dev/null || echo "Branch creation failed"
+!echo "Created and switched to new branch: ${TARGET_BRANCH}"
+
+**If switching to existing branch (--branch):**
+!git pull 2>/dev/null || echo "Pull failed for current branch"
+!git checkout "${TARGET_BRANCH}" 2>/dev/null || echo "Branch switch failed - branch may not exist"
+!git pull 2>/dev/null || echo "Pull failed for target branch"
+!echo "Switched to branch: ${TARGET_BRANCH}"
+
+**Current branch status:**
+!git branch --show-current
+
+## Commit Message Generation
+
+Analyze the staged changes to generate an intelligent commit message:
+!git diff --cached --stat
+!git diff --cached --name-only | head -10
+
+**If custom message provided (--message):**
+Use the provided custom commit message directly.
+
+**Otherwise, generate intelligent commit message:**
+Think step by step about the changes to determine the appropriate commit type:
+- Check for documentation files (.md, README, docs/) → docs
+- Check for test files (test/, spec/, .test., .spec.) → test 
+- Check for dependency files (package.json, requirements.txt) → chore
+- Check for new functionality (new files with functions/classes) → feat
+- Check for bug fixes (fix, bug, error in diff) → fix
+- Check for refactoring (refactor, rename, move) → refactor
+- Default for new files → feat
+- Default for modifications → chore
+
+Generate commit message following Conventional Commits format:
+- type: description (under 50 chars)
+- Include file change summary in body
+- Add standard Claude Code footer
+
+Execute the commit with generated or custom message:
+!git commit -m "Generated commit message based on changes" -m "📋 Change summary:
+* List of changed files and modifications" -m "🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+## Remote Push Operations
+
+Check remote configuration and current branch:
+!git remote -v | grep origin || echo "No origin remote configured"
+!git branch --show-current
+
+**Determine target branch for push:**
+- Use `--branch <branch-name>` if specified
+- Use `--create-branch <branch-name>` if creating new branch
+- Default to current branch
+
+**Push to remote with upstream tracking:**
+
+**If force push requested (--force):**
+!git push --force-with-lease origin ${TARGET_BRANCH} 2>/dev/null || echo "Force push failed - check remote configuration and conflicts"
+
+**Standard push operation:**
+!git push --follow-tags --set-upstream origin ${TARGET_BRANCH} 2>/dev/null || git push --follow-tags 2>/dev/null || echo "Push failed - check remote configuration"
+
+**If new branch creation:**
+!echo "New branch '${TARGET_BRANCH}' has been created and pushed to remote"
+
+**Report results:**
+!git log -1 --oneline
+!echo "✅ Successfully staged, committed, and pushed changes to branch: $(git branch --show-current)"
+
+## Error Handling and Guidance
+
+If any step fails, provide clear error messages with troubleshooting guidance:
+
+**Branch Issues:**
+- Branch doesn't exist: Suggest using `--create-branch` instead of `--branch`
+- Branch already exists: Confirm if you want to switch to existing branch
+- No upstream: Automatically set upstream tracking on first push
+
+**Push Issues:**
+- Remote conflicts: Suggest `--force` flag if appropriate, or manual conflict resolution
+- Authentication: Check git credentials and remote configuration
+- Network issues: Retry or check internet connection
+
+**Validation:**
+- Ensure all staged changes are committed
+- Verify remote branch tracking is properly configured
+- Confirm successful push with remote branch status

package/commands/active/xpipeline.md

@@ -0,0 +1,152 @@
+---
+description: Advanced CI/CD pipeline configuration, build automation, deployment orchestration, and optimization
+tags: [pipeline, cicd, automation, deployment, orchestration, optimization, artifacts]
+---
+
+Configure and manage CI/CD pipelines based on the arguments provided in $ARGUMENTS.
+
+## Usage Examples
+
+**Basic pipeline analysis:**
+```
+/xpipeline
+```
+
+**Initialize new pipeline:**
+```
+/xpipeline --init
+```
+
+**Configure deployment stage:**
+```
+/xpipeline --deploy-stage production
+```
+
+**Help and options:**
+```
+/xpipeline --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+First, examine the current pipeline configuration and environment:
+!find . -name "*.yml" -o -name "*.yaml" | grep -E "(pipeline|workflow|ci|cd)" | head -10
+!ls -la .github/workflows/ .gitlab-ci.yml Jenkinsfile azure-pipelines.yml 2>/dev/null || echo "No CI/CD configurations found"
+!git branch --show-current 2>/dev/null || echo "No git repository"
+
+Based on $ARGUMENTS, perform the appropriate pipeline operation:
+
+## 1. Pipeline Initialization and Setup
+
+If initializing pipeline (--init):
+!find . -name "package.json" -o -name "requirements.txt" -o -name "pom.xml" -o -name "go.mod" | head -3
+!which docker 2>/dev/null || echo "Docker not available"
+!git remote -v 2>/dev/null || echo "No git remotes configured"
+
+Initialize CI/CD pipeline configuration:
+- Detect project type and language
+- Generate platform-specific pipeline configuration
+- Configure basic build, test, and deploy stages
+- Set up environment variables and secrets
+- Configure artifact management and caching
+
+## 2. Stage Configuration and Management
+
+If configuring stages (--stage, --build, --test-stage):
+!find . -name "*.yml" -o -name "*.yaml" | xargs grep -l "stage\|job\|step" 2>/dev/null | head -5
+!python -c "import pytest; print('pytest available')" 2>/dev/null || npm test --version 2>/dev/null || echo "No test framework detected"
+
+Configure pipeline stages:
+- Define stage dependencies and execution order
+- Configure parallel execution for independent stages
+- Set up conditional stage execution criteria
+- Implement manual approval gates
+- Configure stage timeout and retry policies
+
+## 3. Build and Compilation Configuration
+
+If configuring build (--build, --compile):
+!find . -name "Dockerfile" -o -name "docker-compose.yml" | head -3
+!find . -name "Makefile" -o -name "build.gradle" -o -name "webpack.config.js" | head -3
+!ls -la package.json setup.py pyproject.toml 2>/dev/null || echo "No build configuration files"
+
+Configure build automation:
+- Set up compilation and build processes
+- Configure build caching strategies
+- Implement build matrix for multiple variants
+- Optimize build performance and parallelization
+- Configure artifact packaging and versioning
+
+## 4. Testing Pipeline Integration
+
+If configuring testing (--test-stage, --coverage):
+!find . -name "*test*" -type d | head -5
+!find . -name "*.test.js" -o -name "test_*.py" | wc -l
+!python -m pytest --collect-only 2>/dev/null | grep "test" | wc -l || echo "0"
+
+Integrate comprehensive testing:
+- Configure unit, integration, and end-to-end tests
+- Set up code coverage requirements and reporting
+- Implement test parallelization and optimization
+- Configure test environment setup and teardown
+- Integrate security and performance testing
+
+## 5. Deployment and Orchestration
+
+If configuring deployment (--deploy-stage, --strategy):
+!find . -name "*.yml" -o -name "*.yaml" | xargs grep -l "deploy\|release" 2>/dev/null | head -3
+!kubectl version --client 2>/dev/null || docker --version 2>/dev/null || echo "No deployment tools detected"
+
+Configure deployment automation:
+- Set up environment-specific deployment configurations
+- Implement deployment strategies (blue-green, canary, rolling)
+- Configure automated rollback and health checks
+- Set up approval workflows and quality gates
+- Integrate monitoring and observability
+
+## 6. Artifact and Registry Management
+
+If managing artifacts (--artifact, --registry):
+!find . -name "*.tar.gz" -o -name "*.zip" -o -name "*.jar" | head -5 2>/dev/null
+!docker images --format "table {{.Repository}}:{{.Tag}}" 2>/dev/null | head -5
+!npm whoami 2>/dev/null || echo "Not logged into npm registry"
+
+Configure artifact management:
+- Set up artifact registry integration
+- Configure versioning and tagging strategies
+- Implement artifact promotion pipelines
+- Configure retention policies and cleanup
+- Set up artifact security scanning
+
+Think step by step about pipeline configuration and optimization requirements and provide:
+
+1. **Pipeline Analysis**:
+   - Current pipeline configuration assessment
+   - Platform compatibility evaluation
+   - Performance bottleneck identification
+   - Security vulnerability scanning
+
+2. **Configuration Strategy**:
+   - Stage dependency optimization
+   - Parallel execution opportunities
+   - Resource allocation improvements
+   - Cache strategy implementation
+
+3. **Implementation Plan**:
+   - Platform-specific configuration generation
+   - Security integration requirements
+   - Monitoring and observability setup
+   - Quality gate configuration
+
+4. **Optimization Recommendations**:
+   - Build time reduction strategies
+   - Resource utilization improvements
+   - Cost optimization opportunities
+   - Performance monitoring setup
+
+Generate comprehensive pipeline configuration with platform-specific optimizations, security integrations, monitoring setup, and performance recommendations.
+
+If no specific operation is provided, perform pipeline health assessment and recommend configuration improvements based on current setup and best practices.