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

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.

package/commands/active/xtdd.md

@@ -0,0 +1,151 @@
+---
+description: Complete Test-Driven Development workflow automation with Red-Green-Refactor-Commit cycle
+tags: [tdd, testing, red-green-refactor, workflow, specifications, automation]
+---
+
+Execute complete TDD workflow automation based on the arguments provided in $ARGUMENTS.
+
+## Usage Examples
+
+**Basic TDD workflow:**
+```
+/xtdd
+```
+
+**Start RED phase:**
+```
+/xtdd --red ContactForm
+```
+
+**Implement GREEN phase:**
+```
+/xtdd --green
+```
+
+**Help and options:**
+```
+/xtdd --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+First, verify project structure and TDD readiness:
+!ls -la specs/ 2>/dev/null || echo "No specs directory found"
+!find specs/tests/ -name "*.py" | head -5 2>/dev/null || echo "No tests found"
+!python -c "import pytest; print('pytest available')" 2>/dev/null || echo "pytest not available"
+
+Based on $ARGUMENTS, perform the appropriate TDD phase:
+
+## 1. RED Phase - Write Failing Test
+
+If starting RED phase (--red):
+!grep -r "#{#$spec_id" specs/specifications/ 2>/dev/null || echo "Specification not found"
+!find specs/tests/ -name "*.py" -exec grep -l "$spec_id" {} \; 2>/dev/null | head -3
+
+Create failing test for specification:
+- Verify specification exists and is readable
+- Analyze specification requirements and criteria
+- Create test file if not exists
+- Write test that exercises the requirement
+- Ensure test fails (RED phase validation)
+
+## 2. GREEN Phase - Minimal Implementation
+
+If implementing GREEN phase (--green):
+!python -m pytest specs/tests/ -x --tb=short 2>/dev/null || echo "Tests currently failing"
+!find . -name "*.py" | grep -v test | head -5
+
+Implement minimal passing code:
+- Run tests to identify failures
+- Implement simplest code to make tests pass
+- Focus on meeting test requirements only
+- Avoid over-engineering or premature optimization
+- Verify all tests pass (GREEN phase validation)
+
+## 3. REFACTOR Phase - Code Quality Improvement
+
+If refactoring (--refactor):
+!python -m pytest specs/tests/ -v 2>/dev/null || echo "Tests must pass before refactoring"
+!python -c "import mypy" 2>/dev/null && echo "MyPy available" || echo "MyPy not available"
+!python -c "import ruff" 2>/dev/null && echo "Ruff available" || echo "Ruff not available"
+
+Improve code quality while maintaining tests:
+- Verify tests pass before starting
+- Run quality checks (type checking, linting)
+- Apply code formatting and style improvements
+- Remove duplication and improve naming
+- Ensure tests still pass after changes
+
+## 4. COMMIT Phase - Traceability Documentation
+
+If committing changes (--commit):
+!git status --porcelain
+!grep -r "#{#$spec_id" specs/specifications/ 2>/dev/null | grep -o "authority=[^}]*"
+!python -m pytest --cov=. --cov-report=term specs/tests/ 2>/dev/null | grep "TOTAL" || echo "Coverage not available"
+
+Create commit with TDD traceability:
+- Final test validation before commit
+- Extract specification authority level
+- Generate coverage metrics
+- Stage all changes for commit
+- Create detailed commit message with TDD cycle documentation
+
+## 5. Workflow Validation and Guidance
+
+If validating TDD state:
+!find specs/tests/ -name "*.py" -exec grep -l "def test_" {} \; | wc -l
+!python -m pytest specs/tests/ --collect-only 2>/dev/null | grep "test" | wc -l || echo "0"
+
+Validate TDD workflow compliance:
+- Check for existing tests and specifications
+- Verify test-to-specification traceability
+- Analyze current TDD cycle phase
+- Provide next step recommendations
+- Ensure proper TDD discipline
+
+## 6. Quality Gates and Automation
+
+If running quality checks:
+!mypy . --ignore-missing-imports 2>/dev/null || echo "Type checking not available"
+!ruff check . 2>/dev/null || echo "Linting not available" 
+!ruff format . --check 2>/dev/null || echo "Formatting needed"
+
+Automated quality validation:
+- Type checking with MyPy
+- Code linting with Ruff
+- Style formatting validation
+- Test coverage analysis
+- Security and compliance checks
+
+Think step by step about TDD workflow requirements and provide:
+
+1. **Current TDD State Analysis**:
+   - Active TDD phase identification
+   - Test and implementation status
+   - Specification traceability validation
+   - Quality metrics assessment
+
+2. **Phase-Specific Guidance**:
+   - RED: Test creation and failure validation
+   - GREEN: Minimal implementation strategy
+   - REFACTOR: Quality improvement opportunities
+   - COMMIT: Traceability and documentation
+
+3. **Quality Assurance**:
+   - Test coverage and effectiveness
+   - Code quality metrics
+   - Specification compliance
+   - TDD discipline adherence
+
+4. **Workflow Optimization**:
+   - Cycle efficiency improvements
+   - Automation opportunities
+   - Quality gate enforcement
+   - Team collaboration enhancement
+
+Generate comprehensive TDD workflow automation with complete Red-Green-Refactor-Commit cycle, specification traceability, and quality assurance integration.
+
+If no specific phase is provided, analyze current TDD state and recommend next appropriate action based on project status and requirements.

package/commands/active/xtest.md

@@ -0,0 +1,89 @@
+---
+description: Run tests with smart defaults (runs all tests if no arguments)
+tags: [testing, coverage, quality]
+---
+
+# Test Execution
+
+Run tests with intelligent defaults. No parameters needed for basic usage.
+
+## Usage Examples
+
+**Basic usage (runs all available tests):**
+```
+/xtest
+```
+
+**Run with coverage report:**
+```
+/xtest coverage
+```
+
+**Quick unit tests only:**
+```
+/xtest unit
+```
+
+**Help and options:**
+```
+/xtest help
+/xtest --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+First, examine the project structure and detect testing framework:
+!ls -la | grep -E "(test|spec|__tests__|\.test\.|\.spec\.)"
+!find . -name "*test*" -o -name "*spec*" -o -name "__tests__" | head -5
+!python -c "import pytest; print('✓ pytest available')" 2>/dev/null || npm test --version 2>/dev/null || echo "Detecting test framework..."
+
+Determine testing approach based on $ARGUMENTS (default to running all tests):
+
+**Mode 1: Default Test Run (no arguments)**
+If $ARGUMENTS is empty or contains "all":
+
+Auto-detect and run available tests:
+- **Python projects**: Run pytest with sensible defaults
+- **Node.js projects**: Run npm test or jest
+- **Other frameworks**: Detect and run appropriately
+
+!python -m pytest -v --tb=short 2>/dev/null || npm test 2>/dev/null || echo "No standard test configuration found"
+
+**Mode 2: Unit Tests Only (argument: "unit")**
+If $ARGUMENTS contains "unit":
+!python -m pytest -v -k "unit" --tb=short 2>/dev/null || npm test -- --testNamePattern="unit" 2>/dev/null || echo "Running unit tests..."
+
+Focus on fast, isolated tests:
+- Skip integration and e2e tests
+- Quick feedback on core logic
+- Fast execution for frequent testing
+
+**Mode 3: Coverage Analysis (argument: "coverage")**
+If $ARGUMENTS contains "coverage":
+!python -m pytest --cov=. --cov-report=term-missing -v 2>/dev/null || npm test -- --coverage 2>/dev/null || echo "Coverage analysis..."
+
+Generate coverage report:
+- Show percentage of code tested
+- Identify untested code areas
+- Highlight coverage gaps
+- Suggest areas for additional testing
+
+## Test Results Analysis
+
+Think step by step about test execution and provide:
+
+1. **Test Summary**: Clear pass/fail status with count of tests run
+2. **Failed Tests**: List any failures with concise explanations  
+3. **Coverage Status**: Coverage percentage if available
+4. **Next Steps**: Specific actions to improve test quality
+
+Generate a focused test report showing:
+- ✅ Tests passed
+- ❌ Tests failed (with brief error summaries)
+- 📊 Coverage percentage (if requested)
+- 🔧 Recommended improvements
+
+Keep output concise and actionable, focusing on what developers need to know immediately.

package/commands/active/xverify.md

@@ -0,0 +1,80 @@
+---
+description: "Verify references before taking action — catch fabricated URLs, placeholder IDs, and unverified claims"
+tags: ["verification", "quality", "safety", "pre-action"]
+---
+
+# Pre-Action Verification
+
+Scan proposed changes, generated content, or referenced artifacts for fabricated URLs, placeholder IDs, nonexistent file paths, and unverified references. Run this before committing, publishing, or acting on generated content.
+
+## Usage Examples
+
+**Verify current staged changes:**
+```
+/xverify
+```
+
+**Verify a specific file:**
+```
+/xverify README.md
+```
+
+**Verify generated documentation:**
+```
+/xverify docs/
+```
+
+## What Gets Checked
+
+### URLs and Endpoints
+- HTTP/HTTPS URLs: attempt to confirm they are plausible (check format, known domains)
+- API endpoints: verify they match project routes or documented APIs
+- Flag common fabrication patterns: `example.com` placeholders, sequential IDs, lorem ipsum domains
+
+### File Paths and References
+- Verify referenced file paths exist on disk
+- Check import/require statements resolve to real modules
+- Flag references to deleted or renamed files
+
+### IDs and Tokens
+- Flag placeholder patterns: `xxx`, `TODO`, `FIXME`, `your-*-here`, `placeholder`
+- Check for hardcoded test IDs that may not be valid in production
+- Flag UUIDs or IDs that appear fabricated (all zeros, sequential)
+
+### Claims and Assertions
+- Cross-check version numbers against package.json or lock files
+- Verify command names match actual available commands
+- Check that referenced environment variables are documented
+
+## Output Format
+
+For each issue found, report:
+1. **File and line** where the reference appears
+2. **What was found** (the suspicious reference)
+3. **Why it's suspicious** (pattern match or verification failure)
+4. **Suggested fix** (if determinable)
+
+## Implementation
+
+When invoked:
+
+1. **Determine scope**: If a file or directory argument is provided, scan that. Otherwise scan staged git changes (`git diff --cached`), or if nothing is staged, scan recent modifications.
+
+2. **Extract references**: Parse the scoped content for:
+   - URLs (http/https links)
+   - File paths (relative and absolute)
+   - Import/require statements
+   - Version strings
+   - Environment variable references
+   - Command names with `/x` prefix
+
+3. **Verify each reference**:
+   - File paths: check `fs.existsSync` or equivalent
+   - URLs: validate format, flag known placeholder domains
+   - Versions: cross-check against package.json
+   - Commands: cross-check against slash-commands/active/ and experiments/
+   - Env vars: check against .env.example or documentation
+
+4. **Report findings**: Group by severity (error, warning, info) and output a summary table.
+
+5. **Exit cleanly**: This is a read-only verification. No files are modified.