@cloudstreamsoftware/claude-tools 1.2.3 → 1.2.5

package/bin/cloudstream-setup.js

@@ -305,21 +305,23 @@ async function storeCredentials(licenseKey, installType) {
 
 /**
  * Configure MCP server connection
+ * Merges into settings.json (same pattern as mergeHooksIntoSettings)
  */
 async function configureMcpServer(licenseKey) {
-  const mcpConfigPath = path.join(CONFIG.claudeDir, 'mcp.json');
+  const settingsPath = path.join(CONFIG.claudeDir, 'settings.json');
 
-  let existingConfig = { mcpServers: {} };
+  // Read existing settings or create empty object
+  let settings = {};
   try {
-    const content = await fs.readFile(mcpConfigPath, 'utf8');
-    existingConfig = JSON.parse(content);
+    const content = await fs.readFile(settingsPath, 'utf8');
+    settings = JSON.parse(content);
   } catch {
-    // File doesn't exist or is invalid
+    // File doesn't exist, start fresh
   }
 
-  // Add CloudStream knowledge server
-  existingConfig.mcpServers = existingConfig.mcpServers || {};
-  existingConfig.mcpServers['cloudstream-knowledge'] = {
+  // Merge MCP server into settings
+  settings.mcpServers = settings.mcpServers || {};
+  settings.mcpServers['cloudstream-knowledge'] = {
     command: 'npx',
     args: ['@cloudstream/knowledge-mcp-client'],
     env: {
@@ -328,8 +330,17 @@ async function configureMcpServer(licenseKey) {
     }
   };
 
-  await fs.writeFile(mcpConfigPath, JSON.stringify(existingConfig, null, 2));
-  logSuccess('MCP server configured');
+  await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+  logSuccess('MCP server configured in settings.json');
+
+  // Clean up orphaned mcp.json if it exists (from previous installs)
+  const orphanedMcpPath = path.join(CONFIG.claudeDir, 'mcp.json');
+  try {
+    await fs.unlink(orphanedMcpPath);
+    logSuccess('Cleaned up orphaned mcp.json');
+  } catch {
+    // File doesn't exist, nothing to clean up
+  }
 }
 
 /**

package/commands/INDEX.md

@@ -0,0 +1,171 @@
+# Commands Index
+
+Central reference for all 36 slash commands available in CloudStream Claude Tools.
+
+## Quick Reference
+
+| Command | Description | Agent |
+|---------|-------------|-------|
+| `/diagnose` | Deep diagnostic troubleshooting | - |
+| `/eval` | Eval-driven development workflow | - |
+| `/evolve` | Cluster instincts into commands/skills/agents | - |
+| `/health-check` | System health verification | - |
+| `/instinct-export` | Export instincts for sharing | - |
+| `/instinct-import` | Import instincts from teammates | - |
+| `/instinct-status` | View learned instincts with confidence | - |
+| `/onboard` | Interactive setup wizard | - |
+| `/skill-create` | Generate SKILL.md from git history | - |
+| `/team-admin` | Team administration tools | - |
+| `/build-fix` | Fix TypeScript and build errors | build-error-resolver |
+| `/checkpoint` | Create/verify workflow checkpoint | - |
+| `/client-switch` | Switch to client context | - |
+| `/code-review` | Security and quality review | code-reviewer |
+| `/compliance-check` | Run compliance audit | compliance-auditor |
+| `/create-branch` | Create properly-named git branch | - |
+| `/deluge` | Generate/fix Deluge scripts | deluge-reviewer |
+| `/e2e` | Generate and run E2E tests | e2e-runner |
+| `/handoff` | Generate client handoff docs | - |
+| `/learn` | Extract reusable patterns | - |
+| `/orchestrate` | Sequential agent workflow | planner, architect, etc. |
+| `/plan` | Create implementation plan | planner |
+| `/pr-ready` | Pre-PR validation checklist | - |
+| `/quarterly-review` | Review skill effectiveness | - |
+| `/refactor-clean` | Remove dead code safely | refactor-cleaner |
+| `/setup-pm` | Configure package manager | - |
+| `/skill-submit` | Submit skill to team repo | - |
+| `/skill-sync` | Pull shared skills from repo | - |
+| `/tdd` | Test-driven development workflow | tdd-guide |
+| `/test-coverage` | Analyze and improve coverage | - |
+| `/tutorial` | Interactive system tutorial | - |
+| `/update-codemaps` | Update architecture docs | doc-updater |
+| `/update-docs` | Sync documentation | doc-updater |
+| `/verify` | Run comprehensive verification | - |
+| `/verify-setup` | Verify plugin setup and configuration | - |
+| `/zoho-scaffold` | Scaffold Zoho components | creator-architect |
+
+## Commands by Category
+
+### Development Workflow
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/plan](./plan.md) | Create implementation plan | Before starting any feature |
+| [/tdd](./tdd.md) | Test-driven development | When implementing features |
+| [/build-fix](./build-fix.md) | Fix build errors | When build fails |
+| [/code-review](./code-review.md) | Quality and security review | Before committing |
+| [/verify](./verify.md) | Comprehensive validation | Before PR |
+| [/pr-ready](./pr-ready.md) | Pre-PR checklist | Before creating PR |
+| [/create-branch](./create-branch.md) | Create named branch | Starting new work |
+
+### Testing
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/tdd](./tdd.md) | TDD workflow enforcement | Writing new features |
+| [/test-coverage](./test-coverage.md) | Coverage analysis | Improving test coverage |
+| [/e2e](./e2e.md) | End-to-end tests | Testing user journeys |
+
+### Zoho Platform
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/zoho-scaffold](./zoho-scaffold.md) | Scaffold components | Creating new Zoho apps |
+| [/deluge](./deluge.md) | Generate Deluge scripts | Zoho scripting |
+
+### Compliance & Quality
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/compliance-check](./compliance-check.md) | Compliance audit | HIPAA/SOC2/PCI-DSS |
+| [/code-review](./code-review.md) | Security review | Before commits |
+
+### Knowledge Management
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/learn](./learn.md) | Extract patterns | After solving problems |
+| [/skill-sync](./skill-sync.md) | Pull shared skills | Stay updated |
+| [/skill-submit](./skill-submit.md) | Submit skills | Share discoveries |
+| [/quarterly-review](./quarterly-review.md) | Review effectiveness | Every quarter |
+
+### Continuous Learning (v2)
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/skill-create](./skill-create.md) | Generate SKILL.md from git history | Capture project patterns |
+| [/instinct-status](./instinct-status.md) | View learned instincts | Review what Claude learned |
+| [/instinct-export](./instinct-export.md) | Export instincts for sharing | Team knowledge transfer |
+| [/instinct-import](./instinct-import.md) | Import instincts | Onboarding, new machine |
+| [/evolve](./evolve.md) | Cluster instincts into structures | Auto-generate commands/skills |
+| [/eval](./eval.md) | Eval-driven development | Systematic quality tracking |
+
+### Client Management
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/client-switch](./client-switch.md) | Switch client context | Changing projects |
+| [/handoff](./handoff.md) | Generate handoff docs | Project completion |
+
+### Documentation
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/update-codemaps](./update-codemaps.md) | Update architecture docs | After refactoring |
+| [/update-docs](./update-docs.md) | Sync documentation | After changes |
+
+### System & Administration
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/health-check](./health-check.md) | System health verification | Verify setup is working |
+| [/diagnose](./diagnose.md) | Deep diagnostic troubleshooting | When something isn't working |
+| [/onboard](./onboard.md) | Interactive setup wizard | First-time setup |
+| [/verify-setup](./verify-setup.md) | Verify plugin configuration | After setup or changes |
+| [/team-admin](./team-admin.md) | Team administration tools | Team leads managing forks |
+
+### Utilities
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| [/checkpoint](./checkpoint.md) | Create/verify checkpoints | Before risky changes |
+| [/setup-pm](./setup-pm.md) | Configure package manager | Initial setup |
+| [/tutorial](./tutorial.md) | Interactive tutorial | Learning the system |
+| [/orchestrate](./orchestrate.md) | Chain agent workflow | Complex tasks |
+| [/refactor-clean](./refactor-clean.md) | Remove dead code | Code cleanup |
+
+## Command-Agent Relationships
+
+Commands that invoke specialized agents:
+
+| Command | Agent | Model | Purpose |
+|---------|-------|-------|---------|
+| `/build-fix` | build-error-resolver | sonnet | Fast error fixing |
+| `/code-review` | code-reviewer | sonnet | Quality review |
+| `/compliance-check` | compliance-auditor | sonnet | Compliance audit |
+| `/deluge` | deluge-reviewer | sonnet | Deluge validation |
+| `/e2e` | e2e-runner | sonnet | E2E testing |
+| `/orchestrate` | planner, architect, tdd-guide, code-reviewer | opus/sonnet | Full workflow |
+| `/plan` | planner | opus | Planning |
+| `/refactor-clean` | refactor-cleaner | sonnet | Dead code removal |
+| `/tdd` | tdd-guide | sonnet | TDD workflow |
+| `/update-codemaps` | doc-updater | sonnet | Doc updates |
+| `/update-docs` | doc-updater | sonnet | Doc sync |
+
+## Standard Workflow
+
+Recommended command sequence for feature development:
+
+```
+1. /plan [feature]         # Design before coding
+2. /tdd [component]        # Tests first
+3. /code-review            # Quality check
+4. /verify                 # Validation
+5. /pr-ready               # Final checklist
+6. /learn                  # Capture patterns
+```
+
+## See Also
+
+- [Agents Index](../agents/INDEX.md)
+- [Skills Index](../skills/INDEX.md)
+- [Rules Index](../rules/INDEX.md)

package/commands/build-fix.md

@@ -0,0 +1,44 @@
+---
+name: build-fix
+description: Incrementally fix TypeScript and build errors. Runs build, parses errors, and fixes them one by one with minimal diffs.
+---
+
+# Build and Fix
+
+Incrementally fix TypeScript and build errors:
+
+1. Run build: npm run build or pnpm build
+
+2. Parse error output:
+   - Group by file
+   - Sort by severity
+
+3. For each error:
+   - Show error context (5 lines before/after)
+   - Explain the issue
+   - Propose fix
+   - Apply fix
+   - Re-run build
+   - Verify error resolved
+
+4. Stop if:
+   - Fix introduces new errors
+   - Same error persists after 3 attempts
+   - User requests pause
+
+5. Show summary:
+   - Errors fixed
+   - Errors remaining
+   - New errors introduced
+
+Fix one error at a time for safety!
+
+---
+
+## Related
+
+- **Agent:** [build-error-resolver](../agents/build-error-resolver.md) - The specialized agent that executes this command
+- **Commands:**
+  - [/verify](./verify.md) - Run after fixing errors to validate the build
+  - [/tdd](./tdd.md) - Prevent future errors with test-driven development
+- **Skills:** [coding-standards](../skills/coding-standards/SKILL.md) - TypeScript best practices to avoid common errors

package/commands/checkpoint.md

@@ -0,0 +1,80 @@
+---
+name: checkpoint
+description: Create or verify a checkpoint in your workflow. Snapshots current state for safe rollback if needed.
+arguments: create|verify|list [name]
+---
+
+# Checkpoint Command
+
+Create or verify a checkpoint in your workflow.
+
+## Usage
+
+`/checkpoint [create|verify|list] [name]`
+
+## Create Checkpoint
+
+When creating a checkpoint:
+
+1. Run `/verify quick` to ensure current state is clean
+2. Create a git stash or commit with checkpoint name
+3. Log checkpoint to `.claude/checkpoints.log`:
+
+```bash
+echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
+```
+
+4. Report checkpoint created
+
+## Verify Checkpoint
+
+When verifying against a checkpoint:
+
+1. Read checkpoint from log
+2. Compare current state to checkpoint:
+   - Files added since checkpoint
+   - Files modified since checkpoint
+   - Test pass rate now vs then
+   - Coverage now vs then
+
+3. Report:
+```
+CHECKPOINT COMPARISON: $NAME
+============================
+Files changed: X
+Tests: +Y passed / -Z failed
+Coverage: +X% / -Y%
+Build: [PASS/FAIL]
+```
+
+## List Checkpoints
+
+Show all checkpoints with:
+- Name
+- Timestamp
+- Git SHA
+- Status (current, behind, ahead)
+
+## Workflow
+
+Typical checkpoint flow:
+
+```
+[Start] --> /checkpoint create "feature-start"
+   |
+[Implement] --> /checkpoint create "core-done"
+   |
+[Test] --> /checkpoint verify "core-done"
+   |
+[Refactor] --> /checkpoint create "refactor-done"
+   |
+[PR] --> /checkpoint verify "feature-start"
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `create <name>` - Create named checkpoint
+- `verify <name>` - Verify against named checkpoint
+- `list` - Show all checkpoints
+- `clear` - Remove old checkpoints (keeps last 5)

package/commands/client-switch.md

@@ -0,0 +1,114 @@
+---
+name: client-switch
+description: Switch to a specific client context. Loads client CLAUDE.md, environment variables, and displays recent activity.
+arguments: client-id
+---
+
+Switch to client **$ARGUMENTS** context:
+
+1. Load client configuration from `clients/$ARGUMENTS/.claude/CLAUDE.md`
+2. Set client-specific environment variables from `.env.client`
+3. Display recent commits for this client:
+   ```
+   git log --oneline -5 --grep="[$ARGUMENTS]"
+   ```
+4. Show active compliance mode and Zoho org
+5. Confirm client context is active
+
+## Expected Output
+```
+[ClientSwitch] Active client: $ARGUMENTS
+[ClientSwitch] Compliance mode: [hipaa|soc2|pci-dss|standard]
+[ClientSwitch] Zoho Org: [org-id]
+[ClientSwitch] Recent activity:
+  - [last 5 commits for this client]
+```
+
+## Verification
+- Confirm CLAUDE.md exists for client
+- Verify .env.client has required variables
+- Check no other client's credentials are loaded
+
+---
+
+## Usage Examples
+
+### Switch to Healthcare Client (HIPAA)
+```
+> /client-switch ACME
+
+╔═══════════════════════════════════════════════════════════════╗
+║                    Client Context: ACME                        ║
+╠═══════════════════════════════════════════════════════════════╣
+
+📋 Configuration
+   Compliance Mode:  HIPAA
+   Zoho Org ID:      org_acme_health_123
+   Project Path:     clients/ACME/
+
+🔒 Compliance Requirements
+   - ePHI field handling enabled
+   - BAA documentation required
+   - Audit log archival: 7 years
+   - Session timeout: 15 minutes
+
+📊 Recent Activity
+   abc1234 [ACME] feat(patient): Add medication tracking | Time: 2h 15m
+   def5678 [ACME] fix(forms): Correct PHI field encryption | Time: 45m
+   ghi9012 [ACME] docs: Update BAA appendix | Time: 30m
+
+⚠️  Reminders
+   - All PHI fields must use [PHI] prefix
+   - Run /compliance-check before any commit
+
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### Switch to Financial Client (PCI-DSS)
+```
+> /client-switch FINCO
+
+╔═══════════════════════════════════════════════════════════════╗
+║                    Client Context: FINCO                       ║
+╠═══════════════════════════════════════════════════════════════╣
+
+📋 Configuration
+   Compliance Mode:  PCI-DSS
+   Zoho Org ID:      org_finco_456
+   Project Path:     clients/FINCO/
+
+🔒 Compliance Requirements
+   - Use Zoho Checkout only for payments
+   - Tokenization required for card data
+   - SAQ-A compliance level
+
+📊 Recent Activity
+   jkl3456 [FINCO] feat(checkout): Add tokenization flow | Time: 3h
+   mno7890 [FINCO] test: Add PCI compliance tests | Time: 1h 30m
+
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### Error: Client Not Found
+```
+> /client-switch UNKNOWN
+
+❌ Client Not Found: UNKNOWN
+
+   Available clients:
+   ├── ACME (hipaa)
+   ├── FINCO (pci-dss)
+   ├── TECHCORP (soc2)
+   └── STARTUP (standard)
+
+   Create new client directory: clients/UNKNOWN/.claude/CLAUDE.md
+```
+
+---
+
+## Related
+
+- **Commands:**
+  - [/handoff](./handoff.md) - Generate handoff docs for current client
+  - [/compliance-check](./compliance-check.md) - Audit compliance for current client
+- **Skills:** [consultancy-workflows](../skills/consultancy-workflows/SKILL.md) - Client isolation patterns

package/commands/code-review.md

@@ -0,0 +1,45 @@
+---
+name: code-review
+description: Comprehensive security and quality review of uncommitted changes. Checks for vulnerabilities, code quality, Deluge constraints, and compliance.
+---
+
+# Code Review
+
+Comprehensive security and quality review of uncommitted changes:
+
+1. Get changed files: git diff --name-only HEAD
+
+2. For each changed file, check for:
+
+**Security Issues (CRITICAL):**
+- Hardcoded credentials, API keys, tokens
+- SQL injection vulnerabilities
+- XSS vulnerabilities  
+- Missing input validation
+- Insecure dependencies
+- Path traversal risks
+
+**Code Quality (HIGH):**
+- Functions > 50 lines
+- Files > 800 lines
+- Nesting depth > 4 levels
+- Missing error handling
+- console.log statements
+- TODO/FIXME comments
+- Missing JSDoc for public APIs
+
+**Best Practices (MEDIUM):**
+- Mutation patterns (use immutable instead)
+- Emoji usage in code/comments
+- Missing tests for new code
+- Accessibility issues (a11y)
+
+3. Generate report with:
+   - Severity: CRITICAL, HIGH, MEDIUM, LOW
+   - File location and line numbers
+   - Issue description
+   - Suggested fix
+
+4. Block commit if CRITICAL or HIGH issues found
+
+Never approve code with security vulnerabilities!

package/commands/compliance-check.md

@@ -0,0 +1,38 @@
+---
+name: compliance-check
+description: Run a compliance audit against the specified standard (HIPAA, SOC2, or PCI-DSS). Invokes the compliance-auditor agent and generates a findings report.
+arguments: standard
+---
+
+# /compliance-check [standard]
+
+Invoke the **compliance-auditor** agent to audit the project against the specified compliance standard.
+
+## Parameters
+- `standard` — One of: `hipaa`, `soc2`, `pci-dss`
+
+## Workflow
+1. Agent scans all project files for compliance gaps
+2. Checks Zoho configuration against standard requirements
+3. Verifies audit logging implementation
+4. Checks credential handling
+5. Generates findings report with severity levels
+
+## Report Format
+Findings are categorized by severity:
+- **Critical** — Must fix immediately (blocks deployment)
+- **High** — Fix within sprint
+- **Medium** — Fix within 30 days
+- **Low** — Best practice recommendations
+
+## When to Use
+- Before deploying to production
+- After major feature additions
+- During client onboarding (initial audit)
+- Periodic compliance verification
+
+## Integration
+- Use `/client-switch` first to load client context
+- Use `/plan` for remediation of findings
+- Use `/tdd` to implement fixes with tests
+- Re-run `/compliance-check` to verify remediation

package/commands/create-branch.md

@@ -0,0 +1,91 @@
+---
+name: create-branch
+description: Create a properly-named git branch following CloudStream conventions. Validates and formats branch names automatically.
+---
+
+# /create-branch <type> "<description>"
+
+Create a new git branch with proper naming conventions.
+
+## Parameters
+
+- `type` — Branch type: feature, fix, hotfix, docs, chore
+- `description` — Human-readable description (will be converted to kebab-case)
+
+## Branch Types
+
+| Type | Description | Requires Client |
+|------|-------------|-----------------|
+| `feature` | New functionality | Yes |
+| `fix` | Bug fix | Yes |
+| `hotfix` | Critical production fix | Yes |
+| `docs` | Documentation only | No |
+| `chore` | Maintenance task | No |
+
+## Behavior
+
+1. Reads CLIENT-ID from CLAUDE.md (default: CSS)
+2. Converts description to kebab-case
+3. Creates branch: `<type>/<CLIENT>/<kebab-description>`
+4. Switches to new branch
+5. Shows workflow checklist reminder
+
+## Examples
+
+```bash
+/create-branch feature "patient dashboard widgets"
+# Creates: feature/CSS/patient-dashboard-widgets
+
+/create-branch fix "login timeout bug"
+# Creates: fix/CSS/login-timeout-bug
+
+/create-branch docs "update API documentation"
+# Creates: docs/update-api-documentation
+
+/create-branch chore "update dependencies"
+# Creates: chore/update-dependencies
+```
+
+## Naming Convention
+
+**Format:** `<type>/<CLIENT>/<kebab-case-description>`
+
+**Valid examples:**
+- `feature/CSS/add-user-auth`
+- `fix/ACME/bug-123-fix`
+- `hotfix/CSS/critical-patch`
+- `docs/update-readme`
+- `chore/cleanup-deps`
+
+**Invalid examples:**
+- `feature/add-user-auth` (missing client)
+- `Feature/CSS/something` (uppercase type)
+- `feature/css/something` (lowercase client)
+- `feature/CSS/Some_Feature` (underscores)
+
+## After Creating Branch
+
+Follow the workflow:
+
+1. **Plan** - Use `/plan` for non-trivial features
+2. **TDD** - Use `/tdd` to write tests first
+3. **Implement** - Write minimal code to pass tests
+4. **Review** - Use `/code-review` on changes
+5. **Verify** - Use `/verify` before committing
+6. **Commit** - Follow commit conventions
+7. **PR** - Use `/pr-ready` before creating PR
+
+## Validation
+
+Branch names are validated by `scripts/branch-name-validator.js`.
+
+To validate an existing branch:
+```bash
+node scripts/branch-name-validator.js --current
+```
+
+## Integration
+
+- Pairs with `/pr-ready` for PR preparation
+- Uses `rules/tdd-enforcement.md` workflow
+- Follows `rules/git-workflow.md` conventions