@paulduvall/claude-dev-toolkit 0.0.1-alpha.12 → 0.0.1-alpha.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Paul Duvall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # Claude Dev Toolkit
 
-**Transform Claude Code into a complete development platform** with 58 AI-powered custom commands that automate your entire software development workflow.
+**Transform Claude Code into a complete development platform** with 62 AI-powered custom commands that automate your entire software development workflow.
 
 ## 🚀 Quick Installation
 
@@ -15,12 +15,12 @@ claude
 
 ## 📦 What's Included
 
-- **13 Active Commands**: Production-ready commands for immediate use
-- **45 Experimental Commands**: Cutting-edge features for early adopters  
+- **16 Active Commands**: Production-ready commands for immediate use
+- **46 Experimental Commands**: Cutting-edge features for early adopters  
 - **Security Hooks**: Automated security validation and governance
 - **Configuration Templates**: Pre-configured settings for different workflows
 - **Interactive Setup Wizard**: Guided installation with customization options
-- **JavaScript Test Suite**: 100% test coverage with 10 comprehensive test suites
+- **JavaScript Test Suite**: 25 test suites validating package structure, commands, and integration
 
 ## 🎯 Quick Start
 
@@ -33,9 +33,9 @@ npm install -g @paulduvall/claude-dev-toolkit
 ### Option 2: Manual Command Installation
 ```bash
 # Install specific command sets
-claude-commands install --active        # Install 13 production commands
-claude-commands install --experiments  # Install 45 experimental commands  
-claude-commands install --all           # Install all 58 commands
+claude-commands install --active        # Install 16 production commands
+claude-commands install --experiments  # Install 46 experimental commands
+claude-commands install --all           # Install all 62 commands
 ```
 
 ### Option 3: Custom Installation
@@ -68,7 +68,7 @@ claude-commands oidc --help             # Configure GitHub Actions OIDC with AWS
 - **`/xconfig`** - Configuration management
 - **`/xtdd`** - Test-driven development automation
 
-### 🧪 **Experimental Commands** (45 Additional)
+### 🧪 **Experimental Commands** (46 Additional)
 Advanced commands for specialized workflows:
 - **Planning & Analytics**: `/xplanning`, `/xanalytics`, `/xmetrics`
 - **Infrastructure**: `/xinfra`, `/xmonitoring`, `/xaws`
@@ -166,11 +166,11 @@ npm run lint             # Code linting
 ```
 
 ### Test Coverage
-- **10 Test Suites**: 100% passing
-- **Command Validation**: All 58 commands validated
-- **Security Tests**: Comprehensive security pattern validation
-- **Integration Tests**: End-to-end workflow testing
-- **Configuration Tests**: Template and setup validation
+- **25 Test Suites**: Package structure, CLI, and command validation
+- **Command Validation**: All commands validated for structure and naming
+- **Security Tests**: Credential exposure and placeholder detection
+- **Integration Tests**: Hook and subagent workflow testing
+- **Shell Tests**: 8 bash test suites for hooks and lib modules
 
 ### Architecture
 - **Self-Contained Package**: No dependencies on repository cloning
@@ -271,7 +271,7 @@ npm test
 - ✅ **Dependency Validation**: AWS CLI, Git, and GitHub CLI availability checking
 
 ### Version 0.0.1-alpha.8
-- ✅ **Documentation Consistency**: Fixed command counts (58) and subagent counts (26)
+- ✅ **Documentation Consistency**: Fixed command counts and subagent counts
 - ✅ **Test Infrastructure**: Enhanced test-results directory handling
 - ✅ **Repository Cleanup**: Removed outdated documentation and test artifacts
 - ✅ **Validation Logic**: Improved scenario-aware test validation
@@ -288,8 +288,8 @@ npm test
 - ✅ **Symlink Consolidation**: Eliminated duplicate directories
 - ✅ **JavaScript Migration**: Complete test suite migration from Python
 - ✅ **Enhanced Templates**: Fixed configuration template issues
-- ✅ **100% Test Coverage**: All 10 test suites passing
-- ✅ **58 Total Commands**: 13 active + 45 experimental commands
+- ✅ **Test Suites**: Package structure and command validation
+- ✅ **62 Total Commands**: 16 active + 46 experimental commands
 - ✅ **Security Enhancements**: Comprehensive security hook system
 
 ## 📄 License

package/bin/claude-commands

@@ -19,36 +19,75 @@ program
 program
     .command('list')
     .description('List all available commands')
+    .addHelpText('after', `
+Examples:
+  $ claude-commands list              # List all installed commands
+  $ claude-commands list --active     # Show only production commands
+  $ claude-commands list --experiments # Show only experimental commands`)
     .option('-a, --active', 'Show only active commands')
     .option('-e, --experiments', 'Show only experimental commands')
     .action((options) => {
         const claudeDir = path.join(os.homedir(), '.claude', 'commands');
-        
+        const pkgDir = path.join(__dirname, '..', 'commands');
+
         console.log('📦 Claude Custom Commands\n');
-        
-        if (fs.existsSync(claudeDir)) {
-            const allCommands = fs.readdirSync(claudeDir)
+
+        // Determine source: installed commands or package commands
+        const sourceDir = fs.existsSync(claudeDir) ? claudeDir : null;
+
+        if (sourceDir) {
+            let allCommands = fs.readdirSync(sourceDir)
                 .filter(f => f.endsWith('.md'))
                 .map(f => f.replace('.md', ''))
                 .sort();
-            
+
+            // Apply --active/--experiments filters using package source dirs
+            if (options.active || options.experiments) {
+                const activeDir = path.join(pkgDir, 'active');
+                const expDir = path.join(pkgDir, 'experiments');
+                const activeSet = new Set();
+                const expSet = new Set();
+
+                if (fs.existsSync(activeDir)) {
+                    fs.readdirSync(activeDir)
+                        .filter(f => f.endsWith('.md'))
+                        .forEach(f => activeSet.add(f.replace('.md', '')));
+                }
+                if (fs.existsSync(expDir)) {
+                    fs.readdirSync(expDir)
+                        .filter(f => f.endsWith('.md'))
+                        .forEach(f => expSet.add(f.replace('.md', '')));
+                }
+
+                if (options.active) {
+                    allCommands = allCommands.filter(cmd => activeSet.has(cmd));
+                } else if (options.experiments) {
+                    allCommands = allCommands.filter(cmd => expSet.has(cmd));
+                }
+            }
+
             if (allCommands.length > 0) {
-                console.log('🚀 Available Commands:');
+                const label = options.active ? 'Active' : options.experiments ? 'Experimental' : 'Available';
+                console.log(`🚀 ${label} Commands:`);
                 allCommands.forEach(cmd => console.log(`  /${cmd}`));
                 console.log(`\n📊 Total: ${allCommands.length} commands`);
             } else {
-                console.log('  No commands found');
+                console.log('  No commands found matching filter');
             }
         } else {
             console.log('  Commands directory not found');
+            console.log('  Run: claude-commands install');
         }
-        
-        console.log('\n💡 Usage: Try /xhelp in Claude Code to see all commands');
     });
 
 program
     .command('install')
     .description('Install command sets to ~/.claude/commands/')
+    .addHelpText('after', `
+Examples:
+  $ claude-commands install            # Install active commands (default)
+  $ claude-commands install --all      # Install all commands
+  $ claude-commands install --dry-run  # Preview without changes`)
     .option('--active', 'Install production-ready commands (default)')
     .option('--experiments', 'Install experimental commands only')
     .option('--all', 'Install both active and experimental')
@@ -153,6 +192,11 @@ program
 program
     .command('setup')
     .description('Setup the Claude Dev Toolkit with custom commands and configuration')
+    .addHelpText('after', `
+Examples:
+  $ claude-commands setup                            # Interactive setup
+  $ claude-commands setup --type basic --commands all # Basic config, all commands
+  $ claude-commands setup --dry-run                   # Preview setup actions`)
     .option('--type <template>', 'Configuration template to apply (basic, comprehensive, security-focused)')
     .option('--commands <set>', 'Command set to install (active, experiments, all, none)')
     .option('--skip-configure', 'Skip configuration step')
@@ -328,4 +372,23 @@ program
         }
     });
 
+program
+    .command('uninstall')
+    .description('Remove all installed commands, hooks, and subagents')
+    .addHelpText('after', `
+Examples:
+  $ claude-commands uninstall           # Remove all installed files
+  $ claude-commands uninstall --dry-run # Preview what would be removed`)
+    .option('--dry-run', 'Preview what would be removed without deleting')
+    .option('--keep-settings', 'Keep settings.json intact')
+    .action((options) => {
+        const uninstaller = require('../lib/uninstall-command');
+        try {
+            uninstaller.execute(options);
+        } catch (error) {
+            console.error(`Uninstall failed: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
 program.parse(process.argv);

package/commands/active/xcontinue.md

@@ -0,0 +1,92 @@
+---
+description: Continue an execution plan from where it left off across sessions
+tags: [workflow, execution-plan, session-continuity, automation]
+---
+
+# Execution Plan Continuation
+
+Resume a multi-step execution plan, picking up at the next incomplete task.
+
+## Usage Examples
+
+**Resume the current plan:**
+```
+/xcontinue
+```
+
+**Help and options:**
+```
+/xcontinue help
+/xcontinue --help
+```
+
+## Implementation
+
+If $ARGUMENTS contains "help" or "--help":
+Display this usage information and exit.
+
+### Step 1: Find the Execution Plan
+
+Search for execution plan files in the current directory:
+
+```bash
+find . -maxdepth 2 -iname "*plan*" -name "*.md" ! -path "*/node_modules/*" ! -path "*/.git/*" 2>/dev/null
+```
+
+- Common names: `EXECUTION_PLAN.md`, `PLAN.md`, `execution-plan.md`
+
+If no plan file is found:
+- Tell the user: "No execution plan found in this directory."
+- Suggest creating one with a basic template:
+
+```markdown
+# Execution Plan
+
+| # | Task | Status | Notes |
+|---|------|--------|-------|
+| 1 | [First task] | [ ] pending | |
+| 2 | [Second task] | [ ] pending | |
+```
+
+Stop and wait for user input.
+
+### Step 2: Parse Plan Progress
+
+Read the plan file and identify:
+- **Completed tasks**: Lines with `[x]`, `done`, or checkmarks
+- **Pending tasks**: Lines with `[ ]`, `pending`, or unchecked items
+- **In-progress tasks**: Lines with `in-progress` or `in progress`
+
+Display a progress summary:
+```
+Progress: X of Y tasks complete
+Next task: [description of next pending task]
+```
+
+If all tasks are complete:
+- Congratulate the user
+- Summarize what was accomplished
+- Suggest cleanup: "Consider deleting the plan file if work is done."
+- Stop execution.
+
+### Step 3: Execute Next Task
+
+Pick the first task with status `pending` or `[ ]`:
+1. Read the task description and any acceptance criteria
+2. Implement the task fully
+3. Run validation if applicable (tests, lint, build)
+4. Verify acceptance criteria pass
+
+### Step 4: Update Plan and Handoff
+
+After completing the task:
+1. Update the plan file — mark the task as `[x] done` with a timestamp
+2. Update any counters (Done/Remaining) in the plan header
+3. Tell the user:
+
+```
+Task #N complete: [brief summary]
+Run /clear then /xcontinue to proceed to the next task.
+```
+
+This handoff protocol ensures context stays fresh across sessions.

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/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.