@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/scripts/verifiers/skills.js

@@ -0,0 +1,209 @@
+/**
+ * Skills Verifier - Dynamic skill validation using versions.json as source of truth
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createCheck, createResult, SEVERITY } = require('../lib/verify-formatter');
+const { getPluginRoot } = require('./plugin');
+
+const NAME = 'Skills';
+
+/**
+ * Load versions.json registry
+ */
+function loadRegistry() {
+  const pluginRoot = getPluginRoot();
+  const versionsPath = path.join(pluginRoot, 'config', 'versions.json');
+
+  try {
+    const content = fs.readFileSync(versionsPath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get active skills from registry
+ */
+function getRegisteredSkills(versions) {
+  if (!versions || !versions.skills) return [];
+
+  return Object.entries(versions.skills)
+    .filter(([, info]) => info.status === 'active')
+    .map(([name]) => name);
+}
+
+/**
+ * Get existing skill directories
+ */
+function getExistingSkills() {
+  const pluginRoot = getPluginRoot();
+  const skillsDir = path.join(pluginRoot, 'skills');
+
+  if (!fs.existsSync(skillsDir)) return [];
+
+  return fs.readdirSync(skillsDir).filter((f) => {
+    const fullPath = path.join(skillsDir, f);
+    return fs.statSync(fullPath).isDirectory();
+  });
+}
+
+/**
+ * Check registry vs disk bidirectionally
+ */
+function checkRegistrySync() {
+  const versions = loadRegistry();
+  const checks = [];
+
+  if (!versions) {
+    return [
+      createCheck('Skills registry', false, {
+        severity: SEVERITY.CRITICAL,
+        message: 'cannot load versions.json',
+        remediation: 'Fix or create config/versions.json',
+      }),
+    ];
+  }
+
+  const registered = getRegisteredSkills(versions);
+  const existing = getExistingSkills();
+
+  // Check: All registered skills exist on disk
+  const missing = registered.filter((s) => !existing.includes(s));
+  if (missing.length > 0) {
+    checks.push(
+      createCheck('Registered skills exist', false, {
+        severity: SEVERITY.WARNING,
+        message: `missing: ${missing.slice(0, 3).join(', ')}${missing.length > 3 ? '...' : ''}`,
+        remediation: `Create missing skill directories or update versions.json`,
+      })
+    );
+  } else {
+    checks.push(
+      createCheck('Registered skills exist', true, {
+        message: `${registered.length} verified`,
+      })
+    );
+  }
+
+  // Check: All existing skills are registered
+  const unregistered = existing.filter((s) => !registered.includes(s));
+  // Exclude common non-skill directories
+  const filteredUnregistered = unregistered.filter(
+    (s) => !['node_modules', '.git', 'dist'].includes(s)
+  );
+
+  if (filteredUnregistered.length > 0) {
+    checks.push(
+      createCheck('Skills are registered', false, {
+        severity: SEVERITY.WARNING,
+        message: `unregistered: ${filteredUnregistered.slice(0, 3).join(', ')}${filteredUnregistered.length > 3 ? '...' : ''}`,
+        remediation: `Add skills to versions.json or remove directories`,
+      })
+    );
+  } else {
+    checks.push(
+      createCheck('Skills are registered', true, {
+        message: `${existing.length} on disk`,
+      })
+    );
+  }
+
+  return checks;
+}
+
+/**
+ * Check each skill has SKILL.md
+ */
+function checkSkillFiles() {
+  const pluginRoot = getPluginRoot();
+  const skillsDir = path.join(pluginRoot, 'skills');
+  const checks = [];
+
+  if (!fs.existsSync(skillsDir)) {
+    return [
+      createCheck('SKILL.md files', false, {
+        severity: SEVERITY.WARNING,
+        message: 'skills/ directory not found',
+      }),
+    ];
+  }
+
+  const skills = fs.readdirSync(skillsDir).filter((f) => {
+    const fullPath = path.join(skillsDir, f);
+    return fs.statSync(fullPath).isDirectory();
+  });
+
+  let hasSkillMd = 0;
+  let missingSkillMd = [];
+
+  for (const skill of skills) {
+    const skillMdPath = path.join(skillsDir, skill, 'SKILL.md');
+    if (fs.existsSync(skillMdPath)) {
+      hasSkillMd++;
+    } else {
+      missingSkillMd.push(skill);
+    }
+  }
+
+  if (missingSkillMd.length > 0) {
+    checks.push(
+      createCheck('SKILL.md files', false, {
+        severity: SEVERITY.WARNING,
+        message: `${missingSkillMd.length} missing`,
+        remediation: `Add SKILL.md to: ${missingSkillMd.slice(0, 3).join(', ')}${missingSkillMd.length > 3 ? '...' : ''}`,
+      })
+    );
+  } else {
+    checks.push(
+      createCheck('SKILL.md files', true, {
+        message: `${hasSkillMd}/${skills.length} present`,
+      })
+    );
+  }
+
+  return checks;
+}
+
+/**
+ * Check skill-matcher.js loads
+ */
+function checkSkillMatcher() {
+  const pluginRoot = getPluginRoot();
+  const matcherPath = path.join(pluginRoot, 'scripts', 'lib', 'skill-matcher.js');
+
+  if (!fs.existsSync(matcherPath)) {
+    return createCheck('skill-matcher.js', false, {
+      severity: SEVERITY.WARNING,
+      message: 'not found',
+      remediation: 'Create scripts/lib/skill-matcher.js',
+    });
+  }
+
+  try {
+    // Try to require the module (validates syntax and basic structure)
+    require(matcherPath);
+    return createCheck('skill-matcher.js', true, {
+      message: 'loads ok',
+    });
+  } catch (err) {
+    return createCheck('skill-matcher.js', false, {
+      severity: SEVERITY.WARNING,
+      message: err.message.slice(0, 40),
+      remediation: 'Fix errors in skill-matcher.js',
+    });
+  }
+}
+
+/**
+ * Run all skills checks
+ */
+function verify() {
+  const checks = [...checkRegistrySync(), ...checkSkillFiles(), checkSkillMatcher()];
+
+  return createResult(NAME, checks);
+}
+
+module.exports = { verify, NAME };

package/scripts/verify-setup.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+/**
+ * Verify Setup - Main orchestrator for CloudStream Claude Code verification
+ *
+ * Runs modular verifiers to validate the plugin installation and configuration.
+ * Following patterns from health-check.js and diagnose.js.
+ *
+ * Usage:
+ *   node scripts/verify-setup.js           # Full verification
+ *   node scripts/verify-setup.js --quick   # Skip deep checks
+ *   node scripts/verify-setup.js --json    # JSON output for CI/CD
+ *   node scripts/verify-setup.js --module=hooks  # Single module
+ */
+
+const verifiers = require('./verifiers');
+const {
+  formatHeader,
+  formatSection,
+  formatIssues,
+  formatSummary,
+  SEVERITY,
+} = require('./lib/verify-formatter');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const options = {
+  quick: args.includes('--quick'),
+  json: args.includes('--json'),
+  verbose: args.includes('--verbose'),
+  module: args.find((a) => a.startsWith('--module='))?.split('=')[1] || null,
+};
+
+/**
+ * Log to stderr (visible to user)
+ */
+function log(message) {
+  if (!options.json) {
+    console.error(message);
+  }
+}
+
+/**
+ * Run all verifiers in dependency order
+ */
+async function runVerifiers() {
+  const results = [];
+  const allIssues = [];
+  let totalPassed = 0;
+  let totalWarned = 0;
+  let totalFailed = 0;
+
+  // Determine which modules to run
+  let modulesToRun = verifiers.executionOrder;
+  if (options.module) {
+    if (!verifiers.executionOrder.includes(options.module)) {
+      log(`Unknown module: ${options.module}`);
+      log(`Available modules: ${verifiers.executionOrder.join(', ')}`);
+      process.exit(2);
+    }
+    modulesToRun = [options.module];
+  } else if (options.quick) {
+    // Quick mode: only critical checks
+    modulesToRun = ['environment', 'persistence', 'plugin'];
+  }
+
+  // Print header
+  log(formatHeader('CloudStream Claude Code - Setup Verifier'));
+
+  // Run each verifier
+  for (const moduleName of modulesToRun) {
+    try {
+      const verifier = verifiers[moduleName];
+      if (!verifier || typeof verifier.verify !== 'function') {
+        log(`\n  Skipping ${moduleName}: no verify function`);
+        continue;
+      }
+
+      const result = verifier.verify();
+      results.push(result);
+
+      // Aggregate counts
+      totalPassed += result.passed;
+      totalWarned += result.warned;
+      totalFailed += result.failed;
+
+      // Collect issues
+      for (const issue of result.issues) {
+        allIssues.push({
+          module: moduleName,
+          ...issue,
+        });
+      }
+
+      // Print section
+      log(formatSection(result.name, result.checks));
+    } catch (err) {
+      log(`\n  Error running ${moduleName}: ${err.message}`);
+      totalFailed++;
+      allIssues.push({
+        module: moduleName,
+        name: `${moduleName} verifier failed`,
+        severity: SEVERITY.CRITICAL,
+        message: err.message,
+      });
+    }
+  }
+
+  // Print issues
+  if (allIssues.length > 0) {
+    log(formatIssues(allIssues));
+  }
+
+  // Print summary
+  log(formatSummary(totalPassed, totalWarned, totalFailed));
+
+  // JSON output for CI/CD
+  if (options.json) {
+    const output = {
+      success: totalFailed === 0,
+      summary: {
+        passed: totalPassed,
+        warned: totalWarned,
+        failed: totalFailed,
+        total: totalPassed + totalWarned + totalFailed,
+      },
+      modules: results.map((r) => ({
+        name: r.name,
+        passed: r.passed,
+        warned: r.warned,
+        failed: r.failed,
+        checks: r.checks.map((c) => ({
+          name: c.name,
+          passed: c.passed,
+          severity: c.severity,
+          message: c.message,
+        })),
+      })),
+      issues: allIssues.map((i) => ({
+        module: i.module,
+        name: i.name,
+        severity: i.severity,
+        message: i.message,
+        remediation: i.remediation,
+      })),
+    };
+    console.log(JSON.stringify(output, null, 2));
+  }
+
+  // Exit code: 0=pass, 1=warnings only, 2=critical failures
+  if (totalFailed > 0) {
+    process.exit(2);
+  } else if (totalWarned > 0) {
+    process.exit(1);
+  } else {
+    process.exit(0);
+  }
+}
+
+// Run verification
+runVerifiers().catch((err) => {
+  log(`\nFatal error: ${err.message}`);
+  process.exit(2);
+});

package/skills/INDEX.md

@@ -0,0 +1,157 @@
+# Skills Index
+
+Central reference for all 15 active skills available in CloudStream Claude Tools.
+
+> **Note:** 2 skills are archived (tracked in [config/versions.json](../config/versions.json)): eval-harness, verification-loop
+
+## Quick Reference
+
+| Skill | Description | Auto-Activation |
+|-------|-------------|-----------------|
+| [backend-patterns](./backend-patterns/SKILL.md) | Backend architecture, API design, Node.js | Backend file types |
+| [bigquery-patterns](./bigquery-patterns/SKILL.md) | BigQuery optimization, medallion architecture | BigQuery queries, .sql files |
+| [cloudstream-project-template](./cloudstream-project-template/SKILL.md) | Project structure, client onboarding | New project setup |
+| [coding-standards](./coding-standards/SKILL.md) | Universal coding best practices | All code files |
+| [compliance-patterns](./compliance-patterns/SKILL.md) | HIPAA, SOC2, PCI-DSS patterns | Compliance mode active |
+| [consultancy-workflows](./consultancy-workflows/SKILL.md) | Client management, time tracking | Client context |
+| [continuous-learning](./continuous-learning/SKILL.md) | Pattern extraction, skill capture | Session end |
+| [continuous-learning-v2](./continuous-learning-v2/SKILL.md) | Instinct-based learning, evolution | Session hooks |
+| [frontend-patterns](./frontend-patterns/SKILL.md) | React, Next.js, UI patterns | Frontend file types |
+| [gcp-data-engineering](./gcp-data-engineering/SKILL.md) | GCP, Dataflow, dbt patterns | GCP/data tasks |
+| [security-review](./security-review/SKILL.md) | Security checklist, vulnerability detection | Auth, secrets, APIs |
+| [strategic-compact](./strategic-compact/SKILL.md) | Context preservation guidance | Long sessions |
+| [tdd-workflow](./tdd-workflow/SKILL.md) | Test-driven development enforcement | Feature development |
+| [tutorial](./tutorial/SKILL.md) | Interactive system tutorial | /tutorial command |
+| [zoho-patterns](./zoho-patterns/SKILL.md) | Zoho Creator, Catalyst, Deluge | Zoho development |
+
+## Skills by Category
+
+### Platform-Specific
+
+| Skill | Platform | Key Patterns |
+|-------|----------|--------------|
+| [zoho-patterns](./zoho-patterns/SKILL.md) | Zoho Creator, Catalyst | Forms, workflows, Deluge scripts |
+| [bigquery-patterns](./bigquery-patterns/SKILL.md) | Google BigQuery | Schema design, query optimization |
+| [gcp-data-engineering](./gcp-data-engineering/SKILL.md) | Google Cloud | Dataflow, dbt, medallion architecture |
+
+### Development Workflow
+
+| Skill | Purpose | When Activated |
+|-------|---------|----------------|
+| [tdd-workflow](./tdd-workflow/SKILL.md) | Test-first development | Writing features, fixing bugs |
+
+### Code Quality
+
+| Skill | Purpose | Scope |
+|-------|---------|-------|
+| [coding-standards](./coding-standards/SKILL.md) | Universal standards | All code |
+| [backend-patterns](./backend-patterns/SKILL.md) | Server-side patterns | Node.js, APIs |
+| [frontend-patterns](./frontend-patterns/SKILL.md) | Client-side patterns | React, Next.js |
+| [security-review](./security-review/SKILL.md) | Security checks | Auth, input, secrets |
+
+### Compliance
+
+| Skill | Standards | When Required |
+|-------|-----------|---------------|
+| [compliance-patterns](./compliance-patterns/SKILL.md) | HIPAA, SOC2, PCI-DSS | Compliance mode active |
+
+### Consultancy
+
+| Skill | Purpose | Use Case |
+|-------|---------|----------|
+| [consultancy-workflows](./consultancy-workflows/SKILL.md) | Client management | Multi-client work |
+| [cloudstream-project-template](./cloudstream-project-template/SKILL.md) | Project setup | New clients |
+| [continuous-learning](./continuous-learning/SKILL.md) | Knowledge capture | Session end |
+| [continuous-learning-v2](./continuous-learning-v2/SKILL.md) | Instinct-based learning | Automated patterns |
+
+### System
+
+| Skill | Purpose | Activation |
+|-------|---------|------------|
+| [tutorial](./tutorial/SKILL.md) | Onboarding | New users |
+| [strategic-compact](./strategic-compact/SKILL.md) | Context management | Long sessions |
+
+## Skill Lifecycle
+
+Skills progress through these stages:
+
+```
+learned/ (local only)
+    ↓ /skill-submit
+shared/ (team repo, review pending)
+    ↓ PR approved
+active (team-wide)
+    ↓ Quarterly review
+deprecated (flagged for removal)
+    ↓ Grace period
+archived (removed)
+```
+
+### Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `active` | Currently used, fully supported |
+| `deprecated` | Flagged for removal, grace period |
+| `experimental` | Under evaluation |
+| `archived` | No longer available |
+
+## Auto-Injection System
+
+Skills are automatically injected based on:
+
+1. **File patterns** - Working on `.ds` triggers Deluge skills
+2. **Technology detection** - BigQuery imports trigger GCP skills
+3. **Compliance mode** - HIPAA mode activates compliance skills
+4. **Keyword matching** - Terms like "batch processing" trigger relevant patterns
+
+The skill-injector hook manages this automatically via:
+- `scripts/hooks/skill-injector.js`
+- `scripts/lib/skill-matcher.js`
+
+## Skill Structure
+
+Each skill directory contains:
+
+```
+skills/[skill-name]/
+├── SKILL.md           # Main skill document (required)
+├── examples/          # Code examples (optional)
+├── templates/         # Reusable templates (optional)
+└── lessons/           # Tutorial lessons (tutorial only)
+```
+
+### Required Frontmatter
+
+```yaml
+---
+name: skill-name
+description: Brief description
+version: 1.0.0
+status: active
+introduced: 1.0.0
+lastUpdated: YYYY-MM-DD
+activation: (optional) Context triggers
+---
+```
+
+## Related
+
+- [Commands Index](../commands/INDEX.md) - Commands that invoke skills
+- [Agents Index](../agents/INDEX.md) - Agents that use skills
+- [Rules Index](../rules/INDEX.md) - Rules that enforce standards
+
+## Skill Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/learn` | Extract patterns from current session |
+| `/skill-create` | Generate SKILL.md from git history |
+| `/skill-sync` | Pull shared skills from team repo |
+| `/skill-submit` | Submit skill for team review |
+| `/quarterly-review` | Review skill effectiveness |
+| `/instinct-status` | View learned instincts with confidence |
+| `/instinct-export` | Export instincts for sharing |
+| `/instinct-import` | Import instincts from teammates |
+| `/evolve` | Cluster instincts into commands/skills/agents |
+| `/eval` | Eval-driven development workflow |