@cloudstreamsoftware/claude-tools 1.2.2 → 1.2.4

package/commands/skill-create.md

@@ -0,0 +1,99 @@
+---
+description: Analyze git history to generate SKILL.md files from coding patterns
+---
+
+# /skill-create - Local Skill Generation
+
+The `/skill-create` command analyzes a repository's git history to identify coding patterns and generate SKILL.md files that document team practices for Claude.
+
+## When to Use
+
+- After completing a significant project milestone to capture patterns
+- When onboarding new team members who need to understand conventions
+- To document client-specific coding patterns (sanitized) for knowledge capture
+- Before `/learn` to auto-generate skill foundations from git history
+
+## Core Functionality
+
+The tool performs four main operations:
+
+1. **Git Data Collection** - Examines commits, file modifications, and metadata from recent history
+2. **Pattern Recognition** - Identifies recurring conventions including commit message formats, file co-changes, and architectural patterns
+3. **SKILL.md Generation** - Produces structured documentation of detected practices
+4. **Instincts Creation** (optional) - Generates instinct files compatible with continuous-learning-v2 systems
+
+## Usage
+
+```bash
+/skill-create                              # Analyze current repo with defaults
+/skill-create --commits 100                # Analyze last 100 commits
+/skill-create --output ./skills/client/    # Specify output directory
+/skill-create --instincts                  # Also generate instincts
+```
+
+## Pattern Detection
+
+The system identifies several pattern categories:
+
+| Category | Examples |
+|----------|----------|
+| Commit conventions | Message prefixes like `feat:`, `fix:`, `chore:` |
+| File co-changes | Files modified together across commits |
+| Workflow sequences | Repeating file modification patterns |
+| Architecture | Folder structures and naming conventions |
+| Testing patterns | Test file locations and naming standards |
+
+## Output Format
+
+Generated SKILL.md files include frontmatter with metadata, followed by sections documenting discovered patterns.
+
+### Example Output
+
+```markdown
+---
+name: project-typescript-patterns
+description: Conventions detected from 50 commits
+generated: 2026-01-27
+source: git-analysis
+---
+
+# Project TypeScript Patterns
+
+## Commit Conventions
+- Use conventional commits (feat:, fix:, docs:, etc.)
+- Include ticket reference in commit body
+
+## Folder Organization
+- Components in src/components/
+- Utilities in src/lib/
+- Tests co-located with source files
+
+## Component Creation
+1. Create component file
+2. Add tests in same directory
+3. Export from index.ts
+
+## Testing Framework
+- Jest for unit tests
+- Playwright for E2E tests
+```
+
+## Integration with CloudStream
+
+Works with existing `/learn` command:
+- Use `/skill-create` to auto-generate initial patterns from git
+- Use `/learn` to manually capture specific insights
+- Use `/evolve` to cluster instincts into higher-level structures
+
+## GitHub App Option
+
+For larger-scale analysis or team sharing, the Skill Creator GitHub App provides expanded capabilities:
+- Process 10k+ commit histories
+- Share generated skills across team
+- Auto-generate PRs with skill updates
+
+## Related Commands
+
+- `/learn` - Manual pattern extraction
+- `/instinct-status` - View learned instincts
+- `/evolve` - Cluster instincts into commands/skills/agents

package/commands/skill-submit.md

@@ -0,0 +1,121 @@
+---
+name: skill-submit
+description: Submit a learned skill to the shared team repository via PR.
+---
+
+# /skill-submit - Submit Skill to Team
+
+Submit a learned skill from `~/.claude/skills/learned/` to the shared CloudStream knowledge base for team-wide use.
+
+---
+
+## Usage
+
+```
+/skill-submit [skill-name]
+```
+
+If no skill name provided, lists available learned skills to choose from.
+
+## Workflow
+
+### Step 1: Select Skill
+
+List available skills from `~/.claude/skills/learned/`:
+
+```
+Available learned skills:
+
+  # | Name                      | Created
+ ---|---------------------------|------------
+  1 | catalyst-timeout-fix      | 2026-01-20
+  2 | creator-field-validation  | 2026-01-18
+  3 | hipaa-audit-pattern       | 2026-01-15
+
+Select skill number or name:
+```
+
+### Step 2: Review & Sanitize
+
+Before submission, manually verify the skill:
+
+1. **Remove client data** - No real client names, IDs, emails, or org IDs
+2. **Use placeholders** - Replace specific values with `[CLIENT_NAME]`, `user@example.com`, etc.
+3. **Check code examples** - Ensure no real API keys, tokens, or credentials
+
+### Step 3: Create PR
+
+Using the GitHub CLI:
+
+```bash
+# Navigate to learned skills
+cd ~/.claude/skills/learned/
+
+# Create branch
+git checkout -b skill-submit/[skill-name]
+
+# Stage skill file
+git add [skill-name].md
+
+# Commit
+git commit -m "skill: add [skill-name]"
+
+# Push and create PR
+gh pr create --title "skill: add [skill-name]" --body "Submitting learned skill for team review."
+```
+
+**On success:**
+```
+✅ PR created successfully!
+
+  PR URL: https://github.com/cloudstream/knowledge-base/pull/42
+
+Next steps:
+  1. A team member will review within 24 hours
+  2. You may receive feedback for changes
+  3. After approval, run /skill-sync to see it in shared skills
+```
+
+## Pre-Submission Checklist
+
+Before submitting, verify:
+
+- [ ] Skill solves a real, recurring problem
+- [ ] Contains no client-specific information
+- [ ] Has clear Problem and Solution sections
+- [ ] Code examples use placeholder values only
+- [ ] Tested and working (you've used it successfully)
+
+## Examples
+
+### Submit by name
+```
+/skill-submit catalyst-timeout-fix
+```
+
+### Interactive selection
+```
+/skill-submit
+> Shows list of learned skills
+> User selects by number or name
+```
+
+## Requirements
+
+- **Git**: Must be installed and configured
+- **gh CLI**: For PR creation (`gh auth login`)
+- **Repo access**: Must have push access to cloudstream-knowledge-base
+
+## Troubleshooting
+
+### "Permission denied"
+Contact your team lead for repository access.
+
+### "gh: command not found"
+Install GitHub CLI: https://cli.github.com/
+
+## Related Commands
+
+- `/learn` - Extract patterns during a session
+- `/skill-sync` - Pull shared skills from team repo
+- `/skill-gaps` - See your skill coverage vs team

package/commands/skill-sync.md

@@ -0,0 +1,250 @@
+---
+name: skill-sync
+description: Pull the latest shared skills from the CloudStream knowledge base to your local machine.
+---
+
+# /skill-sync - Sync Shared Skills
+
+Pull the latest approved skills from the CloudStream shared knowledge base to your local `~/.claude/skills/shared/` directory.
+
+---
+
+## Why This Matters
+
+### For Your Career
+- **Stay current** with the latest team-approved patterns
+- **Learn from colleagues** without waiting for direct mentorship
+- **Avoid outdated approaches** that have been superseded
+
+### For Your Team
+- **Unified practices** ensure consistent code quality across projects
+- **Distributed expertise** - benefit from specializations you don't have
+- **Continuous improvement** - skills evolve based on real usage
+
+### For Your Clients
+- **Latest best practices** applied to every project automatically
+- **Cross-pollination** - patterns proven on one project benefit others
+- **Reduced risk** through battle-tested, peer-reviewed approaches
+
+> **CloudStream Workflow:** Syncing skills is like keeping your tools sharp. The patterns your colleagues have validated become available to you automatically.
+
+---
+
+## Usage
+
+```
+/skill-sync
+```
+
+No arguments needed. Syncs all shared skills from the team repository.
+
+## Workflow
+
+### Step 1: Check Repository Setup
+
+```javascript
+// Planned implementation - skill-sharing module (Phase 14)
+// const { checkGitSetup, setupSharedRepo } = require('../scripts/lib/skill-sharing');
+// const gitStatus = checkGitSetup();
+```
+
+**If not configured:**
+```
+Setting up shared knowledge repository...
+  Cloning from: https://github.com/cloudstream/knowledge-base
+  To: ~/.claude/repos/knowledge-base
+
+✅ Repository cloned successfully
+```
+
+**If already configured:**
+```
+Updating shared knowledge repository...
+  Pulling latest from: origin/main
+
+✅ Repository updated
+```
+
+### Step 2: Sync Skills
+
+```javascript
+// Planned implementation - skill-sharing module (Phase 14)
+// const { syncFromSharedRepo } = require('../scripts/lib/skill-sharing');
+// const result = syncFromSharedRepo();
+```
+
+### Step 3: Report Results
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                     Skill Sync Complete                       ║
+╠═══════════════════════════════════════════════════════════════╣
+
+Added (3):
+  ✅ zoho/creator-batch-update.md
+     By: @dev1 | Date: 2025-01-20 | v1.0.0
+
+  ✅ compliance/hipaa-field-encryption.md
+     By: @dev2 | Date: 2025-01-19 | v1.0.0
+
+  ✅ troubleshooting/catalyst-memory-leak.md
+     By: @dev3 | Date: 2025-01-18 | v1.0.0
+
+Updated (1):
+  🔄 gcp/bigquery-partitioning.md
+     Version: 1.1.0 → 1.2.0
+
+Unchanged: 12 skills
+
+╠═══════════════════════════════════════════════════════════════╣
+║  Total shared skills: 16                                      ║
+║  Location: ~/.claude/skills/shared/                           ║
+╚═══════════════════════════════════════════════════════════════╝
+
+💡 Tip: Run /skill-gaps to see recommendations based on your usage
+```
+
+**If no changes:**
+```
+✅ Already up to date
+
+  Total shared skills: 16
+  Last sync: 2025-01-25 10:30:00
+
+No new or updated skills since last sync.
+```
+
+### Step 4: Update Skill Injector
+
+The sync automatically updates the skill-injector index so new skills are matched:
+
+```
+Updating skill injector index...
+  Added 3 new matching patterns
+  Skills will now auto-inject when relevant context detected
+```
+
+## What Gets Synced
+
+Skills are organized by category:
+
+| Category | Description | Location |
+|----------|-------------|----------|
+| `zoho/` | Zoho Creator, Catalyst, CRM, Deluge | `~/.claude/skills/shared/zoho/` |
+| `gcp/` | BigQuery, Dataflow, Cloud Functions | `~/.claude/skills/shared/gcp/` |
+| `compliance/` | HIPAA, SOC2, PCI-DSS patterns | `~/.claude/skills/shared/compliance/` |
+| `troubleshooting/` | Common issues and solutions | `~/.claude/skills/shared/troubleshooting/` |
+| `general/` | Cross-platform patterns | `~/.claude/skills/shared/general/` |
+
+## How Shared Skills Work
+
+After syncing, shared skills are automatically applied by the skill-injector hook:
+
+1. **File Pattern Matching**: Working on `.ds` files triggers Deluge skills
+2. **Technology Detection**: BigQuery imports trigger GCP skills
+3. **Compliance Mode**: HIPAA mode triggers compliance skills
+4. **Keyword Matching**: Terms like "batch processing" trigger relevant patterns
+
+You don't need to manually invoke shared skills - they're injected into context automatically.
+
+## Browsing Synced Skills
+
+View locally synced skills:
+
+```bash
+# List all shared skills
+ls ~/.claude/skills/shared/
+
+# View a specific skill
+cat ~/.claude/skills/shared/zoho/creator-batch-update.md
+```
+
+Or use the skill index:
+
+```bash
+cat ~/.claude/skills/shared/index.json
+```
+
+## Configuration
+
+Settings in `config/shared-knowledge.json`:
+
+```json
+{
+  "sharedRepo": {
+    "url": "https://github.com/cloudstream/knowledge-base",
+    "branch": "main",
+    "localPath": "~/.claude/repos/knowledge-base",
+    "syncInterval": "daily",
+    "autoSync": true
+  },
+  "sync": {
+    "notifyOnNew": true,
+    "autoUpdateSkillInjector": true
+  }
+}
+```
+
+### Auto-Sync
+
+If `autoSync` is enabled, skills are synced automatically at session start. Manual sync is still useful to:
+
+- Force an immediate update
+- Check for new skills mid-session
+- Troubleshoot sync issues
+
+## Requirements
+
+- **Git**: Must be installed
+- **Network access**: To reach github.com
+- **Repository access**: Read access to cloudstream-knowledge-base (default for all team members)
+
+## Troubleshooting
+
+### "Clone failed: Permission denied"
+You may not have repository access. Contact your team lead.
+
+### "Pull failed: Merge conflicts"
+Your local repo may have uncommitted changes. Try:
+```bash
+cd ~/.claude/repos/knowledge-base
+git reset --hard origin/main
+```
+Then run `/skill-sync` again.
+
+### "Skills not being injected"
+Check that skill-injector hook is enabled:
+```bash
+cat ~/.claude/settings.json | grep skill-injector
+```
+
+### Slow sync
+First sync clones the entire repo. Subsequent syncs only pull changes.
+
+## Related Commands
+
+- `/skill-submit` - Submit a learned skill to the shared repo
+- `/skill-gaps` - Analyze your skill coverage vs team
+- `/learn` - Extract patterns during a session
+
+## Example Session
+
+```
+> /skill-sync
+
+Syncing from cloudstream-knowledge-base...
+
+Added (3):
+  ✅ zoho/creator-batch-update.md (by @dev1, 2025-01-20)
+  ✅ compliance/hipaa-field-encryption.md (by @dev2, 2025-01-19)
+  ✅ troubleshooting/catalyst-memory-leak.md (by @dev3, 2025-01-18)
+
+Updated (1):
+  🔄 gcp/bigquery-partitioning.md (v1.1.0 → v1.2.0)
+
+Unchanged (12):
+  [list omitted for brevity]
+
+Total shared skills: 16
+Run /skill-gaps to see recommendations based on your usage.
+```

package/commands/tdd.md

@@ -0,0 +1,59 @@
+---
+name: tdd
+description: Enforce test-driven development workflow. Scaffold interfaces, generate tests FIRST, then implement minimal code to pass. Ensure 80%+ coverage.
+---
+
+# /tdd [component-name]
+
+Invoke the **tdd-guide** agent on the specified component or feature.
+
+## Parameters
+- `component-name` — Target file, module, or feature to TDD
+
+## Workflow
+1. Agent scaffolds interfaces/types first
+2. Writes failing tests (RED)
+3. Implements minimal code to pass (GREEN)
+4. Refactors while keeping tests green (REFACTOR)
+5. Verifies 80%+ coverage
+
+## When to Use
+- New features or components
+- Bug fixes (reproduce with test first)
+- Refactoring existing code
+- Critical business logic
+
+## Example Output
+
+```
+TDD WORKFLOW: UserService.create()
+
+RED PHASE:
+  ✗ should create user with valid data
+  ✗ should reject duplicate email
+  ✗ should hash password before storing
+
+GREEN PHASE:
+  ✓ should create user with valid data
+  ✓ should reject duplicate email
+  ✓ should hash password before storing
+
+REFACTOR PHASE:
+  - Extracted validation to separate function
+  - Added JSDoc comments
+  - Tests still passing
+
+COVERAGE: 94% (target: 80%)
+```
+
+---
+
+## Related
+
+- **Agent:** [tdd-guide](../agents/tdd-guide.md) - The specialized agent that executes this command
+- **Commands:**
+  - [/plan](./plan.md) - Use first for complex features
+  - [/code-review](./code-review.md) - Review after TDD completes
+  - [/test-coverage](./test-coverage.md) - Verify coverage gaps
+  - [/verify](./verify.md) - Final validation
+- **Skills:** [tdd-workflow](../skills/tdd-workflow/SKILL.md) - Detailed TDD patterns and best practices

package/commands/team-admin.md

@@ -0,0 +1,179 @@
+---
+name: team-admin
+description: Team administration commands for leads and admins. View team status, metrics, skill submissions, and onboarding progress.
+---
+
+# Team Admin Command
+
+Administrative tools for team leads to monitor and manage their team's usage of CloudStream Claude Tools.
+
+## Instructions
+
+When user runs `/team-admin`, provide team administration capabilities based on the subcommand.
+
+### Subcommands
+
+#### `/team-admin status`
+
+Show team fork synchronization status.
+
+**Checks:**
+1. Read `admin/forks.json` for team member forks
+2. For each fork, check if it's behind upstream
+3. Report sync status
+
+**Output:**
+```
+TEAM SYNC STATUS
+
+Upstream: CloudStreamSoftware/css_claude_code (main)
+
+Team Members:
+  alice/css_claude_code    [OK] Up to date
+  bob/css_claude_code      [BEHIND] 3 commits behind
+  charlie/css_claude_code  [OK] Up to date
+
+Action needed: Notify bob to sync their fork
+```
+
+---
+
+#### `/team-admin metrics`
+
+Quick summary of team metrics.
+
+**Reads:** `admin/aggregated-metrics.json` (created by `npm run metrics:aggregate`)
+
+**Output:**
+```
+TEAM METRICS SUMMARY
+
+Period: Last 7 days
+Team Size: 5 developers
+
+Sessions:
+  Total: 127 sessions
+  Avg per developer: 25.4
+  Most active: alice (38 sessions)
+
+Quality Gates:
+  Pass rate: 94%
+  Blocks prevented: 12
+
+Skills:
+  Team skills: 16
+  Learned skills: 8
+  Pending submissions: 2
+
+Run 'npm run metrics:roi' for detailed ROI analysis.
+```
+
+---
+
+#### `/team-admin skills`
+
+List pending skill submissions and recently added skills.
+
+**Output:**
+```
+SKILL STATUS
+
+Pending Submissions (PRs):
+  #45 - zoho-workflow-pattern by alice (2 days ago)
+  #43 - api-error-handling by bob (5 days ago)
+
+Recently Merged (last 30 days):
+  deluge-pagination - by charlie (merged 3 days ago)
+  creator-form-validation - by alice (merged 1 week ago)
+
+Team Skills: 16 active
+Learned Skills: 8 active
+
+To review: gh pr view 45
+```
+
+---
+
+#### `/team-admin onboarding`
+
+Show new hire onboarding progress.
+
+**Checks:**
+- Recent forks (< 30 days old)
+- Tutorial completion status (via GitHub API if possible, or manual check)
+
+**Output:**
+```
+ONBOARDING STATUS
+
+New Team Members (last 30 days):
+
+  dave (joined 5 days ago)
+    Fork: [OK] Created
+    Dependencies: [OK] Installed
+    Tutorial: [IN PROGRESS] 4/15 lessons
+    First commit: [PENDING]
+    Action: Check in with dave on tutorial progress
+
+  eve (joined 2 days ago)
+    Fork: [OK] Created
+    Dependencies: [UNKNOWN] Check manually
+    Tutorial: [NOT STARTED]
+    First commit: [PENDING]
+    Action: Schedule setup session with eve
+
+Fully onboarded (last 90 days): 3 developers
+```
+
+---
+
+### Admin Configuration
+
+Team admin commands require `admin/forks.json`:
+
+```json
+{
+  "upstream": "CloudStreamSoftware/css_claude_code",
+  "forks": [
+    { "user": "alice", "repo": "css_claude_code", "joined": "2025-01-01" },
+    { "user": "bob", "repo": "css_claude_code", "joined": "2025-01-15" },
+    { "user": "charlie", "repo": "css_claude_code", "joined": "2025-02-01" }
+  ]
+}
+```
+
+## Arguments
+
+$ARGUMENTS should be one of:
+- `status` - Fork sync status
+- `metrics` - Quick metrics summary
+- `skills` - Skill submission status
+- `onboarding` - New hire progress
+- (none) - Show help
+
+## Examples
+
+```
+/team-admin status      # Check fork sync
+/team-admin metrics     # View team metrics
+/team-admin skills      # Check skill submissions
+/team-admin onboarding  # Track new hire progress
+```
+
+## Prerequisites
+
+- Must have `admin/forks.json` configured
+- GitHub CLI (`gh`) should be authenticated
+- For metrics: Run `npm run metrics:aggregate` first
+
+## Related Commands
+
+- `/health-check` - Individual health check
+- `/diagnose` - Individual diagnostics
+- `/skill-sync` - Sync skills from central repo
+- `/skill-submit` - Submit new skill
+
+## See Also
+
+- `docs/ADMIN-RUNBOOK.md` - Full admin operations guide
+- `docs/TEAM-ARCHITECTURE.md` - How the fork model works