@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/tutorial/lessons/11-skills-deep-dive.md

@@ -0,0 +1,272 @@
+# Lesson 11: Skills Deep Dive
+
+Skills are reusable knowledge packages that inform how Claude approaches specific domains.
+
+## Concept
+
+The system includes 16 skills across 5 categories:
+
+| Category | Skills | Purpose |
+|----------|--------|---------|
+| **Development** | 4 skills | Coding patterns, testing, frontend, backend |
+| **Quality** | 1 skill | Security review and vulnerability detection |
+| **Platform** | 3 skills | Zoho, BigQuery, GCP data engineering |
+| **Compliance** | 1 skill | HIPAA, SOC2, PCI-DSS patterns |
+| **Process** | 7 skills | Workflows, templates, learning (v1 + v2), compaction |
+
+## Why This Matters
+
+Skills provide:
+1. **Consistent patterns** - Same approach regardless of who's working
+2. **Domain expertise** - Deep knowledge embedded in the system
+3. **Teachable patterns** - New team members learn through skills
+4. **Extensibility** - Add new skills without modifying core system
+
+When an agent works on a task, it consults relevant skills for guidance.
+
+## The 15 Skills
+
+### Development Skills (4)
+
+| Skill | Location | Purpose |
+|-------|----------|---------|
+| **coding-standards** | `skills/coding-standards/` | JS/TS/Deluge style guides, naming conventions |
+| **tdd-workflow** | `skills/tdd-workflow/` | Test-driven development patterns (RED/GREEN/REFACTOR) |
+| **backend-patterns** | `skills/backend-patterns/` | Node.js, Express, Catalyst function patterns |
+| **frontend-patterns** | `skills/frontend-patterns/` | React, Next.js, Widget development patterns |
+
+### Quality Skills (1)
+
+| Skill | Location | Purpose |
+|-------|----------|---------|
+| **security-review** | `skills/security-review/` | OWASP Top 10, vulnerability detection patterns |
+
+### Platform Skills (3)
+
+| Skill | Location | Purpose |
+|-------|----------|---------|
+| **zoho-patterns** | `skills/zoho-patterns/` | Creator, Catalyst, Deluge, Analytics patterns |
+| **bigquery-patterns** | `skills/bigquery-patterns/` | Data warehouse queries, optimization, partitioning |
+| **gcp-data-engineering** | `skills/gcp-data-engineering/` | Medallion architecture, Dataflow, dbt patterns |
+
+### Compliance Skill (1)
+
+| Skill | Location | Purpose |
+|-------|----------|---------|
+| **compliance-patterns** | `skills/compliance-patterns/` | HIPAA audit logging, SOC2 change management, PCI tokenization |
+
+### Process Skills (6)
+
+| Skill | Location | Purpose |
+|-------|----------|---------|
+| **consultancy-workflows** | `skills/consultancy-workflows/` | Client isolation, handoff, time tracking |
+| **cloudstream-project-template** | `skills/cloudstream-project-template/` | Project structure standards |
+| **tutorial** | `skills/tutorial/` | This tutorial system |
+| **strategic-compact** | `skills/strategic-compact/` | Context management, compaction triggers |
+| **continuous-learning** | `skills/continuous-learning/` | Pattern extraction from sessions |
+| **continuous-learning-v2** | `skills/continuous-learning-v2/` | Instinct-based learning with confidence scoring |
+
+## Skill Anatomy
+
+Every skill has a `SKILL.md` file with this structure:
+
+```markdown
+---
+name: skill-name
+description: One-line description
+---
+
+# Skill Title
+
+## When to Activate
+- Trigger conditions for this skill
+
+## Core Patterns
+- Key patterns and approaches
+
+## Anti-Patterns
+- What NOT to do
+
+## Examples
+- Practical demonstrations
+```
+
+Skills can also have subdirectories for complex domains:
+
+```
+skills/zoho-patterns/
+├── SKILL.md           # Main skill definition
+├── creator/           # Creator-specific patterns
+│   ├── forms.md
+│   └── workflows.md
+├── catalyst/          # Catalyst-specific patterns
+│   └── functions.md
+├── deluge/           # Deluge-specific patterns
+│   ├── syntax.md
+│   └── gotchas.md
+└── integrations/     # Cross-platform patterns
+    └── crm-books.md
+```
+
+## Skill-Agent Relationships
+
+Skills inform agents. Here's which skills support which agents:
+
+| Agent | Primary Skills |
+|-------|---------------|
+| **planner** | All skills (for comprehensive planning) |
+| **architect** | cloudstream-project-template, backend-patterns, frontend-patterns |
+| **tdd-guide** | tdd-workflow, coding-standards |
+| **code-reviewer** | coding-standards, security-review |
+| **security-reviewer** | security-review, compliance-patterns |
+| **compliance-auditor** | compliance-patterns |
+| **deluge-reviewer** | zoho-patterns/deluge |
+| **creator-architect** | zoho-patterns/creator |
+| **catalyst-deployer** | zoho-patterns/catalyst, backend-patterns |
+| **doc-updater** | consultancy-workflows |
+| **e2e-runner** | tdd-workflow, coding-standards |
+| **refactor-cleaner** | coding-standards |
+| **build-error-resolver** | backend-patterns, coding-standards |
+
+## Exercise
+
+### Exercise 11.1: Explore Skill Structure
+
+**Step 1**: List all skills:
+```bash
+ls skills/
+```
+
+You should see 16+ directories (15 active skills + tutorial + archived).
+
+**Step 2**: Read a skill file:
+```bash
+cat skills/zoho-patterns/SKILL.md
+```
+
+Notice the structure:
+- Frontmatter with name and description
+- When to Activate section
+- Core Patterns
+- Anti-Patterns
+
+**Step 3**: Explore skill subdirectories:
+```bash
+ls skills/zoho-patterns/
+```
+
+Complex skills have subfolders for different aspects.
+
+### Exercise 11.2: Count Skill Files
+
+**Step 1**: Count all pattern files:
+```bash
+find skills -name "*.md" | wc -l
+```
+
+**Step 2**: This tells you how much knowledge is embedded in the system.
+
+### Exercise 11.3: Find Skill Coverage
+
+**Step 1**: Pick a domain you work in (e.g., compliance):
+```bash
+cat skills/compliance-patterns/SKILL.md
+```
+
+**Step 2**: Look at subdirectories:
+```bash
+ls skills/compliance-patterns/
+```
+
+**Step 3**: Read specific patterns:
+```bash
+cat skills/compliance-patterns/hipaa/phi-handling.md
+```
+
+(Path may vary based on actual structure)
+
+## Verification
+
+You've completed this exercise successfully if:
+- [ ] You can list all 15 active skills
+- [ ] You understand the SKILL.md format
+- [ ] You know which skills inform which agents
+- [ ] You explored at least one skill's subdirectory structure
+
+## Skills Quick Reference
+
+```
+DEVELOPMENT:
+  coding-standards     - Style guides, naming
+  tdd-workflow        - RED/GREEN/REFACTOR
+  backend-patterns    - Node.js, Catalyst
+  frontend-patterns   - React, Widgets
+
+QUALITY:
+  security-review     - OWASP, vulnerabilities
+
+PLATFORM:
+  zoho-patterns       - Creator/Catalyst/Deluge
+  bigquery-patterns   - Data warehouse
+  gcp-data-engineering - Medallion architecture
+
+COMPLIANCE:
+  compliance-patterns - HIPAA/SOC2/PCI-DSS
+
+PROCESS:
+  consultancy-workflows    - Client isolation
+  cloudstream-project-template - Project structure
+  tutorial                 - This system
+  strategic-compact        - Context management
+  continuous-learning      - Pattern extraction
+  continuous-learning-v2   - Enhanced pattern extraction
+```
+
+## Creating Custom Skills
+
+To add a new skill:
+
+**Step 1**: Create folder:
+```bash
+mkdir skills/your-skill
+```
+
+**Step 2**: Create SKILL.md with frontmatter:
+```markdown
+---
+name: your-skill
+description: One-line description of the skill
+---
+
+# Your Skill Title
+
+## When to Activate
+- Condition 1
+- Condition 2
+
+## Core Patterns
+- Pattern 1
+- Pattern 2
+
+## Anti-Patterns
+- What to avoid
+```
+
+**Step 3**: Add pattern files in subfolders as needed.
+
+**Step 4**: Reference from agents that should use it.
+
+## Key Takeaway
+
+Skills are the knowledge base. They encode patterns, standards, and domain expertise that agents use to produce consistent, high-quality work. The 16 active skills cover development, quality, platforms, compliance, and process.
+
+## Next Steps
+
+In Lesson 12, you'll learn about the Rules System - how behavioral constraints are loaded and applied.
+
+---
+
+**Skills indexed**: 16 active skills across 5 categories
+**Key pattern**: `skills/{skill-name}/SKILL.md`
+**Agent relationship**: Skills inform how agents work
+**Progress**: 12 of 15 lessons complete

package/skills/tutorial/lessons/12-rules-system.md

@@ -0,0 +1,326 @@
+# Lesson 12: Rules System
+
+Rules define behavioral constraints and patterns that Claude follows during execution.
+
+## Concept
+
+Rules are markdown files in `rules/` that set behavioral guardrails. There are **15 rule files** in total:
+
+| Rule File | Purpose | Always Active? |
+|-----------|---------|----------------|
+| **golden-standard.md** | Quality bar definition (top 1%) | Yes |
+| **tdd-enforcement.md** | Test-driven development workflow | Yes |
+| **prompt-routing.md** | Prompt analysis and routing | Yes |
+| **hook-awareness.md** | Hook system behavior | Yes |
+| **agents.md** | Agent orchestration triggers | Yes |
+| **coding-style.md** | Code formatting rules | Yes |
+| **compliance.md** | Compliance mode behavior | When mode set |
+| **git-workflow.md** | Branch naming, commit standards | Yes |
+| **hooks.md** | Hook definitions | Yes |
+| **patterns.md** | Design pattern guidance | Yes |
+| **performance.md** | Model selection, optimization | Yes |
+| **security.md** | Security requirements | Yes |
+| **testing.md** | 80% coverage requirement | Yes |
+| **training.md** | Training mode behavior | When enabled |
+| **INDEX.md** | Rules reference index | — |
+
+## Why This Matters
+
+Without rules:
+- Inconsistent behavior between sessions
+- No enforced quality standards
+- Each session reinvents conventions
+
+With rules:
+- Consistent behavior across all sessions
+- Quality bar is explicitly defined
+- Conventions are automatically applied
+
+## Rule Loading Priority
+
+Rules are loaded in this order (later overrides earlier):
+
+```
+1. System rules (built into Claude)
+     ↓
+2. Plugin rules (rules/*.md in this directory)
+     ↓
+3. Project rules (CLAUDE.md in project root)
+     ↓
+4. Session context (current conversation)
+```
+
+This means:
+- Plugin rules override system defaults
+- Project CLAUDE.md can override plugin rules
+- Session context can temporarily override all
+
+## Rule File Structure
+
+Rules follow a standard format:
+
+```markdown
+---
+name: rule-name
+description: One-line description
+always: true|false
+---
+
+# Rule Title
+
+## Definition
+What this rule means
+
+## When It Applies
+Conditions for activation
+
+## Behavior
+What Claude should do
+
+## Anti-Patterns
+What to avoid
+```
+
+### Frontmatter Fields
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `name` | Yes | Unique identifier |
+| `description` | Yes | Brief explanation |
+| `always` | No | If true, always loaded; if false, conditional |
+
+## The 11 Rules Explained
+
+### 1. Golden Standard (always: true)
+
+**The most important rule.** Defines the quality bar:
+- "Top 1% enterprise professional quality"
+- Production-ready, bulletproof, auditable code
+- 80%+ test coverage
+- OWASP Top 10 security awareness
+- Handoff-ready documentation
+
+### 2. Training Mode
+
+Defines how training mode works:
+- Intent detection keywords and triggers
+- Workflow suggestions for different task types
+- Verbosity levels (minimal, standard, detailed)
+- Skip conditions for simple tasks
+
+### 3. Agents
+
+Defines agent activation:
+- Which agents exist
+- Trigger conditions for each
+- Model selection (Opus for reasoning, Sonnet for execution)
+- Agent capabilities and limitations
+
+### 4. Compliance
+
+Defines compliance mode behavior:
+- HIPAA requirements when `## Compliance Mode: hipaa`
+- SOC2 requirements when `## Compliance Mode: soc2`
+- PCI-DSS requirements when `## Compliance Mode: pci-dss`
+- Multi-mode combinations
+
+### 5. Security
+
+Security patterns to enforce:
+- Input validation requirements
+- Credential handling
+- OWASP Top 10 checks
+- Security review triggers
+
+### 6. Testing
+
+Testing requirements:
+- TDD workflow (RED → GREEN → REFACTOR)
+- Coverage targets (80%+ minimum)
+- Test types (unit, integration, E2E)
+- When testing is mandatory
+
+### 7. Hooks
+
+Hook system documentation:
+- Available hook types
+- How hooks are configured
+- Hook execution flow
+- Creating custom hooks
+
+### 8. Patterns
+
+Design pattern guidance:
+- When to use which patterns
+- Anti-patterns to avoid
+- Architecture decisions
+- Code organization
+
+### 9. Coding Style
+
+Code formatting rules:
+- Naming conventions
+- File organization
+- Comment standards
+- Import ordering
+
+### 10. Git Workflow
+
+Git conventions:
+- Branch naming
+- Commit message format: `[CLIENT-ID] type(scope): description | Time: Xh Xm`
+- PR standards
+- Review requirements
+
+### 11. Performance
+
+Performance guidelines:
+- Zoho platform constraints (statement limits, timeouts)
+- Query optimization
+- Bundle size targets
+- Profiling requirements
+
+## Exercise
+
+### Exercise 12.1: Explore Rules Directory
+
+**Step 1**: List all rules:
+```bash
+ls rules/
+```
+
+You should see 11 .md files.
+
+**Step 2**: Read the golden-standard rule:
+```bash
+cat rules/golden-standard.md
+```
+
+Notice:
+- Frontmatter with `always: true`
+- Clear quality bar definition
+- Verification checklist
+- Anti-patterns section
+
+### Exercise 12.2: Understand Rule Format
+
+**Step 1**: Pick any rule file and examine its structure:
+```bash
+cat rules/training.md
+```
+
+**Step 2**: Identify:
+- Frontmatter (name, description, always)
+- Definition section
+- When It Applies section
+- Behavior section
+
+### Exercise 12.3: Check Active Rules
+
+When Claude starts, it loads rules with `always: true` automatically.
+
+**Step 1**: Count always-active rules:
+```bash
+grep -l "always: true" rules/*.md
+```
+
+**Step 2**: These rules are ALWAYS loaded, regardless of project.
+
+### Exercise 12.4: Project-Level Overrides
+
+**Step 1**: Read the project CLAUDE.md:
+```bash
+cat CLAUDE.md
+```
+
+**Step 2**: Notice how it can set:
+- `## Compliance Mode: hipaa`
+- `## Training Mode: enabled`
+- Project-specific guidelines
+
+These override the default rule behavior.
+
+## Verification
+
+You've completed this exercise successfully if:
+- [ ] You found and read all 11 rule files
+- [ ] You understand the rule loading priority
+- [ ] You know which rules are always active vs. conditional
+- [ ] You understand the frontmatter format
+
+## Creating Custom Rules
+
+To add a project-specific rule:
+
+**Option 1: In Project CLAUDE.md**
+
+Add guidance directly in your project's CLAUDE.md:
+```markdown
+## Project Rules
+
+### No External Libraries
+For this project, avoid adding npm dependencies.
+Use built-in Node.js modules when possible.
+```
+
+**Option 2: Custom Rule File**
+
+Create a new rule in `rules/`:
+```markdown
+---
+name: no-friday-deploys
+description: Prevent deployments on Fridays
+always: true
+---
+
+# No Friday Deploys
+
+## Behavior
+When detecting deployment intent on Fridays:
+1. Alert user to deployment risk
+2. Suggest Monday deployment instead
+3. Require explicit override to proceed
+
+## Rationale
+Friday deployments leave less time to respond to issues.
+```
+
+## Key Takeaway
+
+Rules encode organizational standards. The Golden Standard rule is the baseline - everything produced must meet "top 1% enterprise professional quality."
+
+Rules are loaded hierarchically:
+1. System defaults
+2. Plugin rules (this directory)
+3. Project CLAUDE.md
+4. Session context
+
+## Rules Quick Reference
+
+```
+ALWAYS ACTIVE:
+  golden-standard  - Quality bar definition
+  agents           - Agent triggers
+  security         - Security patterns
+  testing          - Test requirements
+  coding-style     - Code conventions
+  git-workflow     - Git conventions
+  performance      - Performance guidelines
+  hooks            - Hook system
+  patterns         - Design patterns
+
+CONDITIONAL:
+  training         - When Training Mode enabled
+  compliance       - When Compliance Mode set
+```
+
+## Next Steps
+
+In Lesson 13, you'll formally learn the Golden Standard and receive your graduation checklist.
+
+---
+
+**Rules learned**: 11 rule files, loading priority, frontmatter format
+**Critical rule**: `rules/golden-standard.md`
+**Key concept**: Rules encode standards that Claude follows automatically
+**Progress**: 13 of 15 lessons complete