@cloudstreamsoftware/claude-tools 1.2.3 → 1.2.4

package/commands/diagnose.md

@@ -0,0 +1,99 @@
+---
+name: diagnose
+description: Deep diagnostic tool for troubleshooting CloudStream Claude Tools issues. Checks configurations, permissions, recent errors, and provides actionable recommendations.
+---
+
+# Diagnose Command
+
+Perform deep diagnostics when something isn't working correctly.
+
+## Instructions
+
+When user runs `/diagnose`, execute comprehensive diagnostics and provide actionable recommendations.
+
+### What Gets Checked
+
+1. **Configuration Files**
+   - `hooks/hooks.json` - Valid JSON, correct structure
+   - `~/.claude/settings.json` - Valid JSON, MCP configs
+   - `package.json` - Dependencies match
+
+2. **Permissions**
+   - `~/.claude/` - Read/write access
+   - `~/.claude/memory/` - Read/write access
+   - `~/.claude/skills/` - Read/write access
+
+3. **Recent Errors**
+   - Parse last 24h of session files for errors
+   - Identify patterns in failures
+   - Check for hook execution failures
+
+4. **MCP Connectivity**
+   - Test each configured MCP server
+   - Report response times
+   - Identify connection issues
+
+5. **Common Misconfigurations**
+   - Missing environment variables
+   - Incorrect file paths
+   - Version mismatches
+
+### Output Format
+
+```
+DIAGNOSIS REPORT
+
+Checking configurations...
+  hooks.json:           [OK] Valid, 19 hooks
+  settings.json:        [OK] Valid
+  package.json:         [OK] Dependencies installed
+
+Checking permissions...
+  ~/.claude/:           [OK] Writable
+  ~/.claude/memory/:    [OK] Writable
+  ~/.claude/skills/:    [OK] Writable
+
+Checking MCPs...
+  memory:               [OK] Connected (45ms)
+  context7:             [WARN] Slow (2.3s)
+
+Recent Errors (last 24h):
+  - 2 hook execution timeouts
+  - 1 JSON parse error in session file
+
+Recommendations:
+  1. Context7 MCP is slow - check network connectivity
+  2. Review hook timeout in hooks.json (consider increasing)
+  3. Check session file: ~/.claude/sessions/abc123.jsonl
+```
+
+## Arguments
+
+$ARGUMENTS can be:
+- (none) - Run full diagnostics
+- `--config` - Only check configuration files
+- `--permissions` - Only check permissions
+- `--errors` - Only check recent errors
+- `--mcp` - Only check MCP connectivity
+
+## Examples
+
+```
+/diagnose              # Full diagnostics
+/diagnose --config     # Check configs only
+/diagnose --errors     # Check recent errors only
+```
+
+## When to Use
+
+- After `/health-check` shows warnings or failures
+- When Claude isn't remembering corrections
+- When hooks seem to not be running
+- When MCPs aren't responding
+- Before escalating to team lead
+
+## Related Commands
+
+- `/health-check` - Quick health verification
+- `/verify` - Tutorial setup verification
+- `/onboard` - Interactive setup wizard

package/commands/e2e.md

@@ -0,0 +1,34 @@
+---
+name: e2e
+description: Generate and run end-to-end tests with Playwright. Creates test journeys, runs tests, captures screenshots/videos/traces, and uploads artifacts.
+---
+
+# /e2e [user-journey]
+
+Invoke the **e2e-runner** agent to generate, maintain, and execute Playwright tests for the specified user journey.
+
+## Parameters
+- `user-journey` — Description of the user flow to test (e.g., "login and view dashboard")
+
+## Workflow
+1. Agent analyzes user flow and identifies test scenarios
+2. Generates Playwright tests using Page Object Model pattern
+3. Runs tests across browsers (Chrome, Firefox, WebKit)
+4. Captures artifacts on failure (screenshots, videos, traces)
+5. Identifies and quarantines flaky tests
+6. Generates HTML report
+
+## When to Use
+- Testing critical user journeys (login, payments, CRUD flows)
+- Verifying multi-step flows end-to-end
+- Pre-deployment validation
+- Testing UI interactions and navigation
+
+## Artifacts
+- **Always:** HTML report, JUnit XML
+- **On failure:** Screenshots, video recording, trace file, network/console logs
+
+## Integration
+- Use `/plan` first to identify critical journeys
+- Use `/tdd` for unit-level tests (faster, more granular)
+- Use `/code-review` to verify test quality

package/commands/eval.md

@@ -0,0 +1,189 @@
+---
+description: Manage eval-driven development workflow with capability and regression testing
+status: planned
+implementation: Backend not yet implemented
+note: Part of continuous learning path - will be expanded in future releases
+---
+
+# /eval - Eval-Driven Development
+
+> **STATUS: PLANNED** - This command is documented but the backend implementation is not yet complete. The eval-driven development framework will be expanded as part of the continuous learning path.
+
+Manage eval-driven development workflow for systematic quality measurement.
+
+## When to Use
+
+- When implementing new features that need capability verification
+- To track regression testing across iterations
+- For systematic quality measurement aligned with TDD
+- Before marking a feature as complete
+
+## Usage
+
+```bash
+/eval define feature-name        # Create new eval definition
+/eval check feature-name         # Run and check evals
+/eval report feature-name        # Generate full report
+/eval list                       # Show all evals
+/eval clean                      # Remove old eval logs
+```
+
+## Operations
+
+### Define Evals
+
+`/eval define feature-name`
+
+Create a new eval definition:
+
+1. Create `.claude/evals/feature-name.md` with template:
+
+```markdown
+## EVAL: feature-name
+Created: 2026-01-27
+
+### Capability Evals
+- [ ] [Description of capability 1]
+- [ ] [Description of capability 2]
+
+### Regression Evals
+- [ ] [Existing behavior 1 still works]
+- [ ] [Existing behavior 2 still works]
+
+### Success Criteria
+- pass@3 > 90% for capability evals
+- pass^3 = 100% for regression evals
+```
+
+2. User fills in specific criteria
+
+### Check Evals
+
+`/eval check feature-name`
+
+Run evals for a feature:
+
+1. Read eval definition from `.claude/evals/feature-name.md`
+2. For each capability eval:
+   - Attempt to verify criterion
+   - Record PASS/FAIL
+   - Log attempt in `.claude/evals/feature-name.log`
+3. For each regression eval:
+   - Run relevant tests
+   - Compare against baseline
+   - Record PASS/FAIL
+4. Report current status:
+
+```
+EVAL CHECK: feature-name
+========================
+Capability: 3/4 passing
+Regression: 5/5 passing
+Status: IN PROGRESS
+```
+
+### Report Evals
+
+`/eval report feature-name`
+
+Generate comprehensive eval report:
+
+```
+EVAL REPORT: feature-name
+=========================
+Generated: 2026-01-27
+
+CAPABILITY EVALS
+----------------
+[eval-1]: PASS (pass@1)
+[eval-2]: PASS (pass@2) - required retry
+[eval-3]: FAIL - see notes
+
+REGRESSION EVALS
+----------------
+[test-1]: PASS
+[test-2]: PASS
+[test-3]: PASS
+
+METRICS
+-------
+Capability pass@1: 67%
+Capability pass@3: 100%
+Regression pass^3: 100%
+
+NOTES
+-----
+[Any issues, edge cases, or observations]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+### List Evals
+
+`/eval list`
+
+Show all eval definitions:
+
+```
+EVAL DEFINITIONS
+================
+feature-auth      [3/5 passing] IN PROGRESS
+feature-search    [5/5 passing] READY
+feature-export    [0/4 passing] NOT STARTED
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `define <name>` | Create new eval definition |
+| `check <name>` | Run and check evals |
+| `report <name>` | Generate full report |
+| `list` | Show all evals |
+| `clean` | Remove old eval logs (keeps last 10 runs) |
+
+## Success Criteria
+
+| Eval Type | Target |
+|-----------|--------|
+| Capability pass@1 | 67%+ (can pass on first try) |
+| Capability pass@3 | 90%+ (passes within 3 attempts) |
+| Regression pass^3 | 100% (must pass all 3 times) |
+
+## CloudStream Integration
+
+Works with existing TDD workflow:
+
+```bash
+# Define evals for new feature
+/eval define zoho-crm-sync
+
+# Run TDD workflow
+/tdd
+
+# Check eval progress
+/eval check zoho-crm-sync
+
+# Generate report before PR
+/eval report zoho-crm-sync
+```
+
+## Directory Structure
+
+```
+.claude/
+  evals/
+    feature-auth.md         # Eval definition
+    feature-auth.log        # Run history
+    feature-search.md
+    feature-search.log
+```
+
+## Related Commands
+
+- `/tdd` - Test-driven development workflow
+- `/verify` - Comprehensive verification suite
+- `/test-coverage` - Coverage analysis
+- `/code-review` - Code quality review

package/commands/evolve.md

@@ -0,0 +1,170 @@
+---
+description: Analyze instincts and cluster related ones into commands, skills, or agents
+status: experimental
+implementation: Requires continuous-learning-v2 observer (disabled by default)
+note: Part of continuous learning path - observer can be enabled in skills/continuous-learning-v2/config.json
+---
+
+# /evolve - Cluster Instincts into Higher Structures
+
+> **STATUS: EXPERIMENTAL** - This command relies on the continuous-learning-v2 instinct system. The observer is disabled by default for performance reasons. Enable it in `skills/continuous-learning-v2/config.json` to use full functionality.
+
+The `/evolve` command analyzes instincts and groups related ones into higher-level structures through intelligent clustering.
+
+## When to Use
+
+- After accumulating 10+ instincts in a domain
+- To automate creation of commands/skills from learned patterns
+- When you notice repeated workflows that should become formal commands
+- To review potential structure evolution before committing
+
+## Evolution Types
+
+The command categorizes clusters into three types:
+
+### 1. Commands
+Emerge when instincts describe user-invoked actions.
+
+**Example:** "when adding a database table" instincts cluster into `/new-table` command.
+
+```markdown
+# /new-table Command
+Generated from instincts: add-migration, create-model, update-schema
+
+## Steps
+1. Create migration file
+2. Generate model
+3. Update schema types
+```
+
+### 2. Skills
+Form from auto-triggered behaviors like code style enforcement.
+
+**Example:** Instincts about functional programming patterns cluster into `functional-patterns` skill.
+
+```markdown
+# functional-patterns Skill
+Generated from instincts: prefer-pure-functions, avoid-mutations, use-map-filter
+
+## Triggers
+- When writing new functions
+- When refactoring existing code
+```
+
+### 3. Agents
+Handle complex, multi-step processes requiring isolation.
+
+**Example:** Sequential debugging instincts evolve into `debugger` agent.
+
+```markdown
+# debugger Agent
+Generated from instincts: check-logs-first, isolate-component, test-hypothesis
+
+## Workflow
+1. Gather error context
+2. Form hypothesis
+3. Test systematically
+```
+
+## Usage
+
+```bash
+/evolve                                    # Analyze and show suggestions
+/evolve --dry-run                          # Preview without creating
+/evolve --execute                          # Create suggested structures
+/evolve --domain testing                   # Focus on specific domain
+/evolve --threshold 5                      # Require 5+ instincts per cluster
+/evolve --type command                     # Only suggest commands
+```
+
+## Process
+
+1. Read instincts from storage
+2. Group by domain and trigger patterns
+3. Identify clusters of 3+ related instincts
+4. Determine evolution type (command/skill/agent)
+5. Generate appropriate files in evolved structure directory
+
+## Output
+
+```
+EVOLUTION ANALYSIS
+==================
+
+## Command Candidates (2)
+
+📦 /new-api-endpoint (85% confidence)
+   Instincts: create-route, add-validation, write-test, update-docs
+   Would create: commands/new-api-endpoint.md
+
+📦 /db-migration (72% confidence)
+   Instincts: add-migration, update-model, sync-types
+   Would create: commands/db-migration.md
+
+## Skill Candidates (1)
+
+🧠 error-handling-patterns (78% confidence)
+   Instincts: use-try-catch, log-errors, return-early
+   Would create: skills/error-handling-patterns/SKILL.md
+
+## Agent Candidates (1)
+
+🤖 performance-analyzer (68% confidence)
+   Instincts: profile-first, measure-baseline, test-hypothesis
+   Would create: agents/performance-analyzer.md
+
+---
+Run '/evolve --execute' to create these structures.
+```
+
+## Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dry-run` | Preview evolution suggestions | enabled |
+| `--execute` | Create suggested structures | disabled |
+| `--domain <name>` | Filter by domain | all |
+| `--threshold <n>` | Minimum cluster size | 3 |
+| `--type <command\|skill\|agent>` | Target specific evolution type | all |
+| `--min-confidence <n>` | Minimum confidence for suggestions | 0.6 |
+
+## Evolved File Metadata
+
+Generated files include source tracking:
+
+```yaml
+---
+name: new-api-endpoint
+evolved_from:
+  - instinct: create-route
+    confidence: 0.8
+  - instinct: add-validation
+    confidence: 0.75
+  - instinct: write-test
+    confidence: 0.85
+evolution_date: 2026-01-27
+evolution_confidence: 0.85
+---
+```
+
+## CloudStream Integration
+
+Works with the continuous learning ecosystem:
+
+```bash
+# Review what can evolve
+/evolve --dry-run
+
+# Create new command from patterns
+/evolve --execute --type command
+
+# Focus on Zoho-specific patterns
+/evolve --domain zoho --dry-run
+```
+
+## Related Commands
+
+- `/instinct-status` - View current instincts
+- `/skill-create` - Generate skills from git history
+- `/learn` - Manually capture patterns
+- `/orchestrate` - Run multi-agent workflows

package/commands/handoff.md

@@ -0,0 +1,64 @@
+---
+name: handoff
+description: Generate comprehensive client handoff documentation for transferring a project to the client or another team member.
+arguments: client-id
+---
+
+Generate client handoff documentation for **$ARGUMENTS**.
+
+## Documentation Sections
+
+### 1. Executive Summary
+- Project scope and objectives
+- Key deliverables completed
+- Outstanding items and recommendations
+
+### 2. Architecture Overview
+- System diagram (describe components and connections)
+- Technology stack used
+- Data flow between systems
+
+### 3. Zoho Application Inventory
+For each Zoho app:
+- Creator apps: Forms, reports, workflows, widgets
+- Catalyst projects: Functions, AppSail apps
+- CRM customizations: Custom modules, workflows
+- Books integrations: Invoice sync, payment processing
+- Analytics dashboards: Reports, scheduled exports
+
+### 4. Integration Documentation
+For each integration:
+- Source and target systems
+- Authentication method (OAuth connection name)
+- Data flow direction and frequency
+- Error handling and retry logic
+- Known limitations
+
+### 5. Operational Runbook
+- Common administrative tasks
+- Troubleshooting steps for known issues
+- Monitoring and alerting setup
+- Backup and recovery procedures
+
+### 6. Compliance Status
+If compliance mode active:
+- Current compliance status
+- Audit log retention status
+- Outstanding compliance items
+- Ongoing obligations
+
+### 7. Credentials and Access
+- List all required credentials (DO NOT include values)
+- Transfer method: Encrypted password manager only
+- Service accounts and their purposes
+- API keys and connection names
+
+### 8. Known Issues & Technical Debt
+- Documented limitations
+- Future improvement recommendations
+- Performance considerations
+- Security hardening opportunities
+
+## Output Format
+Generate as a markdown document suitable for the client.
+Save to docs/handoff-[client-id]-[date].md

package/commands/health-check.md

@@ -0,0 +1,88 @@
+---
+name: health-check
+description: Run comprehensive system health verification to ensure CloudStream Claude Tools is properly configured and operational.
+---
+
+# Health Check Command
+
+Verify that your CloudStream Claude Tools installation is healthy and properly configured.
+
+## Instructions
+
+When user runs `/health-check`, execute the health check script and display results.
+
+### What Gets Checked
+
+1. **Environment**
+   - Node.js version (18+ required)
+   - Package manager detection (npm/yarn/pnpm)
+   - Git repository status
+
+2. **Claude State**
+   - `~/.claude/` directory exists and is writable
+   - Session memory file is valid JSON
+   - Hooks configuration is valid
+
+3. **Plugin State**
+   - Commands directory accessible
+   - Skills directory accessible
+   - Agents directory accessible
+
+4. **Optional MCPs**
+   - Memory MCP configured
+   - Context7 MCP configured
+
+### Output Format
+
+```
+HEALTH CHECK: [PASS/WARN/FAIL]
+
+Environment:
+  Node.js:        [OK] v20.x
+  Package Mgr:    [OK] npm
+  Git Repo:       [OK] Clean
+
+Claude State:
+  ~/.claude/:     [OK] Writable
+  Session Memory: [OK] Valid
+  Hooks:          [OK] 19 configured
+
+Plugin:
+  Commands:       [OK] 28 found
+  Skills:         [OK] 16 found
+  Agents:         [OK] 13 found
+
+MCPs (optional):
+  memory:         [OK] Configured
+  context7:       [OK] Configured
+
+Issues: None
+```
+
+## Arguments
+
+$ARGUMENTS can be:
+- (none) - Run full health check
+- `--quick` - Only check critical items
+- `--verbose` - Show detailed output for each check
+
+## Examples
+
+```
+/health-check           # Full health check
+/health-check --quick   # Quick critical checks only
+/health-check --verbose # Detailed output
+```
+
+## When to Use
+
+- After initial setup to verify installation
+- When something isn't working as expected
+- Before starting work on a new client project
+- As part of daily workflow verification
+
+## Related Commands
+
+- `/verify` - Verify the tutorial setup
+- `/diagnose` - Deep problem diagnosis
+- `/onboard` - Interactive setup wizard