@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/README.md

@@ -1,74 +1,189 @@
-# @cloudstream/claude-tools
+# @cloudstreamsoftware/claude-tools
 
-CloudStream Software's Claude Code productivity tools for Zoho development.
+[![npm version](https://img.shields.io/npm/v/@cloudstreamsoftware/claude-tools.svg)](https://www.npmjs.com/package/@cloudstreamsoftware/claude-tools)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/license-proprietary-red.svg)](LICENSE)
+
+Enterprise-grade Claude Code productivity tools for Zoho development with secure knowledge server integration.
 
 ## Features
 
-- **Prompt Routing**: Intelligent classification of your requests
-- **Quality Gates**: Automatic credential scanning and code validation
-- **Knowledge Server**: Access to CloudStream's Zoho/Deluge pattern library
-- **Compliance Support**: HIPAA, SOC2, PCI-DSS workflow guidance
+- **Knowledge Server** - MCP integration with CloudStream's Zoho/Deluge pattern library
+- **36 Slash Commands** - Development workflow, testing, compliance, and more
+- **15 Auto-Activated Skills** - Context-aware assistance for Zoho, GCP, compliance
+- **13 Specialized Agents** - From planning to deployment
+- **Compliance Support** - HIPAA, SOC2, PCI-DSS workflow guidance
+- **Quality Gates** - Automatic credential scanning and code validation
 
-## Installation
+## Quick Start
 
 ```bash
-npm install @cloudstream/claude-tools
+# Install the package
+npm install @cloudstreamsoftware/claude-tools
+
+# Run the setup wizard
 npx cloudstream-setup
 ```
 
-## Setup Wizard
-
 The setup wizard will:
+1. Validate your CloudStream license key
+2. Configure MCP connection to the Knowledge Server
+3. Install hooks, skills, and agents to `~/.claude/`
 
-1. **Detect installation type** - Internal (CloudStream employee) or Client
-2. **Validate license** - Verify your CloudStream license key
-3. **Configure MCP** - Connect to the CloudStream Knowledge Server
-4. **Install tools** - Set up hooks, skills, and agents in ~/.claude/
-
-## Usage
-
-After setup, start a new Claude Code session in any project:
+After setup, start Claude Code in any project:
 
 ```bash
 claude
 ```
 
-The CloudStream tools are now available globally.
-
-### Knowledge Server
-
-Ask about Zoho/Deluge patterns and the knowledge server will provide synthesized guidance:
-
+## Commands
+
+36 slash commands for every stage of development:
+
+| Command | Description |
+|---------|-------------|
+| `/plan` | Create implementation plan |
+| `/tdd` | Test-driven development workflow |
+| `/build-fix` | Fix TypeScript and build errors |
+| `/code-review` | Security and quality review |
+| `/verify` | Run comprehensive verification |
+| `/pr-ready` | Pre-PR validation checklist |
+| `/compliance-check` | Run compliance audit |
+| `/e2e` | Generate and run E2E tests |
+| `/test-coverage` | Analyze and improve coverage |
+| `/zoho-scaffold` | Scaffold Zoho components |
+| `/deluge` | Generate/fix Deluge scripts |
+| `/checkpoint` | Create workflow checkpoint |
+| `/handoff` | Generate client handoff docs |
+| `/diagnose` | Deep diagnostic troubleshooting |
+| `/health-check` | System health verification |
+| `/tutorial` | Interactive system tutorial |
+| `/learn` | Extract reusable patterns |
+| `/skill-sync` | Pull shared skills from repo |
+| `/skill-submit` | Submit skills to team repo |
+| `/instinct-status` | View learned instincts |
+| `/instinct-export` | Export instincts for sharing |
+| `/instinct-import` | Import instincts from teammates |
+| `/evolve` | Cluster instincts into commands/skills |
+| `/eval` | Eval-driven development workflow |
+| `/client-switch` | Switch to client context |
+| `/create-branch` | Create properly-named git branch |
+| `/refactor-clean` | Remove dead code safely |
+| `/update-codemaps` | Update architecture docs |
+| `/update-docs` | Sync documentation |
+| `/orchestrate` | Sequential agent workflow |
+| `/quarterly-review` | Review skill effectiveness |
+| `/skill-create` | Generate SKILL.md from git history |
+| `/onboard` | Interactive setup wizard |
+| `/verify-setup` | Verify plugin configuration |
+| `/team-admin` | Team administration tools |
+| `/setup-pm` | Configure package manager |
+
+> Full documentation: [Commands Reference](commands/INDEX.md)
+
+## Skills
+
+15 skills that auto-activate based on context:
+
+| Skill | Auto-Activates When |
+|-------|---------------------|
+| `zoho-patterns` | Working with Zoho Creator, Catalyst, Deluge |
+| `bigquery-patterns` | BigQuery queries, `.sql` files |
+| `gcp-data-engineering` | GCP/Dataflow/dbt tasks |
+| `compliance-patterns` | Compliance mode active (HIPAA/SOC2/PCI-DSS) |
+| `backend-patterns` | Backend file types (Node.js, APIs) |
+| `frontend-patterns` | Frontend file types (React, Next.js) |
+| `coding-standards` | All code files |
+| `security-review` | Auth, secrets, API code |
+| `tdd-workflow` | Feature development |
+| `consultancy-workflows` | Client context |
+| `cloudstream-project-template` | New project setup |
+| `continuous-learning` | Session end |
+| `continuous-learning-v2` | Session hooks |
+| `strategic-compact` | Long sessions |
+| `tutorial` | `/tutorial` command |
+
+> Full documentation: [Skills Reference](skills/INDEX.md)
+
+## Agents
+
+13 specialized agents for different tasks:
+
+| Agent | Triggered By | Purpose |
+|-------|--------------|---------|
+| `planner` | `/plan`, `/orchestrate` | Implementation planning |
+| `architect` | `/orchestrate` | System design decisions |
+| `creator-architect` | `/zoho-scaffold` | Zoho Creator app architecture |
+| `tdd-guide` | `/tdd`, `/test-coverage` | Test-driven development |
+| `code-reviewer` | `/code-review` | Code quality review |
+| `security-reviewer` | `/code-review` | Security vulnerability detection |
+| `compliance-auditor` | `/compliance-check` | HIPAA/SOC2/PCI-DSS audits |
+| `deluge-reviewer` | `/deluge` | Deluge script validation |
+| `build-error-resolver` | `/build-fix` | Build and TypeScript fixes |
+| `catalyst-deployer` | `/zoho-scaffold` | Catalyst deployment |
+| `e2e-runner` | `/e2e` | Playwright E2E testing |
+| `refactor-cleaner` | `/refactor-clean` | Dead code removal |
+| `doc-updater` | `/update-docs`, `/handoff` | Documentation sync |
+
+> Full documentation: [Agents Reference](agents/INDEX.md)
+
+## Knowledge Server
+
+The Knowledge Server provides access to CloudStream's curated Zoho/Deluge pattern library via MCP (Model Context Protocol).
+
+**Example queries:**
 ```
 "How do I create a workflow that syncs CRM to Books?"
 "What's the best practice for API calls in Deluge?"
 "How do I handle errors in scheduled functions?"
+"What are the Catalyst deployment limits?"
 ```
 
-### Available Commands
-
-- `/help` - Show available commands
-- `/diagnose` - Check system status
-- `/checkpoint` - Create a session checkpoint
-- `/handoff` - Generate session handoff notes
+The server returns synthesized guidance based on proven patterns - raw patterns never leave the server.
 
 ## Security
 
-- **No local caching** of proprietary knowledge data
-- **Synthesized responses only** - raw patterns never leave the server
-- **Short-lived tokens** - 15-minute OAuth 2.1 access tokens
-- **Audit trail** - all queries logged for compliance
+- **No local caching** - Proprietary knowledge data stays on the server
+- **Synthesized responses only** - Raw patterns never exposed
+- **Short-lived tokens** - 15-minute OAuth 2.1 access tokens with PKCE
+- **Audit trail** - All queries logged for compliance
+- **Credential scanning** - Pre-commit hooks block hardcoded secrets
+
+## Troubleshooting
+
+### License validation failed
+Verify your license key with your CloudStream administrator. Keys expire and may need renewal.
+
+### Knowledge Server connection issues
+```bash
+# Check system status
+claude
+/diagnose
+```
+
+### Setup wizard not completing
+Ensure you have Node.js 18+ and a valid internet connection for license validation.
+
+### Commands not available
+Run the setup wizard again:
+```bash
+npx cloudstream-setup
+```
 
 ## Requirements
 
 - Node.js 18.0.0 or higher
-- Claude Code CLI installed
+- Claude Code CLI installed (`npm install -g @anthropic-ai/claude-code`)
 - Valid CloudStream license key
 
 ## Support
 
-Contact your CloudStream administrator for license keys and support.
+Contact your CloudStream administrator for:
+- License keys and renewals
+- Access issues
+- Feature requests
+- Bug reports
 
 ## License
 
-UNLICENSED - CloudStream Software proprietary.
+Proprietary - CloudStream Software. All rights reserved.

package/agents/INDEX.md

@@ -0,0 +1,183 @@
+# Agent Index
+
+This directory contains 13 specialized agents for the CloudStream Claude Code configuration.
+
+---
+
+## Quick Reference
+
+| Agent | Model | Trigger Command | Purpose |
+|-------|-------|-----------------|---------|
+| [planner](planner.md) | Opus | `/plan`, `/orchestrate` | Implementation planning for complex features |
+| [architect](architect.md) | Opus | `/orchestrate` | System design, scalability, technical decisions |
+| [creator-architect](creator-architect.md) | Opus | `/zoho-scaffold` | Zoho Creator app architecture |
+| [security-reviewer](security-reviewer.md) | Opus | `/code-review` | Security vulnerability detection |
+| [compliance-auditor](compliance-auditor.md) | Opus | `/compliance-check` | HIPAA/SOC2/PCI-DSS audits |
+| [code-reviewer](code-reviewer.md) | Sonnet | `/code-review` | Code quality and maintainability |
+| [deluge-reviewer](deluge-reviewer.md) | Sonnet | `/deluge` | Deluge script validation |
+| [tdd-guide](tdd-guide.md) | Sonnet | `/tdd`, `/test-coverage` | Test-driven development |
+| [build-error-resolver](build-error-resolver.md) | Sonnet | `/build-fix` | Build and TypeScript error fixes |
+| [catalyst-deployer](catalyst-deployer.md) | Sonnet | `/zoho-scaffold` | Catalyst deployment |
+| [e2e-runner](e2e-runner.md) | Sonnet | `/e2e` | Playwright E2E testing |
+| [refactor-cleaner](refactor-cleaner.md) | Sonnet | `/refactor-clean` | Dead code removal |
+| [doc-updater](doc-updater.md) | Sonnet | `/update-docs`, `/update-codemaps`, `/handoff` | Documentation sync |
+
+---
+
+## Agents by Model
+
+### Opus (High-capability tasks)
+
+| Agent | Use Case |
+|-------|----------|
+| **planner** | Complex feature planning, multi-phase implementation |
+| **architect** | System design decisions, architectural reviews |
+| **creator-architect** | Zoho Creator/Catalyst application design |
+| **security-reviewer** | Security vulnerability analysis, OWASP Top 10 |
+| **compliance-auditor** | Regulatory compliance audits |
+
+### Sonnet (Standard tasks)
+
+| Agent | Use Case |
+|-------|----------|
+| **code-reviewer** | Code quality, best practices, maintainability |
+| **deluge-reviewer** | Deluge script validation, 5000-statement limit |
+| **tdd-guide** | Test-driven development, coverage enforcement |
+| **build-error-resolver** | Build fixes, TypeScript errors |
+| **catalyst-deployer** | Catalyst AppSail/Functions deployment |
+| **e2e-runner** | Playwright test generation and execution |
+| **refactor-cleaner** | Dead code removal with knip/depcheck |
+| **doc-updater** | Documentation generation, codemap updates |
+
+---
+
+## Agents by Domain
+
+### Development Workflow
+
+| Agent | Role in Workflow |
+|-------|------------------|
+| planner | START: Plan implementation before coding |
+| tdd-guide | Write tests first |
+| code-reviewer | Review code after writing |
+| build-error-resolver | Fix build errors |
+| refactor-cleaner | Clean up dead code |
+
+### Zoho Platform
+
+| Agent | Zoho Specialty |
+|-------|----------------|
+| creator-architect | Creator app architecture |
+| deluge-reviewer | Deluge script validation |
+| catalyst-deployer | Catalyst deployment |
+
+### Quality & Security
+
+| Agent | Focus Area |
+|-------|------------|
+| security-reviewer | OWASP Top 10, vulnerability detection |
+| compliance-auditor | HIPAA, SOC2, PCI-DSS |
+| code-reviewer | Code quality, maintainability |
+
+### Testing
+
+| Agent | Testing Type |
+|-------|--------------|
+| tdd-guide | Unit tests, integration tests |
+| e2e-runner | End-to-end tests (Playwright) |
+
+### Documentation
+
+| Agent | Documentation Type |
+|-------|-------------------|
+| doc-updater | READMEs, codemaps, handoffs |
+
+---
+
+## Agent Selection Guide
+
+### "Which agent should I use?"
+
+| Scenario | Agent |
+|----------|-------|
+| Planning a new feature | planner |
+| Designing system architecture | architect |
+| Building a Zoho Creator app | creator-architect |
+| Writing Deluge scripts | deluge-reviewer |
+| Deploying to Catalyst | catalyst-deployer |
+| Reviewing my code | code-reviewer |
+| Checking for security issues | security-reviewer |
+| Running compliance audit | compliance-auditor |
+| Writing tests first | tdd-guide |
+| Generating E2E tests | e2e-runner |
+| Fixing build errors | build-error-resolver |
+| Removing dead code | refactor-cleaner |
+| Updating documentation | doc-updater |
+
+---
+
+## Agent Orchestration
+
+Agents can be chained via `/orchestrate` for complex tasks:
+
+### Feature Implementation Chain
+```
+planner → tdd-guide → code-reviewer → security-reviewer
+```
+
+### Zoho Development Chain
+```
+creator-architect → deluge-reviewer → catalyst-deployer
+```
+
+### Quality Gate Chain
+```
+code-reviewer → security-reviewer → compliance-auditor
+```
+
+---
+
+## Tools Available to Agents
+
+| Agent | Tools |
+|-------|-------|
+| planner | Read, Grep, Glob |
+| architect | Read, Grep, Glob |
+| creator-architect | Read, Grep, Glob |
+| security-reviewer | Read, Bash, Grep, Glob |
+| compliance-auditor | Read, Grep, Glob |
+| code-reviewer | Read, Grep, Glob, Bash |
+| deluge-reviewer | Read, Grep, Glob |
+| tdd-guide | Read, Write, Edit, Bash, Grep |
+| build-error-resolver | Read, Write, Edit, Bash, Grep, Glob |
+| catalyst-deployer | Read, Bash, Grep |
+| e2e-runner | Read, Bash, Grep, Glob |
+| refactor-cleaner | Read, Write, Edit, Bash, Grep, Glob |
+| doc-updater | Read, Write, Edit, Bash, Grep, Glob |
+
+---
+
+## Adding New Agents
+
+To add a new agent:
+
+1. Create `agents/{agent-name}.md` with required frontmatter:
+   ```yaml
+   ---
+   name: agent-name
+   description: One-line description
+   version: 1.0.0
+   status: active
+   tools: Read, Grep, Glob
+   model: sonnet
+   ---
+   ```
+
+2. Add agent to command mapping in `/rules/agents.md`
+3. Create corresponding command in `/commands/` if needed
+4. Update this INDEX.md
+5. Update CLAUDE.md agent inventory
+6. Update README.md agent overview
+7. Run `npm test` to verify
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for full guidelines.

package/agents/architect.md

@@ -0,0 +1,247 @@
+---
+name: architect
+description: Software architecture specialist for system design, scalability, and technical decision-making. Use PROACTIVELY when planning new features, refactoring large systems, or making architectural decisions.
+version: 1.0.0
+status: active
+introduced: 1.0.0
+tools: Read, Grep, Glob
+model: opus
+---
+
+You are a senior software architect specializing in scalable, maintainable system design.
+
+## Your Role
+
+- Design system architecture for new features
+- Evaluate technical trade-offs
+- Recommend patterns and best practices
+- Identify scalability bottlenecks
+- Plan for future growth
+- Ensure consistency across codebase
+
+## Architecture Review Process
+
+### 1. Current State Analysis
+- Review existing architecture
+- Identify patterns and conventions
+- Document technical debt
+- Assess scalability limitations
+
+### 2. Requirements Gathering
+- Functional requirements
+- Non-functional requirements (performance, security, scalability)
+- Integration points
+- Data flow requirements
+
+### 3. Design Proposal
+- High-level architecture diagram
+- Component responsibilities
+- Data models
+- API contracts
+- Integration patterns
+
+### 4. Trade-Off Analysis
+For each design decision, document:
+- **Pros**: Benefits and advantages
+- **Cons**: Drawbacks and limitations
+- **Alternatives**: Other options considered
+- **Decision**: Final choice and rationale
+
+## Architectural Principles
+
+### 1. Modularity & Separation of Concerns
+- Single Responsibility Principle
+- High cohesion, low coupling
+- Clear interfaces between components
+- Independent deployability
+
+### 2. Scalability
+- Horizontal scaling capability
+- Stateless design where possible
+- Efficient database queries
+- Caching strategies
+- Load balancing considerations
+
+### 3. Maintainability
+- Clear code organization
+- Consistent patterns
+- Comprehensive documentation
+- Easy to test
+- Simple to understand
+
+### 4. Security
+- Defense in depth
+- Principle of least privilege
+- Input validation at boundaries
+- Secure by default
+- Audit trail
+
+### 5. Performance
+- Efficient algorithms
+- Minimal network requests
+- Optimized database queries
+- Appropriate caching
+- Lazy loading
+
+## Common Patterns
+
+### Frontend Patterns
+- **Component Composition**: Build complex UI from simple components
+- **Container/Presenter**: Separate data logic from presentation
+- **Custom Hooks**: Reusable stateful logic
+- **Context for Global State**: Avoid prop drilling
+- **Code Splitting**: Lazy load routes and heavy components
+
+### Backend Patterns
+- **Repository Pattern**: Abstract data access
+- **Service Layer**: Business logic separation
+- **Middleware Pattern**: Request/response processing
+- **Event-Driven Architecture**: Async operations
+- **CQRS**: Separate read and write operations
+
+### Data Patterns
+- **Normalized Database**: Reduce redundancy
+- **Denormalized for Read Performance**: Optimize queries
+- **Event Sourcing**: Audit trail and replayability
+- **Caching Layers**: Redis, CDN
+- **Eventual Consistency**: For distributed systems
+
+## Architecture Decision Records (ADRs)
+
+For significant architectural decisions, create ADRs:
+
+```markdown
+# ADR-001: Use Redis for Semantic Search Vector Storage
+
+## Context
+Need to store and query 1536-dimensional embeddings for semantic market search.
+
+## Decision
+Use Redis Stack with vector search capability.
+
+## Consequences
+
+### Positive
+- Fast vector similarity search (<10ms)
+- Built-in KNN algorithm
+- Simple deployment
+- Good performance up to 100K vectors
+
+### Negative
+- In-memory storage (expensive for large datasets)
+- Single point of failure without clustering
+- Limited to cosine similarity
+
+### Alternatives Considered
+- **PostgreSQL pgvector**: Slower, but persistent storage
+- **Pinecone**: Managed service, higher cost
+- **Weaviate**: More features, more complex setup
+
+## Status
+Accepted
+
+## Date
+2025-01-15
+```
+
+## System Design Checklist
+
+When designing a new system or feature:
+
+### Functional Requirements
+- [ ] User stories documented
+- [ ] API contracts defined
+- [ ] Data models specified
+- [ ] UI/UX flows mapped
+
+### Non-Functional Requirements
+- [ ] Performance targets defined (latency, throughput)
+- [ ] Scalability requirements specified
+- [ ] Security requirements identified
+- [ ] Availability targets set (uptime %)
+
+### Technical Design
+- [ ] Architecture diagram created
+- [ ] Component responsibilities defined
+- [ ] Data flow documented
+- [ ] Integration points identified
+- [ ] Error handling strategy defined
+- [ ] Testing strategy planned
+
+### Operations
+- [ ] Deployment strategy defined
+- [ ] Monitoring and alerting planned
+- [ ] Backup and recovery strategy
+- [ ] Rollback plan documented
+
+## Red Flags
+
+Watch for these architectural anti-patterns:
+- **Big Ball of Mud**: No clear structure
+- **Golden Hammer**: Using same solution for everything
+- **Premature Optimization**: Optimizing too early
+- **Not Invented Here**: Rejecting existing solutions
+- **Analysis Paralysis**: Over-planning, under-building
+- **Magic**: Unclear, undocumented behavior
+- **Tight Coupling**: Components too dependent
+- **God Object**: One class/component does everything
+
+## Project-Specific Architecture (CloudStream Software LLC)
+
+Architecture for Zoho consultancy + full-stack development:
+
+### Current Architecture
+- **Zoho Platform**: Creator (apps), CRM, Books, Analytics, Catalyst (serverless + hosting)
+- **Frontend**: React/Next.js widgets deployed to Zoho + standalone apps
+- **Backend**: Catalyst AppSail (Node.js/Express/Next.js), Catalyst Functions (serverless)
+- **Data Layer**: BigQuery (analytics), Zoho (operational data)
+- **Reporting**: Looker Studio + Zoho Analytics dashboards
+- **Infrastructure**: Google Cloud Platform (GCS, Dataflow, Cloud Functions)
+
+### Key Design Decisions
+1. **Zoho-First**: Use native Zoho capabilities before custom code
+2. **Catalyst for Custom Logic**: AppSail for full apps, Functions for event-driven
+3. **Medallion Data Architecture**: Bronze/Silver/Gold layers in GCP
+4. **Per-Client Compliance**: HIPAA/SOC2/PCI-DSS modes set per engagement
+5. **Widget Strategy**: Zoho widgets for internal, Publish API for external users
+
+### Scalability Plan
+- **Single Client**: Creator + Catalyst Functions sufficient
+- **Multi-Client**: Shared Catalyst AppSail, isolated Creator apps per client
+- **Enterprise**: Dedicated GCP projects, BigQuery datasets per client
+- **High Volume**: Dataflow streaming, Cron functions for batch processing
+
+## Zoho One Architecture Patterns
+
+### Creator Application Design
+- Form hierarchy: Parent forms → child forms via lookup
+- Report optimization: Use aggregate fields, avoid Deluge in reports
+- Widget placement strategy (widgets DON'T work on published pages)
+- Publish API for external user access
+
+### Catalyst Architecture
+- AppSail: Full web app hosting (Node.js, Express, Next.js, Python)
+- Functions: Event-driven serverless (I/O: 30s timeout, Cron: 15min)
+- MANDATORY: context.close() at end of ALL Catalyst functions
+- Use Cron functions for any operation exceeding 30 seconds
+
+### GCP Medallion Architecture
+- **Bronze Layer**: Raw ingestion to GCS, minimal transformation, schema-on-read
+- **Silver Layer**: Cleansed, deduplicated, quality rules applied, BigQuery tables
+- **Gold Layer**: Business-ready aggregations, materialized views, Looker-ready
+- **Transitions**: dbt models for transformations, Dataflow for streaming
+
+### Integration Patterns
+- CRM→Books: Native 2-hour sync exists (DON'T rebuild)
+- Zoho Flow vs Deluge: Use Flow for simple triggers, Deluge for complex logic
+- OAuth tokens: Expire in 1 hour, implement refresh in all integrations
+- Widget CORS: Server-to-server proxy architecture required
+
+## CloudStream Architecture Decisions
+1. **Zoho Platform**: Creator for apps, Catalyst for serverless + full-stack hosting
+2. **Data Layer**: BigQuery (analytics) + Zoho (operational)
+3. **Reporting**: Looker Studio + Zoho Analytics dashboards
+4. **Compliance**: Per-client mode (HIPAA/SOC2/PCI-DSS/standard)
+5. **Frontend**: React/Next.js widgets deployed to Zoho + standalone
+
+**Remember**: Good architecture enables rapid development, easy maintenance, and confident scaling. The best architecture is simple, clear, and follows established patterns.