@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/chaos-engineer.md

@@ -0,0 +1,98 @@
+---
+name: chaos-engineer
+description: Use when designing chaos experiments, implementing failure injection frameworks, or conducting game day exercises. Invoke for chaos experiments, resilience testing, blast radius control, game days, antifragile systems.
+triggers:
+  - chaos engineering
+  - resilience testing
+  - failure injection
+  - game day
+  - blast radius
+  - chaos experiment
+  - fault injection
+  - Chaos Monkey
+  - Litmus Chaos
+  - antifragile
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# Chaos Engineer
+
+Senior chaos engineer with deep expertise in controlled failure injection, resilience testing, and building systems that get stronger under stress.
+
+## Role Definition
+
+You are a senior chaos engineer with 10+ years of experience in reliability engineering and resilience testing. You specialize in designing and executing controlled chaos experiments, managing blast radius, and building organizational resilience through scientific experimentation and continuous learning from controlled failures.
+
+## When to Use This Skill
+
+- Designing and executing chaos experiments
+- Implementing failure injection frameworks (Chaos Monkey, Litmus, etc.)
+- Planning and conducting game day exercises
+- Building blast radius controls and safety mechanisms
+- Setting up continuous chaos testing in CI/CD
+- Improving system resilience based on experiment findings
+
+## Core Workflow
+
+1. **System Analysis** - Map architecture, dependencies, critical paths, and failure modes
+2. **Experiment Design** - Define hypothesis, steady state, blast radius, and safety controls
+3. **Execute Chaos** - Run controlled experiments with monitoring and quick rollback
+4. **Learn & Improve** - Document findings, implement fixes, enhance monitoring
+5. **Automate** - Integrate chaos testing into CI/CD for continuous resilience
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Experiments | `references/experiment-design.md` | Designing hypothesis, blast radius, rollback |
+| Infrastructure | `references/infrastructure-chaos.md` | Server, network, zone, region failures |
+| Kubernetes | `references/kubernetes-chaos.md` | Pod, node, Litmus, chaos mesh experiments |
+| Tools & Automation | `references/chaos-tools.md` | Chaos Monkey, Gremlin, Pumba, CI/CD integration |
+| Game Days | `references/game-days.md` | Planning, executing, learning from game days |
+
+## Constraints
+
+### MUST DO
+- Define steady state metrics before experiments
+- Document hypothesis clearly
+- Control blast radius (start small, isolate impact)
+- Enable automated rollback under 30 seconds
+- Monitor continuously during experiments
+- Ensure zero customer impact initially
+- Capture all learnings and share
+- Implement improvements from findings
+
+### MUST NOT DO
+- Run experiments without hypothesis
+- Skip blast radius controls
+- Test in production without safety nets
+- Ignore monitoring during experiments
+- Run multiple variables simultaneously (initially)
+- Forget to document learnings
+- Skip team communication
+- Leave systems in degraded state
+
+## Output Templates
+
+When implementing chaos engineering, provide:
+1. Experiment design document (hypothesis, metrics, blast radius)
+2. Implementation code (failure injection scripts/manifests)
+3. Monitoring setup and alert configuration
+4. Rollback procedures and safety controls
+5. Learning summary and improvement recommendations
+
+## Knowledge Reference
+
+Chaos Monkey, Litmus Chaos, Chaos Mesh, Gremlin, Pumba, toxiproxy, chaos experiments, blast radius control, game days, failure injection, network chaos, infrastructure resilience, Kubernetes chaos, organizational resilience, MTTR reduction, antifragile systems
+
+## Related Skills
+
+- **SRE Engineer** - Reliability and incident response
+- **DevOps Engineer** - CI/CD integration for chaos
+- **Kubernetes Specialist** - K8s-specific chaos engineering
+- **Platform Engineer** - Building chaos platforms
+- **Performance Engineer** - Load and performance chaos

package/merged-commands/chrome-devtools.md

@@ -0,0 +1,407 @@
+---
+name: chrome-devtools
+description: Browser automation, debugging, and performance analysis using Puppeteer CLI scripts. Use for automating browsers, taking screenshots, analyzing performance, monitoring network traffic, web scraping, form automation, and JavaScript debugging.
+license: Apache-2.0
+---
+
+# Chrome DevTools Agent Skill
+
+Browser automation via executable Puppeteer scripts. All scripts output JSON for easy parsing.
+
+## Quick Start
+
+**CRITICAL**: Always check `pwd` before running scripts.
+
+### Installation
+
+#### Step 1: Install System Dependencies (Linux/WSL only)
+
+On Linux/WSL, Chrome requires system libraries. Install them first:
+
+```bash
+pwd  # Should show current working directory
+cd ~/.{TOOL}/skills/chrome-devtools/scripts
+./install-deps.sh  # Auto-detects OS and installs required libs
+```
+
+Supports: Ubuntu, Debian, Fedora, RHEL, CentOS, Arch, Manjaro
+
+**macOS/Windows**: Skip this step (dependencies bundled with Chrome)
+
+#### Step 2: Install Node Dependencies
+
+```bash
+npm install  # Installs puppeteer, debug, yargs
+```
+
+#### Step 3: Install ImageMagick (Optional, Recommended)
+
+ImageMagick enables automatic screenshot compression to keep files under 5MB:
+
+**macOS:**
+
+```bash
+brew install imagemagick
+```
+
+**Ubuntu/Debian/WSL:**
+
+```bash
+sudo apt-get install imagemagick
+```
+
+**Verify:**
+
+```bash
+magick -version  # or: convert -version
+```
+
+Without ImageMagick, screenshots >5MB will not be compressed (may fail to load in Gemini/Claude).
+
+### Test
+
+```bash
+node navigate.js --url https://example.com
+# Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}
+```
+
+## Available Scripts
+
+All scripts are in `~/.{TOOL}/skills/chrome-devtools/scripts/`
+
+**CRITICAL**: Always check `pwd` before running scripts.
+
+### Script Usage
+
+- `./scripts/README.md`
+
+### Core Automation
+
+- `navigate.js` - Navigate to URLs
+- `screenshot.js` - Capture screenshots (full page or element)
+- `click.js` - Click elements
+- `fill.js` - Fill form fields
+- `evaluate.js` - Execute JavaScript in page context
+
+### Analysis & Monitoring
+
+- `snapshot.js` - Extract interactive elements with metadata
+- `console.js` - Monitor console messages/errors
+- `network.js` - Track HTTP requests/responses
+- `performance.js` - Measure Core Web Vitals + record traces
+
+## Usage Patterns
+
+### Single Command
+
+```bash
+pwd  # Should show current working directory
+cd ~/.{TOOL}/skills/chrome-devtools/scripts
+node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
+```
+
+**Important**: Always save screenshots to `./docs/screenshots` directory.
+
+### Automatic Image Compression
+
+Screenshots are **automatically compressed** if they exceed 5MB to ensure compatibility with host AI tool (which have 5MB limits). This uses ImageMagick internally:
+
+```bash
+# Default: auto-compress if >5MB
+node screenshot.js --url https://example.com --output page.png
+
+# Custom size threshold (e.g., 3MB)
+node screenshot.js --url https://example.com --output page.png --max-size 3
+
+# Disable compression
+node screenshot.js --url https://example.com --output page.png --no-compress
+```
+
+**Compression behavior:**
+
+- PNG: Resizes to 90% + quality 85 (or 75% + quality 70 if still too large)
+- JPEG: Quality 80 + progressive encoding (or quality 60 if still too large)
+- Other formats: Converted to JPEG with compression
+- Requires ImageMagick installed (see imagemagick skill)
+
+**Output includes compression info:**
+
+```json
+{
+  "success": true,
+  "output": "/path/to/page.png",
+  "compressed": true,
+  "originalSize": 8388608,
+  "size": 3145728,
+  "compressionRatio": "62.50%",
+  "url": "https://example.com"
+}
+```
+
+### Chain Commands (reuse browser)
+
+```bash
+# Keep browser open with --close false
+node navigate.js --url https://example.com/login --close false
+node fill.js --selector "#email" --value "user@example.com" --close false
+node fill.js --selector "#password" --value "secret" --close false
+node click.js --selector "button[type=submit]"
+```
+
+### Parse JSON Output
+
+```bash
+# Extract specific fields with jq
+node performance.js --url https://example.com | jq '.vitals.LCP'
+
+# Save to file
+node network.js --url https://example.com --output /tmp/requests.json
+```
+
+## Execution Protocol
+
+### Working Directory Verification
+
+BEFORE executing any script:
+
+1. Check current working directory with `pwd`
+2. Verify in `~/.{TOOL}/skills/chrome-devtools/scripts/` directory
+3. If wrong directory, `cd` to correct location
+4. Use absolute paths for all output files
+
+Example:
+
+```bash
+pwd  # Should show: .../chrome-devtools/scripts
+# If wrong:
+cd ~/.{TOOL}/skills/chrome-devtools/scripts
+```
+
+### Output Validation
+
+AFTER screenshot/capture operations:
+
+1. Verify file created with `ls -lh <output-path>`
+2. Read screenshot using Read tool to confirm content
+3. Check JSON output for success:true
+4. Report file size and compression status
+
+Example:
+
+```bash
+node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
+ls -lh ./docs/screenshots/page.png  # Verify file exists
+# Then use Read tool to visually inspect
+```
+
+5. Restart working directory to the project root.
+
+### Error Recovery
+
+If script fails:
+
+1. Check error message for selector issues
+2. Use snapshot.js to discover correct selectors
+3. Try XPath selector if CSS selector fails
+4. Verify element is visible and interactive
+
+Example:
+
+```bash
+# CSS selector fails
+node click.js --url https://example.com --selector ".btn-submit"
+# Error: waiting for selector ".btn-submit" failed
+
+# Discover correct selector
+node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'
+
+# Try XPath
+node click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"
+```
+
+### Common Mistakes
+
+❌ Wrong working directory → output files go to wrong location
+❌ Skipping output validation → silent failures
+❌ Using complex CSS selectors without testing → selector errors
+❌ Not checking element visibility → timeout errors
+
+✅ Always verify `pwd` before running scripts
+✅ Always validate output after screenshots
+✅ Use snapshot.js to discover selectors
+✅ Test selectors with simple commands first
+
+## Common Workflows
+
+### Web Scraping
+
+```bash
+node evaluate.js --url https://example.com --script "
+  Array.from(document.querySelectorAll('.item')).map(el => ({
+    title: el.querySelector('h2')?.textContent,
+    link: el.querySelector('a')?.href
+  }))
+" | jq '.result'
+```
+
+### Performance Testing
+
+```bash
+PERF=$(node performance.js --url https://example.com)
+LCP=$(echo $PERF | jq '.vitals.LCP')
+if (( $(echo "$LCP < 2500" | bc -l) )); then
+  echo "✓ LCP passed: ${LCP}ms"
+else
+  echo "✗ LCP failed: ${LCP}ms"
+fi
+```
+
+### Form Automation
+
+```bash
+node fill.js --url https://example.com --selector "#search" --value "query" --close false
+node click.js --selector "button[type=submit]"
+```
+
+### Error Monitoring
+
+```bash
+node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'
+```
+
+## Script Options
+
+All scripts support:
+
+- `--headless false` - Show browser window
+- `--close false` - Keep browser open for chaining
+- `--timeout 30000` - Set timeout (milliseconds)
+- `--wait-until networkidle2` - Wait strategy
+
+See `./scripts/README.md` for complete options.
+
+## Output Format
+
+All scripts output JSON to stdout:
+
+```json
+{
+  "success": true,
+  "url": "https://example.com",
+  ... // script-specific data
+}
+```
+
+Errors go to stderr:
+
+```json
+{
+  "success": false,
+  "error": "Error message"
+}
+```
+
+## Finding Elements
+
+Use `snapshot.js` to discover selectors:
+
+```bash
+node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'
+```
+
+## Troubleshooting
+
+### Common Errors
+
+**"Cannot find package 'puppeteer'"**
+
+- Run: `npm install` in the scripts directory
+
+**"error while loading shared libraries: libnss3.so"** (Linux/WSL)
+
+- Missing system dependencies
+- Fix: Run `./install-deps.sh` in scripts directory
+- Manual install: `sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1`
+
+**"Failed to launch the browser process"**
+
+- Check system dependencies installed (Linux/WSL)
+- Verify Chrome downloaded: `ls ~/.cache/puppeteer`
+- Try: `npm rebuild` then `npm install`
+
+**Chrome not found**
+
+- Puppeteer auto-downloads Chrome during `npm install`
+- If failed, manually trigger: `npx puppeteer browsers install chrome`
+
+### Script Issues
+
+**Element not found**
+
+- Get snapshot first to find correct selector: `node snapshot.js --url <url>`
+
+**Script hangs**
+
+- Increase timeout: `--timeout 60000`
+- Change wait strategy: `--wait-until load` or `--wait-until domcontentloaded`
+
+**Blank screenshot**
+
+- Wait for page load: `--wait-until networkidle2`
+- Increase timeout: `--timeout 30000`
+
+**Permission denied on scripts**
+
+- Make executable: `chmod +x *.sh`
+
+**Screenshot too large (>5MB)**
+
+- Install ImageMagick for automatic compression
+- Manually set lower threshold: `--max-size 3`
+- Use JPEG format instead of PNG: `--format jpeg --quality 80`
+- Capture specific element instead of full page: `--selector .main-content`
+
+**Compression not working**
+
+- Verify ImageMagick installed: `magick -version` or `convert -version`
+- Check file was actually compressed in output JSON: `"compressed": true`
+- For very large pages, use `--selector` to capture only needed area
+
+## Reference Documentation
+
+Detailed guides available in `./references/`:
+
+- [CDP Domains Reference](./references/cdp-domains.md) - 47 Chrome DevTools Protocol domains
+- [Puppeteer Quick Reference](./references/puppeteer-reference.md) - Complete Puppeteer API patterns
+- [Performance Analysis Guide](./references/performance-guide.md) - Core Web Vitals optimization
+
+## Advanced Usage
+
+### Custom Scripts
+
+Create custom scripts using shared library:
+
+```javascript
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  outputJSON,
+} from "./lib/browser.js";
+// Your automation logic
+```
+
+### Direct CDP Access
+
+```javascript
+const client = await page.createCDPSession();
+await client.send("Emulation.setCPUThrottlingRate", { rate: 4 });
+```
+
+See reference documentation for advanced patterns and complete API coverage.
+
+## External Resources
+
+- [Puppeteer Documentation](https://pptr.dev/)
+- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
+- [Scripts README](./scripts/README.md)

package/merged-commands/cicd-automation-workflow-automate.md

@@ -0,0 +1,51 @@
+---
+name: cicd-automation-workflow-automate
+description: "You are a workflow automation expert specializing in creating efficient CI/CD pipelines, GitHub Actions workflows, and automated development processes. Design automation that reduces manual work, improves consistency, and accelerates delivery while maintaining quality and security."
+---
+
+# Workflow Automation
+
+You are a workflow automation expert specializing in creating efficient CI/CD pipelines, GitHub Actions workflows, and automated development processes. Design and implement automation that reduces manual work, improves consistency, and accelerates delivery while maintaining quality and security.
+
+## Use this skill when
+
+- Automating CI/CD workflows or release pipelines
+- Designing GitHub Actions or multi-stage build/test/deploy flows
+- Replacing manual build, test, or deployment steps
+- Improving pipeline reliability, visibility, or compliance checks
+
+## Do not use this skill when
+
+- You only need a one-off command or quick troubleshooting
+- There is no workflow or automation context
+- The task is strictly product or UI design
+
+## Safety
+
+- Avoid running deployment steps without approvals and rollback plans.
+- Treat secrets and environment configuration changes as high risk.
+
+## Context
+The user needs to automate development workflows, deployment processes, or operational tasks. Focus on creating reliable, maintainable automation that handles edge cases, provides good visibility, and integrates well with existing tools and processes.
+
+## Requirements
+$ARGUMENTS
+
+## Instructions
+
+- Inventory current build, test, and deploy steps plus target environments.
+- Define pipeline stages with caching, artifacts, and quality gates.
+- Add security scans, secret handling, and approvals for risky steps.
+- Document rollout, rollback, and notification strategy.
+- If detailed workflow patterns are required, open `resources/implementation-playbook.md`.
+
+## Output Format
+
+- Summary of pipeline stages and triggers
+- Proposed workflow files or step list
+- Required secrets, env vars, and service integrations
+- Risks, assumptions, and rollback notes
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed workflow patterns and examples.

package/merged-commands/clarity-gate.md

@@ -0,0 +1,22 @@
+---
+name: clarity-gate
+description: "Pre-ingestion verification for epistemic quality in RAG systems with 9-point verification and Two-Round HITL workflow"
+source: "https://github.com/frmoretto/clarity-gate"
+risk: safe
+---
+
+# Clarity Gate
+
+## Overview
+
+Pre-ingestion verification for epistemic quality in RAG systems with 9-point verification and Two-Round HITL workflow
+
+## When to Use This Skill
+
+Use this skill when you need to work with pre-ingestion verification for epistemic quality in rag systems with 9-point verification and two-round hitl workflow.
+
+## Instructions
+
+This skill provides guidance and patterns for pre-ingestion verification for epistemic quality in rag systems with 9-point verification and two-round hitl workflow.
+
+For more information, see the [source repository](https://github.com/frmoretto/clarity-gate).

package/merged-commands/claude-ally-health.md

@@ -0,0 +1,22 @@
+---
+name: claude-ally-health
+description: "A health assistant skill for medical information analysis, symptom tracking, and wellness guidance."
+source: "https://github.com/huifer/Claude-Ally-Health"
+risk: safe
+---
+
+# Claude Ally Health
+
+## Overview
+
+A health assistant skill for medical information analysis, symptom tracking, and wellness guidance.
+
+## When to Use This Skill
+
+Use this skill when you need to work with a health assistant skill for medical information analysis, symptom tracking, and wellness guidance..
+
+## Instructions
+
+This skill provides guidance and patterns for a health assistant skill for medical information analysis, symptom tracking, and wellness guidance..
+
+For more information, see the [source repository](https://github.com/huifer/Claude-Ally-Health).

package/merged-commands/claude-code-guide.md

@@ -0,0 +1,68 @@
+---
+name: Claude Code Guide
+description: Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies "Thinking" keywords, debugging techniques, and best practices for interacting with the agent.
+---
+
+# Claude Code Guide
+
+## Purpose
+
+To provide a comprehensive reference for configuring and using Claude Code (the agentic coding tool) to its full potential. This skill synthesizes best practices, configuration templates, and advanced usage patterns.
+
+## Configuration (`CLAUDE.md`)
+
+When starting a new project, create a `CLAUDE.md` file in the root directory to guide the agent.
+
+### Template (General)
+
+```markdown
+# Project Guidelines
+
+## Commands
+
+- Run app: `npm run dev`
+- Test: `npm test`
+- Build: `npm run build`
+
+## Code Style
+
+- Use TypeScript for all new code.
+- Functional components with Hooks for React.
+- Tailwind CSS for styling.
+- Early returns for error handling.
+
+## Workflow
+
+- Read `README.md` first to understand project context.
+- Before editing, read the file content.
+- After editing, run tests to verify.
+```
+
+## Advanced Features
+
+### Thinking Keywords
+
+Use these keywords in your prompts to trigger deeper reasoning from the agent:
+
+- "Think step-by-step"
+- "Analyze the root cause"
+- "Plan before executing"
+- "Verify your assumptions"
+
+### Debugging
+
+If the agent is stuck or behaving unexpectedly:
+
+1. **Clear Context**: Start a new session or ask the agent to "forget previous instructions" if confused.
+2. **Explicit Instructions**: Be extremely specific about paths, filenames, and desired outcomes.
+3. **Logs**: Ask the agent to "check the logs" or "run the command with verbose output".
+
+## Best Practices
+
+1. **Small Contexts**: Don't dump the entire codebase into the context. Use `grep` or `find` to locate relevant files first.
+2. **Iterative Development**: Ask for small changes, verify, then proceed.
+3. **Feedback Loop**: If the agent makes a mistake, correct it immediately and ask it to "add a lesson" to its memory (if supported) or `CLAUDE.md`.
+
+## Reference
+
+Based on [Claude Code Guide by zebbern](https://github.com/zebbern/claude-code-guide).