@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/tutorial/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: tutorial
+description: Interactive tutorial that guides users through the CloudStream Claude Tools system with hands-on exercises and progressive learning.
+version: 1.0.0
+status: active
+introduced: 1.0.0
+lastUpdated: 2026-01-25
+---
+
+# Interactive Tutorial Skill
+
+This skill provides a guided, interactive learning experience for the CloudStream Claude Tools system.
+
+## When to Activate
+
+- User types `/tutorial` to start the tutorial
+- User asks "how do I learn this system" or similar questions
+- New users who need onboarding to the plugin architecture
+
+## Track Selection
+
+The tutorial offers two learning tracks:
+
+### Standard Track (14 days, 15 lessons)
+- Comprehensive onboarding for all skill levels
+- 1-2 lessons per day
+- Detailed exercises with verification
+- No prerequisites required
+
+```
+/tutorial
+/tutorial 3           # Jump to lesson 3
+/tutorial status      # Check progress
+```
+
+### Accelerated Track (7 days, 7 lessons)
+- Intensive track for experienced developers (2+ years)
+- 2-3 lessons per day (condensed from standard)
+- Two required checkpoints (80% passing)
+- Prerequisites: TypeScript, TDD familiarity
+
+```
+/tutorial accelerated
+/tutorial accelerated day-3    # Jump to day 3
+/tutorial checkpoint-1         # Take checkpoint 1
+```
+
+### Track Comparison
+
+| Aspect | Standard | Accelerated |
+|--------|----------|-------------|
+| Duration | 14 days | 7 days |
+| Lessons | 15 separate | 7 combined |
+| Checkpoints | None | 2 required |
+| Prerequisites | None | 2+ years exp |
+| Recommended for | New developers | Senior developers |
+
+### Milestone Tracking
+
+Both tracks support milestone tracking:
+
+```
+/milestone status             # View milestone progress
+/milestone record first-commit  # Record milestone
+/milestone report             # Generate report
+```
+
+Key milestones:
+- First Session Complete
+- First Unassisted Commit (target: 8 hours)
+- First Complete Workflow (target: 16 hours)
+- Tutorial Completion
+- Client-Ready Work (target: 14 days)
+
+## Standard Tutorial Structure
+
+The standard tutorial consists of 15 progressive lessons (0-14) covering 100% of features:
+
+| # | Lesson | Topics Covered |
+|---|--------|----------------|
+| 0 | Philosophy & Workflow | Daily lifecycle, "aha moment", training mode philosophy |
+| 1 | Core Concepts | Mental model, architecture, Golden Standard intro |
+| 2 | Training Mode | Intent detection, workflow suggestions |
+| 3 | Essential Commands | Top 6 commands including /audit |
+| 4 | Workflow Patterns | plan→tdd→review→verify flow |
+| 5 | Compliance | HIPAA, SOC2, PCI-DSS modes |
+| 6 | Zoho Development | Creator, Catalyst, Deluge integration |
+| 7 | Hooks System | 6 lifecycle events, blocking vs. warning hooks |
+| 8 | MCP Servers | All 12 MCPs across 3 tiers |
+| 9 | Client Management | /client-switch, /handoff, isolation |
+| 10 | Testing & E2E | /e2e, /build-fix, /test-coverage, /eval |
+| 11 | Skills Deep Dive | All 16 skills, agent relationships |
+| 12 | Rules System | 11 rules, loading priority, frontmatter |
+| 13 | Golden Standard Graduation | Quality bar, verification checklist |
+| 14 | Fork Setup & Sync | Staying updated, sync tooling |
+
+## How to Run
+
+### Start from Beginning
+```
+/tutorial
+```
+
+### Jump to Specific Lesson
+```
+/tutorial 3
+```
+
+### Check Progress
+```
+/tutorial status
+```
+
+## Lesson Format
+
+Each lesson follows this structure:
+
+1. **Concept** (2-3 paragraphs)
+   - What is this feature?
+   - Why does it matter?
+   - How does it fit in the system?
+
+2. **Exercise** (hands-on practice)
+   - Specific command to run
+   - Expected output to observe
+   - What to look for
+
+3. **Verification** (confirm understanding)
+   - Check that the exercise worked
+   - Common mistakes to avoid
+
+4. **Quiz** (optional knowledge check)
+   - Quick question to confirm understanding
+   - Immediate feedback
+
+## Progress Tracking
+
+Tutorial progress is tracked in session memory:
+
+```
+Tutorial Progress: [=====>              ] 5/14 lessons complete
+Last Completed: Lesson 4 - Workflow Patterns
+Next: Lesson 5 - Compliance
+```
+
+## Lesson Flow
+
+### Starting a Lesson
+
+When user starts a lesson:
+1. Read the lesson file from `lessons/XX-name.md`
+2. Present the Concept section
+3. Wait for user acknowledgment
+4. Present the Exercise with clear instructions
+5. Guide user through verification
+6. Mark lesson complete and offer next lesson
+
+### Completing Tutorial
+
+After all 14 lessons:
+1. Congratulate user
+2. Provide quick reference card
+3. Suggest next steps (enable training mode on a real project)
+
+## Integration Points
+
+### With Training Mode
+After lesson 2, user can enable training mode to see workflow suggestions in action.
+
+### With Commands
+Lessons involve running actual commands throughout:
+- `/verify`, `/audit` in lessons 1, 3
+- `/plan`, `/tdd`, `/code-review` in lessons 3-4
+- `/compliance-check` in lesson 5
+- `/zoho-scaffold`, `/deluge` in lesson 6
+- `/client-switch`, `/handoff` in lesson 9
+- `/e2e`, `/build-fix`, `/test-coverage` in lesson 10
+
+### With Memory
+Progress is persisted to allow resume:
+- Lesson completion status
+- Exercise verification status
+- User preferences (verbosity, pace)
+
+## Error Handling
+
+### User Skips Exercise
+Allow skipping with note that hands-on practice is recommended.
+
+### Exercise Fails
+Provide troubleshooting steps:
+1. Check prerequisites (correct directory, files exist)
+2. Common error messages and fixes
+3. Option to retry or skip
+
+### User Wants to Restart
+```
+/tutorial reset
+```
+Clears progress and starts from lesson 1.
+
+## Customization
+
+### Verbosity Levels
+
+**Quick Mode** (for experienced devs):
+- Concept summary only
+- Exercise with minimal guidance
+- Skip verification
+
+**Standard Mode** (default):
+- Full concept explanation
+- Step-by-step exercise
+- Verification checks
+
+**Detailed Mode** (for thorough learning):
+- Extended explanations
+- Additional examples
+- Related skill references
+
+## Success Criteria
+
+Tutorial is considered successful when user can:
+1. Explain the daily workflow lifecycle and philosophy
+2. Explain the mental model (commands → agents → rules → skills)
+3. Enable and use training mode
+4. Run the top 6 commands confidently (including /audit)
+5. Execute a complete plan→tdd→review→verify workflow
+6. Set up compliance mode for a project
+7. Scaffold a Zoho component
+8. Understand hooks and when they fire
+9. Configure and use MCP servers
+10. Manage multiple client contexts
+11. Run E2E tests and fix build errors
+12. Navigate and utilize all 16 skills
+13. Apply the Golden Standard quality bar
+14. Keep their fork updated with upstream
+
+## Metrics
+
+Track tutorial effectiveness:
+- Completion rate per lesson
+- Time spent per lesson
+- Exercise success rate
+- User feedback ratings
+
+---
+
+**Remember**: The goal is not just to teach features, but to build muscle memory for productive workflows. Hands-on practice is essential.

package/skills/tutorial/docs/ACCESSIBILITY.md

@@ -0,0 +1,169 @@
+# Accessibility
+
+CloudStream Claude Tools Tutorial is designed to be accessible to all users, including those using screen readers, high-contrast displays, or terminal environments that don't support colors.
+
+## WCAG 2.1 AA Compliance
+
+The tutorial system follows Web Content Accessibility Guidelines (WCAG) 2.1 Level AA where applicable to CLI environments.
+
+## Enabling Accessible Mode
+
+### Option 1: NO_COLOR Environment Variable (Recommended)
+
+Set the standard `NO_COLOR` environment variable:
+
+```bash
+# Linux/macOS
+export NO_COLOR=1
+node scripts/tutorial-runner.js status
+
+# Windows PowerShell
+$env:NO_COLOR = "1"
+node scripts/tutorial-runner.js status
+
+# Windows CMD
+set NO_COLOR=1
+node scripts/tutorial-runner.js status
+```
+
+### Option 2: Command Line Flags
+
+```bash
+# Use --accessible flag
+node scripts/tutorial-runner.js --accessible status
+
+# Or --no-color flag
+node scripts/tutorial-runner.js --no-color status
+```
+
+### Option 3: TERM Environment Variable
+
+Setting `TERM=dumb` also activates accessible mode:
+
+```bash
+TERM=dumb node scripts/tutorial-runner.js status
+```
+
+## Accessibility Features
+
+### 1. Semantic Indicators
+
+The tutorial never relies on color alone to convey information:
+
+| Status | Symbol | Text Indicator |
+|--------|--------|----------------|
+| Completed | ✓ | Checkmark visible |
+| Current | → | "YOU ARE HERE" label |
+| Pending | ○ | Circle indicator |
+
+### 2. Progress Information
+
+Progress is always conveyed through multiple channels:
+
+```
+Progress: [████░░░░░░░░░░░░░░░░] 3/9 lessons (33%)
+```
+
+- Visual progress bar
+- Numeric count (3/9)
+- Percentage (33%)
+
+### 3. High Contrast
+
+In standard mode, the tutorial uses high-contrast color combinations:
+
+| Element | Color | Contrast Ratio |
+|---------|-------|----------------|
+| Title | Cyan on black | >7:1 |
+| Completed | Green on black | >4.5:1 |
+| Current | Yellow on black | >4.5:1 |
+| Pending | Gray on black | >4.5:1 |
+
+### 4. Plain Text Fallbacks
+
+In accessible mode, all visual elements degrade to readable plain text:
+
+```
+════════════════════════════════════════════════════════
+
+  EVERYTHING CLAUDE CODE TUTORIAL
+  Learn the system in 9 interactive lessons
+
+════════════════════════════════════════════════════════
+
+Progress: [░░░░░░░░░░░░░░░░░░░░] 0/9 lessons (0%)
+
+  → Lesson 1: Core Concepts <- YOU ARE HERE
+  ○ Lesson 2: Training Mode
+  ○ Lesson 3: Essential Commands
+  ...
+```
+
+### 5. Error Messages
+
+Error messages are clear and descriptive without relying on color:
+
+```
+Invalid lesson number: 99. Valid: 1-9
+```
+
+## Screen Reader Compatibility
+
+The tutorial output is designed to be screen reader friendly:
+
+1. **Linear reading order** - Content flows logically from top to bottom
+2. **No hidden content** - All information is in the text stream
+3. **Clear labels** - Elements like "Progress:" and "Lesson 1:" are labeled
+4. **No timing** - No time-limited interactions or animations
+
+### Tested Screen Readers
+
+- NVDA (Windows)
+- VoiceOver (macOS)
+- JAWS (Windows)
+
+## Known Limitations
+
+1. **Box-drawing characters** - Unicode box characters (╔, ║, ╚) may not be announced by all screen readers. The content inside is always readable.
+
+2. **Progress bar characters** - Block characters (█, ░) may be read as "block" or similar. The numeric percentage is always provided.
+
+3. **Terminal limitations** - Some terminal emulators may not support all Unicode characters. The tutorial degrades gracefully.
+
+## Reporting Accessibility Issues
+
+If you encounter accessibility issues:
+
+1. Open an issue on GitHub
+2. Describe your assistive technology (screen reader, terminal, etc.)
+3. Include the specific output or behavior
+4. Suggest improvements if possible
+
+## Testing Accessibility
+
+Run the accessibility test suite:
+
+```bash
+node tests/accessibility.test.js
+```
+
+Expected output:
+
+```
+=== Accessibility Tests (WCAG 2.1 AA) ===
+
+NO_COLOR Environment Variable:
+  ✓ NO_COLOR=1 produces output without ANSI escape codes
+  ✓ --accessible flag produces output without ANSI codes
+  ...
+
+=== Accessibility Test Results ===
+Passed: 13
+Failed: 0
+```
+
+## References
+
+- [NO_COLOR Standard](https://no-color.org/)
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [CLI Accessibility Best Practices](https://clig.dev/#accessibility)

package/skills/tutorial/lessons/00-philosophy-and-workflow.md

@@ -0,0 +1,198 @@
+# Lesson 0: The Philosophy - How to Approach Development
+
+Before learning any commands, understand **why** this system exists and **how** to approach development with it.
+
+## Why This System Exists
+
+CloudStream Software LLC is a consultancy. Every engagement means:
+- **Billable work** that must be traceable
+- **Multiple clients** that require isolation
+- **Regulated industries** (HIPAA, SOC2, PCI-DSS) with compliance requirements
+- **Knowledge that compounds** across projects
+
+The "CloudStream Claude Tools" system was built to solve these challenges with a single principle:
+
+> **All work must meet top 1% enterprise professional quality - the Golden Standard.**
+
+This means code that would pass review at Google, Microsoft, or Amazon. Every commit auditable. Every pattern reusable.
+
+## The Daily Workflow Lifecycle
+
+Your day with this system follows a predictable pattern:
+
+### Session Start (Automatic)
+
+When you launch Claude Code, the system automatically:
+- Restores context from your previous session
+- Detects which client you're working on (credentials, compliance mode)
+- Shows tutorial progress if you haven't completed it
+- Loads learned patterns from previous work
+
+**You don't start with a blank slate - the system remembers.**
+
+### Working on a Feature (The Core Loop)
+
+Every feature follows the same four-step sequence:
+
+```
+/plan  -->  /tdd  -->  /code-review  -->  /verify
+```
+
+| Step | Command | Why It Matters |
+|------|---------|----------------|
+| 1 | `/plan` | Design before coding (prevents scope creep) |
+| 2 | `/tdd` | Tests first (ensures testability) |
+| 3 | `/code-review` | Quality gate (catches issues) |
+| 4 | `/verify` | Final validation (before commit) |
+
+This sequence isn't arbitrary - it's battle-tested to prevent the most common development mistakes:
+- Planning prevents "I coded for 2 hours, now we're changing requirements"
+- TDD prevents untestable spaghetti code
+- Code review catches security issues before production
+- Verify ensures no broken builds are committed
+
+### Session End (Automatic)
+
+When your session ends:
+- Session state is saved automatically
+- Use `/learn` to capture reusable patterns from today's work
+- Your discoveries become available for future projects
+
+## The "Aha Moment"
+
+The breakthrough understanding that makes this system powerful:
+
+**Your work on one client directly accelerates delivery for the next client.**
+
+How it works:
+1. You solve a problem for Client A
+2. You run `/learn` to extract the pattern (sanitized - no client-specific data)
+3. That pattern goes into the knowledge base with tags (industry, compliance, technology)
+4. Next quarter, when Client B has a similar problem, the pattern is ready
+
+In consulting, this is rare. Most firms rebuild the same solutions repeatedly. This system creates compounding returns on your expertise.
+
+## Training Mode: Teaching While You Work
+
+This is what makes CloudStream Claude Tools fundamentally different from vanilla Claude Code.
+
+| Vanilla Claude | CloudStream Claude Tools |
+|----------------|------------------------|
+| Reactive: you ask, it does | Proactive: it teaches while you work |
+| No guidance on approach | Suggests optimal workflows |
+| Each session starts fresh | Context and knowledge persist |
+| You must know best practices | Best practices are built-in |
+
+### How Training Mode Works
+
+When you type a request, the system:
+1. **Analyzes your intent** through keyword detection
+   - "Add a feature" → feature workflow
+   - "Fix this bug" → bug fix workflow
+   - "Refactor the code" → refactor workflow
+2. **Suggests the optimal command sequence**
+3. **Explains WHY** this order matters
+4. **Lets you proceed, modify, or skip**
+
+Example:
+```
+You: "Add a login feature"
+
+[Training Mode] Intent detected: NEW FEATURE + SECURITY-SENSITIVE
+
+Suggested workflow:
+  /plan "Add login feature"
+  /tdd "Login component"
+  /code-review (with security focus)
+  /verify
+
+Rationale: Plan prevents scope creep. TDD ensures testability.
+Security review catches auth vulnerabilities before production.
+
+Ready to proceed? (yes/modify/skip)
+```
+
+Over time, you internalize these patterns. Training mode makes them muscle memory.
+
+## What Makes This Different
+
+Think of the difference this way:
+
+**Without this system:**
+- You code first, plan later (maybe)
+- Tests are an afterthought
+- Security issues found in production
+- Each project reinvents patterns
+- Knowledge lives in developers' heads
+
+**With this system:**
+- Plan → Code → Review → Verify (every time)
+- Tests drive development
+- Security reviewed before merge
+- Patterns extracted and reused
+- Knowledge persists in the system
+
+The goal isn't to slow you down - it's to make the right way the easy way.
+
+## Exercise
+
+### Exercise 0.1: Understand Your Session Context
+
+When Claude Code starts, notice what context is restored:
+- Previous session state?
+- Which client/project?
+- Compliance mode?
+- Tutorial progress?
+
+**Observation**: The system already knows context you'd normally have to re-establish.
+
+### Exercise 0.2: Observe Training Mode
+
+Try typing a request and observe the suggestion:
+
+```
+Add validation to the user form
+```
+
+Notice:
+- Does it suggest a workflow?
+- Does it explain why?
+- Can you modify or skip?
+
+### Exercise 0.3: Preview the Core Loop
+
+These are the commands you'll master in upcoming lessons:
+
+| Command | Purpose | Lesson |
+|---------|---------|--------|
+| `/verify` | Validate project state | 1 |
+| `/plan` | Design implementation | 3 |
+| `/tdd` | Test-driven development | 3 |
+| `/code-review` | Quality check | 3 |
+| `/checkpoint` | Create safe restore point | 3 |
+
+You don't need to memorize them now - just know they exist and work together.
+
+## Verification
+
+You've understood this lesson if you can answer:
+
+- [ ] Why does planning come before coding?
+- [ ] What happens automatically when a session starts?
+- [ ] What is the "aha moment" about knowledge compounding?
+- [ ] How does training mode help you learn optimal patterns?
+
+## Key Takeaway
+
+This system is designed to make the right way the easy way. It teaches while you work, enforces quality automatically, and compounds your expertise across projects.
+
+**The goal: Build muscle memory for Golden Standard quality.**
+
+## Next Steps
+
+In Lesson 1, you'll learn the core architecture (Commands → Agents → Rules → Skills) and run your first command.
+
+---
+
+**Concepts learned**: Daily workflow, core loop (plan/tdd/review/verify), training mode, knowledge compounding
+**Key insight**: The system teaches while you work - it's proactive, not just reactive

package/skills/tutorial/lessons/01-basics.md

@@ -0,0 +1,81 @@
+# Lesson 1: Core Concepts
+
+Welcome to the CloudStream Claude Tools tutorial. This lesson introduces the fundamental mental model.
+
+> **Prerequisite**: If you haven't read [Lesson 0: Philosophy & Workflow](00-philosophy-and-workflow.md), start there to understand the "why" before the "what".
+
+## The Golden Standard
+
+Before diving into commands, understand the quality bar: **top 1% enterprise professional quality**. This isn't aspirational - it's the baseline. Everything you produce should be:
+- Production-ready and bulletproof
+- 80%+ test coverage (TDD workflow)
+- Security-reviewed (OWASP Top 10 awareness)
+- Handoff-ready documentation
+
+The system enforces this through rules, hooks, and guided workflows.
+
+## Overview
+
+The CloudStream Claude Tools system is built around a simple hierarchy:
+
+**Commands** → **Agents** → **Rules** → **Skills**
+
+- **Commands** are what you type (e.g., `/verify`, `/tdd`, `/plan`)
+- **Agents** are specialized AI personas that execute commands
+- **Rules** define behavior constraints and patterns
+- **Skills** provide reusable knowledge and templates
+
+Think of it like a restaurant:
+- Commands = your order ("I'll have the steak")
+- Agents = the chef who prepares it (knows techniques)
+- Rules = the recipe (constraints and steps)
+- Skills = cooking techniques the chef knows
+
+## Why This Matters
+
+This architecture means:
+1. **Consistency**: Same command always triggers the same workflow
+2. **Expertise**: Agents have deep domain knowledge built-in
+3. **Customization**: Rules can be adjusted per-project
+4. **Extensibility**: New skills can be added without breaking existing ones
+
+You don't need to memorize all agents or rules. Just learn the commands, and the system handles the rest.
+
+## Exercise
+
+Let's run your first command. The `/verify` command is the most important - it validates your entire project.
+
+**Step 1**: Navigate to a project directory (or the tutorial-test folder)
+
+**Step 2**: Run the verify command:
+```
+/verify
+```
+
+**Step 3**: Watch what happens:
+1. Build check runs
+2. Tests execute
+3. Lint validates code style
+4. Type check verifies TypeScript
+
+## Verification
+
+You've completed this exercise successfully if:
+- [ ] You saw output from multiple verification steps
+- [ ] Each step showed a pass/fail status
+- [ ] The command finished with an overall status
+
+If `/verify` found issues, that's okay! The point is to see the multi-step workflow in action.
+
+## Key Takeaway
+
+The `/verify` command is your safety net. Run it before every commit to catch issues early.
+
+## Next Steps
+
+In Lesson 2, you'll learn about Training Mode - how the system suggests optimal workflows based on your intent.
+
+---
+
+**Command learned**: `/verify` - runs build, tests, lint, and type checks
+**Progress**: 2 of 15 lessons complete