@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/consultancy-workflows/documentation-automation.md

@@ -0,0 +1,454 @@
+# Documentation Automation
+
+## Overview
+
+CloudStream delivers billable client work that must be auditable, defensible, and handoff-ready. Manual documentation is time-consuming, error-prone, and frequently falls behind code changes. This guide defines how to auto-generate client documentation from code, commits, and project structure -- ensuring documentation stays in sync with reality.
+
+> **WARNING**: Client documentation is a deliverable. Undocumented work cannot be handed off, cannot be maintained by other team members, and cannot be defended in disputes. Automate documentation generation as part of every project.
+
+---
+
+## Auto-Generating Client Documentation from Code and Commits
+
+### Documentation Sources
+
+| Source | What It Produces | Automation Method |
+|---|---|---|
+| Git commit history | Change logs, release notes | Commit message parsing |
+| Code comments/JSDoc | API reference docs | Comment extraction |
+| Deluge function headers | Function catalog | Header parsing |
+| Creator form structure | Data dictionary | API export + formatting |
+| Catalyst function configs | Deployment runbook | Config file parsing |
+| Workflow definitions | Process documentation | Workflow export |
+| File/folder structure | Architecture overview | Directory tree analysis |
+
+### Commit-Driven Documentation Pipeline
+
+```
+Developer commits code
+    |
+    | (Conventional Commits format)
+    v
+Pre-commit hook validates format
+    |
+    v
+Post-push hook triggers doc generation
+    |
+    v
+Claude Code parses commit history
+    |
+    v
+Documentation artifacts updated:
+    - CHANGELOG.md (per project)
+    - API reference (if endpoints changed)
+    - Architecture docs (if structure changed)
+    - Runbook (if deployment config changed)
+```
+
+---
+
+## Extracting Architecture Diagrams from Code Structure
+
+### Directory-to-Architecture Mapping
+
+```
+project-root/
+├── forms/                    → Data Layer documentation
+│   ├── Patient_Records/      → Entity: Patient Records
+│   ├── Appointments/         → Entity: Appointments
+│   └── Audit_Logs/           → Entity: Audit Trail
+├── workflows/                → Business Logic documentation
+│   ├── approval/             → Approval Process flows
+│   ├── notifications/        → Notification system
+│   └── scheduled/            → Scheduled job documentation
+├── functions/                → API/Integration documentation
+│   ├── catalyst/             → Serverless functions
+│   ├── webhooks/             → Webhook handlers
+│   └── integrations/         → Third-party integrations
+├── reports/                  → Reporting documentation
+└── portals/                  → User-facing documentation
+```
+
+### Architecture Document Auto-Generation Prompt
+
+When using Claude Code to generate architecture docs from a project:
+
+```
+Analyze the project structure at [path] and generate:
+1. A component diagram showing major subsystems
+2. A data flow diagram showing how data moves between forms
+3. An integration diagram showing external connections
+4. A deployment diagram showing environments and their relationships
+
+Format as markdown with Mermaid diagram syntax.
+Include all Creator forms, Catalyst functions, and external integrations.
+```
+
+### Sample Generated Architecture Section
+
+```markdown
+## System Architecture
+
+### Component Overview
+
+```mermaid
+graph TD
+    Portal[Customer Portal] --> Creator[Zoho Creator]
+    Creator --> Forms[Form Layer]
+    Creator --> Workflows[Workflow Engine]
+    Forms --> AuditLog[Audit Logging]
+    Workflows --> Catalyst[Catalyst Functions]
+    Catalyst --> BigQuery[GCP BigQuery]
+    Catalyst --> Payments[Zoho Payments]
+    Workflows --> Email[Zoho Mail]
+```
+```
+
+---
+
+## Generating API Documentation from Deluge/Catalyst Functions
+
+### Deluge Function Header Standard
+
+Every Deluge function MUST include a documentation header:
+
+```deluge
+// ============================================================
+// FUNCTION: functionName
+// PURPOSE: Brief description of what this function does
+// TRIGGER: How this function is invoked (button/workflow/schedule/API)
+// INPUTS:
+//   - paramName (Type): Description
+//   - paramName2 (Type): Description
+// OUTPUTS:
+//   - Return value description
+// SIDE EFFECTS:
+//   - Records created/modified
+//   - Emails sent
+//   - External API calls made
+// COMPLIANCE: HIPAA|SOC2|PCI (which frameworks apply)
+// AUTHOR: developer@cloudstreamsoftware.com
+// CREATED: 2025-01-15
+// MODIFIED: 2025-02-20 - Added error handling
+// ============================================================
+```
+
+### Auto-Extraction Script
+
+```javascript
+// Extract documentation headers from Deluge files
+// Run as part of CI/CD or pre-handoff process
+
+const fs = require('fs');
+const path = require('path');
+
+function extractDelugeDoc(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const headerRegex = /\/\/ ={50,}\n([\s\S]*?)\/\/ ={50,}/g;
+  const headers = [];
+  let match;
+
+  while ((match = headerRegex.exec(content)) !== null) {
+    const header = parseHeader(match[1]);
+    headers.push(header);
+  }
+
+  return headers;
+}
+
+function parseHeader(headerText) {
+  const lines = headerText.split('\n').map(l => l.replace(/^\/\/\s*/, '').trim());
+  const doc = {};
+
+  lines.forEach(line => {
+    if (line.startsWith('FUNCTION:')) doc.name = line.replace('FUNCTION:', '').trim();
+    if (line.startsWith('PURPOSE:')) doc.purpose = line.replace('PURPOSE:', '').trim();
+    if (line.startsWith('TRIGGER:')) doc.trigger = line.replace('TRIGGER:', '').trim();
+    if (line.startsWith('COMPLIANCE:')) doc.compliance = line.replace('COMPLIANCE:', '').trim();
+    // ... parse other fields
+  });
+
+  return doc;
+}
+
+function generateApiReference(headers) {
+  let markdown = '# API Reference\n\n';
+  markdown += '| Function | Purpose | Trigger | Compliance |\n';
+  markdown += '|---|---|---|---|\n';
+
+  headers.forEach(h => {
+    markdown += `| ${h.name} | ${h.purpose} | ${h.trigger} | ${h.compliance} |\n`;
+  });
+
+  return markdown;
+}
+```
+
+---
+
+## Commit Message Analysis for Change Logs
+
+### Conventional Commits Format (Required)
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types and Their Documentation Impact
+
+| Type | Changelog Section | Example |
+|---|---|---|
+| `feat` | New Features | `feat(appointments): add recurring appointment support` |
+| `fix` | Bug Fixes | `fix(billing): correct tax calculation for multi-state` |
+| `docs` | Documentation | `docs(api): update webhook endpoint reference` |
+| `refactor` | Technical Changes | `refactor(audit): optimize BigQuery batch insert` |
+| `perf` | Performance | `perf(search): add index to Patient_Records lookup` |
+| `security` | Security Updates | `security(auth): enforce MFA for admin roles` |
+| `compliance` | Compliance Changes | `compliance(hipaa): add field-level encryption for SSN` |
+
+### Changelog Generation Script
+
+```javascript
+// Generate CHANGELOG.md from git log
+// Run: node generate-changelog.js [since-tag]
+
+const { execSync } = require('child_process');
+
+function generateChangelog(sinceTag) {
+  const log = execSync(
+    `git log ${sinceTag}..HEAD --pretty=format:"%H|%s|%an|%ad" --date=short`
+  ).toString();
+
+  const entries = log.split('\n').filter(Boolean).map(line => {
+    const [hash, message, author, date] = line.split('|');
+    const match = message.match(/^(\w+)(?:\(([^)]+)\))?: (.+)$/);
+    return match ? { hash, type: match[1], scope: match[2], desc: match[3], author, date } : null;
+  }).filter(Boolean);
+
+  const sections = {
+    feat: '### New Features',
+    fix: '### Bug Fixes',
+    security: '### Security Updates',
+    compliance: '### Compliance Changes',
+    perf: '### Performance Improvements',
+    refactor: '### Technical Changes'
+  };
+
+  let changelog = `## [${getNextVersion()}] - ${new Date().toISOString().split('T')[0]}\n\n`;
+
+  Object.entries(sections).forEach(([type, header]) => {
+    const items = entries.filter(e => e.type === type);
+    if (items.length) {
+      changelog += `${header}\n`;
+      items.forEach(item => {
+        changelog += `- ${item.scope ? `**${item.scope}**: ` : ''}${item.desc} (${item.hash.substring(0,7)})\n`;
+      });
+      changelog += '\n';
+    }
+  });
+
+  return changelog;
+}
+```
+
+---
+
+## Automated Handoff Document Generation
+
+### Handoff Document Structure
+
+When the `/handoff` command is invoked, generate the following document automatically:
+
+```markdown
+# Project Handoff Document
+## [Client Name] - [Project Name]
+## Generated: [Date]
+
+### 1. Project Overview
+- Client: [from project config]
+- Engagement type: [from project config]
+- Primary contacts: [from project config]
+- Environments: [from deployment config]
+
+### 2. Architecture Summary
+[Auto-generated from code structure analysis]
+
+### 3. Access & Credentials
+- Zoho Org: [org details - NOT credentials]
+- GCP Project: [project ID]
+- Repository: [repo URL]
+- Key contacts for access: [list]
+
+### 4. Active Workflows
+[Auto-extracted from workflow definitions]
+
+### 5. Scheduled Jobs
+[Auto-extracted from Catalyst cron configs]
+
+### 6. Integration Points
+[Auto-extracted from API connection configs]
+
+### 7. Compliance Requirements
+[Auto-extracted from compliance markers in code]
+
+### 8. Known Issues / Technical Debt
+[Auto-extracted from TODO comments and issue tracker]
+
+### 9. Recent Changes
+[Auto-generated from last 30 days of commits]
+
+### 10. Runbook
+[Auto-generated from deployment configs and operational docs]
+```
+
+### Integration with /handoff Command
+
+```javascript
+// In the handoff skill implementation
+// Auto-collect documentation sources and generate
+
+async function generateHandoffDoc(clientId, projectPath) {
+  const doc = {};
+
+  // 1. Project config
+  doc.overview = await readProjectConfig(projectPath);
+
+  // 2. Architecture
+  doc.architecture = await analyzeProjectStructure(projectPath);
+
+  // 3. Access (never include actual credentials)
+  doc.access = await extractAccessInfo(projectPath);
+
+  // 4. Workflows
+  doc.workflows = await extractWorkflowDefinitions(projectPath);
+
+  // 5. Scheduled jobs
+  doc.scheduledJobs = await extractCronConfigs(projectPath);
+
+  // 6. Integrations
+  doc.integrations = await extractApiConnections(projectPath);
+
+  // 7. Compliance
+  doc.compliance = await extractComplianceMarkers(projectPath);
+
+  // 8. Known issues
+  doc.issues = await extractTodosAndIssues(projectPath);
+
+  // 9. Recent changes
+  doc.recentChanges = await generateChangelog('30-days-ago');
+
+  // 10. Runbook
+  doc.runbook = await generateRunbook(projectPath);
+
+  return formatAsMarkdown(doc);
+}
+```
+
+---
+
+## Documentation Templates
+
+### Architecture Document Template
+
+| Section | Content | Auto-Generated? |
+|---|---|---|
+| Executive Summary | High-level overview | Partially (needs human review) |
+| System Context | External dependencies | Yes (from integrations) |
+| Component Diagram | Internal architecture | Yes (from structure) |
+| Data Model | Forms and relationships | Yes (from Creator API) |
+| Integration Map | External connections | Yes (from configs) |
+| Security Model | Auth, encryption, access | Partially |
+| Deployment Model | Environments, promotion | Yes (from configs) |
+| Operational Model | Monitoring, alerting | Partially |
+
+### Runbook Template
+
+| Section | Content | Auto-Generated? |
+|---|---|---|
+| Service Overview | What the system does | Yes (from README/config) |
+| Health Checks | How to verify system health | Yes (from monitoring config) |
+| Common Issues | Known problems and solutions | No (from knowledge base) |
+| Restart Procedures | How to restart components | Partially |
+| Escalation Path | Who to contact | No (from project config) |
+| Deployment Steps | How to deploy changes | Yes (from CI/CD config) |
+
+### API Reference Template
+
+| Section | Content | Auto-Generated? |
+|---|---|---|
+| Endpoint List | All API endpoints | Yes (from function headers) |
+| Authentication | How to authenticate | Partially |
+| Request/Response | Formats and examples | Yes (from code analysis) |
+| Error Codes | Error responses | Yes (from error handling code) |
+| Rate Limits | Throttling rules | No (from platform docs) |
+
+---
+
+## Keeping Docs in Sync with Code Changes
+
+### Automated Sync Triggers
+
+| Trigger | Action | Tool |
+|---|---|---|
+| New commit pushed | Update changelog | Git hook + script |
+| New form created | Update data dictionary | Creator webhook |
+| New function deployed | Update API reference | Deployment hook |
+| Quarterly review | Full doc regeneration | Scheduled task |
+| Pre-handoff | Complete doc package | /handoff command |
+
+### Staleness Detection
+
+```javascript
+// Check if documentation is stale relative to code changes
+function checkDocStaleness(projectPath) {
+  const lastDocUpdate = getLastModified(`${projectPath}/docs/`);
+  const lastCodeChange = getLastCommitDate(projectPath);
+
+  const daysSinceDocUpdate = daysBetween(lastDocUpdate, new Date());
+  const daysSinceCodeChange = daysBetween(lastCodeChange, new Date());
+
+  if (daysSinceCodeChange < daysSinceDocUpdate && daysSinceDocUpdate > 14) {
+    return {
+      stale: true,
+      message: `Documentation last updated ${daysSinceDocUpdate} days ago, but code changed ${daysSinceCodeChange} days ago.`,
+      recommendation: 'Run documentation regeneration.'
+    };
+  }
+
+  return { stale: false };
+}
+```
+
+---
+
+## Client-Facing vs. Internal Documentation Standards
+
+### Client-Facing Documentation
+
+| Characteristic | Standard |
+|---|---|
+| Language | Professional, non-technical where possible |
+| Detail level | Enough for client's IT team to understand |
+| Credentials | NEVER included -- reference "contact CloudStream" |
+| Architecture | High-level diagrams, not implementation details |
+| Code snippets | Only when explaining customization options |
+| Branding | Client logo/branding, CloudStream attribution |
+| Format | PDF deliverable + shared folder access |
+
+### Internal Documentation
+
+| Characteristic | Standard |
+|---|---|
+| Language | Technical, developer-focused |
+| Detail level | Complete implementation details |
+| Credentials | Reference to credential store (never plaintext) |
+| Architecture | Detailed component diagrams with data flows |
+| Code snippets | Comprehensive with context |
+| Branding | CloudStream internal |
+| Format | Markdown in project repository |
+
+> **WARNING**: Never accidentally deliver internal documentation to clients. Internal docs may reference other clients, pricing strategies, or technical shortcuts that are inappropriate for external consumption. Always generate client-facing docs separately.

package/skills/consultancy-workflows/handoff-procedures.md

@@ -0,0 +1,257 @@
+# Client Handoff Procedures
+
+## When Handoffs Occur
+
+| Scenario | Trigger | Recipient |
+|----------|---------|-----------|
+| Project completion | All deliverables accepted | Client internal team |
+| Team member change | Employee departure/transition | New CloudStream developer |
+| Support transition | Active dev → maintenance mode | Support team |
+| Emergency coverage | Illness, PTO, unavailability | Backup developer |
+
+---
+
+## Architecture Handoff Checklist
+
+### System Documentation
+
+- [ ] Architecture diagram (draw.io or Lucidchart, exported as PNG + editable source)
+- [ ] All Zoho apps listed with links:
+  - Creator apps (form links, widget links)
+  - CRM modules and custom fields
+  - Catalyst projects (console links)
+  - Analytics workspaces and dashboards
+  - Books organization and chart of accounts
+- [ ] All integrations documented:
+  - OAuth connections (name, scope, expiry schedule)
+  - Webhooks (source, destination, payload format)
+  - Scheduled jobs (frequency, purpose, error handling)
+  - API endpoints (Catalyst functions, AppSail routes)
+- [ ] Data flow diagram showing:
+  - Where data enters the system
+  - How it moves between Zoho apps
+  - External systems connected
+  - GCP pipeline stages (if applicable)
+
+### Code Documentation
+
+- [ ] Repository structure explained
+- [ ] Key Deluge scripts documented (purpose, trigger, dependencies)
+- [ ] Catalyst function index (name, type, trigger, timeout)
+- [ ] Widget source code location and build instructions
+- [ ] Environment variables documented (what each one controls)
+- [ ] Test procedures documented (how to validate changes)
+
+### Compliance Documentation (if applicable)
+
+- [ ] Compliance mode documented (HIPAA/SOC2/PCI-DSS/standard)
+- [ ] ePHI field inventory (HIPAA clients)
+- [ ] Access control matrix current and signed
+- [ ] Audit log archival status confirmed (no gaps)
+- [ ] BAA/DPA agreements referenced (not included - legal holds)
+- [ ] Last compliance review date and findings
+
+---
+
+## Credential Rotation During Handoff
+
+### NEVER Transfer Credentials Via
+
+- Email (unencrypted, logged, forwarded)
+- Chat/messaging (Slack, Teams - retained in logs)
+- Shared documents (Google Docs, OneDrive)
+- Git repositories (even private ones)
+- Screenshots (may be backed up to cloud)
+
+### Approved Credential Transfer Methods
+
+| Method | Use When | Steps |
+|--------|----------|-------|
+| Password manager (1Password/LastPass) | Ongoing team access | Create shared vault, add credentials, invite recipient |
+| Zoho Vault | Client uses Zoho One | Create shared secret, set access duration |
+| In-person + secure wipe | Highest security | Show on screen, recipient types, verify, clear clipboard |
+| Secure video call | Remote handoff | Screen share credential, recipient confirms, revoke screen share |
+
+### Credential Rotation Procedure
+
+1. Generate NEW credentials (don't transfer existing)
+2. Update the application to use new credentials
+3. Verify application works with new credentials
+4. Revoke OLD credentials
+5. Document new credential locations in password manager
+6. Update `.env.client` template if format changed
+
+### Credentials to Rotate at Handoff
+
+| Credential | Rotation Steps |
+|-----------|----------------|
+| Zoho OAuth Refresh Token | Revoke old in API Console, generate new with same scopes |
+| GCP Service Account Key | Create new key, deploy, delete old key |
+| GitHub Personal Access Token | Generate new under recipient's account |
+| dbt Cloud Token | Create new service token, revoke old |
+| Webhook secrets | Generate new secret, update both endpoints |
+| Catalyst environment variables | Update in Catalyst Console |
+
+---
+
+## Documentation Package Contents
+
+The handoff package is a folder (physical or shared drive) containing:
+
+```
+handoff-package/
+├── 01-architecture-overview.md        # System design document
+├── 02-component-inventory.md          # All apps, forms, functions listed
+├── 03-integration-map.md              # Data flows and connections
+├── 04-api-reference.md                # Custom endpoints documentation
+├── 05-operational-runbook.md          # Day-to-day operations guide
+├── 06-known-issues.md                 # Technical debt and workarounds
+├── 07-future-recommendations.md       # Suggested improvements
+├── 08-compliance-status.md            # Current compliance state
+├── 09-credential-inventory.md         # WHERE credentials are stored (not the credentials)
+├── 10-contact-directory.md            # Key contacts and escalation paths
+├── diagrams/
+│   ├── architecture.png
+│   ├── architecture.drawio            # Editable source
+│   ├── data-flow.png
+│   └── data-flow.drawio
+└── appendix/
+    ├── sample-api-responses.json
+    ├── form-screenshots/              # Current form layouts
+    └── dashboard-screenshots/         # Current report/dashboard state
+```
+
+---
+
+## Operational Runbook Template
+
+### Section 1: Daily Operations
+
+```markdown
+## Daily Checks
+1. Verify scheduled jobs ran successfully
+   - Check: Catalyst Console → Functions → Execution Logs
+   - Expected: All cron functions show "SUCCESS" status
+   - If failed: Check error logs, re-run manually if safe
+
+2. Monitor API credit usage
+   - Check: Zoho API Console → Usage
+   - Threshold: Alert if >70% of daily limit consumed
+   - Action: Identify high-usage script, optimize or schedule off-peak
+
+3. Check BigQuery pipeline (if applicable)
+   - Check: GCP Console → BigQuery → Jobs
+   - Verify: Bronze ingestion completed, silver refresh succeeded
+   - If failed: Check source availability, re-trigger pipeline
+```
+
+### Section 2: Weekly Operations
+
+```markdown
+## Weekly Tasks
+1. Review audit logs for anomalies
+2. Check Zoho subscription usage (storage, API credits)
+3. Verify backup/archival jobs completed
+4. Update project status in internal tracking
+```
+
+### Section 3: Monthly Operations
+
+```markdown
+## Monthly Tasks
+1. Export audit logs to BigQuery (compliance clients)
+2. Review and rotate any expiring credentials
+3. Generate monthly usage report for client
+4. Review error logs for recurring issues
+```
+
+### Section 4: Troubleshooting
+
+```markdown
+## Common Issues
+
+### "Token Expired" in Deluge Scripts
+- Cause: OAuth connection needs reauthorization
+- Fix: Setup → Developer → Connections → Re-authorize
+- Prevention: Monitor token expiry dates
+
+### Catalyst Function Timeout
+- Cause: Processing exceeds 30s (I/O) or 15min (Cron)
+- Fix: Optimize query, add pagination, or split into smaller batches
+- Prevention: Add timeout monitoring, break large jobs into chunks
+
+### "Maximum records limit reached" in Creator
+- Cause: Form approaching 500K record limit
+- Fix: Archive old records to BigQuery, delete from Creator
+- Prevention: Schedule monthly archival
+
+### Webhook Not Firing
+- Cause: Workflow disabled, URL changed, or target unreachable
+- Fix: Verify workflow is active, check target URL, test manually
+- Prevention: Monitor webhook delivery status
+```
+
+---
+
+## Knowledge Transfer Session Structure
+
+### Session 1: Architecture Overview (60 minutes)
+
+1. Walk through architecture diagram (15 min)
+2. Demo key user workflows in the live system (20 min)
+3. Show data flow: source → Zoho → GCP → reports (15 min)
+4. Q&A and gap identification (10 min)
+
+### Session 2: Technical Deep-Dive (90 minutes)
+
+1. Repository structure and code organization (15 min)
+2. Key Deluge scripts walkthrough (30 min)
+3. Catalyst functions and deployment process (20 min)
+4. Widget development and testing (15 min)
+5. Q&A (10 min)
+
+### Session 3: Operations and Support (60 minutes)
+
+1. Walk through operational runbook live (20 min)
+2. Simulate common troubleshooting scenarios (20 min)
+3. Review credential locations and rotation process (10 min)
+4. Define support escalation path (10 min)
+
+### Session 4: Compliance (30 minutes, if applicable)
+
+1. Review compliance mode and requirements (10 min)
+2. Walk through audit log configuration (10 min)
+3. Demonstrate audit response procedure (10 min)
+
+---
+
+## Post-Handoff Support Window
+
+| Period | Support Level | Response Time | Scope |
+|--------|--------------|---------------|-------|
+| Days 1-7 | Full availability | Same day | All questions |
+| Days 8-14 | Available on request | 24 hours | Technical issues |
+| Days 15-30 | Email only | 48 hours | Critical issues only |
+| Day 31+ | New engagement | Per contract | Requires SOW |
+
+### Support Window Expectations
+
+- Recipient should attempt self-resolution using documentation first
+- Questions should be batched where possible (not 20 individual messages)
+- Critical issues (production down, data loss risk) bypass normal channels
+- All support interactions are logged for knowledge base improvement
+
+---
+
+## Handoff Completion Criteria
+
+The handoff is considered complete when:
+
+- [ ] All documentation delivered and acknowledged
+- [ ] Credentials rotated and verified working
+- [ ] Knowledge transfer sessions completed (recorded if possible)
+- [ ] Recipient can independently deploy a code change
+- [ ] Recipient can independently troubleshoot a common issue
+- [ ] Recipient can independently respond to an audit request (compliance clients)
+- [ ] Support window start date agreed upon
+- [ ] Final sign-off from client/recipient