@atlashub/smartstack-cli 1.23.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, APEX, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/check-version/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: check-version
+description: Verify version alignment between package.json and documentation
+model: haiku
+---
+
+<objective>
+Verify that the version in `package.json` is aligned with all documentation files in `.documentation/`.
+Use before releases or as part of release process to ensure documentation is up-to-date.
+</objective>
+
+<quick_start>
+```bash
+/check-version            # Check version alignment (interactive)
+/check-version:fix        # Auto-update all doc files
+/check-version:report     # Detailed report without prompts
+```
+</quick_start>
+
+<subcommands>
+
+| Command | Description |
+|---------|-------------|
+| `/check-version` | Check alignment, prompt to fix if mismatches |
+| `/check-version:fix` | Auto-update documentation versions |
+| `/check-version:report` | Detailed report without prompts |
+
+</subcommands>
+
+<workflow>
+
+## Step 1: Read Package Version
+
+```bash
+PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)
+echo "Package version: $PKG_VERSION"
+```
+
+## Step 2: Scan Documentation Files
+
+```bash
+echo "Scanning documentation files..."
+
+for file in .documentation/*.html; do
+  if [ -f "$file" ]; then
+    DOC_VERSION=$(grep -oP 'version-badge">v?\K[^<]+' "$file" | head -1)
+    if [ -n "$DOC_VERSION" ]; then
+      FILENAME=$(basename "$file")
+      DOC_VERSION_CLEAN=${DOC_VERSION#v}
+
+      if [ "$DOC_VERSION_CLEAN" = "$PKG_VERSION" ]; then
+        echo "OK $FILENAME: v$DOC_VERSION_CLEAN"
+      else
+        echo "MISMATCH $FILENAME: v$DOC_VERSION_CLEAN (expected v$PKG_VERSION)"
+      fi
+    fi
+  fi
+done
+```
+
+## Step 3: Generate Report
+
+Display results:
+```
+================================================================================
+                    VERSION ALIGNMENT CHECK
+================================================================================
+
+Package version: vX.Y.Z
+Documentation files checked: N
+Mismatches found: M
+
+STATUS: PASSED | FAILED
+================================================================================
+```
+
+## Step 4: Handle Mismatches (Interactive)
+
+If mismatches detected, ask user:
+
+```yaml
+questions:
+  - header: "Fix versions"
+    question: "Des fichiers de documentation ont des versions obsoletes. Voulez-vous les mettre a jour automatiquement?"
+    options:
+      - label: "Oui, mettre a jour (Recommended)"
+        description: "Met a jour tous les fichiers avec la version actuelle"
+      - label: "Non, ignorer"
+        description: "Continuer sans corriger les versions"
+    multiSelect: false
+```
+
+</workflow>
+
+<fix_command>
+
+## /check-version:fix
+
+Auto-update all documentation files:
+
+```bash
+PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)
+
+echo "Updating documentation to v$PKG_VERSION..."
+
+UPDATED_COUNT=0
+
+for file in .documentation/*.html; do
+  if [ -f "$file" ]; then
+    DOC_VERSION=$(grep -oP 'version-badge">v?\K[^<]+' "$file" | head -1)
+    if [ -n "$DOC_VERSION" ]; then
+      DOC_VERSION_CLEAN=${DOC_VERSION#v}
+      if [ "$DOC_VERSION_CLEAN" != "$PKG_VERSION" ]; then
+        sed -i "s/version-badge\">v[^<]*/version-badge\">v$PKG_VERSION/" "$file"
+        UPDATED_COUNT=$((UPDATED_COUNT + 1))
+        echo "UPDATED $(basename "$file"): v$DOC_VERSION_CLEAN -> v$PKG_VERSION"
+      fi
+    fi
+  fi
+done
+
+echo ""
+if [ "$UPDATED_COUNT" -gt 0 ]; then
+  echo "OK $UPDATED_COUNT file(s) updated"
+  echo ""
+  echo "Next steps:"
+  echo "  1. Review changes: git diff .documentation/"
+  echo "  2. Commit: /gitflow:commit"
+fi
+```
+
+</fix_command>
+
+<report_command>
+
+## /check-version:report
+
+Detailed report without prompts:
+
+```
+================================================================================
+         VERSION ALIGNMENT DETAILED REPORT
+================================================================================
+
+Package: @atlashub/smartstack-cli
+Current version: vX.Y.Z
+
+---------------------------------------------------------------------
+FILE                          | DOC VERSION | STATUS
+---------------------------------------------------------------------
+guide.html                    | vX.Y.Z      | OK
+api-reference.html            | vX.Y.Y      | MISMATCH
+---------------------------------------------------------------------
+```
+
+</report_command>
+
+<gitflow_integration>
+
+This skill is automatically called during `/gitflow:11-finish` for release branches.
+
+If mismatches detected during release finish:
+- Warning displayed
+- User prompted to fix with `/check-version:fix`
+- Release blocked until versions aligned
+
+</gitflow_integration>
+
+<files_checked>
+
+- `.documentation/*.html` - All HTML documentation files
+- Pattern: `<span class="version-badge">vX.Y.Z</span>`
+
+</files_checked>
+
+<exit_codes>
+
+| Code | Meaning |
+|------|---------|
+| 0 | All versions aligned |
+| 1 | Mismatches detected (blocking for releases) |
+
+</exit_codes>

package/templates/skills/debug/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: debug
+description: Systematic bug debugging with deep analysis and resolution
+argument-hint: <log|error|problem-description>
+---
+
+<objective>
+Follow an ultra-deep analysis workflow to identify, understand, and resolve bugs.
+**ULTRA THINK** at each phase transition.
+</objective>
+
+<quick_start>
+```bash
+/debug "NullReferenceException in UserService"
+/debug paste the error log here
+/debug why does login fail on mobile?
+```
+</quick_start>
+
+<workflow>
+
+## 1. ANALYZE: Deep Log/Error Analysis
+
+- Parse the provided log/error message carefully
+- Extract key error patterns, stack traces, and symptoms
+- Identify error types: runtime, compile-time, logic, performance
+- **CRITICAL**: Document exact error context and reproduction steps
+
+## 2. EXPLORE: Targeted Codebase Investigation
+
+Launch **parallel subagents** to search for error-related code:
+
+**Agent 1: Codebase Search** (`explore-codebase`)
+```
+Find code related to this error: {error_description}
+Search for:
+- Error source location from stack trace
+- Related error handling patterns
+- Similar code that works correctly
+Report file paths with line numbers.
+```
+
+**Agent 2: Documentation** (`explore-docs`)
+```
+Research documentation for: {libraries_in_stacktrace}
+Find:
+- Known issues or breaking changes
+- Correct usage patterns
+- Migration guides if version issues
+```
+
+**Agent 3: Web Research** (`websearch`)
+```
+Search for: {error_message}
+Find:
+- Similar issues reported by others
+- Solutions and workarounds
+- Root cause explanations
+```
+
+Additional investigation:
+- Search for similar error patterns in codebase using Grep
+- Find all files related to the failing component/module
+- Examine recent changes that might have introduced the bug
+- **ULTRA THINK**: Connect error symptoms to potential root causes
+
+## 3. ULTRA-THINK: Deep Root Cause Analysis
+
+**THINK DEEPLY** about the error chain: symptoms -> immediate cause -> root cause
+
+Consider all possible causes:
+- Code logic errors
+- Configuration issues
+- Environment problems
+- Race conditions
+- Memory issues
+- Network problems
+
+**CRITICAL**: Map the complete failure path from root cause to visible symptom
+Validate hypotheses against the evidence
+
+### WHY Technique
+
+Ask "why" at least 5 times:
+1. Why did the error occur? -> X happened
+2. Why did X happen? -> Y was in invalid state
+3. Why was Y invalid? -> Z didn't initialize properly
+4. Why didn't Z initialize? -> A dependency was missing
+5. Why was dependency missing? -> Configuration error
+
+## 4. RESEARCH: Solution Investigation
+
+Launch **parallel subagents** for solution research:
+
+**Agent: Solution Search** (`websearch`)
+```
+Search for solutions to: {root_cause}
+Find:
+- Recommended fixes
+- Best practices
+- Workarounds if fix is complex
+```
+
+Evaluate solutions:
+- Search for similar issues and solutions online
+- Check documentation for affected libraries/frameworks
+- Look for known bugs, workarounds, and best practices
+- **THINK**: Evaluate solution approaches for this specific context
+
+## 5. IMPLEMENT: Systematic Resolution
+
+- Choose the most appropriate solution based on analysis
+- Follow existing codebase patterns and conventions
+- Implement minimal, targeted fixes
+- **STAY IN SCOPE**: Fix only what's needed for this specific bug
+- Add defensive programming where appropriate
+
+## 6. VERIFY: Comprehensive Testing
+
+- Test the specific scenario that was failing
+- Run related tests to ensure no regressions
+- Check edge cases around the fix
+- **CRITICAL**: Verify the original error is completely resolved
+
+</workflow>
+
+<analysis_techniques>
+
+### Log Analysis
+- Extract timestamps, error codes, stack traces
+- Identify error propagation patterns
+- Look for correlation with system events
+
+### Code Investigation
+- Trace execution path to error location
+- Check variable states and data flow
+- Examine error handling patterns
+- Review recent commits affecting the area
+
+### Root Cause Mapping
+- **WHY technique**: Ask "why" 5 times minimum
+- Consider environmental factors
+- Check for timing/concurrency issues
+- Validate assumptions about data/state
+
+</analysis_techniques>
+
+<execution_rules>
+
+- **ULTRA THINK** at each phase transition
+- Use parallel agents for comprehensive investigation
+- Document findings and reasoning at each step
+- **NEVER guess** - validate all hypotheses with evidence
+- **MINIMAL CHANGES**: Fix root cause, not symptoms
+- Test thoroughly before declaring resolution complete
+
+</execution_rules>
+
+<priority>
+Understanding > Speed > Completeness. Every bug must be fully understood before attempting fixes.
+</priority>

package/templates/skills/explore/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: explore
+description: Deep codebase exploration to answer specific questions
+argument-hint: <question>
+---
+
+<objective>
+Answer questions about the codebase through systematic investigation using parallel exploration agents.
+</objective>
+
+<quick_start>
+```bash
+/explore where is authentication handled?
+/explore how does the payment flow work?
+/explore what patterns are used for validation?
+```
+</quick_start>
+
+<workflow>
+
+## 1. Parse Question
+
+- Extract key terms and concepts from question
+- Identify file types, patterns, or areas to search
+- Determine if web research is needed
+
+## 2. Search Codebase (Parallel Agents)
+
+Launch multiple exploration agents **in parallel**:
+
+**Agent 1: Codebase Exploration** (`explore-codebase`)
+```
+Find existing code related to: {question}
+
+Report ONLY what exists:
+1. Files that contain related code (with paths and line numbers)
+2. Existing patterns used for similar features
+3. Utility functions that might be relevant
+4. How similar features are currently structured
+5. Test file locations and patterns
+
+DO NOT suggest what to build. Just report what's there.
+```
+
+**Agent 2: Documentation Research** (`explore-docs`)
+```
+Research documentation for libraries used in: {question}
+
+Find:
+1. How the relevant libraries/frameworks work
+2. API documentation for tools being used
+3. Best practices from official docs
+```
+
+**Agent 3: Web Research** (`websearch`) - *if external context needed*
+```
+Search for context about: {question}
+
+Find:
+1. How this is typically implemented
+2. Common patterns and approaches
+3. Known pitfalls or gotchas
+```
+
+**CRITICAL**: Launch agents in a SINGLE message for parallel execution.
+
+## 3. Analyze Findings
+
+- Read relevant files found by agents
+- Trace relationships between files
+- Identify patterns and conventions
+- Note file paths with line numbers (e.g., `src/app.ts:42`)
+
+## 4. Answer Question
+
+Provide comprehensive response:
+- Direct answer to the question
+- Supporting evidence with file references
+- Code examples if relevant
+- Architectural context when useful
+
+</workflow>
+
+<execution_rules>
+
+- **PARALLEL SEARCH**: Launch multiple agents simultaneously
+- **CITE SOURCES**: Always reference file paths and line numbers
+- **STAY FOCUSED**: Only explore what's needed to answer the question
+- **BE THOROUGH**: Don't stop at first match - gather complete context
+- **ULTRA THINK**: Consider relationships between discovered elements
+
+</execution_rules>
+
+<priority>
+Accuracy > Speed > Brevity. Provide complete answers with evidence.
+</priority>

package/templates/skills/quick-search/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: quick-search
+description: Lightning-fast search to answer specific questions - optimized for speed
+argument-hint: <question>
+allowed-tools: Grep, Glob, Read
+model: haiku
+---
+
+<objective>
+Answer questions at maximum speed using direct search tools. No agents, no deep analysis - just fast answers with citations.
+</objective>
+
+<quick_start>
+```bash
+/quick-search where is LoginForm defined?
+/quick-search find all API routes
+/quick-search what config files exist?
+```
+</quick_start>
+
+<workflow>
+
+## 1. Identify
+
+Parse the question:
+- Extract key search terms
+- Determine target file types or patterns
+- **CRITICAL**: Be surgical - know exactly what to search
+
+## 2. Search (Direct Tools Only)
+
+Use direct tools - **NO AGENTS**:
+- `Grep` for code content search with specific patterns
+- `Glob` for file name/path patterns
+- Launch searches **in parallel** when possible
+
+**SPEED RULE**: Max 2-3 search iterations total
+
+## 3. Read (Targeted)
+
+- `Read` only the most relevant files found
+- **CRITICAL**: Max 3-5 files - be selective
+- Scan for the specific answer needed
+
+## 4. Answer
+
+Direct response:
+- Immediate answer to the question
+- Include file references with line numbers (`file.ts:42`)
+- **NO**: Long explanations or architectural context
+- **YES**: Concise answer with evidence
+
+</workflow>
+
+<search_patterns>
+
+**Finding implementations:**
+```
+Grep: pattern="class FooBar" or "function fooBar"
+```
+
+**Finding configs:**
+```
+Glob: pattern="**/config.{js,ts,json}"
+```
+
+**Finding imports/usage:**
+```
+Grep: pattern="from ['\"].*moduleName['\"]"
+```
+
+</search_patterns>
+
+<execution_rules>
+
+- **SPEED FIRST**: Answer in under 30 seconds
+- **NO AGENTS**: Use direct tools only (Grep, Glob, Read)
+- **PARALLEL SEARCH**: Run independent searches simultaneously
+- **MINIMAL READING**: Read only what's absolutely necessary
+- **NO DEEP ANALYSIS**: Surface-level answers with citations
+- **STOP EARLY**: Once you have the answer, respond immediately
+
+</execution_rules>
+
+<priority>
+Speed > Completeness. Fast answers beat perfect answers.
+</priority>