@atlashub/smartstack-cli 4.32.0 → 4.34.0

package/templates/skills/apex/steps/step-03a-layer0-domain.md

@@ -0,0 +1,118 @@
+---
+name: step-03a-layer0-domain
+description: "Layer 0: Domain entities, EF configs, migration"
+model: opus
+parent_step: steps/step-03-execute.md
+---
+
+## Layer 0 — Domain + Infrastructure (sequential, agent principal)
+
+### Task Progress
+TaskUpdate(taskId: layer0_task_id, status: "in_progress")
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 0",
+  activeForm: "Executing Layer 0")
+
+### Domain Entities
+
+```
+For each entity to create/modify:
+  → MCP scaffold_extension (type: "entity", target: entity_name)
+  → Verify: inherits BaseEntity, implements ITenantEntity + IAuditableEntity
+  → Verify entity matches patterns in references/smartstack-api.md
+```
+
+### Code Generation Integration
+
+```
+For each entity with auto-generated code ({code_patterns} from step-00):
+  IF {code_patterns} has entry for this entity AND strategy != "manual":
+    → Pass codePattern in scaffold_extension options:
+      MCP scaffold_extension (type: "entity", target: entity_name, options: {
+        codePattern: {
+          strategy: {code_patterns[entity].strategy},
+          prefix: {code_patterns[entity].prefix},
+          digits: {code_patterns[entity].digits},
+          includeTenantSlug: {code_patterns[entity].includeTenantSlug},
+          separator: {code_patterns[entity].separator}
+        }
+      })
+    → Verify: Code property exists on entity but is NOT in CreateDto
+    → Verify: ICodeGenerator<{Entity}> is ready for DI registration (Layer 2)
+  ELSE:
+    → Default behavior (strategy: "manual", Code in CreateDto)
+```
+
+### Enum Serialization Check
+
+```
+For each enum type created in Domain/Enums/:
+  1. Grep("JsonStringEnumConverter", "src/**/Program.cs")
+  2. IF global config exists → no action
+  3. IF no global config → add [JsonConverter(typeof(JsonStringEnumConverter))] on each enum
+```
+
+### Person Extension Detection
+
+**If entity has personRoleConfig (mandatory or optional UserId link):**
+See `references/person-extension-pattern.md` for full entity, EF config, service, DTO, and frontend patterns.
+
+```
+1. scaffold_extension with options: { isPersonRole: true, userLinkMode: 'mandatory' | 'optional' }
+2. Verify: EF config has unique index on (TenantId, UserId)
+   → Mandatory variant: plain .IsUnique()
+   → Optional variant: .IsUnique().HasFilter("[UserId] IS NOT NULL")
+3. Verify all build checks pass before continuing
+```
+
+### EF Core Configurations
+
+```
+For each entity:
+  → Create IEntityTypeConfiguration<T> manually per smartstack-api.md patterns
+  → Verify: table name, relationships, indexes
+  → Register DbSet in ExtensionsDbContext if new entity
+```
+
+<!-- TODO A6: Replace with MCP scaffold_extension(type: "ef-config") when B2 is ready -->
+
+### Migration
+
+> Migration must cover ALL entities. Root cause (test-apex-007): Migration was created once for 3 entities, then 4 more entities were added later without re-running → 4 entities had no tables. Create/update migration AFTER ALL entities and EF configs are registered in DbContext. If entities are added incrementally, create a new migration for each batch.
+
+```
+1. Verify all entities have been added as DbSet in ExtensionsDbContext
+2. Verify all EF configurations are registered (ApplyConfigurationsFromAssembly or individual)
+3. MCP suggest_migration → get standardized name
+4. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
+5. dotnet ef database update (if local DB)
+6. dotnet build
+7. Verify: dotnet ef migrations has-pending-model-changes → must report "No pending model changes"
+```
+
+If build fails after migration, fix EF configs before proceeding.
+If `has-pending-model-changes` reports pending changes, entities are missing from the migration — create a new migration.
+
+### Post-Layer 0 Build Gate
+
+```bash
+dotnet build
+# Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
+```
+
+Must pass before Layer 1. If NuGet error, run `dotnet restore` first. If file lock (MSB3021), use `--output /tmp/{project}_build`.
+
+TaskUpdate(taskId: layer0_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+
+### Layer 0 Commit
+
+```
+feat({module}): [domain+infra] {short description}
+```
+
+---
+
+## NEXT SUB-STEP
+
+Load `steps/step-03b-layer1-seed.md`

package/templates/skills/apex/steps/step-03b-layer1-seed.md

@@ -0,0 +1,91 @@
+---
+name: step-03b-layer1-seed
+description: "Layer 1: Seed data (navigation, permissions, roles)"
+model: opus
+parent_step: steps/step-03-execute.md
+---
+
+## Layer 1 — Seed Data (DEDICATED LAYER — sequential, agent principal)
+
+### Task Progress
+TaskUpdate(taskId: layer1_task_id, status: "in_progress")
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 1",
+  activeForm: "Executing Layer 1")
+
+> This layer is required. Seed data makes modules visible in the UI. Without it, the module exists in code but is invisible to users. Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
+
+### Application-Level Seed Data (ONCE per application)
+
+```
+1. NavigationApplicationSeedData.cs
+   → Application-level navigation entry (MUST be first)
+   → 4 language translations (fr, en, it, de)
+
+2. ApplicationRolesSeedData.cs
+   → 4 roles: admin, manager, contributor, viewer
+   → References NavigationApplicationSeedData.ApplicationId
+```
+
+### Per-Module Seed Data
+
+```
+3. NavigationModuleSeedData.cs
+   → 4 languages (fr, en, it, de), GetModuleEntry() + GetTranslationEntries()
+   → If sections defined: GetSectionEntries() + GetSectionTranslationEntries()
+   → If resources defined: GetResourceEntries() + resource translations
+   → Query actual parent from DB for FK (NOT deterministic GUID)
+
+4. Permissions.cs
+   → MCP generate_permissions (PRIMARY tool)
+   → Static constants: public static class {Module} { public const string Read = "..."; }
+   → Permission paths MUST use kebab-case matching NavRoute codes
+
+5. PermissionsSeedData.cs
+   → MCP generate_permissions first, fallback template
+   → Paths match Permissions.cs, wildcard + CRUD
+
+6. RolesSeedData.cs
+   → Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R
+   → Code-based role mapping (not deterministic GUIDs for roles)
+   → Look up roles by Code at runtime
+```
+
+### Infrastructure Provider (ONCE per application)
+
+```
+7. {App}SeedDataProvider.cs
+   → Implements IClientSeedDataProvider
+   → SeedNavigationAsync(): Application → Module → Section → Resource + translations
+   → SeedRolesAsync(): application-scoped roles from ApplicationRolesSeedData
+   → SeedPermissionsAsync(): permission entries from PermissionsSeedData
+   → SeedRolePermissionsAsync(): maps roles to permissions (by Code, NOT by GUID)
+   → DI: services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()
+```
+
+<!-- TODO A4: Replace direct seed generation with MCP scaffold_seed_data when B1 is ready. This will eliminate the need for references/core-seed-data.md (1464 lines). -->
+
+### Post-Layer 1 Build Gate
+
+```bash
+dotnet build
+```
+
+Must pass before Layer 2.
+
+TaskUpdate(taskId: layer1_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+
+### Layer 1 Commit
+
+```
+feat({module}): [seed] navigation, permissions, roles
+```
+
+> **Context release:** `references/core-seed-data.md` is no longer needed after Layer 1. Its templates have been consumed. Do not reference it in Layer 2+.
+
+---
+
+## NEXT SUB-STEP
+
+Load `steps/step-03c-layer2-backend.md`

package/templates/skills/apex/steps/step-03c-layer2-backend.md

@@ -0,0 +1,240 @@
+---
+name: step-03c-layer2-backend
+description: "Layer 2: Backend services, controllers, and tests"
+model: opus
+parent_step: steps/step-03-execute.md
+---
+
+## Layer 2 — Backend (Services + Controllers)
+
+### Task Progress
+TaskUpdate(taskId: layer2_task_id, status: "in_progress")
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 2",
+  activeForm: "Executing Layer 2")
+
+> **Layer 2 rules** are in `references/smartstack-layers.md` (already in context from step-02):
+> - NavRoute and permission kebab-case (Layer 2 - API section)
+> - Controller route attributes (FORBIDDEN: [Route] alongside [NavRoute])
+> - Validators DI registration
+> - DateOnly vs string for DTO date fields
+> - Code generation patterns (ICodeGenerator<T> registration, see references/code-generation.md)
+
+### Backend Tasks (sequential or parallel within layer)
+
+- Services/DTOs: MCP scaffold_extension
+- Controllers: use /controller skill for complex, MCP scaffold_extension for simple
+- Important: All GetAll endpoints must support `?search=` query parameter (enables EntityLookup on frontend)
+- Guard: DTO mapping in services MUST use inline construction (`new ResponseDto(...)`) inside IQueryable `.Select()`. Never use helper methods (MapToDto, ToDto) inside `.Select()` — EF Core cannot translate them. Helper methods are allowed only after materialization (ToListAsync, FirstAsync).
+
+### Code Generation Service Registration (per entity)
+
+```
+For each entity where {code_patterns} defines strategy != "manual":
+  1. Verify DI registration in DependencyInjection.cs:
+     → services.AddScoped<ICodeGenerator<{Entity}>>(sp => new CodeGenerator<{Entity}>(...))
+     → Use CodePatternConfig matching {code_patterns[entity]} values
+     → See references/code-generation.md "DI Registration Pattern"
+     → Guard: Do NOT duplicate if ICodeGenerator<{Entity}> is already registered
+  2. Verify service injection:
+     → {Entity}Service constructor receives ICodeGenerator<{Entity}>
+     → CreateAsync uses _codeGenerator.NextCodeAsync(ct) instead of dto.Code
+     → See references/code-generation.md "Service Integration Pattern"
+  3. Verify CreateDto:
+     → Code property MUST NOT be in Create{Entity}Dto
+     → Code property MUST be in {Entity}ResponseDto
+     → See references/code-generation.md "CreateDto Changes"
+  4. Verify Validator:
+     → Create{Entity}Validator has NO Code rule (auto-generated)
+     → Update{Entity}Validator has Code rule with regex ^[a-z0-9_-]+$ (if Code is mutable)
+```
+- FK inter-entity pattern: When an entity has FK to another business entity (e.g., Absence → Employee), use navigation properties directly inside `.Select()` (e.g., `x.Employee.Code`, `x.Employee.User!.LastName`). EF Core translates navigation access to SQL JOINs automatically. Do NOT use `.Include()` with `.Select()` — it is ignored. See `references/smartstack-api.md` "Service Pattern — Entity with FK to another business entity" for the full pattern.
+
+### Skill Delegation
+
+| Skill | When | Context to provide |
+|-------|------|--------------------|
+| /controller | Custom routes, complex auth, file upload | entity, CRUD actions, permissions, routes |
+| /application | Full app/module from scratch | app, module names |
+| /ui-components | Complex pages (tables, grids, dashboards) | entity, fields, page type |
+| /efcore | Complex EF configs, inheritance | relationships, indexes |
+| /notification | In-app or email notifications | trigger, recipients, template |
+| /workflow | Automated workflows | trigger, steps, conditions |
+
+### If NOT economy_mode AND multiple entities: Parallel Agents (within layer)
+
+> **Protocol:** See `references/parallel-execution.md`
+
+```
+IF NOT economy_mode AND entities.length > 1:
+  For each entity, launch in parallel (single message):
+    Agent(subagent_type='Snipper', model='opus',
+      prompt='Execute Layer 2 backend for {EntityName}:
+        - Application service/DTO: MCP scaffold_extension
+        - Controller: /controller skill or MCP scaffold_extension
+        - IMPORTANT: GetAll endpoint MUST support ?search= parameter
+        - Validators: FluentValidation + DI registration
+        - CODE GENERATION: {code_patterns[EntityName] summary — e.g., "strategy: sequential, prefix: emp, digits: 5" or "manual"}
+          If strategy != "manual": read references/code-generation.md, then:
+          → Register ICodeGenerator<{EntityName}> in DI (DependencyInjection.cs) with CodePatternConfig matching {code_patterns}
+          → Inject ICodeGenerator<{EntityName}> in {EntityName}Service, use _codeGenerator.NextCodeAsync(ct) in CreateAsync
+          → Remove Code from Create{EntityName}Dto (auto-generated, not user-provided)
+          → Keep Code in {EntityName}ResponseDto
+          → Create{EntityName}Validator: NO Code rule. Update{EntityName}Validator: Code rule with regex ^[a-z0-9_-]+$
+        - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
+        - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
+  # All agents launched in parallel
+
+ELSE:
+  # Agent principal handles all entities sequentially
+```
+
+### Parallel Agents + TaskCreate Integration
+
+When launching agents for multi-entity layers:
+- Each agent receives its task ID and metadata context in the prompt
+- Agent must call TaskUpdate(status: "in_progress") before starting
+- Agent must call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done
+- Agent principal monitors via TaskList() after all agents complete
+- Agent principal updates activeForm after each entity completion:
+  `TaskUpdate(taskId: layer2_task_id, activeForm: "Building {EntityName} backend (2/5 entities)")`
+
+### Controller NavRoute Attribute (MANDATORY)
+
+After controller generation, verify `[NavRoute]` attribute is present on every controller:
+- Expected: `[NavRoute("{app_name}.{module_code}.{section_code}")]` on the controller class
+- If missing: Add it manually above `[Authorize]`
+- When calling `scaffold_extension(type: "controller")`, always pass `navRoute` in options
+- This is REQUIRED for `scaffold_routes` to auto-detect routes in Layer 3
+
+### Guard: NavRoute Uniqueness and Segment Count (MANDATORY)
+
+**BEFORE proceeding past Layer 2**, verify for EACH controller:
+
+1. **Unique NavRoute:** No two controllers may share the same `[NavRoute("...")]` value. Duplicate NavRoutes cause routing conflicts → 404s on one of the controllers.
+
+2. **Segment count matches hierarchy:** Count the dots in the NavRoute value:
+   - 1 dot = 2 segments (module-level, e.g., `human-resources.employees`) — controller is at `Controllers/{App}/`
+   - 2 dots = 3 segments (section-level, e.g., `human-resources.employees.contracts`) — controller is at `Controllers/{App}/{Module}/` or in a section subfolder
+   - **If a controller is in a section subfolder** (e.g., `Controllers/{App}/Employees/ContractsController.cs`) **but has only 2 segments** → the API route will be wrong → 404. It MUST have 3 segments.
+   - 0 dots = INVALID → BLOCK
+
+```bash
+# Quick validation
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+for f in $CTRL_FILES; do
+  NAVROUTE=$(grep -oP '\[NavRoute\("\K[^"]+' "$f")
+  if [ -n "$NAVROUTE" ]; then
+    DOTS=$(echo "$NAVROUTE" | tr -cd '.' | wc -c)
+    if [ "$DOTS" -eq 0 ]; then
+      echo "BLOCKING: NavRoute '$NAVROUTE' has only 1 segment (need minimum 2): $f"
+      exit 1
+    fi
+    # Check if controller is in a section subfolder but NavRoute has only 2 segments
+    DEPTH=$(echo "$f" | grep -oP 'Controllers/[^/]+/[^/]+/' | wc -l)
+    if [ "$DEPTH" -gt 0 ] && [ "$DOTS" -eq 1 ]; then
+      echo "WARNING: Controller in section subfolder but NavRoute has only 2 segments: $f"
+      echo "  NavRoute: $NAVROUTE — expected 3 segments (app.module.section)"
+    fi
+  fi
+done
+```
+
+```bash
+# Quick check: all controllers must have [NavRoute] (not just [Route])
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+for f in $CTRL_FILES; do
+  if ! grep -q "\[NavRoute" "$f" && grep -q "\[Route" "$f"; then
+    echo "WARNING: $f has [Route] but no [NavRoute] — add [NavRoute] for route auto-detection"
+  fi
+done
+```
+
+### Layer 2 Build Gate — NavRoute Verification
+
+> Fail-fast check: detect MCP generation errors BEFORE Layer 3.
+> Does NOT auto-fix — flags as BLOCKING for manual correction.
+> Full validation in step-04 POST-CHECK C43 + C56.
+
+After all controllers are generated and build passes:
+
+```bash
+# Check only controllers generated in this run (match against {entities})
+for ENTITY in $ENTITIES; do
+  CTRL=$(find src/ -path "*/Controllers/*" -name "${ENTITY}*Controller.cs" 2>/dev/null | head -1)
+  [ -z "$CTRL" ] && continue
+
+  HAS_NAVROUTE=$(grep -c "\[NavRoute" "$CTRL")
+  HAS_ROUTE=$(grep -cP "^\s*\[Route\(" "$CTRL")  # class-level only
+
+  if [ "$HAS_NAVROUTE" -eq 0 ] && [ "$HAS_ROUTE" -gt 0 ]; then
+    echo "BLOCKING: $CTRL has [Route] but NO [NavRoute]"
+    echo "MCP scaffold_extension generated [Route] instead of [NavRoute]"
+    echo "Fix: Replace [Route(\"api/...\")] with [NavRoute(\"{app}.{module}.{section}\")]"
+    echo "  NavRoute value: derive from naming rules (section 4f)"
+    echo "  Add: using SmartStack.Api.Routing;"
+  fi
+
+  if [ "$HAS_NAVROUTE" -eq 0 ] && [ "$HAS_ROUTE" -eq 0 ]; then
+    echo "BLOCKING: $CTRL has NO route attribute at all"
+    echo "Fix: Add [NavRoute(\"{app}.{module}.{section}\")] from naming rules"
+  fi
+done
+```
+
+> IF any BLOCKING found: fix the controller(s) BEFORE proceeding to Layer 3.
+> The fix is: remove [Route], add [NavRoute] with the correct dot-separated value,
+> add `using SmartStack.Api.Routing;`.
+
+### Post-Layer 2 Build Gate
+
+```bash
+dotnet build
+```
+
+Must pass before backend tests.
+
+TaskUpdate(taskId: layer2_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+TaskUpdate(taskId: progress_tracker_id,
+  activeForm: "Running build gate (Layer 2)")
+
+### Backend Tests Inline
+
+> **Tests are scaffolded and run WITHIN Layer 2, not deferred to step-07.**
+
+```
+1. Scaffold backend tests:
+   → MCP scaffold_tests (target_layer: "domain", module: "{module_code}", test_type: "unit")
+   → MCP scaffold_tests (target_layer: "application", module: "{module_code}", test_type: "unit")
+   → MCP scaffold_tests (target_layer: "api", module: "{module_code}", test_type: "integration")
+
+2. Run tests:
+   dotnet test --no-build --verbosity normal
+
+3. Fix loop (max 3 iterations):
+   IF tests fail:
+     → Identify root cause (ALWAYS code bug, not test bug)
+     → Fix production CODE via appropriate skill/MCP
+     → dotnet build --no-restore
+     → dotnet test --no-build
+     → Repeat until pass or max 3
+
+4. If still failing after 3 iterations: note failures, continue to Layer 3.
+   Step-07 "Final Test Sweep" will handle remaining failures.
+```
+
+### Layer 2 Commits
+
+```
+feat({module}): [app+api] {short description}
+test({module}): backend unit and integration tests
+```
+
+> **Context release:** `references/smartstack-api.md` entity patterns and `references/smartstack-layers.md` Layer 2 rules have been consumed. Layer 3 only needs their frontend sections (already covered by `smartstack-frontend.md`).
+
+---
+
+## NEXT SUB-STEP
+
+Load `steps/step-03d-layer3-frontend.md`