@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/consultancy-workflows/knowledge-capture.md

@@ -0,0 +1,513 @@
+# Knowledge Capture
+
+## Overview
+
+CloudStream delivers repeated patterns across client engagements -- HIPAA audit logging, Zoho Creator workflows, GCP integrations, compliance configurations. Without systematic knowledge capture, every new engagement starts from scratch, wasting billable hours on solved problems. This document defines how to extract, catalog, and reuse patterns across projects while maintaining client data isolation.
+
+> **WARNING**: Knowledge capture MUST maintain strict client isolation. Shared patterns must NEVER contain client-specific data, credentials, business logic, or identifiable information. Violating client confidentiality is a breach of contract and professional ethics.
+
+---
+
+## Pattern Extraction Across Client Projects
+
+### What to Extract
+
+| Category | Examples | Reuse Value |
+|---|---|---|
+| **Architecture Patterns** | Form structures for common use cases | High |
+| **Deluge Templates** | Audit logging, CRUD operations, integrations | Very High |
+| **Compliance Configurations** | HIPAA/SOC2/PCI implementation checklists | Critical |
+| **Workflow Patterns** | Approval chains, notification sequences | High |
+| **Integration Patterns** | Zoho-to-GCP, webhook handlers, API connectors | High |
+| **Deployment Procedures** | Environment promotion, rollback steps | Medium |
+| **Troubleshooting Guides** | Common Creator/Catalyst issues and fixes | High |
+| **Estimation Templates** | Hours-by-task-type for project planning | Very High |
+
+### What NOT to Extract
+
+| Never Share | Reason |
+|---|---|
+| Client business rules | Proprietary to client |
+| Client data samples | Confidentiality + compliance |
+| Client credentials | Security |
+| Client-specific pricing | Competitive sensitivity |
+| Client names in examples | NDA obligations |
+| Client org IDs | Security |
+| Production URLs | Security |
+
+---
+
+## Extraction Process
+
+### Post-Engagement Pattern Review
+
+After every completed engagement (or major milestone):
+
+```
+1. Developer reviews completed work
+    |
+    v
+2. Identify reusable patterns (code, config, process)
+    |
+    v
+3. Abstract pattern (remove ALL client-specific details)
+    |
+    v
+4. Document pattern with:
+    - Problem it solves
+    - When to use it
+    - Implementation steps
+    - Known limitations
+    - Compliance implications
+    |
+    v
+5. Tag pattern (industry, compliance, technology, complexity)
+    |
+    v
+6. Peer review (another developer validates reusability)
+    |
+    v
+7. Add to internal knowledge base
+    |
+    v
+8. Announce in team channel
+```
+
+### Abstraction Example
+
+**Client-Specific (DO NOT SHARE)**:
+```deluge
+// Acme Healthcare patient intake form
+patientRecord = zoho.creator.getRecordById("acme-health-app", "Patient_Intake", patientId);
+sendmail [to: "intake@acmehealthcare.com", subject: "New patient: " + patientRecord.get("Name")];
+```
+
+**Abstracted Pattern (SAFE TO SHARE)**:
+```deluge
+// Pattern: Record notification on creation
+// Use case: Alert stakeholders when new records are created
+// Compliance: Ensure notification does not contain ePHI in subject/body for HIPAA
+
+record = zoho.creator.getRecordById("[APP_NAME]", "[FORM_NAME]", recordId);
+sendmail [
+    to: "[NOTIFICATION_EMAIL]",
+    subject: "New [RECORD_TYPE] submitted - ID: " + record.get("ID"),
+    message: "A new record requires attention. View in application."
+    // WARNING: Do NOT include ePHI in email body for HIPAA clients
+];
+```
+
+---
+
+## Building Reusable Templates from Completed Work
+
+### Template Categories
+
+#### 1. Form Templates
+
+```json
+{
+  "template_id": "TMPL-FORM-001",
+  "name": "HIPAA Audit Log Form",
+  "category": "compliance",
+  "tags": ["hipaa", "audit", "logging", "healthcare"],
+  "description": "Standard audit log form for HIPAA-regulated Creator applications",
+  "fields": [
+    {"name": "Audit_ID", "type": "auto-number", "required": true},
+    {"name": "Timestamp", "type": "datetime", "required": true},
+    {"name": "User_Email", "type": "email", "required": true},
+    {"name": "Action_Type", "type": "picklist", "required": true,
+     "values": ["Access", "Create", "Update", "Delete", "Export", "Share"]},
+    {"name": "Form_Name", "type": "single-line", "required": true},
+    {"name": "Record_ID", "type": "number", "required": true},
+    {"name": "Field_Name", "type": "single-line", "required": false},
+    {"name": "Old_Value", "type": "multi-line", "required": false},
+    {"name": "New_Value", "type": "multi-line", "required": false}
+  ],
+  "permissions": {
+    "admin": "view-only",
+    "all_others": "no-access",
+    "service_account": "add-only"
+  },
+  "compliance_notes": "Must be paired with BigQuery archival for 6-year retention",
+  "used_in_projects": 7,
+  "last_updated": "2025-01-15",
+  "author": "developer@cloudstreamsoftware.com"
+}
+```
+
+#### 2. Workflow Templates
+
+```json
+{
+  "template_id": "TMPL-WF-003",
+  "name": "Multi-Level Approval Workflow",
+  "category": "business-process",
+  "tags": ["approval", "workflow", "soc2", "change-management"],
+  "description": "Configurable multi-level approval with separation of duties",
+  "stages": [
+    {"name": "Submit", "actor": "Requester", "actions": ["submit"]},
+    {"name": "Review", "actor": "Reviewer", "actions": ["approve", "reject", "request-info"]},
+    {"name": "Approve", "actor": "Approver", "actions": ["approve", "reject"],
+     "constraint": "Cannot be same person as Requester"},
+    {"name": "Implement", "actor": "Implementer", "actions": ["complete", "rollback"],
+     "constraint": "Cannot be same person as Requester for SOC2"}
+  ],
+  "deluge_template": "[see approval-workflow.deluge in templates/]",
+  "customization_points": ["Number of approval levels", "Approval criteria", "Notification recipients"],
+  "used_in_projects": 12,
+  "avg_implementation_hours": 8
+}
+```
+
+#### 3. Integration Templates
+
+```json
+{
+  "template_id": "TMPL-INT-005",
+  "name": "Creator-to-BigQuery Archival",
+  "category": "integration",
+  "tags": ["bigquery", "gcp", "archival", "hipaa", "catalyst"],
+  "description": "Monthly batch export of Creator form data to BigQuery for long-term storage",
+  "components": [
+    "Catalyst Cron function (scheduled trigger)",
+    "Creator API integration (data source)",
+    "BigQuery client library (data destination)",
+    "Alerting function (failure notification)"
+  ],
+  "estimated_hours": 16,
+  "prerequisites": ["GCP project", "BigQuery dataset", "Catalyst plan", "BAA if HIPAA"],
+  "used_in_projects": 5
+}
+```
+
+---
+
+## Documenting Lessons Learned Per Engagement
+
+### Lessons Learned Template
+
+```markdown
+# Lessons Learned: [Project Code - NO client name]
+## Date: [Engagement end date]
+## Duration: [weeks/months]
+## Team: [CloudStream team members]
+
+### What Went Well
+- [Specific practice that saved time or prevented issues]
+- [Tool/approach that exceeded expectations]
+
+### What Went Poorly
+- [Issue encountered and root cause]
+- [Time lost and how it could have been prevented]
+
+### Technical Discoveries
+- [Platform behavior not documented elsewhere]
+- [Workaround for Zoho/GCP limitation]
+- [Performance insight at scale]
+
+### Process Improvements
+- [Estimation accuracy: actual vs estimated hours]
+- [Communication patterns that worked/failed]
+- [Handoff process improvements needed]
+
+### Reusable Artifacts Created
+- [Templates added to knowledge base]
+- [Scripts/functions contributed to shared repo]
+- [Documentation patterns established]
+
+### Compliance Insights
+- [Audit findings and resolutions]
+- [Compliance requirements discovered mid-project]
+- [Platform limitations affecting compliance]
+
+### Tags
+Industry: [healthcare/finance/enterprise]
+Compliance: [hipaa/soc2/pci-dss/none]
+Technology: [creator/catalyst/bigquery/etc]
+Complexity: [simple/moderate/complex]
+```
+
+---
+
+## Internal Knowledge Base Structure
+
+### Repository Organization
+
+```
+cloudstream-knowledge-base/
+├── patterns/
+│   ├── compliance/
+│   │   ├── hipaa/
+│   │   ├── soc2/
+│   │   └── pci-dss/
+│   ├── integration/
+│   │   ├── zoho-to-gcp/
+│   │   ├── webhooks/
+│   │   └── third-party/
+│   ├── forms/
+│   │   ├── healthcare/
+│   │   ├── finance/
+│   │   └── enterprise/
+│   └── workflows/
+│       ├── approvals/
+│       ├── notifications/
+│       └── scheduled/
+├── templates/
+│   ├── deluge/
+│   ├── catalyst/
+│   ├── documentation/
+│   └── project-setup/
+├── lessons-learned/
+│   ├── 2024/
+│   └── 2025/
+├── estimation/
+│   ├── task-benchmarks.md
+│   └── complexity-matrix.md
+├── troubleshooting/
+│   ├── creator-issues.md
+│   ├── catalyst-issues.md
+│   └── integration-issues.md
+└── onboarding/
+    ├── week-1-guide.md
+    ├── tool-setup.md
+    └── compliance-training.md
+```
+
+---
+
+## Tagging Patterns by Industry/Compliance/Technology
+
+### Tag Taxonomy
+
+| Dimension | Values | Purpose |
+|---|---|---|
+| **Industry** | healthcare, finance, enterprise, retail, education | Filter by client vertical |
+| **Compliance** | hipaa, soc2, pci-dss, none | Filter by regulatory need |
+| **Technology** | creator, catalyst, bigquery, cloud-functions, zoho-crm | Filter by platform |
+| **Complexity** | starter, intermediate, advanced | Match to team skill level |
+| **Type** | pattern, template, guide, troubleshooting, lesson | Filter by artifact type |
+| **Status** | draft, reviewed, production-tested, deprecated | Quality indicator |
+
+### Search Examples
+
+```
+# Find all HIPAA audit patterns for Creator
+tags: hipaa + creator + audit + pattern
+
+# Find all BigQuery integration templates
+tags: bigquery + template + integration
+
+# Find lessons learned for healthcare projects
+tags: healthcare + lesson
+
+# Find starter-level workflow patterns
+tags: workflow + starter + pattern
+```
+
+---
+
+## Quarterly Knowledge Sharing Sessions
+
+### Session Format (90 minutes)
+
+| Time | Activity | Presenter |
+|---|---|---|
+| 0-10 min | New patterns added this quarter | Knowledge lead |
+| 10-30 min | Deep dive: Pattern of the quarter | Subject expert |
+| 30-50 min | Lessons learned review (anonymized) | Team discussion |
+| 50-70 min | Live demo: Applying a pattern to a new project | Developer |
+| 70-85 min | Q&A and improvement suggestions | All |
+| 85-90 min | Action items and next quarter focus | Knowledge lead |
+
+### Session Outputs
+
+- Updated knowledge base with new patterns discussed
+- Action items for filling identified knowledge gaps
+- Recording stored in internal learning library
+- Summary posted in team channel
+
+---
+
+## Onboarding New Employees with Captured Knowledge
+
+### Onboarding Path (First 30 Days)
+
+| Week | Focus | Knowledge Base Resources |
+|---|---|---|
+| Week 1 | Tool setup + CloudStream processes | `onboarding/week-1-guide.md`, `onboarding/tool-setup.md` |
+| Week 2 | Compliance fundamentals | `patterns/compliance/` (all README files) |
+| Week 3 | Zoho Creator/Catalyst deep-dive | `patterns/forms/`, `templates/deluge/` |
+| Week 4 | First project (paired with senior dev) | `estimation/task-benchmarks.md` |
+
+### Self-Assessment Checkpoints
+
+```markdown
+## Week 2 Checkpoint
+
+- [ ] Can explain HIPAA 6-year retention requirement
+- [ ] Understands BAA chain for Zoho + GCP
+- [ ] Can identify which forms need audit logging
+- [ ] Knows where to find compliance patterns in the knowledge base
+- [ ] Has read the SOC 2 change management process
+- [ ] Understands PCI SAQ-A scope reduction via hosted pages
+```
+
+---
+
+## Measuring Knowledge Reuse
+
+### Metrics to Track
+
+| Metric | How to Measure | Target |
+|---|---|---|
+| Template usage rate | Projects using templates vs. building from scratch | >70% |
+| Time-to-first-commit | Days from project start to first meaningful work | <3 days |
+| Estimation accuracy | Actual hours vs. estimated (using benchmarks) | Within 20% |
+| Pattern adoption | New patterns used within 1 quarter of creation | >50% |
+| Onboarding time | Days to productive contribution for new hires | <30 days |
+| Knowledge base growth | New patterns/templates per quarter | >5 per quarter |
+| Stale content ratio | Patterns not updated in >6 months | <20% |
+
+### Quarterly Knowledge Health Report
+
+```markdown
+## Q1 2025 Knowledge Base Health
+
+### Growth
+- New patterns added: 8
+- Templates updated: 12
+- Lessons learned documented: 4
+
+### Usage
+- Projects leveraging templates: 6/8 (75%)
+- Most-used pattern: HIPAA Audit Logging (used in 3 projects)
+- Least-used category: Troubleshooting (needs refresh)
+
+### Quality
+- Patterns reviewed this quarter: 15/42 (36%)
+- Deprecated patterns removed: 3
+- Stale content flagged: 7 (assigned for update)
+
+### Team Impact
+- Average estimation accuracy: +/-18% (on target)
+- New hire onboarding: 22 days to first solo task (improved from 35)
+```
+
+---
+
+## Avoiding Client-Specific Data in Shared Patterns
+
+### Sanitization Checklist
+
+Before adding any artifact to the shared knowledge base:
+
+- [ ] No client names, logos, or branding references
+- [ ] No org IDs, project IDs, or account numbers
+- [ ] No real email addresses (use `user@example.com`)
+- [ ] No real URLs (use `https://client-app.example.com`)
+- [ ] No real data values (use synthetic/placeholder data)
+- [ ] No client business rules that could identify them
+- [ ] No pricing, contract terms, or financial details
+- [ ] No employee names from client organizations
+- [ ] No proprietary algorithms or trade secrets
+- [ ] Variable names genericized (`clientApp` not `acmeHealthApp`)
+
+### Automated Sanitization Check
+
+```javascript
+// Pre-commit hook for knowledge base repo
+// Flags potential client data leaks
+
+const SENSITIVE_PATTERNS = [
+  /\b[A-Za-z0-9._%+-]+@(?!example\.com|cloudstreamsoftware\.com)[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/, // Real emails
+  /org_[a-z0-9]{10,}/,     // Zoho org IDs
+  /CLT-\d{3}/,              // Client IDs
+  /https?:\/\/(?!example\.com)[a-z0-9.-]+\.zoho(creator)?\.com/,  // Real Zoho URLs
+  /\b\d{3}-\d{2}-\d{4}\b/, // SSN patterns
+  /\b\d{16}\b/,             // Card numbers
+];
+
+function checkForSensitiveData(content) {
+  const findings = [];
+  SENSITIVE_PATTERNS.forEach(pattern => {
+    if (pattern.test(content)) {
+      findings.push(`Potential sensitive data: ${pattern.toString()}`);
+    }
+  });
+  return findings;
+}
+```
+
+---
+
+## Contributing Back to the cloudstream-claude-code Repo
+
+### Contribution Workflow
+
+```
+Developer identifies reusable pattern from client work
+    |
+    v
+Abstract and sanitize (remove ALL client specifics)
+    |
+    v
+Create branch: knowledge/[pattern-name]
+    |
+    v
+Add pattern to appropriate directory
+    |
+    v
+Include: README, code template, usage examples
+    |
+    v
+Open PR with tags: industry, compliance, technology
+    |
+    v
+Peer review (minimum 1 reviewer)
+    |
+    v
+Merge to main
+    |
+    v
+Announce in #knowledge-sharing channel
+```
+
+### PR Template for Knowledge Contributions
+
+```markdown
+## Knowledge Contribution
+
+### Pattern Name
+[Name]
+
+### Category
+[compliance/integration/forms/workflows/troubleshooting]
+
+### Tags
+- Industry: [healthcare/finance/enterprise]
+- Compliance: [hipaa/soc2/pci-dss/none]
+- Technology: [creator/catalyst/bigquery]
+- Complexity: [starter/intermediate/advanced]
+
+### Problem It Solves
+[1-2 sentences]
+
+### Times Used in Client Projects
+[Number - demonstrates proven value]
+
+### Sanitization Checklist
+- [ ] No client names or identifiers
+- [ ] No real credentials or URLs
+- [ ] No proprietary business logic
+- [ ] Placeholder values for all examples
+- [ ] Reviewed by second team member
+
+### Quality Checklist
+- [ ] Clear README with usage instructions
+- [ ] Code template with comments
+- [ ] Known limitations documented
+- [ ] Compliance implications noted
+```
+
+> **WARNING**: All contributions to the shared repo undergo mandatory peer review for client data leakage. Any PR containing identifiable client information must be rejected and the contributor notified immediately. This is a fireable offense if intentional.

package/skills/consultancy-workflows/time-tracking.md

@@ -0,0 +1,26 @@
+# Time Tracking in Commits
+
+## Commit Convention
+```
+[CLIENT-ID] type(scope): description | Time: Xh Xm
+```
+
+Examples:
+```
+[CSI] feat(widget): Add dashboard KPI cards | Time: 2h 30m
+[PROGUARD] fix(deluge): Fix null check in invoice sync | Time: 0h 45m
+[ZUBLER] docs(handoff): Complete API documentation | Time: 1h 15m
+```
+
+## Time Categories
+- Development: Writing code, testing, debugging
+- Architecture: Design, planning, decision-making
+- Documentation: Writing docs, updating runbooks
+- Communication: Client meetings, email correspondence
+- Research: Learning new APIs, investigating solutions
+
+## Billing Rules
+- Round to nearest 15 minutes
+- Minimum billable: 15 minutes
+- Include research time when directly for client
+- Track admin time separately (not billable)

package/skills/continuous-learning/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: continuous-learning
+description: Automatically extract reusable patterns from Claude Code sessions and save them as learned skills for future use.
+version: 1.0.0
+status: active
+introduced: 1.0.0
+lastUpdated: 2026-01-25
+---
+
+# Continuous Learning Skill
+
+Automatically evaluates Claude Code sessions on end to extract reusable patterns that can be saved as learned skills.
+
+## How It Works
+
+This skill runs as a **Stop hook** at the end of each session:
+
+1. **Session Evaluation**: Checks if session has enough messages (default: 10+)
+2. **Pattern Detection**: Identifies extractable patterns from the session
+3. **Skill Extraction**: Saves useful patterns to `~/.claude/skills/learned/`
+
+## Configuration
+
+Edit `config.json` to customize:
+
+```json
+{
+  "min_session_length": 10,
+  "extraction_threshold": "medium",
+  "auto_approve": false,
+  "learned_skills_path": "~/.claude/skills/learned/",
+  "patterns_to_detect": [
+    "error_resolution",
+    "user_corrections",
+    "workarounds",
+    "debugging_techniques",
+    "project_specific"
+  ],
+  "ignore_patterns": [
+    "simple_typos",
+    "one_time_fixes",
+    "external_api_issues"
+  ]
+}
+```
+
+## Pattern Types
+
+| Pattern | Description |
+|---------|-------------|
+| `error_resolution` | How specific errors were resolved |
+| `user_corrections` | Patterns from user corrections |
+| `workarounds` | Solutions to framework/library quirks |
+| `debugging_techniques` | Effective debugging approaches |
+| `project_specific` | Project-specific conventions |
+
+## Hook Setup
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.claude/skills/continuous-learning/evaluate-session.sh"
+      }]
+    }]
+  }
+}
+```
+
+## Why Stop Hook?
+
+- **Lightweight**: Runs once at session end
+- **Non-blocking**: Doesn't add latency to every message
+- **Complete context**: Has access to full session transcript
+
+## Related
+
+- `/learn` command - Manual pattern extraction mid-session
+- Memory persistence hooks - For state that survives compaction

package/skills/continuous-learning/config.json

@@ -0,0 +1,18 @@
+{
+  "min_session_length": 10,
+  "extraction_threshold": "medium",
+  "auto_approve": false,
+  "learned_skills_path": "~/.claude/skills/learned/",
+  "patterns_to_detect": [
+    "error_resolution",
+    "user_corrections",
+    "workarounds",
+    "debugging_techniques",
+    "project_specific"
+  ],
+  "ignore_patterns": [
+    "simple_typos",
+    "one_time_fixes",
+    "external_api_issues"
+  ]
+}

package/skills/continuous-learning/evaluate-session.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Continuous Learning - Session Evaluator
+# Runs on Stop hook to extract reusable patterns from Claude Code sessions
+#
+# Why Stop hook instead of UserPromptSubmit:
+# - Stop runs once at session end (lightweight)
+# - UserPromptSubmit runs every message (heavy, adds latency)
+#
+# Hook config (in ~/.claude/settings.json):
+# {
+#   "hooks": {
+#     "Stop": [{
+#       "matcher": "*",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/skills/continuous-learning/evaluate-session.sh"
+#       }]
+#     }]
+#   }
+# }
+#
+# Patterns to detect: error_resolution, debugging_techniques, workarounds, project_specific
+# Patterns to ignore: simple_typos, one_time_fixes, external_api_issues
+# Extracted skills saved to: ~/.claude/skills/learned/
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONFIG_FILE="$SCRIPT_DIR/config.json"
+LEARNED_SKILLS_PATH="${HOME}/.claude/skills/learned"
+MIN_SESSION_LENGTH=10
+
+# Load config if exists
+if [ -f "$CONFIG_FILE" ]; then
+  MIN_SESSION_LENGTH=$(jq -r '.min_session_length // 10' "$CONFIG_FILE")
+  LEARNED_SKILLS_PATH=$(jq -r '.learned_skills_path // "~/.claude/skills/learned/"' "$CONFIG_FILE" | sed "s|~|$HOME|")
+fi
+
+# Ensure learned skills directory exists
+mkdir -p "$LEARNED_SKILLS_PATH"
+
+# Get transcript path from environment (set by Claude Code)
+transcript_path="${CLAUDE_TRANSCRIPT_PATH:-}"
+
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+  exit 0
+fi
+
+# Count messages in session
+message_count=$(grep -c '"type":"user"' "$transcript_path" 2>/dev/null || echo "0")
+
+# Skip short sessions
+if [ "$message_count" -lt "$MIN_SESSION_LENGTH" ]; then
+  echo "[ContinuousLearning] Session too short ($message_count messages), skipping" >&2
+  exit 0
+fi
+
+# Signal to Claude that session should be evaluated for extractable patterns
+echo "[ContinuousLearning] Session has $message_count messages - evaluate for extractable patterns" >&2
+echo "[ContinuousLearning] Save learned skills to: $LEARNED_SKILLS_PATH" >&2