@cloudstreamsoftware/claude-tools 1.2.2 → 1.2.4

package/commands/test-coverage.md

@@ -0,0 +1,43 @@
+---
+name: test-coverage
+description: Analyze test coverage and generate missing tests. Targets 80%+ coverage for JS/TS code with prioritized test generation.
+---
+
+# Test Coverage
+
+Analyze test coverage and generate missing tests:
+
+1. Run tests with coverage: npm test --coverage or pnpm test --coverage
+
+2. Analyze coverage report (coverage/coverage-summary.json)
+
+3. Identify files below 80% coverage threshold
+
+4. For each under-covered file:
+   - Analyze untested code paths
+   - Generate unit tests for functions
+   - Generate integration tests for APIs
+   - Generate E2E tests for critical flows
+
+5. Verify new tests pass
+
+6. Show before/after coverage metrics
+
+7. Ensure project reaches 80%+ overall coverage
+
+Focus on:
+- Happy path scenarios
+- Error handling
+- Edge cases (null, undefined, empty)
+- Boundary conditions
+
+---
+
+## Related
+
+- **Agent:** [tdd-guide](../agents/tdd-guide.md) - The specialized agent that executes this command
+- **Commands:**
+  - [/tdd](./tdd.md) - Use for test-first development on new code
+  - [/e2e](./e2e.md) - Generate end-to-end tests for critical flows
+  - [/verify](./verify.md) - Validate tests pass before committing
+- **Skills:** [tdd-workflow](../skills/tdd-workflow/SKILL.md) - Testing patterns and coverage strategies

package/commands/tutorial.md

@@ -0,0 +1,100 @@
+---
+name: tutorial
+description: Interactive tutorial that guides users through the CloudStream Claude Tools system with hands-on exercises and progressive learning.
+---
+
+# Tutorial Command
+
+Start the interactive tutorial to learn the CloudStream Claude Tools system.
+
+## Instructions
+
+When user runs `/tutorial`, guide them through progressive lessons:
+
+### Starting the Tutorial
+
+If no argument provided, start from Lesson 0 or resume from last completed lesson.
+
+### Lesson Structure
+
+The tutorial has 15 lessons (0-14):
+
+| # | Lesson | Topics |
+|---|--------|--------|
+| 0 | Philosophy & Workflow | Daily lifecycle, "aha moment", training mode philosophy |
+| 1 | Core Concepts | Mental model, architecture, Golden Standard intro |
+| 2 | Training Mode | Intent detection, workflow suggestions |
+| 3 | Essential Commands | Top 6 commands: /verify, /plan, /tdd, /code-review, /checkpoint, /health-check |
+| 4 | Workflow Patterns | plan→tdd→review→verify flows |
+| 5 | Compliance | HIPAA, SOC2, PCI-DSS modes |
+| 6 | Zoho Development | Creator, Catalyst, Deluge integration |
+| 7 | Hooks System | 6 lifecycle events, blocking vs. warning hooks |
+| 8 | MCP Servers | All 12 MCPs across 3 tiers |
+| 9 | Client Management | /client-switch, /handoff, isolation |
+| 10 | Testing & E2E | /e2e, /build-fix, /test-coverage, /eval |
+| 11 | Skills Deep Dive | All 16 skills, agent relationships |
+| 12 | Rules System | 11 rules, loading priority, frontmatter |
+| 13 | Golden Standard Graduation | Quality bar, verification checklist |
+| 14 | Fork Setup & Sync | Staying updated, sync tooling |
+
+### For Each Lesson
+
+1. Read the lesson file from `skills/tutorial/lessons/XX-name.md`
+2. Present the **Concept** section clearly
+3. Guide user through the **Exercise** with specific instructions
+4. Help verify completion with the **Verification** checklist
+5. Offer to proceed to next lesson or take a break
+
+### Lesson Flow
+
+Present each lesson section in order:
+- **Concept**: What it is and why it matters (2-3 paragraphs)
+- **Exercise**: Hands-on command to run with expected output
+- **Verification**: Checklist to confirm understanding
+
+After each lesson, ask: "Ready for the next lesson, or would you like to practice more?"
+
+## Arguments
+
+$ARGUMENTS can be:
+- (none) - Start from beginning or resume
+- `0-14` - Jump to specific lesson number
+- `status` - Show progress through lessons
+- `reset` - Start over from Lesson 0
+
+## Examples
+
+```
+/tutorial           # Start or resume
+/tutorial 3         # Jump to Lesson 3: Essential Commands
+/tutorial status    # Show progress
+/tutorial reset     # Start over
+```
+
+## Progress Display
+
+Show progress at start of each session:
+```
+Tutorial Progress: [=====>    ] 5/15 lessons complete
+Last: Lesson 5 - Compliance
+Next: Lesson 6 - Zoho Development
+```
+
+## Lesson Files Location
+
+Read lessons from: `skills/tutorial/lessons/`
+- 00-philosophy-and-workflow.md
+- 01-basics.md
+- 02-training.md
+- 03-commands.md
+- 04-workflows.md
+- 05-compliance.md
+- 06-zoho.md
+- 07-hooks-system.md
+- 08-mcp-servers.md
+- 09-client-management.md
+- 10-testing-e2e.md
+- 11-skills-deep-dive.md
+- 12-rules-system.md
+- 13-golden-standard-graduation.md
+- 14-fork-setup-and-sync.md

package/commands/update-codemaps.md

@@ -0,0 +1,57 @@
+---
+name: update-codemaps
+description: Analyze codebase structure and update architecture documentation. Scans imports, exports, and dependencies to generate codemaps.
+---
+
+# Update Codemaps
+
+Analyze the codebase structure and **generate** architecture documentation. The `docs/CODEMAPS/` directory is **created** by this command - it does not need to exist beforehand.
+
+## Workflow
+
+1. Scan all source files for imports, exports, and dependencies
+2. **Generate** token-lean codemaps in `docs/CODEMAPS/`:
+   - `architecture.md` - Overall architecture
+   - `backend.md` - Backend structure
+   - `frontend.md` - Frontend structure
+   - `data.md` - Data models and schemas
+
+3. Calculate diff percentage from previous version
+4. If changes > 30%, request user approval before updating
+5. Add freshness timestamp to each codemap
+6. Save reports to `.reports/codemap-diff.txt`
+
+## Note
+
+The `docs/CODEMAPS/` directory and its contents are **generated outputs** from analyzing the source code. If the directory doesn't exist, it will be created on first run.
+
+Use TypeScript/Node.js for analysis. Focus on high-level structure, not implementation details.
+
+---
+
+## Example Output
+
+```
+CODEMAP UPDATE: 2026-01-25
+
+Files scanned: 147
+Dependencies analyzed: 42
+
+Generated:
+  ✓ docs/CODEMAPS/architecture.md (12% changed)
+  ✓ docs/CODEMAPS/backend.md (8% changed)
+  ✓ docs/CODEMAPS/frontend.md (3% changed)
+  ✓ docs/CODEMAPS/data.md (0% changed)
+
+Diff saved to: .reports/codemap-diff.txt
+```
+
+---
+
+## Related
+
+- **Agent:** [doc-updater](../agents/doc-updater.md) - The specialized agent that executes this command
+- **Commands:**
+  - [/update-docs](./update-docs.md) - Update documentation from source files
+  - [/handoff](./handoff.md) - Generate client handoff documentation
+- **Skills:** [consultancy-workflows](../skills/consultancy-workflows/SKILL.md) - Documentation standards for handoff-ready work

package/commands/update-docs.md

@@ -0,0 +1,51 @@
+---
+name: update-docs
+description: Sync documentation from source-of-truth. Reads package.json, source files, and generates up-to-date documentation.
+---
+
+# Update Documentation
+
+Sync documentation from source-of-truth. This command **generates** output files - they do not need to exist beforehand.
+
+## Workflow
+
+1. Read package.json scripts section
+   - Generate scripts reference table
+   - Include descriptions from comments
+
+2. Read .env.example (if exists)
+   - Extract all environment variables
+   - Document purpose and format
+
+3. **Generate** docs/CONTRIB.md with:
+   - Development workflow
+   - Available scripts
+   - Environment setup
+   - Testing procedures
+
+4. **Generate** docs/RUNBOOK.md with:
+   - Deployment procedures
+   - Monitoring and alerts
+   - Common issues and fixes
+   - Rollback procedures
+
+5. Identify obsolete documentation:
+   - Find docs not modified in 90+ days
+   - List for manual review
+
+6. Show diff summary
+
+## Note
+
+The output files (`docs/CONTRIB.md`, `docs/RUNBOOK.md`) are **generated** by this command. If they don't exist, they will be created. The source of truth is `package.json` and `.env.example` (when present).
+
+---
+
+## Related
+
+- **Agent:** [doc-updater](../agents/doc-updater.md) - The specialized agent that executes this command
+- **Commands:**
+  - [/update-codemaps](./update-codemaps.md) - Update architecture documentation
+  - [/handoff](./handoff.md) - Generate client handoff documentation
+  - [/verify](./verify.md) - Validate documentation accuracy
+- **Skills:** [consultancy-workflows](../skills/consultancy-workflows/SKILL.md) - Documentation standards for client work

package/commands/verify-setup.md

@@ -0,0 +1,98 @@
+---
+name: verify-setup
+description: Verify CloudStream Claude Code plugin setup and configuration
+usage: /verify-setup [--quick] [--json] [--module=<name>]
+self-contained: true
+---
+
+# Verify Setup Command
+
+Run comprehensive verification of the CloudStream Claude Code plugin installation.
+
+## Usage
+
+```
+/verify-setup              # Full verification
+/verify-setup --quick      # Quick mode (critical checks only)
+/verify-setup --json       # JSON output for CI/CD
+/verify-setup --module=X   # Single module (environment, persistence, plugin, config, hooks, skills, agents)
+```
+
+## What It Checks
+
+### Environment
+- Node.js version (>= 18 required)
+- Git installation
+- Package manager availability
+- Git user configuration
+
+### Persistence
+- ~/.claude directory exists and is writable
+- sessions/, memory/, plans/ directories
+
+### Plugin
+- plugin.json exists and is valid
+- commands/, skills/, hooks/ directories configured
+- agents/ directory (optional)
+
+### Config
+- versions.json (skills/agents registry)
+- quality-gates.json (compliance gates)
+- No .env files in repository
+
+### Hooks
+- hooks.json configuration
+- Hook scripts exist and have valid syntax
+- Global settings.json has hooks configured
+
+### Skills (Dynamic)
+- All registered skills exist on disk
+- All existing skills are registered in versions.json
+- Each skill has SKILL.md
+
+### Agents (Dynamic)
+- All registered agents exist on disk
+- All existing agents are registered in versions.json
+- Each agent has valid frontmatter (name, model)
+
+## Exit Codes
+
+- **0**: All checks passed
+- **1**: Warnings only (non-critical issues)
+- **2**: Critical failures
+
+## Example Output
+
+```
+╔═══════════════════════════════════════════════╗
+║    CloudStream Claude Code - Setup Verifier   ║
+╚═══════════════════════════════════════════════╝
+
+Environment:
+  Node.js                    [OK] v22.0.0
+  Git                        [OK] v2.43.0
+  Package Manager            [OK] npm
+
+Plugin:
+  plugin.json valid          [OK] cloudstream-claude-code
+  commands/                  [OK] 35 files
+  skills/                    [OK] 14 dirs
+
+━━━━━━━━━━━━━━━━ ISSUES FOUND ━━━━━━━━━━━━━━━━
+
+[WARN] Git user.email not configured
+       Fix: git config --global user.email "you@example.com"
+
+╔═══════════════════════════════════════════════╗
+║  Result: 23/24 passed, 1 warning, 0 critical  ║
+╚═══════════════════════════════════════════════╝
+```
+
+## Implementation
+
+This command runs `node scripts/verify-setup.js` which orchestrates modular verifiers.
+
+## Related Commands
+
+- `/health-check` - Quick system health check
+- `/diagnose` - Deep diagnostic troubleshooting

package/commands/verify.md

@@ -0,0 +1,75 @@
+---
+name: verify
+description: Run comprehensive verification on current codebase state. Checks build, tests, linting, and type safety in sequence.
+---
+
+# Verification Command
+
+Run comprehensive verification on current codebase state.
+
+## Instructions
+
+Execute verification in this exact order:
+
+1. **Build Check**
+   - Run the build command for this project
+   - If it fails, report errors and STOP
+
+2. **Type Check**
+   - Run TypeScript/type checker
+   - Report all errors with file:line
+
+3. **Lint Check**
+   - Run linter
+   - Report warnings and errors
+
+4. **Test Suite**
+   - Run all tests
+   - Report pass/fail count
+   - Report coverage percentage
+
+5. **Console.log Audit**
+   - Search for console.log in source files
+   - Report locations
+
+6. **Git Status**
+   - Show uncommitted changes
+   - Show files modified since last commit
+
+## Output
+
+Produce a concise verification report:
+
+```
+VERIFICATION: [PASS/FAIL]
+
+Build:    [OK/FAIL]
+Types:    [OK/X errors]
+Lint:     [OK/X issues]
+Tests:    [X/Y passed, Z% coverage]
+Secrets:  [OK/X found]
+Logs:     [OK/X console.logs]
+
+Ready for PR: [YES/NO]
+```
+
+If any critical issues, list them with fix suggestions.
+
+## Arguments
+
+$ARGUMENTS can be:
+- `quick` - Only build + types
+- `full` - All checks (default)
+- `pre-commit` - Checks relevant for commits
+- `pre-pr` - Full checks plus security scan
+
+---
+
+## Related
+
+- **Commands:**
+  - [/tdd](./tdd.md) - Test-driven development workflow
+  - [/code-review](./code-review.md) - Code quality and security review
+  - [/build-fix](./build-fix.md) - Fix build and TypeScript errors
+  - [/pr-ready](./pr-ready.md) - Pre-PR validation checklist
+- **Scripts:** `npm run verify`, `npm run preflight`

package/commands/zoho-scaffold.md

@@ -0,0 +1,159 @@
+---
+name: zoho-scaffold
+description: Scaffold a new Zoho component (Creator app, Catalyst function, or Widget). Generates boilerplate with compliance fields and best practices built in.
+arguments: type name
+---
+
+Scaffold a new Zoho component. Type: first word of $ARGUMENTS, Name: remaining words.
+
+## Component Types
+
+### creator
+Generate Creator application template:
+- Main form with standard fields (Created_By, Modified_By, timestamps)
+- List report for the main form
+- Basic workflow (on create, on edit)
+- If compliance mode is HIPAA: Add audit logging fields
+- If compliance mode is SOC2: Add change tracking fields
+
+### catalyst
+Generate Catalyst function template:
+- Basic I/O function with proper structure
+- context.close() in finally block (MANDATORY)
+- Error handling with structured response
+- package.json with required dependencies
+- catalyst.json configuration
+- Health check endpoint (for AppSail)
+
+### widget
+Generate React widget template:
+- package.json with build scripts
+- src/App.jsx with ZOHO.CREATOR.init()
+- ZOHO SDK mock for testing
+- Vite/webpack config for widget bundle
+- index.html with Zoho SDK script tag
+- Basic test file with SDK mock
+
+## Output Structure
+Create files in the appropriate directory within the project.
+Display created files list when complete.
+
+---
+
+## Usage Examples
+
+### Scaffold Creator App
+```
+> /zoho-scaffold creator PatientIntake
+
+╔═══════════════════════════════════════════════════════════════╗
+║                Creator App: PatientIntake                      ║
+╠═══════════════════════════════════════════════════════════════╣
+
+📁 Generated Files:
+   creator/PatientIntake/
+   ├── forms/
+   │   └── PatientIntake.json          # Main form definition
+   ├── reports/
+   │   └── PatientIntake_List.json     # List report
+   ├── workflows/
+   │   ├── onCreate.ds                  # Create workflow
+   │   └── onEdit.ds                    # Edit workflow
+   └── README.md                        # App documentation
+
+📋 Form Fields (Standard):
+   - Created_By (auto)
+   - Created_Time (auto)
+   - Modified_By (auto)
+   - Modified_Time (auto)
+   - Status (single select)
+
+🔒 HIPAA Mode Detected - Added:
+   - [PHI] fields marked
+   - AuditLog form created
+   - Encryption enabled for SSN
+
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### Scaffold Catalyst Function
+```
+> /zoho-scaffold catalyst sendNotifications
+
+╔═══════════════════════════════════════════════════════════════╗
+║             Catalyst Function: sendNotifications               ║
+╠═══════════════════════════════════════════════════════════════╣
+
+📁 Generated Files:
+   functions/sendNotifications/
+   ├── index.js                         # Main handler
+   ├── package.json                     # Dependencies
+   ├── catalyst.json                    # Catalyst config
+   └── test/
+       └── index.test.js                # Unit tests
+
+📋 Template Includes:
+   ✓ context.close() in finally block (MANDATORY)
+   ✓ Structured error response
+   ✓ 30-second timeout handling
+   ✓ Health check endpoint
+
+🔧 Next Steps:
+   1. cd functions/sendNotifications
+   2. npm install
+   3. Edit index.js with your logic
+   4. npm test
+   5. catalyst deploy
+
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### Scaffold Widget
+```
+> /zoho-scaffold widget PatientDashboard
+
+╔═══════════════════════════════════════════════════════════════╗
+║                Widget: PatientDashboard                        ║
+╠═══════════════════════════════════════════════════════════════╣
+
+📁 Generated Files:
+   widgets/PatientDashboard/
+   ├── src/
+   │   ├── App.jsx                      # Main component
+   │   ├── index.jsx                    # Entry point
+   │   └── zohoInit.js                  # SDK initialization
+   ├── public/
+   │   └── index.html                   # HTML with SDK script
+   ├── test/
+   │   ├── App.test.jsx                 # Component tests
+   │   └── mocks/zohoSdk.js             # SDK mock for testing
+   ├── package.json                     # Build scripts
+   ├── vite.config.js                   # Bundle config
+   └── README.md                        # Widget documentation
+
+⚠️  Widget Constraints:
+   - Widgets do NOT work on published pages
+   - Use in form headers, footers, or tabs only
+   - Maximum 50 widgets per Zoho One account
+
+🔧 Next Steps:
+   1. cd widgets/PatientDashboard
+   2. npm install
+   3. npm run dev (local development)
+   4. npm run build (production bundle)
+   5. Upload to Creator widget settings
+
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Related
+
+- **Agents:**
+  - [creator-architect](../agents/creator-architect.md) - Design Creator app architecture first
+  - [catalyst-deployer](../agents/catalyst-deployer.md) - Deploy Catalyst functions
+- **Commands:**
+  - [/deluge](./deluge.md) - Generate Deluge scripts for workflows
+  - [/tdd](./tdd.md) - Write tests for generated code
+- **Skills:** [zoho-patterns](../skills/zoho-patterns/SKILL.md) - Zoho platform patterns and constraints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudstreamsoftware/claude-tools",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "CloudStream Claude Code productivity tools - hooks, skills, agents, and knowledge server integration",
   "main": "dist/index.js",
   "bin": {
@@ -40,6 +40,7 @@
     "hooks/",
     "skills/",
     "agents/",
+    "commands/",
     "README.md"
   ],
   "dependencies": {