@atlashub/smartstack-cli 3.37.0 → 3.39.0

package/templates/mcp-scaffolding/frontend/nav-routes.ts.hbs

@@ -11,11 +11,11 @@
  */
 
 export interface NavRoute {
-  /** NavRoute path (e.g., "platform.administration.users") */
+  /** NavRoute path (e.g., "administration.users") */
   navRoute: string;
-  /** API endpoint path (e.g., "/api/platform/administration/users") */
+  /** API endpoint path (e.g., "/api/administration/users") */
   api: string;
-  /** Frontend route path (e.g., "/platform/administration/users") */
+  /** Frontend route path (e.g., "/administration/users") */
   web: string;
   /** Required permissions to access this route */
   permissions: string[];
@@ -72,43 +72,43 @@ export function hasRoutePermission(navRoute: string, userPermissions: string[]):
 }
 
 /**
- * Get all routes for a context (e.g., "platform")
+ * Get all routes for an application (e.g., "administration")
  */
-export function getRoutesByContext(context: string): NavRoute[] {
-  return Object.values(ROUTES).filter(r => r.navRoute.startsWith(`${context}.`));
+export function getRoutesByApplication(application: string): NavRoute[] {
+  return Object.values(ROUTES).filter(r => r.navRoute.startsWith(`${application}.`));
 }
 
 /**
- * Get all routes for a context and application (e.g., "platform.administration")
+ * Get all routes for an application and module (e.g., "administration.users")
  */
-export function getRoutesByApplication(context: string, application: string): NavRoute[] {
-  const prefix = `${context}.${application}`;
+export function getRoutesByModule(application: string, module: string): NavRoute[] {
+  const prefix = `${application}.${module}`;
   return Object.values(ROUTES).filter(r => r.navRoute.startsWith(`${prefix}.`) || r.navRoute === prefix);
 }
 
 /**
- * Get all unique contexts
+ * Get all unique applications
  */
-export function getContexts(): string[] {
-  const contexts = new Set<string>();
+export function getApplications(): string[] {
+  const applications = new Set<string>();
   for (const route of Object.values(ROUTES)) {
-    contexts.add(route.navRoute.split('.')[0]);
+    applications.add(route.navRoute.split('.')[0]);
   }
-  return Array.from(contexts);
+  return Array.from(applications);
 }
 
 /**
- * Get all unique applications within a context
+ * Get all unique modules within an application
  */
-export function getApplications(context: string): string[] {
-  const apps = new Set<string>();
+export function getModules(application: string): string[] {
+  const modules = new Set<string>();
   for (const route of Object.values(ROUTES)) {
     const parts = route.navRoute.split('.');
-    if (parts[0] === context && parts.length >= 2) {
-      apps.add(parts[1]);
+    if (parts[0] === application && parts.length >= 2) {
+      modules.add(parts[1]);
     }
   }
-  return Array.from(apps);
+  return Array.from(modules);
 }
 
 /**

package/templates/mcp-scaffolding/frontend/routes.tsx.hbs

@@ -19,7 +19,7 @@ import { ProtectedRoute, PermissionGuard } from './guards';
 // Layouts
 // ============================================================================
 
-{{#each contexts}}
+{{#each applications}}
 import { {{capitalize this}}Layout } from '../layouts/{{capitalize this}}Layout';
 {{/each}}
 
@@ -52,38 +52,30 @@ const routes: RouteObject[] = [
     element: <Navigate to="{{defaultPath}}" replace />,
   },
 
-{{#each contextTree}}
-  // {{uppercase @key}} Context
+{{#each applicationTree}}
+  // {{uppercase @key}} Application
   {
     path: '{{@key}}',
     element: <{{capitalize @key}}Layout />,
     children: [
 {{#each this}}
-      // {{uppercase @key}} Application
       {
-        path: '{{@key}}',
-        children: [
-{{#each this}}
-          {
-            path: '{{modulePath this.navRoute}}',
+        path: '{{modulePath this.navRoute}}',
 {{#if this.permissions.length}}
-            element: (
-              <PermissionGuard permissions={ROUTES['{{this.navRoute}}'].permissions}>
-                <Suspense fallback={<PageLoader />}>
-                  <{{pageName this.navRoute}}Page />
-                </Suspense>
-              </PermissionGuard>
-            ),
+        element: (
+          <PermissionGuard permissions={ROUTES['{{this.navRoute}}'].permissions}>
+            <Suspense fallback={<PageLoader />}>
+              <{{pageName this.navRoute}}Page />
+            </Suspense>
+          </PermissionGuard>
+        ),
 {{else}}
-            element: (
-              <Suspense fallback={<PageLoader />}>
-                <{{pageName this.navRoute}}Page />
-              </Suspense>
-            ),
+        element: (
+          <Suspense fallback={<PageLoader />}>
+            <{{pageName this.navRoute}}Page />
+          </Suspense>
+        ),
 {{/if}}
-          },
-{{/each}}
-        ],
       },
 {{/each}}
     ],

package/templates/mcp-scaffolding/migrations/seed-roles.cs.hbs

@@ -152,8 +152,8 @@ public partial class {{migrationName}} : Migration
                 FROM core.auth_Permissions
                 WHERE IsDeleted = 0
                   AND Code NOT LIKE '%.delete'
-                  AND Code NOT LIKE 'platform.administration.users.%'
-                  AND Code NOT LIKE 'platform.administration.roles.%';
+                  AND Code NOT LIKE 'administration.users.%'
+                  AND Code NOT LIKE 'administration.roles.%';
 
                 PRINT 'Read, create, update permissions granted to Contributor (excluding user management)';
             END

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

@@ -129,9 +129,9 @@ FOR each module:
       "issues": [
         {
           "type": "endpoint_mismatch",
-          "documented": ["GET /api/business/sla", "POST /api/business/sla"],
-          "actual": ["GET /api/business/sla", "POST /api/business/sla", "PATCH /api/business/sla/{id}/status"],
-          "message": "Endpoint PATCH /api/business/sla/{id}/status exists in code but not in documentation"
+          "documented": ["GET /api/support/sla", "POST /api/support/sla"],
+          "actual": ["GET /api/support/sla", "POST /api/support/sla", "PATCH /api/support/sla/{id}/status"],
+          "message": "Endpoint PATCH /api/support/sla/{id}/status exists in code but not in documentation"
         }
       ]
     }

package/templates/skills/_shared.md

@@ -19,11 +19,11 @@ Domain → Application → Infrastructure → API → Web
 ### Layers
 | Layer | Responsibility | Namespace | Folder Hierarchy |
 |-------|-----------------|-----------|------------------|
-| Domain | Entities, ValueObjects | `SmartStack.Domain.{Context}.{App}.{Module}` | `Domain/{Context}/{App}/{Module}/` |
-| Application | Interfaces (Common), DTOs | `SmartStack.Application.Common.Interfaces` / `.{Context}.{App}.{Module}.DTOs` | `Application/Common/Interfaces/` + `Application/{Context}/{App}/{Module}/DTOs/` |
-| Infrastructure | Service Impl, EF Core | `SmartStack.Infrastructure.Services.{Context}.{App}.{Module}` | `Infrastructure/Services/{Context}/{App}/{Module}/` + `Persistence/Configurations/{Context}/{App}/{Module}/` |
-| API | Controllers, Middleware | `SmartStack.Api.Controllers.{Context}` | `Api/Controllers/{Context}/` |
-| Web | React components, pages | N/A | `pages/{context}/{app}/{module}/` + `components/{context}/{module}/` |
+| Domain | Entities, ValueObjects | `SmartStack.Domain.{App}.{Module}` | `Domain/{App}/{Module}/` |
+| Application | Interfaces (Common), DTOs | `SmartStack.Application.Common.Interfaces` / `.{App}.{Module}.DTOs` | `Application/Common/Interfaces/` + `Application/{App}/{Module}/DTOs/` |
+| Infrastructure | Service Impl, EF Core | `SmartStack.Infrastructure.Services.{App}.{Module}` | `Infrastructure/Services/{App}/{Module}/` + `Persistence/Configurations/{App}/{Module}/` |
+| API | Controllers, Middleware | `SmartStack.Api.Controllers` | `Api/Controllers/` |
+| Web | React components, pages | N/A | `pages/{app}/{module}/` + `components/{module}/` |
 
 ## Permissions (2 mandatory files)
 
@@ -31,10 +31,10 @@ Domain → Application → Infrastructure → API → Web
 ```csharp
 public static class {Module}
 {
-    public const string View = "{context}.{app}.{module}.view";
-    public const string Create = "{context}.{app}.{module}.create";
-    public const string Update = "{context}.{app}.{module}.update";
-    public const string Delete = "{context}.{app}.{module}.delete";
+    public const string View = "{app}.{module}.view";
+    public const string Create = "{app}.{module}.create";
+    public const string Update = "{app}.{module}.update";
+    public const string Delete = "{app}.{module}.delete";
 }
 ```
 
@@ -59,14 +59,12 @@ builder.HasData(
 ### i18n Structure
 ```json
 {
-  "{context}": {
-    "{application}": {
-      "{module}": {
-        "title": "...",
-        "fields": { ... },
-        "actions": { ... },
-        "messages": { ... }
-      }
+  "{application}": {
+    "{module}": {
+      "title": "...",
+      "fields": { ... },
+      "actions": { ... },
+      "messages": { ... }
     }
   }
 }

package/templates/skills/ai-prompt/SKILL.md

@@ -60,7 +60,7 @@ JSON Schema for validation: Code, Name, JsonSchema, DotNetType
 
 ## Implementation
 
-See [steps/step-01-implementation.md](steps/step-01-implementation.md) for:
+Start with [steps/step-00-init.md](steps/step-00-init.md) to gather requirements, then proceed to [steps/step-01-implementation.md](steps/step-01-implementation.md) for:
 - Workflow steps (define use case, create prompt, define schema, execute)
 - AI service interfaces (IAiCompletionService, IPromptService)
 - Frontend integration (API, hooks, components)

package/templates/skills/ai-prompt/steps/step-00-init.md

@@ -0,0 +1,47 @@
+# Step 0: Initialization
+
+## YOUR TASK
+Gather context about the AI integration requirements before implementation.
+
+## EXECUTION SEQUENCE
+
+### 1. Identify AI Use Case
+- What type of AI integration? (prompt execution, chat, content generation, validation, analysis)
+- What model/provider should be used? (Claude, GPT-4, GPT-4o, Gemini, local model)
+- What is the input schema? (user query, structured data, multiple parameters)
+- What is the expected output? (text, JSON, structured object, classification)
+
+### 2. Check Existing Patterns
+- Search existing `Application/Common/Interfaces/IAiCompletionService` usage
+- Identify reusable patterns: AiProviderInstance configuration, OutputSchema definitions
+- Check for existing Prompt entities with similar use cases
+- Review error handling patterns for API failures and quota limits
+
+### 3. Plan Implementation
+- Determine required files:
+  - Prompt entity and PromptBlock creation
+  - OutputSchema if structured response needed
+  - Service integration with IAiCompletionService
+  - Frontend API client and React hook
+- Identify dependencies:
+  - Which AI provider instance to use? (API keys, budget limits)
+  - Token budget and cost implications
+  - Error handling strategy (fallback provider, graceful degradation)
+- Map variables and placeholders for dynamic content
+
+### 4. Define Success Criteria
+- Prompt executes with correct model and parameters
+- Response validates against OutputSchema (if applicable)
+- Token usage logged and budget respected
+- Error handling covers API downtime and quota exhaustion
+- Frontend integrates with loading/error states
+
+## SUCCESS METRICS
+- AI use case clearly identified and documented
+- Implementation plan with all required files listed
+- Dependencies identified (provider instance, budget, error handling)
+- Decision on structured vs. unstructured response
+- Token budget and cost reviewed
+
+## NEXT STEP
+Proceed to `./step-01-implementation.md` to implement the Prompt, OutputSchema, Service integration, and Frontend components.

package/templates/skills/apex/SKILL.md

@@ -11,7 +11,7 @@ argument-hint: "[-a] [-x] [-s] [-e] [-r] [-pr] <task description>"
 ---
 
 <objective>
-Execute incremental SmartStack development using the APEX methodology. This skill knows the SmartStack hierarchy (context/application/module/section/resource), delegates code creation to existing skills (/controller, /application, /ui-components, /efcore, /notification, /workflow) and MCP tools, and validates via MCP conventions.
+Execute incremental SmartStack development using the APEX methodology. This skill knows the SmartStack hierarchy (application/module/section/resource), delegates code creation to existing skills (/controller, /application, /ui-components, /efcore, /notification, /workflow) and MCP tools, and validates via MCP conventions.
 
 **Key principle:** /apex ORCHESTRATES — it never generates SmartStack code directly. All generation goes through skills and MCP tools.
 </objective>
@@ -57,7 +57,6 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `{delegate_mode}` | boolean | Delegated by `/ralph-loop` via `-d` flag |
 | `{delegate_prd_path}` | string? | Path to PRD file (`.ralph/prd.json` or `.ralph/prd-{module}.json`) |
 | `{foundation_mode}` | boolean | Foundation mode: entities-only (no services/controllers/frontend). Used by ralph-loop Phase 0. |
-| `{context_code}` | string | "business", "platform", "personal" |
 | `{app_name}` | string | Application name |
 | `{module_code}` | string | Module code |
 | `{sections}` | object[] | Sections (MANDATORY, min 1) with code/labels/icon/displayOrder |
@@ -84,7 +83,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | Step | File | Model | Purpose |
 |------|------|-------|---------|
-| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect context, verify MCP, define hierarchy (5 levels), challenge need |
+| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect application, verify MCP, define hierarchy (4 levels), challenge need |
 | 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (Agent Teams or direct) |
 | 02 | `steps/step-02-plan.md` | Opus | Layer-by-layer plan with skill/MCP mapping |
 | 03 | `steps/step-03-execute.md` | Opus | Orchestrate execution via skills and MCP |
@@ -158,7 +157,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 </error_handling>
 
 <success_criteria>
-- SmartStack context detected (context/app/module)
+- SmartStack hierarchy detected (app/module)
 - Plan validated with skill/MCP mapped for each file
 - Code created/corrected via existing skills and MCP (no direct generation)
 - MCP validate_conventions: 0 errors

package/templates/skills/apex/_shared.md

@@ -13,15 +13,6 @@
 3. `.ralph/prd-*.json` → PRDs exist
 4. `src/pages/` → React frontend exists
 
-### Context-to-Folder Mapping
-
-| Context | Backend | Controller | Frontend Layout |
-|---------|---------|------------|----------------|
-| `business` | `Business` | `Business` | `BusinessLayout` |
-| `platform.administration` | `Platform/Administration` | `Admin` | `AdminLayout` |
-| `platform.support` | `Platform/Support` | `Support` | `AdminLayout` |
-| `personal` | `Personal` | `User` | `UserLayout` |
-
 ---
 
 ## Delegate Mode Context
@@ -32,7 +23,6 @@ When `/ralph-loop` invokes `/apex -d {prd_path}`:
 
 1. **Read PRD** from `{delegate_prd_path}` (`.ralph/prd.json` or `.ralph/prd-{module}.json`)
 2. **Extract context:**
-   - `context_code` = `prd.project.context` (e.g., "business")
    - `app_name` = `prd.project.application` (e.g., "HumanResources")
    - `module_code` = `prd.project.module` (e.g., "EmployeeManagement")
    - `sections` = from `_seedDataMeta.coreSeedData.navigationSections` in infrastructure tasks
@@ -72,23 +62,23 @@ Write back to {delegate_prd_path}
 
 | Level | Permission format | Segments |
 |-------|------------------|----------|
-| Module | `{context}.{app}.{module}.{action}` | 3+1 segments |
-| Section | `{context}.{app}.{module}.{section}.{action}` | 4+1 segments |
-| Resource | `{context}.{app}.{module}.{section}.{resource}.{action}` | 5+1 segments |
+| Module | `{app}.{module}.{action}` | 2+1 segments |
+| Section | `{app}.{module}.{section}.{action}` | 3+1 segments |
+| Resource | `{app}.{module}.{section}.{resource}.{action}` | 4+1 segments |
 
 **Examples:**
-- Module: `business.human-resources.employees.read` (3+1)
-- Section: `business.human-resources.employees.departments.read` (4+1)
-- Resource: `business.human-resources.employees.departments.export.execute` (5+1)
+- Module: `human-resources.employees.read` (2+1)
+- Section: `human-resources.employees.departments.read` (3+1)
+- Resource: `human-resources.employees.departments.export.execute` (4+1)
 
 > **CRITICAL — Permission codes use the SAME kebab-case segments as NavRoute codes.**
 > Every dot-separated segment in a permission path is a navigation entity code.
 > Multi-word codes MUST be kebab-case: `human-resources`, NOT `humanresources`.
 >
-> SmartStack.app reference: `business.support-client.my-tickets.read`, `platform.administration.email-templates.read`
+> SmartStack.app reference: `support-client.my-tickets.read`, `administration.email-templates.read`
 >
-> **FORBIDDEN:** `business.humanresources.employees.read` (concatenated — no kebab-case)
-> **CORRECT:** `business.human-resources.employees.read` (kebab-case — matches NavRoute)
+> **FORBIDDEN:** `humanresources.employees.read` (concatenated — no kebab-case)
+> **CORRECT:** `human-resources.employees.read` (kebab-case — matches NavRoute)
 
 ### Generation (step-03)
 
@@ -144,7 +134,7 @@ Write back to {delegate_prd_path}
 | Skill | When to delegate |
 |-------|-----------------|
 | `/controller` | Complex controller with custom routes |
-| `/application` | New context/application/module structure |
+| `/application` | New application/module structure |
 | `/ui-components` | Complex React pages (tables, grids, dashboards) |
 | `/efcore` | Complex EF Core configurations |
 | `/notification` | In-app or email notifications |

package/templates/skills/apex/references/analysis-methods.md

@@ -0,0 +1,141 @@
+# Analysis Methods — FK Detection, Tenant Modes, Code Patterns, Gap Analysis
+
+> **Loaded by:** step-01-analyze.md (sections 4-7)
+> **Purpose:** Detailed methods for analyzing existing code and planning entity-level requirements.
+
+---
+
+## FK Field Detection
+
+For each entity found (or to be created), identify FK relationships:
+- Properties ending in "Id" with matching navigation property
+- Record: `{ entity, fkProperty, targetEntity, isRequired }`
+
+**Why:** FK fields drive two critical requirements:
+1. **Frontend:** Each FK field MUST use `<EntityLookup />` (NEVER `<input>`, NEVER `<select>`)
+2. **Backend:** Each target entity's GetAll MUST support `?search=` parameter + return `PaginatedResult<T>`
+
+See `references/execution-frontend-patterns.md` for EntityLookup patterns.
+
+---
+
+## Tenant Mode Decision
+
+For each entity found (or to be created), determine the `tenantMode`:
+
+| Mode | Meaning | Examples | EF Filter |
+|------|---------|----------|-----------|
+| `strict` | Data belongs to one tenant | Employee, Order, Invoice | `TenantId == current` |
+| `optional` | Can be shared or tenant-specific | Department, Currency, JobTitle | `TenantId == current OR TenantId == null` |
+| `scoped` | Explicit scope rules | Settings, Workflow, EmailTemplate | `TenantId == current AND Scope == current` |
+| `none` | Platform-wide (never filtered) | Navigation, Permission, User | No TenantId |
+
+**Why:** Tenant mode drives EF query filters, seed data generation, and API access control.
+
+**Reference:** See `references/smartstack-api.md` for TenantId handling patterns and `smartstack-layers.md` for seed data strategies per tenant mode.
+
+---
+
+## Code Pattern Detection
+
+For each entity found (or to be created), identify code generation needs:
+
+```
+IF feature.json exists AND entity has codePattern:
+  → Use codePattern config from feature.json (strategy, prefix, digits, etc.)
+  → Record in analysis: entity has auto-generated code
+
+ELSE IF feature.json exists BUT entity has NO codePattern:
+  → Record: entity needs codePattern decision in step-02
+  → Apply heuristic default based on entity name:
+    Invoice/Order/Receipt → timestamp-daily
+    Ticket/Incident → timestamp-minute
+    Contract/Policy → year-sequential
+    Reference/Category → uuid-short
+    Employee/Customer/Project → sequential
+
+ELSE (no feature.json):
+  → Propose codePattern during step-02 planning based on task description
+```
+
+**Why:** Code generation strategy drives CreateDto structure, service injection (ICodeGenerator<T>), and DI registration.
+
+**Reference:** See `references/code-generation.md` for strategy table, volume-to-digits calculation, and backend patterns.
+
+---
+
+## Gap Analysis
+
+Compare what EXISTS vs what the TASK REQUIRES:
+
+```
+For each element: EXISTS+COMPLETE → "skip" | EXISTS+INCOMPLETE → "modify" | MISSING → "create"
+```
+
+Cross-reference with step-00 challenge responses:
+- Each entity: entity, EF config, service, controller, frontend pages → exists/missing
+- Each section: NavigationSectionSeedData, frontend route → exists/missing
+- If dependencies: verify FK target entities and their `?search=` support
+
+---
+
+## Scope Re-Check (after exploration)
+
+**Re-validate scope after code exploration reveals the true entity count.**
+Step-00 guard uses the user's description (may undercount). Now we know the actual entities.
+
+```
+IF NOT delegate_mode:
+  actual_entities = count of entities marked "create" in gap analysis
+  actual_sections = count of sections marked "create"
+
+  IF actual_entities > 6:
+    WARNING: "Code exploration reveals {actual_entities} entities.
+     This exceeds the recommended maximum (4) for a single /apex invocation.
+     Risk: incomplete migrations, lost conventions, missing pages.
+     Consider: split into {ceil(actual_entities/4)} iterations of ~4 entities each."
+
+    Ask user to confirm or re-scope.
+```
+
+---
+
+## Analysis Validation — User Checkpoint
+
+**Objective:** Present findings and validate scope BEFORE planning.
+
+### Present Findings
+
+```
+ANALYSIS FINDINGS
+═══════════════════════════════════════════════════════════════
+
+Entities expected / found / to create: {summary}
+Sections expected / found / to create: {summary}
+FK Relationships: {fkFields summary}
+Dependencies: {cross-module refs or "none"}
+Complexity: {module_complexity}
+```
+
+### Validate with User (if NOT auto_mode)
+
+Question template (same as step-01 section 6b):
+- "Scope is correct" (Recommended)
+- "Add elements" → update entities/sections, re-run gap analysis
+- "Reduce scope" → update accordingly
+- "Change approach" → potentially restart from step-00
+
+---
+
+## Analysis Summary Output
+
+```
+**APEX SmartStack - Analysis Complete**
+
+Navigation: {app_name} → {module_code} → {sections[].code}
+Entities: {entity_name → create | modify | skip}
+Existing: entities, configs, services, controllers, pages, seed data, tests (with paths)
+Required: create / modify / skip lists
+Profile: complexity, dependencies, FK fields, workflow, notifications
+ACs: AC1..ACn (inferred from PRD/feature/task/challenge)
+```

package/templates/skills/apex/references/challenge-questions.md

@@ -5,26 +5,6 @@
 
 ---
 
-## Context Detection (section 2)
-
-If hierarchy cannot be inferred, ask the user:
-
-```yaml
-questions:
-  - header: "Context"
-    question: "What is the SmartStack context for this work?"
-    options:
-      - label: "Business (Recommended)"
-        description: "Business application module"
-      - label: "Platform"
-        description: "Platform administration or support"
-      - label: "Personal"
-        description: "Personal user space"
-    multiSelect: false
-```
-
----
-
 ## 4a. Application Validation
 
 If `{app_name}` was NOT clearly inferred from the task description:
@@ -37,7 +17,7 @@ questions:
       - label: "<best guess from task> (Recommended)"
         description: "Inferred from your task description"
       - label: "New application"
-        description: "Create a new application in the {context_code} context"
+        description: "Create a new application"
       - label: "Existing application"
         description: "Add to an existing application (specify in Other)"
     multiSelect: false