@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/tutorial/lessons/15-living-examples-system.md

@@ -0,0 +1,221 @@
+# Lesson 15: Living Examples System (Phase 10)
+
+The Living Examples System transforms documentation into validated, real-world code examples with community curation.
+
+## Concept
+
+Every scraped documentation page gets an associated **validated code example** that:
+1. Passes 3-stage validation (syntax, standards, security)
+2. Can be verified by community members
+3. Evolves through corrections and improvements
+4. Integrates with the learning/instincts system
+
+```
+Documentation → Example Generator → Validation Pipeline → Community Verification
+                                                                ↓
+                                                        Knowledge Base
+```
+
+## Why This Matters
+
+Without living examples:
+- Documentation is passive - users must figure out implementation
+- No way to know if examples actually work
+- Knowledge stagnates without community input
+- No quality metrics on guidance provided
+
+With living examples:
+- Every doc has a working example attached
+- Community verification confirms real-world validity
+- Users can report and fix broken examples
+- Quality scores show trustworthiness
+
+## Architecture
+
+### The Pipeline
+
+| Component | Purpose | Status |
+|-----------|---------|--------|
+| **Example Generator** | Claude-powered example creation | Scheduled worker |
+| **Example Validator** | 3-stage validation pipeline | Scheduled worker |
+| **Community Feedback** | User corrections and improvements | Via MCP tools |
+| **Reference Library** | Ground truth corpus | Grows organically |
+
+### Trust Levels
+
+Examples have different trust levels based on validation and community input:
+
+| Level | Badge | Criteria |
+|-------|-------|----------|
+| **Gold** | 🏆 | 90%+ quality, 5+ verifications |
+| **Verified** | ✅ | Community verified (3+ users) |
+| **Standard** | ✓ | Passed validation pipeline |
+| **Pending** | ⏳ | Awaiting validation |
+
+## MCP Tools
+
+### For All Users
+
+| Tool | Purpose |
+|------|---------|
+| `get_code_example` | Get validated example for a doc |
+| `search_reference_examples` | Search the example corpus |
+| `verify_example_works` | Confirm an example works |
+| `get_example_history` | View version history |
+| `submit_url_for_scraping` | Suggest new URLs to index |
+
+### For Submitting Feedback
+
+| Tool | Purpose |
+|------|---------|
+| `submit_example_feedback` | Report issues or suggest fixes |
+| `check_url_status` | Check if a URL is indexed |
+
+### For Reviewers
+
+| Tool | Purpose |
+|------|---------|
+| `get_pending_reviews` | View pending feedback |
+| `approve_feedback` | Approve and merge fixes |
+| `reject_feedback` | Reject submissions |
+| `get_review_stats` | Dashboard metrics |
+
+## Validation Pipeline
+
+Every example goes through 3 stages:
+
+### Stage 1: Syntax Validation
+```
+✓ Brace matching
+✓ Basic structure
+✓ No obvious errors
+```
+
+### Stage 2: Standards Compliance
+```
+✓ Variable naming (camelCase)
+✓ Function naming (verb_noun)
+✓ Error handling present
+✓ No hardcoded credentials
+✓ Within size limits
+```
+
+### Stage 3: Security Scan
+```
+✓ No credential patterns
+✓ Input validation present
+✓ No injection vulnerabilities
+✓ Safe API usage
+```
+
+## Community Feedback Flow
+
+```
+User finds broken example
+        ↓
+Submits feedback (MCP tool)
+        ↓
+Auto-validation checks
+        ↓
+Queued for reviewer
+        ↓
+Reviewer approves → New version created
+                    All users get fixed example
+```
+
+### Feedback Types
+
+| Type | Priority | Purpose |
+|------|----------|---------|
+| 🔴 `security_issue` | Critical | Security problems |
+| 🟠 `broken` | High | Non-working examples |
+| 🟡 `improvement` | Medium | Enhancements |
+| 🟢 `works` | Low | Confirms example works |
+
+## Exercise
+
+### Exercise 15.1: Explore Examples
+
+**Step 1**: Search for examples related to a function:
+```
+Use: search_reference_examples
+Args: { "function_name": "getRecords" }
+```
+
+**Step 2**: Notice the quality metrics:
+- Quality score (percentage)
+- Verification count
+- Trust level badge
+
+### Exercise 15.2: View Example Details
+
+**Step 1**: Get a specific example:
+```
+Use: get_code_example
+Args: { "doc_url": "https://www.zoho.com/creator/help/..." }
+```
+
+**Step 2**: Notice the metadata:
+- Trust level box
+- Validation details table
+- Action links for feedback
+
+### Exercise 15.3: Verify an Example
+
+**Step 1**: If you've used an example in production:
+```
+Use: verify_example_works
+Args: { "example_id": "ex_abc123" }
+```
+
+**Step 2**: Your verification contributes to community trust.
+
+## Learning Integration
+
+Verified examples can be exported as **instincts**:
+
+```
+Use: export_example_as_instinct
+Args: { "example_id": "ex_abc123" }
+```
+
+This creates a YAML file you can save to:
+```
+~/.claude/homunculus/instincts/inherited/
+```
+
+Instincts inform Claude's future behavior based on validated patterns.
+
+## Reviewer Dashboard
+
+Designated reviewers see:
+- Pending feedback count
+- Pending URL submissions
+- Approval rate
+- Community health metrics
+
+Use `get_review_stats` to see the dashboard.
+
+## Verification
+
+You've completed this lesson successfully if:
+- [ ] You can search for reference examples
+- [ ] You understand the validation pipeline stages
+- [ ] You know how to verify an example works
+- [ ] You understand the feedback flow
+- [ ] You can export examples as instincts
+
+## Key Takeaway
+
+The Living Examples System creates a **compound growth loop**: users submit corrections, reviewers approve them, and the entire community benefits from improved examples. Quality scores and trust badges let you know exactly how reliable each example is.
+
+## Next Steps
+
+You've completed the CloudStream Claude Tools tutorial! Review the [Golden Standard Graduation](./13-golden-standard-graduation.md) checklist to confirm you're ready for production work.
+
+---
+
+**System indexed**: 27 MCP tools including 17 for Living Examples
+**Key pattern**: Documentation → Example → Validation → Community
+**Trust levels**: Gold (🏆) → Verified (✅) → Standard (✓)
+**Progress**: 16 of 16 lessons complete

package/skills/tutorial/tracks/accelerated/README.md

@@ -0,0 +1,134 @@
+# Accelerated Track - 7-Day Intensive Onboarding
+
+This track is designed for experienced developers (2+ years) joining CloudStream Software LLC. It condenses the standard 14-day, 15-lesson tutorial into an intensive 7-day program.
+
+## Prerequisites
+
+Before starting this track, you should have:
+
+- [ ] 2+ years professional development experience
+- [ ] Familiarity with TypeScript/JavaScript
+- [ ] Experience with test-driven development concepts
+- [ ] Basic understanding of CI/CD pipelines
+- [ ] Comfort with command-line tools
+
+If you're missing any of these, consider the [Standard Track](../README.md) instead.
+
+## Track Structure
+
+| Day | Focus | Standard Lessons Covered | Time |
+|-----|-------|-------------------------|------|
+| 1 | Core Concepts | Lessons 0-1: Philosophy, Architecture | 2-3 hrs |
+| 2 | Essential Commands | Lessons 2-3: Training Mode, Commands | 2-3 hrs |
+| 3 | Workflow Mastery | Lesson 4: Complete Workflow Patterns | 2-3 hrs |
+| 4 | Compliance & Zoho | Lessons 5-6: HIPAA/SOC2/PCI, Zoho Platform | 3-4 hrs |
+| 5 | Hooks & Skills | Lessons 7-8, 11-12: Hooks, MCP, Skills, Rules | 3-4 hrs |
+| 6 | Client & Testing | Lessons 9-10: Client Management, E2E Testing | 3-4 hrs |
+| 7 | Graduation | Lessons 13-14: Golden Standard, Fork Sync | 2-3 hrs |
+
+**Total Time**: ~18-24 hours across 7 days
+
+## Assessments
+
+Two checkpoints ensure comprehension before advancing:
+
+| Checkpoint | After Day | Topics | Passing Score |
+|------------|-----------|--------|---------------|
+| 1 | Day 3 | Core concepts, commands, workflows | 80% |
+| 2 | Day 6 | Compliance, Zoho, hooks, skills, testing | 80% |
+
+Checkpoints are required. Failing blocks progress until passed (max 2 retakes).
+
+## Key Differences from Standard Track
+
+| Aspect | Standard | Accelerated |
+|--------|----------|-------------|
+| Duration | 14 days | 7 days |
+| Lessons | 15 separate | 7 combined |
+| Pace | 1-2 lessons/day | 2-3 lessons/day |
+| Exercises | Detailed | Condensed |
+| Checkpoints | None | 2 required |
+| Prerequisites | None | 2+ years exp |
+
+## How to Start
+
+```
+/tutorial accelerated
+```
+
+Or jump to a specific day:
+```
+/tutorial accelerated day-3
+```
+
+## Daily Schedule Recommendation
+
+```
+Morning (1-2 hrs):
+  - Read day's content
+  - Complete first exercise set
+
+Afternoon (1-2 hrs):
+  - Complete remaining exercises
+  - Practice commands on real project
+
+End of day:
+  - Run /verify on practice work
+  - Note questions for next session
+```
+
+## Milestones to Track
+
+By completing this track, you should hit these milestones:
+
+| Milestone | Target | Day |
+|-----------|--------|-----|
+| First Session Complete | Day 1 | 1 |
+| First Unassisted Commit | 8 hours | 1-2 |
+| First Complete Workflow | Day 3 | 3 |
+| Tutorial Complete | Day 7 | 7 |
+| Client-Ready Work | 14 days | Post-track |
+
+Run `/milestone status` to track your progress.
+
+## Quick Reference
+
+### Core Commands (Master by Day 3)
+```
+/verify     - Validate project (before every commit)
+/plan       - Design implementation
+/tdd        - Test-driven development
+/code-review - Quality check
+/checkpoint - Create recovery point
+/audit      - System health check
+```
+
+### The Golden Standard
+- Production-ready, bulletproof code
+- 80%+ test coverage
+- Security-reviewed (OWASP Top 10)
+- Handoff-ready documentation
+
+### Daily Workflow
+```
+/audit → /checkpoint → /plan → /tdd → /code-review → /verify → commit
+```
+
+## Getting Help
+
+- Questions during tutorial: Ask Claude directly
+- System issues: `/audit` to diagnose
+- Stuck on exercise: Skip and note for follow-up
+- Need more depth: Reference standard track lessons
+
+## Next Steps After Completion
+
+1. Apply workflow to first real client project
+2. Run `/learn` after completing first feature to extract patterns
+3. Review `/skill-gaps` to identify areas for continued learning
+4. Target: Client-ready work within 14 days of track completion
+
+---
+
+**Track Version**: 1.0.0
+**Last Updated**: 2026-01-25

package/skills/tutorial/tracks/accelerated/assessment/checkpoint-1.md

@@ -0,0 +1,161 @@
+# Checkpoint 1: Foundations Assessment
+
+**Covers**: Days 1-3 (Core Concepts, Commands, Workflows)
+**Passing Score**: 80% (8/10 correct)
+**Max Retakes**: 2
+
+---
+
+## Instructions
+
+Answer each question. Run `/tutorial checkpoint-1 submit` when ready to check your answers.
+
+---
+
+## Questions
+
+### Q1: Core Workflow
+What is the correct order of the core development workflow?
+
+A) tdd → plan → verify → code-review
+B) plan → tdd → code-review → verify
+C) code-review → plan → tdd → verify
+D) verify → plan → tdd → code-review
+
+---
+
+### Q2: Golden Standard
+What is the minimum test coverage required by the Golden Standard?
+
+A) 50%
+B) 70%
+C) 80%
+D) 100%
+
+---
+
+### Q3: Essential Commands
+Which command should you run BEFORE every git commit?
+
+A) /audit
+B) /plan
+C) /verify
+D) /checkpoint
+
+---
+
+### Q4: Checkpoint Purpose
+What is the primary purpose of the `/checkpoint` command?
+
+A) To commit code to git
+B) To create a recovery point for safe rollback
+C) To run tests
+D) To switch client contexts
+
+---
+
+### Q5: Architecture
+In the system architecture (Commands → Agents → Rules → Skills), what do Agents represent?
+
+A) User input commands
+B) Specialized AI personas that execute commands
+C) Behavioral constraints
+D) Reusable knowledge packages
+
+---
+
+### Q6: Training Mode
+What does Training Mode do when it detects your intent?
+
+A) Automatically executes commands without asking
+B) Suggests optimal workflow with rationale
+C) Blocks all operations until approved
+D) Sends notifications to the team
+
+---
+
+### Q7: Bug Fix Workflow
+According to the TDD approach, what should you do FIRST when fixing a bug?
+
+A) Fix the code immediately
+B) Write a failing test that reproduces the bug
+C) Run /plan to design the fix
+D) Create a checkpoint
+
+---
+
+### Q8: Safety Workflow
+What is the recommended full safety workflow sequence?
+
+A) plan → tdd → verify
+B) checkpoint → code-review → verify
+C) audit → checkpoint → plan → tdd → code-review → verify
+D) tdd → plan → code-review → checkpoint
+
+---
+
+### Q9: Refactoring
+When starting a refactoring task, what should you do FIRST?
+
+A) Start modifying code
+B) Run /plan
+C) Create a /checkpoint
+D) Run tests
+
+---
+
+### Q10: Verification
+Which checks does the `/verify` command run?
+
+A) Only tests
+B) Only type checking
+C) Build, tests, lint, and type checking
+D) Only linting
+
+---
+
+## Answer Key
+
+*(For self-assessment - do not look before attempting)*
+
+<details>
+<summary>Click to reveal answers</summary>
+
+1. **B** - plan → tdd → code-review → verify
+2. **C** - 80%
+3. **C** - /verify
+4. **B** - To create a recovery point for safe rollback
+5. **B** - Specialized AI personas that execute commands
+6. **B** - Suggests optimal workflow with rationale
+7. **B** - Write a failing test that reproduces the bug
+8. **C** - audit → checkpoint → plan → tdd → code-review → verify
+9. **C** - Create a /checkpoint
+10. **C** - Build, tests, lint, and type checking
+
+**Passing Score: 8/10 (80%)**
+
+</details>
+
+---
+
+## Results
+
+After checking your answers:
+
+- **8-10 correct**: PASSED - Proceed to Day 4
+- **6-7 correct**: Review Days 1-3, retake assessment
+- **Below 6**: Review material more thoroughly, retake assessment
+
+---
+
+## Retake Policy
+
+- Maximum 2 retakes allowed
+- Review relevant material before retaking
+- Same questions with shuffled order
+
+If you fail after 2 retakes, complete the standard track exercises for Days 1-3 before attempting again.
+
+---
+
+**Run `/tutorial checkpoint-1 submit` to submit your answers**

package/skills/tutorial/tracks/accelerated/assessment/checkpoint-2.md

@@ -0,0 +1,175 @@
+# Checkpoint 2: Advanced Assessment
+
+**Covers**: Days 4-6 (Compliance, Zoho, Hooks, Skills, Testing)
+**Passing Score**: 80% (8/10 correct)
+**Max Retakes**: 2
+
+---
+
+## Instructions
+
+Answer each question. Run `/tutorial checkpoint-2 submit` when ready to check your answers.
+
+---
+
+## Questions
+
+### Q1: Compliance Modes
+Which compliance mode should you enable for a healthcare application handling patient data?
+
+A) soc2
+B) pci-dss
+C) hipaa
+D) standard
+
+---
+
+### Q2: Deluge Constraints
+What is the maximum number of statements allowed in a single Deluge function?
+
+A) 1,000
+B) 5,000
+C) 10,000
+D) Unlimited
+
+---
+
+### Q3: Catalyst Timeout
+What is the default timeout for Catalyst functions?
+
+A) 10 seconds
+B) 30 seconds
+C) 40 seconds
+D) 60 seconds
+
+---
+
+### Q4: Hooks - Blocking vs Warning
+Which of these hooks BLOCKS the operation (vs just warning)?
+
+A) Console.log warning
+B) Credential check
+C) Tmux reminder
+D) Git push review
+
+---
+
+### Q5: Hook Lifecycle
+Which hook type fires BEFORE a tool executes?
+
+A) PostToolUse
+B) PreToolUse
+C) SessionEnd
+D) Stop
+
+---
+
+### Q6: Skills Count
+How many skills are included in the CloudStream Claude Tools system?
+
+A) 8
+B) 12
+C) 16
+D) 20
+
+---
+
+### Q7: Rules Loading
+In what order do rules load (from first to last)?
+
+A) Directory CLAUDE.md → Project → Global
+B) Project CLAUDE.md → Global → Directory
+C) Global CLAUDE.md → Project → Directory
+D) They all load simultaneously
+
+---
+
+### Q8: Test Coverage Target
+What is the test coverage target for the Golden Standard?
+
+A) 60%+
+B) 70%+
+C) 80%+
+D) 90%+
+
+---
+
+### Q9: Client Management
+Which command generates comprehensive documentation when transitioning a client?
+
+A) /client-switch
+B) /handoff
+C) /document
+D) /export
+
+---
+
+### Q10: E2E Testing
+Which command generates and runs end-to-end Playwright tests?
+
+A) /tdd
+B) /test-coverage
+C) /e2e
+D) /verify
+
+---
+
+## Answer Key
+
+*(For self-assessment - do not look before attempting)*
+
+<details>
+<summary>Click to reveal answers</summary>
+
+1. **C** - hipaa
+2. **B** - 5,000
+3. **C** - 40 seconds
+4. **B** - Credential check (blocks on secrets found)
+5. **B** - PreToolUse
+6. **C** - 16
+7. **C** - Global CLAUDE.md → Project → Directory
+8. **C** - 80%+
+9. **B** - /handoff
+10. **C** - /e2e
+
+**Passing Score: 8/10 (80%)**
+
+</details>
+
+---
+
+## Results
+
+After checking your answers:
+
+- **8-10 correct**: PASSED - Proceed to Day 7 (Graduation)
+- **6-7 correct**: Review Days 4-6, retake assessment
+- **Below 6**: Review material more thoroughly, retake assessment
+
+---
+
+## Retake Policy
+
+- Maximum 2 retakes allowed
+- Review relevant material before retaking
+- Same questions with shuffled order
+
+If you fail after 2 retakes, complete the standard track exercises for Days 4-6 before attempting again.
+
+---
+
+## Additional Study Resources
+
+If you struggled with specific topics:
+
+| Topic | Review |
+|-------|--------|
+| Compliance | Day 4, Part 1 + skills/compliance-patterns |
+| Zoho | Day 4, Part 2-3 + skills/zoho-patterns |
+| Hooks | Day 5, Part 1 + hooks/hooks.json |
+| Skills | Day 5, Part 3 + skills/ directory |
+| Testing | Day 6, Part 2-3 + /tdd help |
+
+---
+
+**Run `/tutorial checkpoint-2 submit` to submit your answers**