@atlashub/smartstack-cli 2.7.3 → 2.7.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "2.7.3",
-  "description": "SmartStack Claude Code automation toolkit - GitFlow, APEX, EF Core migrations, prompts and more",
+  "version": "2.7.4",
+  "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",
     "email": "contact@smartstack.app",
@@ -41,7 +41,6 @@
     "claude",
     "claude-code",
     "gitflow",
-    "apex",
     "efcore",
     "entity-framework",
     "migrations",

package/templates/agents/docs-sync-checker.md

@@ -93,11 +93,11 @@ For each drifted module, identify the type of changes:
 - `src/.../CreateSlaCommand.cs` → Use Cases section
 
 ### Recommended Action
-Run `/apex -d` to sync documentation, or `/documentation:update business/support/sla`
+Run `/documentation:update business/support/sla` to sync documentation
 
 ## Actions Required
 
-1. **DRIFT modules ({count}):** Run `/apex -d` or `/documentation` to update
+1. **DRIFT modules ({count}):** Run `/documentation` to update
 2. **MISSING modules ({count}):** Run `/business-analyse` to create documentation
 3. **SYNCED modules ({count}):** No action needed
 ```

package/templates/hooks/docs-drift-check.md

@@ -60,7 +60,7 @@ if [ "$DRIFT_FOUND" = true ]; then
   echo "Documentation drift detected:"
   echo -e "$DRIFT_MODULES"
   echo ""
-  echo "Consider running /apex -d or /documentation to update."
+  echo "Consider running /documentation to update."
   echo ""
 fi
 
@@ -85,13 +85,12 @@ exit 0
 ## Integration
 
 This hook integrates with:
-- `docs-manifest.json` (created by BA step-06 and APEX step-04b)
-- `/apex -d` flag for automatic documentation sync
-- `/documentation` skill for manual documentation updates
+- `docs-manifest.json` (created by BA step-06)
+- `/documentation` skill for documentation updates
 
 ## Notes
 
 - **Non-blocking by design:** Documentation drift should never prevent commits
-- The warning suggests running `/apex -d` (documentation sync) or `/documentation` (manual update)
+- The warning suggests running `/documentation` to update
 - If `jq` is not installed, the hook silently exits (graceful degradation)
 - Cross-platform: Works on Linux, macOS, and Windows (Git Bash/WSL)

package/templates/skills/_resources/context-digest-template.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Reduces token usage between multi-step skill executions (APEX, BA) by compressing step outputs into compact summaries.
+Reduces token usage between multi-step skill executions (BA, ralph-loop) by compressing step outputs into compact summaries.
 
 ## How It Works
 
@@ -41,8 +41,8 @@ Step N+1 reads:
 
 ## Applies To
 
-- APEX skill (all step transitions)
 - BA skill (between phases)
+- Ralph-loop skill (between tasks)
 - Any future multi-step skill
 
 ## Resume Exception

package/templates/skills/_resources/doc-context-cache.md

@@ -56,7 +56,5 @@ Caches the output of `docs-context-reader` agent to avoid redundant documentatio
 
 | Consumer | Check Cache? |
 |----------|-------------|
-| APEX step-01 (analyze) | Yes |
-| APEX step-04b (doc-sync) | Yes |
 | BA step-01 (discover) | Yes |
 | docs-sync-checker agent | No (always fresh) |

package/templates/skills/_resources/docs-manifest-schema.md

@@ -72,7 +72,7 @@ The `docs-manifest.json` file maps code modules to their documentation artifacts
 | Status | Meaning | Action |
 |--------|---------|--------|
 | `synced` | Documentation matches code | No action needed |
-| `drift` | Code changed after last doc update | Run `/apex -d` or `/documentation` to update |
+| `drift` | Code changed after last doc update | Run `/documentation` to update |
 | `missing` | Module exists in code but has no documentation | Run `/business-analyse` or `/documentation` to create |
 
 ## Usage
@@ -84,13 +84,11 @@ The `docs-manifest.json` file maps code modules to their documentation artifacts
 ### Read by
 - `docs-context-reader` agent (for context injection)
 - `docs-sync-checker` agent (for drift detection)
-- APEX step-04b (doc-sync) to identify affected modules
 - BA step-04 (validate) for freshness check
 - Drift hook (pre-commit) for commit warnings
 
 ### Updated by
 - BA step-06 (on doc generation)
-- APEX step-04b (on doc sync)
 - Documentation skill (on doc update)
 
 ## Drift Detection Logic

package/templates/skills/_resources/mcp-validate-documentation-spec.md

@@ -159,7 +159,7 @@ FOR each module:
     }
   ],
   "recommendations": [
-    "Run `/apex -d` for business/support/sla to sync documentation",
+    "Run `/documentation` for business/support/sla to sync documentation",
     "Run `/business-analyse` for business/support/tickets to create documentation"
   ]
 }
@@ -169,9 +169,7 @@ FOR each module:
 
 | Consumer | When | Fallback |
 |----------|------|----------|
-| APEX step-04b (doc-sync) | After code validation | `docs-sync-checker` agent |
 | BA step-04 (validate) | During specification validation | Read manifest + git log |
-| APEX step-05 (examine) | During adversarial review | Manual checklist |
 | Drift hook (pre-commit) | Before commit | Bash script reading manifest |
 
 ## Implementation Notes

package/templates/skills/_shared.md

@@ -160,7 +160,6 @@ If MCP is not available, display this message and **STOP the skill immediately**
 | business-analyse | **YES** | Analysis, specification, validation |
 | application | **YES** | Navigation + code generation |
 | controller | **YES** | Controller scaffolding |
-| apex | **YES** | Generation + validation |
 | ralph-loop | **YES** | Iterative code generation |
 | validate | **YES** | Convention validation |
 | efcore | **YES** | Migration management |
@@ -173,38 +172,38 @@ If MCP is not available, display this message and **STOP the skill immediately**
 
 ### Outils Core
 
-| Tool | Usage | Step APEX |
-|------|-------|-----------|
-| `mcp__smartstack__validate_conventions` | Valider conventions SmartStack (tables, migrations, services, namespaces, entities, tenants, controllers) | step-04-validate |
-| `mcp__smartstack__scaffold_extension` | Génération code (feature, entity, service, controller, component, dto, validator, repository) | step-03-execute |
-| `mcp__smartstack__check_migrations` | Analyser migrations EF Core (conflits, ordre, ModelSnapshot) | step-04-validate |
-| `mcp__smartstack__api_docs` | Documentation API depuis Swagger/OpenAPI ou controllers | step-01-analyze |
-| `mcp__smartstack__suggest_migration` | Suggérer nom migration ({context}_v{version}_{sequence}_{Description}) | step-03-execute |
-| `mcp__smartstack__generate_permissions` | Générer permissions RBAC depuis NavRoute | step-03-execute |
+| Tool | Usage | Used By |
+|------|-------|---------|
+| `mcp__smartstack__validate_conventions` | Valider conventions SmartStack (tables, migrations, services, namespaces, entities, tenants, controllers) | application, controller, ralph-loop |
+| `mcp__smartstack__scaffold_extension` | Génération code (feature, entity, service, controller, component, dto, validator, repository) | application, ralph-loop |
+| `mcp__smartstack__check_migrations` | Analyser migrations EF Core (conflits, ordre, ModelSnapshot) | application, ralph-loop |
+| `mcp__smartstack__api_docs` | Documentation API depuis Swagger/OpenAPI ou controllers | controller |
+| `mcp__smartstack__suggest_migration` | Suggérer nom migration ({context}_v{version}_{sequence}_{Description}) | application, ralph-loop |
+| `mcp__smartstack__generate_permissions` | Générer permissions RBAC depuis NavRoute | application, ralph-loop |
 
 ### Outils Tests
 
-| Tool | Usage | Step APEX |
-|------|-------|-----------|
-| `mcp__smartstack__scaffold_tests` | Générer tests unitaires/intégration/sécurité | step-07-tests |
-| `mcp__smartstack__analyze_test_coverage` | Analyser couverture de tests du projet | step-07-tests |
-| `mcp__smartstack__validate_test_conventions` | Valider conventions de nommage des tests | step-07-tests |
-| `mcp__smartstack__suggest_test_scenarios` | Suggérer scénarios de test basés sur le code | step-07-tests |
+| Tool | Usage | Used By |
+|------|-------|---------|
+| `mcp__smartstack__scaffold_tests` | Générer tests unitaires/intégration/sécurité | application, ralph-loop |
+| `mcp__smartstack__analyze_test_coverage` | Analyser couverture de tests du projet | ralph-loop |
+| `mcp__smartstack__validate_test_conventions` | Valider conventions de nommage des tests | ralph-loop |
+| `mcp__smartstack__suggest_test_scenarios` | Suggérer scénarios de test basés sur le code | ralph-loop |
 
 ### Outils Frontend
 
-| Tool | Usage | Step APEX |
-|------|-------|-----------|
-| `mcp__smartstack__scaffold_api_client` | Générer client TypeScript avec NavRoute | step-03-execute |
-| `mcp__smartstack__scaffold_routes` | Générer React Router depuis NavRoute backend | step-03-execute |
-| `mcp__smartstack__validate_frontend_routes` | Valider synchronisation routes frontend/backend | step-04-validate |
-| `mcp__smartstack__scaffold_frontend_extension` | Générer infrastructure extension frontend | step-03-execute |
-| `mcp__smartstack__analyze_extension_points` | Analyser points d'extension dans les pages React | step-01-analyze |
+| Tool | Usage | Used By |
+|------|-------|---------|
+| `mcp__smartstack__scaffold_api_client` | Générer client TypeScript avec NavRoute | application, ralph-loop |
+| `mcp__smartstack__scaffold_routes` | Générer React Router depuis NavRoute backend | application, ralph-loop |
+| `mcp__smartstack__validate_frontend_routes` | Valider synchronisation routes frontend/backend | application, ralph-loop |
+| `mcp__smartstack__scaffold_frontend_extension` | Générer infrastructure extension frontend | application |
+| `mcp__smartstack__analyze_extension_points` | Analyser points d'extension dans les pages React | application |
 
 ### Outils Documentation
 
-| Tool | Usage | Step APEX |
-|------|-------|-----------|
-| `mcp__smartstack__validate_documentation` | Valider fraîcheur, complétude et exactitude de la documentation (FUTURE - voir `_resources/mcp-validate-documentation-spec.md`) | step-04b-doc-sync |
+| Tool | Usage | Used By |
+|------|-------|---------|
+| `mcp__smartstack__validate_documentation` | Valider fraîcheur, complétude et exactitude de la documentation (FUTURE - voir `_resources/mcp-validate-documentation-spec.md`) | documentation |
 
 > **Fallback** : En attendant l'implémentation MCP, utiliser l'agent `docs-sync-checker` pour la détection de drift et l'agent `docs-context-reader` pour l'injection de contexte documentation.

package/templates/skills/application/steps/step-04-backend.md

@@ -49,16 +49,18 @@ code: "order-items"     → entityName: "OrderItem"
 code: "user-profiles"   → entityName: "UserProfile"
 ```
 
-### 2. Determine Table Prefix
+### 2. Determine Table Prefix and Controller Folder
 
 Based on navigation context:
 
-| Context | Prefix |
-|---------|--------|
-| platform.administration | `auth_` or `cfg_` |
-| platform.support | `support_` |
-| business.* | `ref_` or domain-specific |
-| personal.* | `usr_` |
+| Context | Table Prefix | Controller Folder |
+|---------|--------|-------------------|
+| platform.administration | `auth_` or `cfg_` | `Admin` |
+| platform.support | `support_` | `Support` |
+| business.* | `ref_` or domain-specific | `Business` |
+| personal.* | `usr_` | `User` |
+
+Store: `{controller_folder}` = the Controller Folder from the table above.
 
 ### 3. Call MCP scaffold_extension
 
@@ -85,7 +87,7 @@ The tool generates (paths organized by navRoute hierarchy `{context}.{applicatio
 - `Infrastructure/Persistence/Configurations/{Module}/{EntityName}Configuration.cs` - EF Config
 - `Application/Common/Interfaces/I{EntityName}Service.cs` - Service Interface
 - `Infrastructure/Services/{Module}/{EntityName}Service.cs` - Service Implementation
-- `Api/Controllers/{Context}/{EntityName}Controller.cs` - REST Controller
+- `Api/Controllers/{controller_folder}/{Application}/{EntityName}Controller.cs` - REST Controller
 - `Application/{Context}/{Application}/{Module}/DTOs/{EntityName}ResponseDto.cs` - Response DTO
 - `Application/{Context}/{Application}/{Module}/DTOs/Create{EntityName}Dto.cs` - Create request
 - `Application/{Context}/{Application}/{Module}/DTOs/Update{EntityName}Dto.cs` - Update request
@@ -109,7 +111,7 @@ The tool generates (paths organized by navRoute hierarchy `{context}.{applicatio
 - `{Context}/{Application}/{Module}/DTOs/Update{EntityName}Dto.cs`
 
 ### API Layer
-- `Controllers/{Context}/{EntityName}Controller.cs`
+- `Controllers/{controller_folder}/{Application}/{EntityName}Controller.cs`
   - NavRoute: `{full_path}`
   - Endpoints:
     - GET /api/{code} - List all
@@ -240,7 +242,38 @@ Store entity information for frontend generation:
 
 ---
 
-## CONTROLLER NAVROUTE
+## CONTROLLER NAVROUTE AND FOLDER HIERARCHY
+
+### Controller File Location
+
+Controllers are organized by **context short name** and **application** (matching SmartStack.app pattern):
+
+```
+Api/Controllers/
+├── Admin/                     ← platform.administration
+│   ├── {Application}/         ← Application sub-folder (e.g., AI/, Communications/, Tenants/)
+│   │   └── {EntityName}Controller.cs
+│   └── {EntityName}Controller.cs  ← Direct controllers (no application sub-folder)
+├── Business/                  ← business.*
+│   └── {EntityName}Controller.cs
+├── Support/                   ← platform.support
+│   └── {EntityName}Controller.cs
+├── User/                      ← personal.*
+│   └── {EntityName}Controller.cs
+└── {SharedControllers}.cs     ← Root-level (Auth, Config, Navigation, etc.)
+```
+
+### Context-to-Folder Mapping
+
+| NavRoute Context | Controller Folder | Example |
+|-----------------|-------------------|---------|
+| `platform.administration` | `Admin` | `Controllers/Admin/TenantsController.cs` |
+| `platform.administration.{app}` | `Admin/{App}` | `Controllers/Admin/AI/AiPromptsController.cs` |
+| `platform.support` | `Support` | `Controllers/Support/TicketsController.cs` |
+| `business.*` | `Business` | `Controllers/Business/MyTicketsController.cs` |
+| `personal.*` | `User` | `Controllers/User/PreferencesController.cs` |
+
+### Controller Attributes
 
 The generated controller uses NavRoute attribute:
 
@@ -262,6 +295,7 @@ This ensures:
 - API route is derived from navigation path
 - Permissions use the constants from Permissions.cs
 - Frontend can discover API path from NavRoute registry
+- Controller file is in the correct context/application folder
 
 ---
 
@@ -357,6 +391,146 @@ Verify:
 
 IF configuration is incomplete: Fix it before continuing.
 
+### Check 5b: Seeding Infrastructure (BLOCKING - first entity only)
+
+**If this is the FIRST entity created in this project (no existing DevDataSeeder):**
+
+Scaffold the full seeding infrastructure following the SmartStack.app architecture:
+
+1. **Create `Infrastructure/Persistence/Seeding/Data/SeedConstants.cs`**
+
+   ```csharp
+   namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
+
+   /// <summary>
+   /// Shared constants for seed data across all modules.
+   /// </summary>
+   public static class SeedConstants
+   {
+       public static readonly DateTime SeedDate = new(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+   }
+   ```
+
+2. **Create `Infrastructure/Persistence/Seeding/DevDataSeeder.cs`**
+
+   ```csharp
+   using Microsoft.EntityFrameworkCore;
+   using Microsoft.Extensions.Logging;
+   using SmartStack.Application.Common.Interfaces;
+
+   namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
+
+   /// <summary>
+   /// Seeds development/demo data at application startup.
+   /// Only runs when EnableDevSeeding = true.
+   /// </summary>
+   public class DevDataSeeder : IDevDataSeeder
+   {
+       private readonly ExtensionsDbContext _context;
+       private readonly ILogger<DevDataSeeder> _logger;
+
+       public DevDataSeeder(ExtensionsDbContext context, ILogger<DevDataSeeder> logger)
+       {
+           _context = context;
+           _logger = logger;
+       }
+
+       public async Task SeedAsync(CancellationToken cancellationToken = default)
+       {
+           _logger.LogInformation("Starting development data seeding...");
+           // Add Seed{Entity}sAsync calls here as entities are created
+           _logger.LogInformation("Development data seeding complete.");
+       }
+   }
+   ```
+
+3. **Register DevDataSeeder in `Infrastructure/DependencyInjection.cs`:**
+   ```csharp
+   services.AddScoped<IDevDataSeeder, DevDataSeeder>();
+   ```
+
+**If DevDataSeeder already exists:** Skip this check.
+
+### Check 5c: SqlObjects Directory (BLOCKING - first entity only)
+
+**If this is the FIRST entity in the project (no existing SqlObjectHelper):**
+
+Scaffold the SQL objects infrastructure:
+
+1. **Create `Infrastructure/Persistence/SqlObjects/SqlObjectHelper.cs`**
+
+   ```csharp
+   using System.Reflection;
+   using Microsoft.EntityFrameworkCore.Migrations;
+
+   namespace {BaseNamespace}.Infrastructure.Persistence.SqlObjects;
+
+   /// <summary>
+   /// Helper for applying SQL objects (Functions, Views, Stored Procedures) from embedded resources.
+   /// SQL files use CREATE OR ALTER for idempotency — safe to re-run on any migration or squash.
+   /// </summary>
+   public static class SqlObjectHelper
+   {
+       private static readonly Assembly Assembly = typeof(SqlObjectHelper).Assembly;
+       private const string ResourcePrefix = "{BaseNamespace}.Infrastructure.Persistence.SqlObjects.";
+
+       public static void ApplyAll(MigrationBuilder migrationBuilder)
+       {
+           ApplyAllFunctions(migrationBuilder);
+       }
+
+       public static void ApplyAllFunctions(MigrationBuilder migrationBuilder)
+       {
+           ApplyCategory(migrationBuilder, "Functions");
+       }
+
+       public static void ApplyOne(MigrationBuilder migrationBuilder, string resourceName)
+       {
+           var sql = ReadSqlObject(resourceName);
+           migrationBuilder.Sql(sql);
+       }
+
+       public static string ReadSqlObject(string resourceName)
+       {
+           var fullName = ResourcePrefix + resourceName;
+           using var stream = Assembly.GetManifestResourceStream(fullName)
+               ?? throw new InvalidOperationException(
+                   $"SQL object resource '{fullName}' not found. " +
+                   $"Ensure the .sql file is marked as EmbeddedResource in the .csproj.");
+           using var reader = new StreamReader(stream);
+           return reader.ReadToEnd();
+       }
+
+       private static void ApplyCategory(MigrationBuilder migrationBuilder, string category)
+       {
+           var prefix = ResourcePrefix + category + ".";
+           var resources = Assembly.GetManifestResourceNames()
+               .Where(n => n.StartsWith(prefix, StringComparison.Ordinal)
+                        && n.EndsWith(".sql", StringComparison.Ordinal))
+               .OrderBy(n => n, StringComparer.Ordinal);
+
+           foreach (var resource in resources)
+           {
+               using var stream = Assembly.GetManifestResourceStream(resource)!;
+               using var reader = new StreamReader(stream);
+               migrationBuilder.Sql(reader.ReadToEnd());
+           }
+       }
+   }
+   ```
+
+2. **Create empty directory `Infrastructure/Persistence/SqlObjects/Functions/`**
+   - Where `.sql` files for TVFs and scalar functions will be stored
+
+3. **Ensure `.csproj` has EmbeddedResource glob for SQL files:**
+   ```xml
+   <ItemGroup>
+     <EmbeddedResource Include="Persistence\SqlObjects\**\*.sql" />
+   </ItemGroup>
+   ```
+
+**If SqlObjectHelper already exists:** Skip this check.
+
 ---
 
 ## SUCCESS METRICS
@@ -367,7 +541,7 @@ IF configuration is incomplete: Fix it before continuing.
 - NavRoute attribute included
 - Entity seeding offered to user (SeedData.cs + DevDataSeeder if accepted)
 - Entity info stored for frontend
-- Post-generation verification passed (all 5 checks)
+- Post-generation verification passed (all 7 checks: 5 original + 5b Seeding + 5c SqlObjects)
 - Proceeded to step-05-frontend.md
 
 ## FAILURE MODES

package/templates/skills/application/steps/step-06-migration.md

@@ -66,24 +66,56 @@ IF build fails:
 Tool: mcp__smartstack__suggest_migration
 Args:
   description: "Add {entity_name} with navigation and permissions"
-  context: "core"
+  context: "{db_context}"   # "core" or "extensions" based on project type
 ```
 
-Response example:
+Response example (core project):
 ```
 Migration name: core_v1.2.0_003_Add{EntityName}WithNavigationAndPermissions
 Command: dotnet ef migrations add core_v1.2.0_003_Add{EntityName}WithNavigationAndPermissions --context CoreDbContext -o Persistence/Migrations
 ```
 
+Response example (client project):
+```
+Migration name: extensions_v1.0.0_001_Add{EntityName}ModuleEntities
+Command: dotnet ef migrations add extensions_v1.0.0_001_Add{EntityName}ModuleEntities --context ExtensionsDbContext -o Persistence/Migrations
+```
+
 ### 2. Create Migration
 
 Use the /efcore:migration skill or direct command:
 
+**For core projects:**
 ```bash
 cd Infrastructure
 dotnet ef migrations add {suggested_migration_name} --context CoreDbContext -o Persistence/Migrations
 ```
 
+**For client projects (ExtensionsDbContext):**
+```bash
+cd Infrastructure
+dotnet ef migrations add {suggested_migration_name} --context ExtensionsDbContext -o Persistence/Migrations
+```
+
+> **CRITICAL:** Always use `-o Persistence/Migrations` to ensure ALL migrations are in the SAME directory.
+> NEVER create subdirectories under `Migrations/` (e.g., `Migrations/Extensions/`).
+> All migrations for a given DbContext MUST share the same namespace to avoid EF Core errors.
+
+### 2b. Inject SQL Objects (if any exist)
+
+Check if any SQL object files exist:
+```
+Glob: **/Persistence/SqlObjects/Functions/*.sql
+```
+
+If SQL files are found, the migration's `Up()` method should include a call to re-apply all SQL objects:
+```csharp
+// At the end of the Up() method:
+SqlObjectHelper.ApplyAll(migrationBuilder);
+```
+
+This ensures SQL functions/views are re-applied with each migration (`CREATE OR ALTER` = idempotent).
+
 ### 3. Verify Migration Content
 
 The migration should include:
@@ -93,13 +125,20 @@ The migration should include:
 - RolePermissions (role assignments)
 - Domain entity table
 - Indexes and constraints
+- SQL Objects injection (if any .sql files exist)
 
 ### 4. Apply Migration
 
+**For core projects:**
 ```bash
 dotnet ef database update --context CoreDbContext
 ```
 
+**For client projects:**
+```bash
+dotnet ef database update --context ExtensionsDbContext
+```
+
 ### 5. Present Final Checklist
 
 ```markdown