@atlashub/smartstack-cli 3.7.0 → 3.9.0

package/templates/skills/gitflow/steps/step-start.md

@@ -131,6 +131,16 @@ esac
 }
 ```
 
+### 5b. EF Core Migration Pre-flight (Release/Hotfix only)
+
+**BLOCKING CHECK: Validate migration naming conventions BEFORE creating the release branch.**
+
+See [references/start-efcore-preflight.md](../references/start-efcore-preflight.md) for the full validation script and user choice handling.
+
+Expected format: `{context}_v{version}_{sequence}_{Description}` (e.g., `core_v2.0.0_001_InitialSchema`)
+
+---
+
 ### 6. Create Branch and Worktree
 
 **Read worktree mode from config (already loaded by read_gitflow_config):**
@@ -177,132 +187,12 @@ fi
 
 ### 7. Create Local Environment Config (Backend + Frontend)
 
-**Detect project structure:**
-```bash
-# Find API project directory
-API_DIR=$(find "$WORKTREE_PATH" -type d -name "*.Api" -path "*/src/*" | head -1)
-# Find Web project directory
-WEB_DIR=$(find "$WORKTREE_PATH" -type d -name "*-web" -path "*/web/*" | head -1)
-
-# Generate unique ports based on branch name hash (to avoid conflicts between worktrees)
-# Use shasum (portable across macOS/Linux/Windows Git Bash) with md5sum fallback
-HASH=$(echo "$BRANCH_NAME" | shasum 2>/dev/null || echo "$BRANCH_NAME" | md5sum 2>/dev/null || echo "$BRANCH_NAME" | cksum)
-HASH=$(echo "$HASH" | cut -c1-4)
-HASH_NUM=$((16#$HASH % 100))
-API_PORT=$((5200 + HASH_NUM))
-WEB_PORT=$((5300 + HASH_NUM))
-
-# Project name from config (not from pwd)
-PROJECT_NAME=$(echo "$GF_PROJECT_NAME" | tr '[:upper:]' '[:lower:]')
-DB_NAME=$(echo "${PROJECT_NAME}_${branch_type}_${BRANCH_NAME}" | cut -c1-63)
-```
-
-#### 7a. Backend: appsettings.Local.json
-
-**If API project detected:**
-```bash
-[ -n "$API_DIR" ] && [ -f "$API_DIR/appsettings.json" ] && {
-  cat > "$API_DIR/appsettings.Local.json" << EOF
-{
-  "ConnectionStrings": {
-    "DefaultConnection": "Server=localhost;Database=${DB_NAME};Trusted_Connection=true;TrustServerCertificate=true"
-  },
-  "SmartStack": {
-    "AutoMigrate": true,
-    "FailOnMigrationError": true,
-    "EnableDevSeeding": true
-  },
-  "Authentication": {
-    "FrontendUrl": "http://localhost:${WEB_PORT}"
-  },
-  "Kestrel": {
-    "Endpoints": {
-      "Http": {
-        "Url": "http://localhost:${API_PORT}"
-      }
-    }
-  },
-  "Serilog": {
-    "MinimumLevel": {
-      "Default": "Debug"
-    }
-  }
-}
-EOF
-  echo "Created: $API_DIR/appsettings.Local.json (DB: $DB_NAME, Port: $API_PORT)"
-}
-```
-
-#### 7b. Frontend: .env.local + npm script
-
-**If Web project detected:**
-```bash
-[ -n "$WEB_DIR" ] && [ -f "$WEB_DIR/package.json" ] && {
-  # Create .env.local
-  cat > "$WEB_DIR/.env.local" << EOF
-# Local environment configuration
-# Generated by /gitflow:start for branch: ${FULL_BRANCH}
-# Run with: npm run local
-
-VITE_API_URL=http://localhost:${API_PORT}
-VITE_APP_ENV=local
-VITE_DEBUG=true
-EOF
-  echo "Created: $WEB_DIR/.env.local (API: localhost:$API_PORT)"
-
-  # Add "local" script to package.json if not exists
-  if ! grep -q '"local"' "$WEB_DIR/package.json"; then
-    # Use Node.js to safely modify package.json
-    node -e "
-      const fs = require('fs');
-      const pkg = JSON.parse(fs.readFileSync('$WEB_DIR/package.json', 'utf8'));
-      if (!pkg.scripts.local) {
-        pkg.scripts.local = 'vite --mode local --port ${WEB_PORT}';
-        fs.writeFileSync('$WEB_DIR/package.json', JSON.stringify(pkg, null, 2) + '\n');
-        console.log('Added script: npm run local');
-      }
-    "
-  fi
-}
-```
-
-#### 7c. Backend: launchSettings.json Local Profile
-
-**If API project detected and Properties/launchSettings.json exists:**
-```bash
-LAUNCH_SETTINGS="$API_DIR/Properties/launchSettings.json"
-[ -n "$API_DIR" ] && [ -f "$LAUNCH_SETTINGS" ] && {
-  # Use Node.js to safely add/update Local profile in launchSettings.json
-  node -e "
-    const fs = require('fs');
-    const ls = JSON.parse(fs.readFileSync('$LAUNCH_SETTINGS', 'utf8'));
-    ls.profiles = ls.profiles || {};
-    ls.profiles.Local = {
-      commandName: 'Project',
-      dotnetRunMessages: true,
-      launchBrowser: false,
-      applicationUrl: 'http://localhost:${API_PORT}',
-      environmentVariables: {
-        ASPNETCORE_ENVIRONMENT: 'Local'
-      }
-    };
-    fs.writeFileSync('$LAUNCH_SETTINGS', JSON.stringify(ls, null, 2) + '\n');
-    console.log('Updated: launchSettings.json Local profile (Port: ${API_PORT})');
-  "
-}
-```
-
-#### 7d. Summary of local config
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  LOCAL ENVIRONMENT CONFIGURED                               │
-├─────────────────────────────────────────────────────────────┤
-│  Database:  ${DB_NAME}                                      │
-│  API Port:  ${API_PORT}  →  dotnet run --launch-profile Local│
-│  Web Port:  ${WEB_PORT}  →  npm run local                   │
-└─────────────────────────────────────────────────────────────┘
-```
+See [references/start-local-config.md](../references/start-local-config.md) for the full configuration:
+- **Port generation:** Unique ports per branch (API: 5200+, Web: 5300+) based on branch name hash
+- **7a. Backend:** `appsettings.Local.json` (DB connection, SmartStack config, Kestrel port)
+- **7b. Frontend:** `.env.local` + `npm run local` script
+- **7c. Backend:** `launchSettings.json` Local profile with unique port
+- **7d. Summary:** Display configured DB name, API port, Web port
 
 ### 8. Store State
 

package/templates/skills/mcp/SKILL.md

@@ -21,148 +21,17 @@ Manages MCP server connectivity and health verification.
 
 > **Note:** The MCP server is now bundled inside `@atlashub/smartstack-cli`. There is no separate `@atlashub/smartstack-mcp` package.
 
-## SUBCOMMANDS
+## Subcommands
 
 | Command | Description |
 |---------|-------------|
-| `/mcp:healthcheck` | Full MCP health check with version verification |
-| `/mcp:tools` | List all available MCP tools with descriptions |
-
----
-
-## /mcp:healthcheck
-
-Performs a complete MCP health check and updates the cache.
-
-### Workflow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    MCP HEALTH CHECK                         │
-├─────────────────────────────────────────────────────────────┤
-│  1. Test MCP Connectivity                                   │
-│     └─▶ Call mcp__smartstack__validate_conventions          │
-│                                                             │
-│  2. Get MCP Version                                         │
-│     └─▶ smartstack --version (bundled in CLI)               │
-│                                                             │
-│  3. List Available Tools                                    │
-│     └─▶ Enumerate mcp__smartstack__* tools                  │
-│                                                             │
-│  4. Update Cache                                            │
-│     └─▶ Write .claude/mcp-status.json                       │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Step 1: Test Connectivity
-
-Call MCP with minimal parameters:
-
-```
-mcp__smartstack__validate_conventions({
-  checks: ["tables"]
-})
-```
-
-**Expected:** Response without connection error
-
-**On failure:**
-```
-❌ MCP CONNECTION FAILED
-   Error: <error_message>
-
-   Actions:
-   1. Verify MCP is configured: claude mcp list
-   2. Re-register: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
-   3. Restart Claude Code
-```
-
-### Step 2: Get Version
-
-```bash
-# Read CLI package version (MCP is bundled inside)
-npx smartstack --version 2>/dev/null || smartstack --version
-```
-
-### Step 3: List Tools
-
-Verify these critical tools are available:
-
-| Tool | Purpose |
-|------|---------|
-| `validate_conventions` | Convention validation |
-| `scaffold_extension` | Code generation |
-| `suggest_migration` | Migration naming |
-| `check_migrations` | Conflict detection |
-| `generate_permissions` | RBAC generation |
-
-### Step 4: Update Cache
-
-Write to `.claude/mcp-status.json`:
-
-```json
-{
-  "lastCheck": "<ISO_DATE>",
-  "mcpVersion": "<VERSION>",
-  "bundled": true,
-  "status": "ok",
-  "toolsAvailable": [
-    "validate_conventions",
-    "scaffold_extension",
-    "suggest_migration",
-    "check_migrations",
-    "generate_permissions"
-  ]
-}
-```
-
-### Output Format
-
-**Success:**
-```
-MCP HEALTH CHECK ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Status      : OK
-  Version     : 2.0.0 (bundled)
-  Tools       : 19 available
-  Cache       : Updated (.claude/mcp-status.json)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Next check  : in 7 days (auto)
-```
-
-**Warning (update available):**
-```
-MCP HEALTH CHECK ⚠️
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Status      : UPDATE AVAILABLE
-  Current     : 1.38.0
-  Latest      : 2.0.0
-  Action      : npm update -g @atlashub/smartstack-cli
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Error:**
-```
-MCP HEALTH CHECK ❌
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Status      : ERROR
-  Issue       : MCP server not responding
-
-  Troubleshooting:
-  1. Check registration: claude mcp list
-  2. Re-register: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
-  3. Update CLI: npm update -g @atlashub/smartstack-cli
-  4. Restart Claude Code
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
----
+| `/mcp:healthcheck` | Full MCP health check with version verification. See [steps/step-01-healthcheck.md](steps/step-01-healthcheck.md) |
+| `/mcp:tools` | List all available MCP tools with descriptions. See [steps/step-02-tools.md](steps/step-02-tools.md) |
 
 ## Cache File
 
 **Location:** `.claude/mcp-status.json`
 
-**Structure:**
 ```json
 {
   "lastCheck": "2024-01-15T10:30:00.000Z",
@@ -176,8 +45,6 @@ MCP HEALTH CHECK ❌
 
 **Validity:** 7 days
 
----
-
 ## Integration with Hook
 
 The `mcp-check` hook automatically:
@@ -187,80 +54,9 @@ The `mcp-check` hook automatically:
 
 This skill provides the **full check** that the hook references.
 
----
-
-## /mcp:tools
-
-Lists all available MCP tools with their descriptions.
-
-### Core Tools (6)
-| Tool | Description |
-|------|-------------|
-| `validate_conventions` | Validate SmartStack conventions (tables, migrations, services, namespaces, controllers) |
-| `check_migrations` | Analyze EF Core migrations for conflicts and ordering issues |
-| `scaffold_extension` | Generate code: feature, entity, service, controller, component, dto, validator, repository |
-| `api_docs` | Get API documentation from Swagger/OpenAPI or controller files |
-| `suggest_migration` | Suggest migration name following SmartStack conventions |
-| `generate_permissions` | Generate RBAC permissions (HasData for PermissionConfiguration.cs) |
-
-### Test Tools (4)
-| Tool | Description |
-|------|-------------|
-| `scaffold_tests` | Generate test files for entities, services, controllers |
-| `analyze_test_coverage` | Analyze test coverage and identify missing tests |
-| `validate_test_conventions` | Validate test naming and structure conventions |
-| `suggest_test_scenarios` | Suggest test scenarios based on code analysis |
-
-### Frontend Tools (5)
-| Tool | Description |
-|------|-------------|
-| `scaffold_routes` | Generate frontend routes from backend NavRoute attributes |
-| `validate_frontend_routes` | Validate frontend routes match backend NavRoutes |
-| `scaffold_api_client` | Generate TypeScript API client with React Query hooks |
-| `scaffold_frontend_extension` | Generate frontend extension infrastructure (types, slots, contexts) |
-| `analyze_extension_points` | Analyze React components for extension points |
-
-### Security & Quality Tools (4)
-| Tool | Description |
-|------|-------------|
-| `validate_security` | Validate OWASP security patterns |
-| `analyze_code_quality` | Analyze code quality metrics |
-| `analyze_hierarchy_patterns` | Analyze entity hierarchy patterns |
-| `review_code` | Comprehensive code review with security, performance, a11y checks |
-
-### Output Format
-
-```
-MCP TOOLS REFERENCE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-CORE TOOLS (6)
-  validate_conventions    Validate SmartStack conventions
-  check_migrations        Analyze EF Core migrations
-  scaffold_extension      Generate code (entity, service, etc.)
-  api_docs                Get API documentation
-  suggest_migration       Suggest migration name
-  generate_permissions    Generate RBAC permissions
-
-TEST TOOLS (4)
-  scaffold_tests          Generate test files
-  analyze_test_coverage   Analyze test coverage
-  validate_test_conventions  Validate test conventions
-  suggest_test_scenarios  Suggest test scenarios
-
-FRONTEND TOOLS (5)
-  scaffold_routes         Generate frontend routes
-  validate_frontend_routes  Validate route alignment
-  scaffold_api_client     Generate TypeScript API client
-  scaffold_frontend_extension  Generate extension infrastructure
-  analyze_extension_points  Analyze React extension points
-
-SECURITY & QUALITY TOOLS (4)
-  validate_security       Validate OWASP patterns
-  analyze_code_quality    Analyze code quality
-  analyze_hierarchy_patterns  Analyze hierarchy patterns
-  review_code             Comprehensive code review
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Total: 19 tools available
-```
+<success_criteria>
+- MCP server connectivity verified (healthcheck passes)
+- Tool list displayed with descriptions
+- Cache status updated in .claude/mcp-status.json
+- Clear error message if MCP unavailable with remediation steps
+</success_criteria>

package/templates/skills/mcp/steps/step-01-healthcheck.md

@@ -0,0 +1,108 @@
+# MCP Health Check
+
+Performs a complete MCP health check and updates the cache.
+
+## Workflow
+
+```
+1. Test MCP Connectivity  -> Call mcp__smartstack__validate_conventions
+2. Get MCP Version        -> smartstack --version (bundled in CLI)
+3. List Available Tools   -> Enumerate mcp__smartstack__* tools
+4. Update Cache           -> Write .claude/mcp-status.json
+```
+
+## Step 1: Test Connectivity
+
+Call MCP with minimal parameters:
+
+```
+mcp__smartstack__validate_conventions({
+  checks: ["tables"]
+})
+```
+
+**Expected:** Response without connection error
+
+**On failure:**
+```
+MCP CONNECTION FAILED
+   Error: <error_message>
+
+   Actions:
+   1. Verify MCP is configured: claude mcp list
+   2. Re-register: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
+   3. Restart Claude Code
+```
+
+## Step 2: Get Version
+
+```bash
+# Read CLI package version (MCP is bundled inside)
+npx smartstack --version 2>/dev/null || smartstack --version
+```
+
+## Step 3: List Tools
+
+Verify these critical tools are available:
+
+| Tool | Purpose |
+|------|---------|
+| `validate_conventions` | Convention validation |
+| `scaffold_extension` | Code generation |
+| `suggest_migration` | Migration naming |
+| `check_migrations` | Conflict detection |
+| `generate_permissions` | RBAC generation |
+
+## Step 4: Update Cache
+
+Write to `.claude/mcp-status.json`:
+
+```json
+{
+  "lastCheck": "<ISO_DATE>",
+  "mcpVersion": "<VERSION>",
+  "bundled": true,
+  "status": "ok",
+  "toolsAvailable": [
+    "validate_conventions",
+    "scaffold_extension",
+    "suggest_migration",
+    "check_migrations",
+    "generate_permissions"
+  ]
+}
+```
+
+## Output Formats
+
+**Success:**
+```
+MCP HEALTH CHECK
+  Status      : OK
+  Version     : 2.0.0 (bundled)
+  Tools       : 19 available
+  Cache       : Updated (.claude/mcp-status.json)
+  Next check  : in 7 days (auto)
+```
+
+**Warning (update available):**
+```
+MCP HEALTH CHECK
+  Status      : UPDATE AVAILABLE
+  Current     : 1.38.0
+  Latest      : 2.0.0
+  Action      : npm update -g @atlashub/smartstack-cli
+```
+
+**Error:**
+```
+MCP HEALTH CHECK
+  Status      : ERROR
+  Issue       : MCP server not responding
+
+  Troubleshooting:
+  1. Check registration: claude mcp list
+  2. Re-register: claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp
+  3. Update CLI: npm update -g @atlashub/smartstack-cli
+  4. Restart Claude Code
+```

package/templates/skills/mcp/steps/step-02-tools.md

@@ -0,0 +1,73 @@
+# MCP Tools Reference
+
+Lists all available MCP tools with their descriptions.
+
+## Core Tools (6)
+| Tool | Description |
+|------|-------------|
+| `validate_conventions` | Validate SmartStack conventions (tables, migrations, services, namespaces, controllers) |
+| `check_migrations` | Analyze EF Core migrations for conflicts and ordering issues |
+| `scaffold_extension` | Generate code: feature, entity, service, controller, component, dto, validator, repository |
+| `api_docs` | Get API documentation from Swagger/OpenAPI or controller files |
+| `suggest_migration` | Suggest migration name following SmartStack conventions |
+| `generate_permissions` | Generate RBAC permissions (HasData for PermissionConfiguration.cs) |
+
+## Test Tools (4)
+| Tool | Description |
+|------|-------------|
+| `scaffold_tests` | Generate test files for entities, services, controllers |
+| `analyze_test_coverage` | Analyze test coverage and identify missing tests |
+| `validate_test_conventions` | Validate test naming and structure conventions |
+| `suggest_test_scenarios` | Suggest test scenarios based on code analysis |
+
+## Frontend Tools (5)
+| Tool | Description |
+|------|-------------|
+| `scaffold_routes` | Generate frontend routes from backend NavRoute attributes |
+| `validate_frontend_routes` | Validate frontend routes match backend NavRoutes |
+| `scaffold_api_client` | Generate TypeScript API client with React Query hooks |
+| `scaffold_frontend_extension` | Generate frontend extension infrastructure (types, slots, contexts) |
+| `analyze_extension_points` | Analyze React components for extension points |
+
+## Security & Quality Tools (4)
+| Tool | Description |
+|------|-------------|
+| `validate_security` | Validate OWASP security patterns |
+| `analyze_code_quality` | Analyze code quality metrics |
+| `analyze_hierarchy_patterns` | Analyze entity hierarchy patterns |
+| `review_code` | Comprehensive code review with security, performance, a11y checks |
+
+## Output Format
+
+```
+MCP TOOLS REFERENCE
+
+CORE TOOLS (6)
+  validate_conventions    Validate SmartStack conventions
+  check_migrations        Analyze EF Core migrations
+  scaffold_extension      Generate code (entity, service, etc.)
+  api_docs                Get API documentation
+  suggest_migration       Suggest migration name
+  generate_permissions    Generate RBAC permissions
+
+TEST TOOLS (4)
+  scaffold_tests          Generate test files
+  analyze_test_coverage   Analyze test coverage
+  validate_test_conventions  Validate test conventions
+  suggest_test_scenarios  Suggest test scenarios
+
+FRONTEND TOOLS (5)
+  scaffold_routes         Generate frontend routes
+  validate_frontend_routes  Validate route alignment
+  scaffold_api_client     Generate TypeScript API client
+  scaffold_frontend_extension  Generate extension infrastructure
+  analyze_extension_points  Analyze React extension points
+
+SECURITY & QUALITY TOOLS (4)
+  validate_security       Validate OWASP patterns
+  analyze_code_quality    Analyze code quality
+  analyze_hierarchy_patterns  Analyze hierarchy patterns
+  review_code             Comprehensive code review
+
+Total: 19 tools available
+```

package/templates/skills/notification/SKILL.md

@@ -164,3 +164,10 @@ else await SendBatch($"{entities.Count} new elements", ...);
 | `Infrastructure/Services/SignalR/NotificationHubService.cs` | Real-time |
 | `web/src/hooks/useSignalR.ts` | Frontend hook |
 | `web/src/components/notifications/NotificationBell.tsx` | UI |
+
+<success_criteria>
+- INotificationService integration wired with correct NotificationType
+- relatedEntityType/Id and actionUrl set for navigation context
+- SignalR real-time delivery working via NotificationHubService
+- User preference filtering respected
+</success_criteria>

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

@@ -92,3 +92,8 @@ Grep: pattern="from ['\"].*moduleName['\"]"
 <priority>
 Speed > Completeness. Fast answers beat perfect answers.
 </priority>
+
+<success_criteria>
+- Question answered with file path and line number citations
+- Response delivered within 2-3 search iterations
+</success_criteria>