@atlashub/smartstack-cli 1.23.0 → 1.25.0

package/templates/{commands/validate.md → skills/validate/SKILL.md}

@@ -1,36 +1,42 @@
 ---
+name: validate
 description: Validate SmartStack conventions using MCP
-agent: action
+argument-hint: "[scope]"
 model: sonnet
 ---
 
-# /validate - SmartStack Conventions Validator
-
-Validates the SmartStack project against established conventions using **SmartStack MCP**.
-
-**USAGE:** Before commits, PRs, or as part of CI/CD to ensure code quality.
-
-**INTEGRATION:** Uses `mcp__smartstack__validate_conventions` for comprehensive analysis.
-
----
+<objective>
+Validate the SmartStack project against established conventions using the SmartStack MCP server.
+Use before commits, PRs, or as part of CI/CD to ensure code quality.
+</objective>
+
+<quick_start>
+```bash
+/validate                 # Run all validations
+/validate:tables          # Validate table naming only
+/validate:migrations      # Validate migration naming only
+/validate:services        # Validate service patterns only
+/validate:namespaces      # Validate namespace structure only
+```
+</quick_start>
 
-## Available Commands
+<subcommands>
 
-| Command | Description | Checks |
-|---------|-------------|--------|
-| `/validate` | Run all validations | All |
-| `/validate:tables` | Validate table naming | SQL schemas, prefixes |
-| `/validate:migrations` | Validate migration naming | Format, order |
-| `/validate:services` | Validate service pattern | I*Service interfaces |
-| `/validate:namespaces` | Validate namespace structure | Layer separation |
+| Command | Checks | Description |
+|---------|--------|-------------|
+| `/validate` | all | Run all convention checks |
+| `/validate:tables` | tables | SQL schemas, domain prefixes |
+| `/validate:migrations` | migrations | Naming format, ordering |
+| `/validate:services` | services | I*Service interfaces |
+| `/validate:namespaces` | namespaces | Layer separation |
 
----
+</subcommands>
 
-## STEP 1: Invoke MCP validate_conventions
+<mcp_integration>
 
-> **MCP INTEGRATION:** This command uses the SmartStack MCP server for validation.
+**Tool:** `mcp__smartstack__validate_conventions`
 
-**Claude instruction:** Call the MCP tool:
+Call the MCP tool with appropriate checks:
 
 ```json
 {
@@ -42,46 +48,55 @@ Validates the SmartStack project against established conventions using **SmartSt
 ```
 
 For specific checks:
-
 ```json
 {
-  "tool": "mcp__smartstack__validate_conventions",
-  "parameters": {
-    "checks": ["tables", "migrations"]
-  }
+  "checks": ["tables", "migrations"]
 }
 ```
 
----
+</mcp_integration>
 
-## STEP 2: Parse MCP Response
+<validation_rules>
 
-The MCP returns a `ValidationResult`:
+### Tables (`checks: ["tables"]`)
 
-```typescript
-interface ValidationResult {
-  valid: boolean;
-  errors: ValidationIssue[];
-  warnings: ValidationIssue[];
-  summary: string;
-}
+| Rule | Valid | Invalid |
+|------|-------|---------|
+| Schema | `core`, `extensions` | `dbo`, custom |
+| Prefix | `auth_Users`, `nav_Items` | `Users`, `Items` |
 
-interface ValidationIssue {
-  type: 'error' | 'warning';
-  category: 'tables' | 'migrations' | 'services' | 'namespaces';
-  message: string;
-  file?: string;
-  line?: number;
-  suggestion?: string;
-}
-```
+**Valid prefixes:** `auth_`, `nav_`, `usr_`, `ai_`, `cfg_`, `wkf_`, `support_`, `entra_`, `ref_`, `loc_`, `lic_`
 
----
+### Migrations (`checks: ["migrations"]`)
 
-## STEP 3: Display Results
+| Rule | Valid | Invalid |
+|------|-------|---------|
+| Format | `core_v1.0.0_001_AddUsers` | `AddUsersTable` |
+| Order | v1.0.0 before v1.1.0 | v1.1.0 before v1.0.0 |
 
-**If `valid: true` with no warnings:**
+**Format:** `{context}_v{version}_{sequence}_{Description}`
+
+### Services (`checks: ["services"]`)
+
+| Rule | Valid | Invalid |
+|------|-------|---------|
+| Interface | `IUserService` | `UserServiceInterface` |
+| Implementation | `UserService : IUserService` | `UserService` (no interface) |
+
+### Namespaces (`checks: ["namespaces"]`)
 
+| Layer | Expected Namespace |
+|-------|-------------------|
+| Domain | `SmartStack.Domain.*` |
+| Application | `SmartStack.Application.*` |
+| Infrastructure | `SmartStack.Infrastructure.*` |
+| Api | `SmartStack.Api.*` |
+
+</validation_rules>
+
+<output_format>
+
+**If `valid: true` with no warnings:**
 ```
 ================================================================================
                     SMARTSTACK CONVENTIONS VALIDATION
@@ -94,12 +109,10 @@ Errors: 0
 Warnings: 0
 
 All conventions validated successfully!
-
 ================================================================================
 ```
 
 **If `valid: false` or has warnings:**
-
 ```
 ================================================================================
                     SMARTSTACK CONVENTIONS VALIDATION
@@ -107,68 +120,25 @@ All conventions validated successfully!
 
 STATUS: {valid ? "PASSED (with warnings)" : "FAILED"}
 
-ERRORS ({errors.length})
+ERRORS ({count})
 --------------------------------------------------------------------------------
-{for each error in errors}
-  [{error.category}] {error.message}
-    File: {error.file}
-    Suggestion: {error.suggestion}
-{end for}
+  [{category}] {message}
+    File: {file}
+    Suggestion: {suggestion}
 --------------------------------------------------------------------------------
 
-WARNINGS ({warnings.length})
+WARNINGS ({count})
 --------------------------------------------------------------------------------
-{for each warning in warnings}
-  [{warning.category}] {warning.message}
-    File: {warning.file}
-    Suggestion: {warning.suggestion}
-{end for}
+  [{category}] {message}
+    File: {file}
+    Suggestion: {suggestion}
 --------------------------------------------------------------------------------
-
 ================================================================================
 ```
 
----
-
-## Validation Rules
-
-### Tables (`checks: ["tables"]`)
-
-| Rule | Valid | Invalid |
-|------|-------|---------|
-| Schema | `core`, `extensions` | `dbo`, custom |
-| Prefix | `auth_Users`, `nav_Items` | `Users`, `Items` |
-
-**Valid prefixes:** `auth_`, `nav_`, `usr_`, `ai_`, `cfg_`, `wkf_`, `support_`, `entra_`, `ref_`, `loc_`, `lic_`
-
-### Migrations (`checks: ["migrations"]`)
-
-| Rule | Valid | Invalid |
-|------|-------|---------|
-| Format | `core_v1.0.0_001_AddUsers` | `AddUsersTable` |
-| Order | v1.0.0 before v1.1.0 | v1.1.0 before v1.0.0 |
-
-**Format:** `{context}_v{version}_{sequence}_{Description}`
-
-### Services (`checks: ["services"]`)
-
-| Rule | Valid | Invalid |
-|------|-------|---------|
-| Interface | `IUserService` | `UserServiceInterface` |
-| Implementation | `UserService : IUserService` | `UserService` (no interface) |
+</output_format>
 
-### Namespaces (`checks: ["namespaces"]`)
-
-| Layer | Expected Namespace |
-|-------|-------------------|
-| Domain | `SmartStack.Domain.*` |
-| Application | `SmartStack.Application.*` |
-| Infrastructure | `SmartStack.Infrastructure.*` |
-| Api | `SmartStack.Api.*` |
-
----
-
-## Options
+<options>
 
 | Option | Description |
 |--------|-------------|
@@ -176,9 +146,9 @@ WARNINGS ({warnings.length})
 | `--json` | Output raw MCP JSON response |
 | `--strict` | Treat warnings as errors |
 
----
+</options>
 
-## CI/CD Integration
+<cicd_integration>
 
 ```yaml
 # GitHub Actions
@@ -192,42 +162,13 @@ WARNINGS ({warnings.length})
     fi
 ```
 
----
-
-## Pre-Commit Hook Integration
+</cicd_integration>
 
-Add to `.claude/hooks/PreToolUse`:
-
-```json
-{
-  "matcher": "Edit|Write",
-  "hooks": [{
-    "type": "command",
-    "command": "claude-code /validate:quick"
-  }]
-}
-```
-
----
-
-## MCP Tool Reference
-
-**Tool:** `mcp__smartstack__validate_conventions`
-
-**Description:** Validate AtlasHub/SmartStack conventions: SQL schemas (core/extensions), domain table prefixes (auth_, nav_, ai_, etc.), migration naming ({context}_v{version}_{sequence}_*), service interfaces (I*Service), namespace structure
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `path` | string | Project path (default: auto-detect) |
-| `checks` | string[] | Types of checks: `tables`, `migrations`, `services`, `namespaces`, `all` |
-
----
-
-## Why MCP Integration?
+<why_mcp>
 
 1. **Centralized Rules:** Convention rules defined once in MCP config
 2. **Consistency:** Same validation in CLI, CI/CD, and IDE
 3. **Extensibility:** Add new checks in MCP, available everywhere
 4. **Structured Output:** Typed responses for automation
+
+</why_mcp>

package/templates/commands/check-version.md

@@ -1,267 +0,0 @@
----
-description: Verify version alignment between package.json and documentation
-agent: action
-model: haiku
----
-
-# /check-version - Version Alignment Validator
-
-Verifies that the version in `package.json` is aligned with all documentation files in `.documentation/`.
-
-**USAGE:** Run before releases or as part of release process to ensure documentation is up-to-date.
-
-**INTEGRATION:** Called automatically by `/gitflow:11-finish` for release branches.
-
----
-
-## STEP 1: Read Package Version
-
-**EXECUTE:**
-
-```bash
-# Get version from package.json
-PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)
-echo "Package version: $PKG_VERSION"
-```
-
----
-
-## STEP 2: Scan Documentation Files
-
-**EXECUTE:**
-
-```bash
-# Find all HTML files with version-badge
-echo ""
-echo "Scanning documentation files..."
-echo ""
-
-# Extract versions from all doc 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")
-      # Remove 'v' prefix if present for comparison
-      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
-
-**EXECUTE:**
-
-```bash
-echo ""
-echo "====================================================================="
-echo "                    VERSION ALIGNMENT CHECK"
-echo "====================================================================="
-echo ""
-
-PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)
-MISMATCH_COUNT=0
-TOTAL_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
-      TOTAL_COUNT=$((TOTAL_COUNT + 1))
-      DOC_VERSION_CLEAN=${DOC_VERSION#v}
-      if [ "$DOC_VERSION_CLEAN" != "$PKG_VERSION" ]; then
-        MISMATCH_COUNT=$((MISMATCH_COUNT + 1))
-      fi
-    fi
-  fi
-done
-
-echo "Package version: v$PKG_VERSION"
-echo "Documentation files checked: $TOTAL_COUNT"
-echo "Mismatches found: $MISMATCH_COUNT"
-echo ""
-
-if [ "$MISMATCH_COUNT" -eq 0 ]; then
-  echo "STATUS: PASSED - All versions aligned"
-else
-  echo "STATUS: FAILED - Version mismatches detected"
-  echo ""
-  echo "Run /check-version:fix to auto-update documentation"
-fi
-echo ""
-echo "====================================================================="
-```
-
----
-
-## Conditional: If Mismatches Detected
-
-**IF** `MISMATCH_COUNT > 0`:
-
-Use `AskUserQuestion` tool to ask:
-
-```json
-{
-  "questions": [{
-    "question": "Des fichiers de documentation ont des versions obsoletes. Voulez-vous les mettre a jour automatiquement ?",
-    "header": "Fix versions",
-    "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
-  }]
-}
-```
-
-**IF** user selects "Oui":
-- Execute the fix command below
-
----
-
-## /check-version:fix - Auto-Update Documentation Versions
-
-**EXECUTE:**
-
-```bash
-PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)
-
-echo "Updating documentation to v$PKG_VERSION..."
-echo ""
-
-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
-        # Update version in file
-        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 "Files modified:"
-  git status --porcelain .documentation/*.html | grep "^ M" | sed 's/^ M /  /'
-  echo ""
-  echo "Next steps:"
-  echo "  1. Review changes: git diff .documentation/"
-  echo "  2. Commit: /gitflow:commit"
-else
-  echo "OK No files needed updating"
-fi
-```
-
----
-
-## /check-version:report - Detailed Report
-
-**EXECUTE:**
-
-```bash
-PKG_VERSION=$(cat package.json | grep -oP '"version":\s*"\K[^"]+' | head -1)
-
-echo "====================================================================="
-echo "         VERSION ALIGNMENT DETAILED REPORT"
-echo "====================================================================="
-echo ""
-echo "Package: @atlashub/smartstack-cli"
-echo "Current version: v$PKG_VERSION"
-echo ""
-echo "---------------------------------------------------------------------"
-echo "FILE                          | DOC VERSION | STATUS"
-echo "---------------------------------------------------------------------"
-
-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}
-
-      # Pad filename to 30 chars
-      PADDED_NAME=$(printf "%-28s" "$FILENAME")
-
-      if [ "$DOC_VERSION_CLEAN" = "$PKG_VERSION" ]; then
-        printf "%s | v%-10s | OK\n" "$PADDED_NAME" "$DOC_VERSION_CLEAN"
-      else
-        printf "%s | v%-10s | MISMATCH\n" "$PADDED_NAME" "$DOC_VERSION_CLEAN"
-      fi
-    fi
-  fi
-done
-
-echo "---------------------------------------------------------------------"
-```
-
----
-
-## Integration with GitFlow Release
-
-This command is automatically called during `/gitflow:11-finish` for release branches.
-
-**In release finish workflow:**
-
-```bash
-# Before creating tag, verify versions are aligned
-if [[ "$TYPE" = "release" ]]; then
-  /check-version
-
-  # If mismatches, prompt to fix before continuing
-  if [ "$MISMATCH_COUNT" -gt 0 ]; then
-    echo "WARNING: Documentation versions not aligned"
-    echo "Fix with: /check-version:fix"
-    # Block release until fixed
-  fi
-fi
-```
-
----
-
-## Usage Examples
-
-| Command | Description |
-|---------|-------------|
-| `/check-version` | Check version alignment (interactive) |
-| `/check-version:fix` | Auto-update all doc files |
-| `/check-version:report` | Detailed report without prompts |
-
----
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | All versions aligned |
-| 1 | Mismatches detected (blocking for releases) |
-
----
-
-## Files Checked
-
-- `.documentation/*.html` - All HTML documentation files
-- Looks for `<span class="version-badge">vX.Y.Z</span>` pattern

package/templates/commands/debug.md

@@ -1,95 +0,0 @@
----
-description: Systematic bug debugging with deep analysis and resolution
-argument-hint: <log|error|problem-description>
-allowed-tools: Bash, Read, Edit, MultiEdit, Write, Grep, Glob, Task, WebSearch, WebFetch
----
-
-You are a systematic debugging specialist. Follow this ultra-deep analysis workflow to identify, understand, and resolve bugs.
-
-**You need to always ULTRA THINK.**
-
-## 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 (`explore-codebase`, `explore-docs`, `websearch`)
-   - 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
-
-4. **RESEARCH**: Solution investigation
-   - Launch **parallel subagents** for web research (`websearch`)
-   - 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
-
-## Deep 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
-
-## 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
-
-## Priority
-
-Understanding > Speed > Completeness. Every bug must be fully understood before attempting fixes.
-
----
-
-User: $ARGUMENTS