@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/tutorial/tracks/accelerated/day-5-hooks-skills.md

@@ -0,0 +1,344 @@
+# Day 5: Hooks System & Skills Deep Dive
+
+**Duration**: 3-4 hours
+**Covers**: Standard Lessons 7-8, 11-12 (Hooks, MCP, Skills, Rules)
+
+---
+
+## Part 1: The Hooks System
+
+Hooks are scripts that run automatically at specific lifecycle events, enforcing quality without manual intervention.
+
+### Hook Lifecycle Events
+
+| Hook Type | When It Runs | Use Cases |
+|-----------|--------------|-----------|
+| **PreToolUse** | Before a tool executes | Block dangerous ops, validate inputs |
+| **PostToolUse** | After a tool completes | Auto-format, type check, warn |
+| **Stop** | When Claude response ends | Final validation |
+| **SessionStart** | When session begins | Load context, detect environment |
+| **SessionEnd** | When session closes | Persist state, capture patterns |
+| **PreCompact** | Before context compaction | Save important state |
+
+### Current Production Hooks
+
+#### Blocking Hooks (exit 1 = operation stopped)
+
+| Hook | What It Does | Trigger |
+|------|--------------|---------|
+| Credential Check | Scans for hardcoded secrets | Edit/Write operations |
+| Dev Server Block | BLOCKS dev servers outside tmux | `npm run dev` |
+| Doc Blocker | BLOCKS random .md file creation | Write to non-README .md |
+| Quality Gates | BLOCKS code violating critical rules | Edit/Write operations |
+
+#### Warning Hooks (stderr only, operation continues)
+
+| Hook | What It Does | Trigger |
+|------|--------------|---------|
+| Tmux Reminder | Suggests tmux for long commands | npm install, docker, pytest |
+| Git Push Review | Reminds to review before push | `git push` commands |
+| Console.log Warning | Warns about console.log | After editing JS/TS |
+
+#### Auto-Enhancement Hooks
+
+| Hook | What It Does | Trigger |
+|------|--------------|---------|
+| Prettier Format | Auto-formats JS/TS files | After editing .js/.ts |
+| TypeScript Check | Runs `tsc --noEmit` | After editing .ts/.tsx |
+| Skill Injector | Injects relevant skill guidance | PreToolUse on code files |
+
+#### Session Hooks
+
+| Hook | What It Does |
+|------|--------------|
+| SessionStart | Loads previous context, detects package manager |
+| SessionEnd | Persists session state, extracts patterns |
+| PreCompact | Saves state before memory trim |
+
+### Hook Configuration
+
+Hooks are defined in `hooks/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "tool == \"Edit\" || tool == \"Write\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/credential-check.js"
+          }
+        ],
+        "description": "Scan for hardcoded credentials"
+      }
+    ]
+  }
+}
+```
+
+### Matcher Syntax
+
+| Matcher | Meaning |
+|---------|---------|
+| `*` | Always run |
+| `tool == "Edit"` | Only on Edit tool |
+| `tool == "Bash" && tool_input.command matches "git push"` | Specific bash command |
+| `tool_input.file_path matches "\\.ts$"` | TypeScript files |
+
+---
+
+## Part 2: MCP Servers
+
+MCP (Model Context Protocol) provides external capabilities to Claude Code.
+
+### MCP Servers in This System
+
+| Server | Purpose | Key Functions |
+|--------|---------|---------------|
+| **Memory** | Persistent knowledge graph | Stores entities, relations across sessions |
+| **Context7** | Library documentation lookup | Real-time docs for npm packages |
+| **Sequential Thinking** | Structured reasoning | Chain-of-thought for complex problems |
+
+### Memory MCP
+
+Enables cross-session memory:
+
+```javascript
+// Store knowledge
+mcp__plugin_memory__create_entities({
+  entities: [{ name: "UserPreferences", entityType: "config", observations: ["dark mode", "vim bindings"] }]
+})
+
+// Query knowledge
+mcp__plugin_memory__search_nodes({ query: "user preferences" })
+```
+
+### Using MCP in Practice
+
+Run `/health-check` to verify MCP servers are connected:
+
+```
+/health-check
+```
+
+Output shows:
+- Memory MCP: Connected/Disconnected
+- Context7: Available/Unavailable
+- Sequential Thinking: Ready/Not configured
+
+---
+
+## Part 3: Skills System
+
+Skills are reusable knowledge packages that inform how Claude approaches domains.
+
+### The 15 Skills by Category
+
+| Category | Skills | Purpose |
+|----------|--------|---------|
+| **Development** | coding-standards, tdd-workflow, backend-patterns, frontend-patterns | Coding patterns |
+| **Quality** | security-review | Security and vulnerability detection |
+| **Platform** | zoho-patterns, bigquery-patterns, gcp-data-engineering | Platform-specific |
+| **Compliance** | compliance-patterns | Regulatory requirements |
+| **Process** | consultancy-workflows, cloudstream-project-template, tutorial, strategic-compact, continuous-learning, continuous-learning-v2 | Workflow patterns |
+
+### Skill Anatomy
+
+Every skill has a `SKILL.md`:
+
+```markdown
+---
+name: skill-name
+description: One-line description
+version: 1.0.0
+status: active
+---
+
+# Skill Title
+
+## When to Activate
+- Trigger conditions
+
+## Core Patterns
+- Key approaches
+
+## Anti-Patterns
+- What NOT to do
+
+## Examples
+- Demonstrations
+```
+
+### Skill-Agent Relationships
+
+Skills inform agents:
+
+| Agent | Primary Skills |
+|-------|---------------|
+| planner | All skills (comprehensive planning) |
+| tdd-guide | tdd-workflow, coding-standards |
+| code-reviewer | coding-standards, security-review |
+| deluge-reviewer | zoho-patterns/deluge |
+| creator-architect | zoho-patterns/creator |
+| security-reviewer | security-review, compliance-patterns |
+
+---
+
+## Part 4: Rules System
+
+Rules define behavioral constraints. They load in priority order.
+
+### Rule Loading Order
+
+1. **Global CLAUDE.md** - System-wide defaults
+2. **Project .claude/CLAUDE.md** - Project-specific rules
+3. **Directory CLAUDE.md files** - Local overrides
+
+### Rule Frontmatter
+
+```markdown
+---
+description: What this ruleset does
+globs: src/**/*.ts
+alwaysApply: true
+---
+
+# Rules Content
+
+## Standards
+- Rule 1
+- Rule 2
+```
+
+### Key Fields
+
+| Field | Purpose |
+|-------|---------|
+| `description` | Human-readable summary |
+| `globs` | File patterns to apply rules to |
+| `alwaysApply` | Whether rules are always active |
+
+---
+
+## Exercises
+
+### Exercise 5.1: Examine Hooks Configuration
+
+```bash
+# View hooks configuration
+cat hooks/hooks.json
+
+# Count hooks by type
+grep -c "PreToolUse\|PostToolUse\|SessionStart" hooks/hooks.json
+```
+
+Questions:
+- How many PreToolUse hooks exist?
+- Which hooks are blocking vs. warning?
+
+### Exercise 5.2: Trigger a Hook
+
+1. Create a TypeScript file with an issue:
+```typescript
+const x = 1;
+console.log(x);  // Will trigger warning hook
+```
+
+2. Observe:
+   - Prettier formats the file
+   - TypeScript check runs
+   - Console.log warning appears
+
+### Exercise 5.3: Verify MCP Status
+
+```
+/health-check
+```
+
+Check:
+- Memory MCP connection status
+- Other MCP servers available
+
+### Exercise 5.4: Explore Skills
+
+```bash
+# List all skills
+ls skills/
+
+# Read a skill definition
+cat skills/zoho-patterns/SKILL.md
+
+# Explore skill subdirectories
+ls skills/zoho-patterns/
+```
+
+### Exercise 5.5: Examine Rules Loading
+
+```bash
+# View global rules
+cat CLAUDE.md
+
+# Check for project rules
+ls -la .claude/
+
+# View frontmatter patterns
+grep -A 5 "^---" CLAUDE.md
+```
+
+---
+
+## Verification Checklist
+
+Before proceeding to Day 6, confirm:
+
+- [ ] Understand the 6 hook lifecycle events
+- [ ] Know which hooks block vs. warn
+- [ ] Saw hooks fire when editing a file
+- [ ] Verified MCP status with `/health-check`
+- [ ] Can list and navigate the 15 active skills
+- [ ] Understand skill-agent relationships
+- [ ] Know the rules loading priority order
+
+---
+
+## Key Takeaways
+
+1. **Hooks are invisible guardrails** - quality enforcement without manual steps
+2. **Blocking hooks prevent bad operations** - credentials, outside-tmux servers
+3. **Skills inform agents** - domain knowledge embedded in the system
+4. **Rules cascade** - global → project → directory
+5. **MCP enables persistence** - memory across sessions
+
+---
+
+## Quick Reference
+
+### Hook Types
+```
+BLOCKING: credential-check, dev-server-block, doc-blocker, quality-gates
+WARNING:  console-log, tmux-reminder, git-push-review
+AUTO:     prettier-format, typescript-check, skill-injector
+SESSION:  session-start, session-end, pre-compact
+```
+
+### Skill Categories
+```
+DEVELOPMENT:  coding-standards, tdd-workflow, backend-patterns, frontend-patterns
+QUALITY:      security-review
+PLATFORM:     zoho-patterns, bigquery-patterns, gcp-data-engineering
+COMPLIANCE:   compliance-patterns
+PROCESS:      consultancy-workflows, project-template, tutorial, strategic-compact, continuous-learning
+```
+
+### Rules Loading
+```
+1. Global CLAUDE.md (system defaults)
+2. .claude/CLAUDE.md (project rules)
+3. Directory CLAUDE.md (local overrides)
+```
+
+---
+
+**Day 5 Complete** | Next: [Day 6 - Client Management & Testing](day-6-client-testing.md)

package/skills/tutorial/tracks/accelerated/day-6-client-testing.md

@@ -0,0 +1,386 @@
+# Day 6: Client Management & Testing
+
+**Duration**: 3-4 hours
+**Covers**: Standard Lessons 9-10 (Client Management, E2E Testing)
+**Assessment**: Checkpoint 2 after this day
+
+---
+
+## Part 1: Client Management
+
+CloudStream is a consultancy serving multiple clients. Proper isolation is critical.
+
+### Why Client Isolation Matters
+
+| Risk | Consequence |
+|------|-------------|
+| Data leak | Client A's data visible to Client B |
+| Config leak | Wrong API keys used |
+| Compliance breach | HIPAA data in non-HIPAA project |
+| Billing confusion | Time tracked to wrong client |
+
+### Client Context System
+
+Each client has isolated:
+- Environment variables (API keys, credentials)
+- Compliance mode (HIPAA, SOC2, PCI-DSS)
+- Project-specific CLAUDE.md rules
+- Session memory and learned patterns
+
+### Key Commands
+
+```
+/client-switch CLIENT-ID    - Switch to client context
+/handoff                    - Generate handoff documentation
+```
+
+### /client-switch
+
+Switches to a client context:
+
+```
+/client-switch CLT-042
+```
+
+This:
+1. Loads client's environment variables
+2. Sets appropriate compliance mode
+3. Loads client-specific rules
+4. Displays recent activity summary
+
+### /handoff
+
+Generates comprehensive handoff documentation:
+
+```
+/handoff
+```
+
+Produces:
+- Project status summary
+- Outstanding tasks
+- Known issues and workarounds
+- Configuration details
+- Team contact information
+
+Use when:
+- Transitioning client to another developer
+- Client completing engagement
+- Quarterly documentation refresh
+
+### Client Configuration
+
+Client settings in `.claude/clients/CLIENT-ID/`:
+
+```
+.claude/clients/CLT-042/
+├── config.json       # Client settings
+├── .env              # Client environment variables
+├── CLAUDE.md         # Client-specific rules
+└── recent-activity/  # Session logs
+```
+
+---
+
+## Part 2: Testing & E2E
+
+Comprehensive testing ensures quality and catches regressions.
+
+### The Testing Pyramid
+
+```
+        /\
+       /  \
+      / E2E \      ← Fewer, slower, critical paths
+     /--------\
+    /Integration\   ← Medium, API boundaries
+   /--------------\
+  /   Unit Tests   \  ← Many, fast, isolated
+ /------------------\
+```
+
+### Key Testing Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/tdd` | Test-driven development | All new code |
+| `/e2e` | End-to-end Playwright tests | Critical user journeys |
+| `/build-fix` | Fix build/type errors | When builds fail |
+| `/test-coverage` | Analyze and increase coverage | Before PR, after features |
+| `/eval` | Run quality evaluations | Quality gates, benchmarks |
+
+### /e2e Command
+
+Generates and runs end-to-end tests:
+
+```
+/e2e "user login flow"
+```
+
+This:
+1. Creates Playwright test file
+2. Defines user journey steps
+3. Runs the test
+4. Captures screenshots/videos
+5. Reports results
+
+### /build-fix Command
+
+Iteratively fixes build errors:
+
+```
+/build-fix
+```
+
+This:
+1. Parses current build errors
+2. Fixes one error at a time
+3. Re-runs build
+4. Repeats until green
+
+### /test-coverage Command
+
+Analyzes and improves coverage:
+
+```
+/test-coverage
+```
+
+This:
+1. Runs coverage analysis
+2. Identifies uncovered lines
+3. Generates missing tests
+4. Reports coverage percentage
+
+Target: 80%+ coverage
+
+### /eval Command
+
+Runs quality evaluations:
+
+```
+/eval check auth-login
+```
+
+Evals are defined tests for specific functionality. They ensure:
+- Regressions are caught
+- Quality remains high
+- Critical paths work
+
+---
+
+## Part 3: Testing Patterns
+
+### TDD Workflow (Review)
+
+```
+/tdd "feature name"
+```
+
+1. **RED**: Write failing test
+2. **GREEN**: Minimal code to pass
+3. **REFACTOR**: Clean up while green
+
+### E2E Test Structure
+
+```javascript
+// tests/e2e/login.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  // Arrange
+  await page.goto('/login');
+
+  // Act
+  await page.fill('[name="email"]', 'user@example.com');
+  await page.fill('[name="password"]', 'password123');
+  await page.click('button[type="submit"]');
+
+  // Assert
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.locator('h1')).toHaveText('Welcome');
+});
+```
+
+### Coverage Strategy
+
+| Coverage Level | Target | For |
+|----------------|--------|-----|
+| Unit | 80%+ | Business logic |
+| Integration | 70%+ | API endpoints |
+| E2E | Critical paths | User journeys |
+
+### Handling Flaky Tests
+
+E2E tests can be flaky. The system:
+1. Retries failed tests (2x)
+2. Captures screenshots on failure
+3. Records video for debugging
+4. Quarantines persistently flaky tests
+
+---
+
+## Exercises
+
+### Exercise 6.1: Client Switch Simulation
+
+If you have client configurations:
+
+```
+/client-switch CLT-001
+```
+
+Observe:
+- Environment loaded message
+- Compliance mode indication
+- Recent activity display
+
+If no clients configured:
+```
+# Create mock client config
+mkdir -p .claude/clients/TEST-001
+echo '{"name": "Test Client", "compliance": "standard"}' > .claude/clients/TEST-001/config.json
+```
+
+### Exercise 6.2: Generate Handoff Documentation
+
+```
+/handoff
+```
+
+Review the generated documentation:
+- Is project status accurate?
+- Are known issues documented?
+- Is configuration captured?
+
+### Exercise 6.3: Write E2E Test
+
+```
+/e2e "user signup flow"
+```
+
+Observe:
+- Test file generation
+- Step definitions
+- Assertion patterns
+
+### Exercise 6.4: Fix Build Errors
+
+Create a file with type errors:
+
+```typescript
+// broken.ts
+const x: number = "not a number";  // Type error
+```
+
+Run:
+```
+/build-fix
+```
+
+Observe:
+- Error parsing
+- Suggested fix
+- Verification
+
+### Exercise 6.5: Coverage Analysis
+
+```
+/test-coverage
+```
+
+Review:
+- Current coverage percentage
+- Uncovered lines identified
+- Suggested tests
+
+### Exercise 6.6: Run Eval
+
+```
+/eval list
+```
+
+See available evals, then run one:
+
+```
+/eval check [eval-name]
+```
+
+---
+
+## Verification Checklist
+
+Before taking Checkpoint 2, confirm:
+
+- [ ] Understand client isolation importance
+- [ ] Can use `/client-switch` command
+- [ ] Can generate handoff documentation
+- [ ] Know the testing pyramid
+- [ ] Practiced `/e2e` test generation
+- [ ] Used `/build-fix` for error resolution
+- [ ] Ran `/test-coverage` analysis
+- [ ] Understand eval system basics
+
+---
+
+## Checkpoint 2 Assessment
+
+After completing Day 6, you must pass Checkpoint 2 before proceeding.
+
+Run:
+```
+/tutorial checkpoint-2
+```
+
+Topics covered:
+- Compliance modes (HIPAA/SOC2/PCI-DSS)
+- Zoho platform development
+- Hooks system
+- Skills and rules
+- Client management
+- Testing (E2E, coverage, evals)
+
+Passing score: 80%
+Max retakes: 2
+
+See: [Checkpoint 2 Assessment](assessment/checkpoint-2.md)
+
+---
+
+## Key Takeaways
+
+1. **Client isolation is non-negotiable** - data leaks have legal consequences
+2. **Always handoff properly** - documentation prevents knowledge loss
+3. **Testing pyramid matters** - many unit tests, fewer E2E
+4. **80% coverage target** - quality gate for production
+5. **E2E tests critical paths** - user journeys that can't fail
+
+---
+
+## Quick Reference
+
+### Client Commands
+```
+/client-switch CLIENT-ID    - Switch context
+/handoff                    - Generate handoff docs
+```
+
+### Testing Commands
+```
+/tdd "name"           - Test-driven development
+/e2e "journey"        - End-to-end tests
+/build-fix            - Fix build errors
+/test-coverage        - Coverage analysis
+/eval check [name]    - Run evaluation
+```
+
+### Testing Targets
+```
+Unit:        80%+ coverage
+Integration: 70%+ coverage
+E2E:         All critical paths
+```
+
+---
+
+**Day 6 Complete** | **CHECKPOINT 2 REQUIRED** | Next: [Day 7 - Graduation](day-7-graduation.md)