@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/tutorial/lessons/09-client-management.md

@@ -0,0 +1,215 @@
+# Lesson 9: Client Management
+
+CloudStream is a consultancy. Managing multiple clients requires isolation, context switching, and handoff documentation.
+
+## Concept
+
+Client management commands ensure you never mix contexts:
+
+| Command | Purpose | What It Does |
+|---------|---------|--------------|
+| `/client-switch` | Switch client context | Loads client CLAUDE.md, sets compliance mode, shows recent activity |
+| `/handoff` | Generate handoff docs | Creates comprehensive project documentation for transitions |
+
+## Why This Matters
+
+Without client isolation:
+- Credentials get mixed up
+- Wrong compliance mode applied
+- Context leaks between projects
+- Handoffs are incomplete
+
+With proper management:
+- Clean context boundaries
+- Compliance automatically set
+- Seamless project transitions
+- Professional handoff documentation
+
+## Client Context Structure
+
+Each client should have:
+
+```
+clients/
+  acme-corp/
+    CLAUDE.md           # Client-specific config
+    .env.local          # Client credentials
+    activity-log.md     # Recent work (auto-generated)
+  beta-inc/
+    CLAUDE.md
+    .env.local
+    activity-log.md
+```
+
+### Client CLAUDE.md Example
+
+```markdown
+# ACME Corp Project
+
+## Company Context
+Enterprise SaaS company, 500 employees
+Primary contact: jane@acme.com
+
+## Technology Stack
+- Zoho Creator (CRM customizations)
+- Zoho Catalyst (serverless functions)
+- GCP BigQuery (analytics)
+
+## Compliance Mode: soc2
+SOC2 audit scheduled for Q2
+
+## Billing
+Rate: $150/hr
+Time tracking: Required
+```
+
+## Exercise
+
+### Exercise 9.1: Client Switching
+
+**Step 1**: List available clients:
+```
+/client-switch
+```
+
+**What happens:**
+- Scans `clients/` directory
+- Shows available client contexts
+- Displays current client (if set)
+
+**Step 2**: Switch to a client:
+```
+/client-switch acme-corp
+```
+
+**What happens:**
+1. Loads `clients/acme-corp/CLAUDE.md`
+2. Sets compliance mode from config
+3. Loads environment variables from `.env.local`
+4. Displays recent activity summary
+5. Updates session context
+
+### Exercise 9.2: Handoff Documentation
+
+Generate comprehensive handoff documentation:
+```
+/handoff
+```
+
+**What the `doc-updater` agent generates:**
+
+1. **Project Summary**
+   - Current state
+   - Key stakeholders
+   - Project timeline
+
+2. **Architecture Overview**
+   - System components
+   - Integration points
+   - Data flows
+
+3. **Setup Instructions**
+   - Environment requirements
+   - Installation steps
+   - Configuration needed
+
+4. **Outstanding Tasks**
+   - In-progress work
+   - Known issues
+   - Backlog items
+
+5. **Runbook**
+   - Common operations
+   - Troubleshooting guides
+   - Contact information
+
+### Exercise 9.3: Creating a New Client
+
+**Step 1**: Create client directory:
+```bash
+mkdir -p clients/new-client
+```
+
+**Step 2**: Create client CLAUDE.md:
+```bash
+cat > clients/new-client/CLAUDE.md << 'EOF'
+# New Client Project
+
+## Company Context
+[Description]
+
+## Technology Stack
+[Stack details]
+
+## Compliance Mode: hipaa
+[If applicable]
+
+## Billing
+Rate: $XXX/hr
+EOF
+```
+
+**Step 3**: Switch to the new client:
+```
+/client-switch new-client
+```
+
+## Verification
+
+You've completed this exercise successfully if:
+- [ ] `/client-switch` showed available clients or prompted to create
+- [ ] You understand client directory structure
+- [ ] `/handoff` generated documentation (or you understand the sections)
+- [ ] You can create a new client context
+
+## Multi-Client Workflow
+
+```
+MORNING: Check which client you're working on
+  /client-switch                    # Show current context
+
+STARTING WORK ON CLIENT:
+  /client-switch acme-corp          # Switch context
+  # Compliance mode auto-set
+  # Credentials loaded
+  # Recent activity shown
+
+DURING WORK:
+  /plan <feature>                   # Plan with client context
+  /tdd <component>                  # Tests include compliance
+  /code-review                      # Review against client standards
+
+END OF ENGAGEMENT:
+  /handoff                          # Generate transition docs
+  # Everything documented
+  # Clean handoff ready
+```
+
+## Agent Reference
+
+| Agent | Command | What It Does |
+|-------|---------|--------------|
+| **doc-updater** | `/handoff` | Generates comprehensive project documentation |
+
+## Security Best Practices
+
+1. **Never commit `.env.local`** - Client credentials stay local
+2. **Separate credentials per client** - No shared tokens
+3. **Review before switching** - Ensure previous work is committed
+4. **Verify compliance mode** - Check it matches client requirements
+5. **Clean handoffs** - Document everything before transition
+
+## Key Takeaway
+
+Client management is about **isolation and professionalism**. Use `/client-switch` to set context, `/handoff` to document transitions. Never mix client contexts.
+
+## Next Steps
+
+In Lesson 10, you'll learn about testing and quality commands - E2E testing, build error resolution, and coverage analysis.
+
+---
+
+**Commands learned**: `/client-switch`, `/handoff`
+**Agent introduced**: doc-updater
+**Key concept**: Client isolation and professional handoffs
+**Progress**: 10 of 15 lessons complete

package/skills/tutorial/lessons/10-testing-e2e.md

@@ -0,0 +1,260 @@
+# Lesson 10: Testing & E2E
+
+Beyond unit tests, you need end-to-end testing, build error resolution, and coverage analysis to ensure quality.
+
+## Concept
+
+Quality assurance requires multiple layers:
+
+| Command | Purpose | Agent |
+|---------|---------|-------|
+| `/e2e` | End-to-end tests | e2e-runner |
+| `/build-fix` | Fix build errors | build-error-resolver |
+| `/test-coverage` | Analyze coverage | tdd-guide |
+| `/eval` | Track quality metrics | (self-contained) |
+
+## Why This Matters
+
+**Unit tests** verify individual functions. **E2E tests** verify user journeys.
+
+Without E2E:
+- Integration bugs slip through
+- User flows break silently
+- Regressions go unnoticed
+
+Without build error resolution:
+- TypeScript errors pile up
+- Broken builds block deployments
+- Manual fixes are inconsistent
+
+## Exercise
+
+### Exercise 10.1: End-to-End Testing
+
+Generate and run E2E tests for a user journey:
+```
+/e2e "user login flow"
+```
+
+**What the `e2e-runner` agent does:**
+
+1. **Creates Playwright test file**
+   ```typescript
+   // tests/e2e/login.spec.ts
+   import { test, expect } from '@playwright/test';
+
+   test('user can log in successfully', async ({ page }) => {
+     await page.goto('/login');
+     await page.fill('[name="email"]', 'test@example.com');
+     await page.fill('[name="password"]', 'password123');
+     await page.click('button[type="submit"]');
+     await expect(page).toHaveURL('/dashboard');
+   });
+   ```
+
+2. **Defines user journey steps**
+   - Navigate to page
+   - Fill form fields
+   - Submit action
+   - Verify result
+
+3. **Runs the tests**
+   ```bash
+   npx playwright test tests/e2e/login.spec.ts
+   ```
+
+4. **Captures artifacts on failure**
+   - Screenshots
+   - Videos
+   - Trace files
+
+5. **Reports results**
+   ```
+   E2E Test Results:
+     ✓ user can log in successfully (2.3s)
+     ✓ user sees error on invalid credentials (1.8s)
+     ✓ user can reset password (3.1s)
+
+   3 passed (7.2s)
+   ```
+
+### Exercise 10.2: Build Error Resolution
+
+When your build fails, fix errors systematically:
+```
+/build-fix
+```
+
+**What the `build-error-resolver` agent does:**
+
+1. **Runs build command**
+   ```bash
+   npm run build
+   # or
+   npx tsc --noEmit
+   ```
+
+2. **Parses error output**
+   ```
+   src/api/auth.ts:45:3 - error TS2322: Type 'string' is not assignable to type 'number'.
+   src/utils/format.ts:12:5 - error TS2345: Argument of type 'undefined' is not assignable...
+   ```
+
+3. **Fixes each error with minimal changes**
+   - One error at a time
+   - Smallest possible diff
+   - No unrelated refactoring
+
+4. **Re-runs build to verify**
+   - Confirms fix worked
+   - Checks for new errors
+
+5. **Repeats until build passes**
+   ```
+   Build Error Resolution:
+     ✓ Fixed: src/api/auth.ts:45 - type mismatch
+     ✓ Fixed: src/utils/format.ts:12 - undefined argument
+     ✓ Build passes
+
+   2 errors fixed in 3 iterations
+   ```
+
+### Exercise 10.3: Test Coverage Analysis
+
+Analyze test coverage for the project:
+```
+/test-coverage
+```
+
+**What the `tdd-guide` agent does:**
+
+1. **Runs coverage command**
+   ```bash
+   npm test -- --coverage
+   ```
+
+2. **Parses coverage report**
+   ```
+   Coverage Summary:
+     Statements: 78.5%
+     Branches: 65.2%
+     Functions: 82.1%
+     Lines: 79.3%
+   ```
+
+3. **Identifies files below 80% threshold**
+   ```
+   Critical Gaps (below 80%):
+   1. src/api/auth.ts - 45% (needs: login, logout, refresh tests)
+   2. src/utils/validate.ts - 62% (needs: edge case tests)
+   ```
+
+4. **Suggests tests for uncovered paths**
+   - Prioritizes by risk (critical paths first)
+   - Provides specific test suggestions
+   - Estimates effort to reach 80%
+
+### Exercise 10.4: Evaluation System
+
+Create and run evaluations to track quality over time:
+```
+/eval
+```
+
+**Creating an eval case:**
+```
+/eval create "API response times"
+```
+
+**Running evals:**
+```
+/eval run
+```
+
+**What the eval system tracks:**
+- Test pass rate
+- Coverage percentage
+- Lint error count
+- Build time
+- Bundle size
+
+**Expected output:**
+```
+Evaluation Results:
+  Test Pass Rate: 98.5% (↑ 0.5%)
+  Coverage: 82.3% (↑ 2.1%)
+  Lint Errors: 0 (same)
+  Build Time: 12.3s (↓ 0.8s)
+
+Trend: IMPROVING
+```
+
+## Verification
+
+You've completed this exercise successfully if:
+- [ ] `/e2e` created a Playwright test (or you understand the pattern)
+- [ ] `/build-fix` demonstrated error resolution workflow
+- [ ] `/test-coverage` showed coverage percentages
+- [ ] You understand the 80% coverage target
+- [ ] `/eval` concepts make sense (tracking metrics over time)
+
+## The Quality Workflow
+
+Integrate all quality commands:
+
+```
+DEVELOPMENT:
+  /tdd <component>           # Tests first (target 80%+)
+
+BEFORE COMMIT:
+  /test-coverage             # Verify coverage achieved
+  /build-fix                 # Fix any build errors
+  /code-review               # Quality review
+
+BEFORE DEPLOY:
+  /e2e "critical flows"      # Verify user journeys
+  /eval run                  # Check quality metrics
+  /verify                    # Final validation
+```
+
+## Agent Reference
+
+| Agent | Command | Specialty |
+|-------|---------|-----------|
+| **e2e-runner** | `/e2e` | Playwright tests, user journeys, artifact capture |
+| **build-error-resolver** | `/build-fix` | TypeScript/build error fixing with minimal diffs |
+| **tdd-guide** | `/test-coverage`, `/tdd` | Coverage analysis, test-driven development |
+| **code-reviewer** | `/code-review` | Quality review, code standards |
+| **security-reviewer** | (proactive) | Security-specific quality checks |
+
+## E2E Best Practices
+
+1. **Test critical paths first** - Login, checkout, core features
+2. **Use stable selectors** - `data-testid` over CSS classes
+3. **Handle async** - Wait for elements, not arbitrary timeouts
+4. **Isolate tests** - Each test should run independently
+5. **Capture artifacts** - Screenshots/videos for debugging
+
+## Coverage Guidelines
+
+| Coverage Level | Quality |
+|----------------|---------|
+| < 60% | Critical gap - immediate action needed |
+| 60-79% | Below target - prioritize coverage work |
+| 80-89% | Target achieved - maintain coverage |
+| 90%+ | Excellent - don't sacrifice quality for numbers |
+
+## Key Takeaway
+
+Quality is multi-layered: unit tests, E2E tests, coverage, and metrics. Use `/e2e` for user journeys, `/build-fix` for errors, `/test-coverage` for gaps, and `/eval` for trends.
+
+## Next Steps
+
+In Lesson 11, you'll dive deep into the Skills system - all 16 skills and their relationships to agents.
+
+---
+
+**Commands learned**: `/e2e`, `/build-fix`, `/test-coverage`, `/eval`
+**Agents introduced**: e2e-runner, build-error-resolver, tdd-guide (coverage role)
+**Key concept**: Multi-layer quality assurance
+**Progress**: 11 of 15 lessons complete