@atlashub/smartstack-cli 3.53.0 → 4.0.0

package/templates/skills/apex/references/smartstack-layers.md

@@ -95,83 +95,11 @@ Web            → Application (via API clients)
 
 ---
 
-## Layer 1 — Application (parallel with API)
-
-**Services:** `Application/Services/{App}/{Module}/` (interface)
-**Service impls:** `Infrastructure/Services/{App}/{Module}/` (implementation)
-**DTOs:** `Application/DTOs/{App}/{Module}/`
-**Validators:** `Application/Validators/{App}/{Module}/`
-
-| Action | Tool |
-|--------|------|
-| Create service/DTO | MCP `scaffold_extension` |
-| Complex service logic | /application skill |
-| Validate | MCP `validate_conventions` |
-
-**Rules:**
-- **Tenant injection depends on entity tenant mode** (see entity rules below):
-  - **strict mode (default):** Inject `ICurrentTenantService` + guard clause: `var tenantId = _currentTenant.TenantId ?? throw new TenantContextRequiredException();` (mandatory, returns 400)
-  - **optional mode:** Inject `ICurrentTenantService`, no guard: `var tenantId = _currentTenant.TenantId;` (nullable). EF global filter handles shared+tenant data.
-  - **scoped mode:** Inject `ICurrentTenantService`, validate Scope + TenantId consistency. Tenant scope requires TenantId.
-  - **none mode:** No `ICurrentTenantService` injection needed (cross-tenant data, no filtering)
-- **ALL services MUST inject `ICurrentUserService`** for audit trails
-- **ALL services MUST inject `ILogger<T>`** for production diagnostics
-- CQRS with MediatR
-- FluentValidation for all commands — **MUST register validators via DI:**
-  `services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();`
-  Without DI registration, `[FromBody]` DTOs are never validated (POST-CHECK 38)
-- **Date fields in DTOs MUST use `DateOnly`**, not `string` (POST-CHECK 39). See `smartstack-api.md` DTO Type Mapping.
-- DTOs separate from domain entities
-- Service interfaces in Application, implementations in Infrastructure
-- **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`), `string` type for date fields
-- **Person Extension services:** If entity has `personRoleConfig`:
-  - `Include(x => x.User)` on ALL queries (mandatory)
-  - Inject `ICoreDbContext` for User existence checks
-  - Mandatory: search on `User.FirstName`, `User.LastName`, `User.Email`
-  - Optional: search fallback `User.FirstName ?? x.FirstName`
-  - CreateAsync: verify User exists + no duplicate `(TenantId, UserId)`
-  - ResponseDto: include `Display*` fields resolved from User join
-
----
-
-## Layer 1 — API (parallel with Application)
-
-**Controllers:** `Api/Controllers/{AppPascal}/{Entity}Controller.cs`
-
-| Action | Tool |
-|--------|------|
-| Simple CRUD controller | MCP `scaffold_extension` |
-| Complex controller | /controller skill |
-| Validate | MCP `validate_security` |
-
-**Rules:**
-- `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
-- **NavRoute minimum 2 segments** (application.module):
-  - `[NavRoute("human-resources.employees")]` (CORRECT — module-level, 2 segments)
-  - `[NavRoute("human-resources.employees.departments")]` (CORRECT — section-level, 3 segments)
-  - `[NavRoute("administration.ai", Suffix = "prompts")]` (CORRECT — sub-resource with Suffix)
-- **NavRoute values MUST use kebab-case for ALL multi-word segments:**
-  - `[NavRoute("human-resources.employees")]` (CORRECT)
-  - `[NavRoute("humanresources.employees")]` (WRONG — missing hyphens)
-  - `[NavRoute("project-management.projects")]` (CORRECT)
-  - `[NavRoute("projectmanagement.projects")]` (WRONG)
-- Permission paths MUST use kebab-case matching NavRoute codes (e.g., `human-resources.employees.read`)
-- FORBIDDEN: concatenated segments like `humanresources` — must be `human-resources`
-- POST-CHECK 32 detects non-kebab-case NavRoute values. POST-CHECK 33 detects non-kebab-case permissions
-- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes 404s (POST-CHECK 41)
-- `[NavRoute]` is the ONLY route attribute needed — resolves routes from DB at startup
-- NEVER use `[Authorize]` without specific permission
-- Swagger XML documentation
-- Return DTOs, never domain entities
-- **Person Extension DTOs:** ResponseDto MUST include `Display*` fields (`DisplayFirstName`, `DisplayLastName`, `DisplayEmail`) resolved from User join. Mandatory CreateDto: `Guid UserId` only. Optional CreateDto: `Guid? UserId` + person fields.
-
----
-
-## Layer 1 — Seed Data (parallel)
+## Layer 1 — Seed Data (DEDICATED LAYER — sequential)
 
 **Folder:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/`
 
-> **Detailed templates:** See ralph-loop `references/core-seed-data.md` for complete C# code templates.
+> **Detailed templates:** See `references/core-seed-data.md` for complete C# code templates.
 > Navigation hierarchy: Application → Module → Section → Resource (ALL levels need seed data).
 
 | Action | Tool |
@@ -268,7 +196,79 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 
 ---
 
-## Layer 2 — Frontend (parallel with I18n)
+## Layer 2 — Application (parallel with API within layer)
+
+**Services:** `Application/Services/{App}/{Module}/` (interface)
+**Service impls:** `Infrastructure/Services/{App}/{Module}/` (implementation)
+**DTOs:** `Application/DTOs/{App}/{Module}/`
+**Validators:** `Application/Validators/{App}/{Module}/`
+
+| Action | Tool |
+|--------|------|
+| Create service/DTO | MCP `scaffold_extension` |
+| Complex service logic | /application skill |
+| Validate | MCP `validate_conventions` |
+
+**Rules:**
+- **Tenant injection depends on entity tenant mode** (see entity rules below):
+  - **strict mode (default):** Inject `ICurrentTenantService` + guard clause: `var tenantId = _currentTenant.TenantId ?? throw new TenantContextRequiredException();` (mandatory, returns 400)
+  - **optional mode:** Inject `ICurrentTenantService`, no guard: `var tenantId = _currentTenant.TenantId;` (nullable). EF global filter handles shared+tenant data.
+  - **scoped mode:** Inject `ICurrentTenantService`, validate Scope + TenantId consistency. Tenant scope requires TenantId.
+  - **none mode:** No `ICurrentTenantService` injection needed (cross-tenant data, no filtering)
+- **ALL services MUST inject `ICurrentUserService`** for audit trails
+- **ALL services MUST inject `ILogger<T>`** for production diagnostics
+- CQRS with MediatR
+- FluentValidation for all commands — **MUST register validators via DI:**
+  `services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();`
+  Without DI registration, `[FromBody]` DTOs are never validated (POST-CHECK 38)
+- **Date fields in DTOs MUST use `DateOnly`**, not `string` (POST-CHECK 39). See `smartstack-api.md` DTO Type Mapping.
+- DTOs separate from domain entities
+- Service interfaces in Application, implementations in Infrastructure
+- **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`), `string` type for date fields
+- **Person Extension services:** If entity has `personRoleConfig`:
+  - `Include(x => x.User)` on ALL queries (mandatory)
+  - Inject `ICoreDbContext` for User existence checks
+  - Mandatory: search on `User.FirstName`, `User.LastName`, `User.Email`
+  - Optional: search fallback `User.FirstName ?? x.FirstName`
+  - CreateAsync: verify User exists + no duplicate `(TenantId, UserId)`
+  - ResponseDto: include `Display*` fields resolved from User join
+
+---
+
+## Layer 2 — API (parallel with Application within layer)
+
+**Controllers:** `Api/Controllers/{AppPascal}/{Entity}Controller.cs`
+
+| Action | Tool |
+|--------|------|
+| Simple CRUD controller | MCP `scaffold_extension` |
+| Complex controller | /controller skill |
+| Validate | MCP `validate_security` |
+
+**Rules:**
+- `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
+- **NavRoute minimum 2 segments** (application.module):
+  - `[NavRoute("human-resources.employees")]` (CORRECT — module-level, 2 segments)
+  - `[NavRoute("human-resources.employees.departments")]` (CORRECT — section-level, 3 segments)
+  - `[NavRoute("administration.ai", Suffix = "prompts")]` (CORRECT — sub-resource with Suffix)
+- **NavRoute values MUST use kebab-case for ALL multi-word segments:**
+  - `[NavRoute("human-resources.employees")]` (CORRECT)
+  - `[NavRoute("humanresources.employees")]` (WRONG — missing hyphens)
+  - `[NavRoute("project-management.projects")]` (CORRECT)
+  - `[NavRoute("projectmanagement.projects")]` (WRONG)
+- Permission paths MUST use kebab-case matching NavRoute codes (e.g., `human-resources.employees.read`)
+- FORBIDDEN: concatenated segments like `humanresources` — must be `human-resources`
+- POST-CHECK 32 detects non-kebab-case NavRoute values. POST-CHECK 33 detects non-kebab-case permissions
+- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes 404s (POST-CHECK 41)
+- `[NavRoute]` is the ONLY route attribute needed — resolves routes from DB at startup
+- NEVER use `[Authorize]` without specific permission
+- Swagger XML documentation
+- Return DTOs, never domain entities
+- **Person Extension DTOs:** ResponseDto MUST include `Display*` fields (`DisplayFirstName`, `DisplayLastName`, `DisplayEmail`) resolved from User join. Mandatory CreateDto: `Guid UserId` only. Optional CreateDto: `Guid? UserId` + person fields.
+
+---
+
+## Layer 3 — Frontend (parallel with I18n within layer)
 
 > **Detailed patterns:** See `references/smartstack-frontend.md` for complete code templates.
 
@@ -390,7 +390,7 @@ See `references/smartstack-frontend.md` section 6 for the full `EntityLookup` co
 
 ---
 
-## Layer 2 — I18n
+## Layer 3 — I18n
 
 > **Template:** See `references/smartstack-frontend.md` Section 2 for complete JSON template.
 
@@ -409,7 +409,7 @@ t('{module}:actions.create', 'Create entity') // ALWAYS with namespace prefix
 
 ---
 
-## Layer 2b — Documentation (after frontend pages exist)
+## Layer 3 — Documentation (after frontend pages exist)
 
 > **After frontend pages are created, generate module documentation.**
 
@@ -428,19 +428,19 @@ See `references/smartstack-frontend.md` section 7 for the component pattern.
 
 ---
 
-## Layer 3 — Tests (sequential)
+## Layer 4 — DevData (optional)
+
+**Folder:** `Infrastructure/Persistence/Seeding/DevData/`
 
 | Action | Tool |
 |--------|------|
-| Unit tests (domain) | MCP `scaffold_tests` (target_layer: domain) |
-| Unit tests (app) | MCP `scaffold_tests` (target_layer: application) |
-| Integration tests (api) | MCP `scaffold_tests` (target_layer: api, type: integration) |
-| Security tests | MCP `scaffold_tests` (type: security) |
-| Coverage check | MCP `analyze_test_coverage` |
-| Scenarios | MCP `suggest_test_scenarios` |
+| Create DevDataSeeder | Manual / template |
 
-**Target:** >= 80% coverage, 100% pass rate.
-**Fix CODE, not tests.**
+**Rules:**
+- Business test data for development/demo environments
+- ALL DevData entities MUST include `TenantId`
+- DevData depends on seed data (navigation, permissions) being in place
+- Optional — skip if no meaningful test data needed
 
 ---
 
@@ -466,23 +466,28 @@ For EACH file in the plan, specify HOW it will be created/modified:
 | 2 | Infrastructure/.../EntityConfiguration.cs | create | MCP scaffold_extension |
 | 3 | Infrastructure/Migrations/ | create | MCP suggest_migration + dotnet ef |
 
-**Layer 1 — Application + API + Seed Data (parallel):**
+**Layer 1 — Seed Data (sequential):**
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 4 | Seeding/Data/NavigationApplicationSeedData.cs | create | Reference core-seed-data.md (once per app) |
+| 4b | Seeding/Data/ApplicationRolesSeedData.cs | create | Reference core-seed-data.md (once per app) |
+| 5 | Seeding/Data/.../NavigationModuleSeedData.cs | create | Reference core-seed-data.md (4 langs) |
+| 5b | Application/Authorization/Permissions.cs | create | MCP generate_permissions |
+| 6 | Seeding/Data/.../PermissionsSeedData.cs | create | MCP generate_permissions |
+| 7 | Seeding/Data/.../RolesSeedData.cs | create | Reference core-seed-data.md |
+| 7b | Seeding/{App}SeedDataProvider.cs | create | Reference core-seed-data.md (IClientSeedDataProvider + DI) |
+
+**Layer 2 — Backend (parallel within layer):**
 
 | # | File | Action | Tool |
 |---|------|--------|------|
-| 4 | Application/Services/.../Service.cs | create | MCP scaffold_extension |
-| 5 | Application/DTOs/.../Dto.cs | create | MCP scaffold_extension |
-| 6 | Api/Controllers/.../Controller.cs | create | /controller skill or MCP scaffold_extension |
-| 7 | Seeding/Data/NavigationApplicationSeedData.cs | create | Reference Layer 1 Seed Data (once per app) |
-| 7b | Seeding/Data/ApplicationRolesSeedData.cs | create | Reference Layer 1 Seed Data (once per app) |
-| 7c | Infrastructure/Services/CodeGeneration/ | create | Reference code-generation.md (if codePattern != manual) |
-| 8 | Seeding/Data/.../NavigationModuleSeedData.cs | create | Reference core-seed-data.md (4 langs) |
-| 8b | Application/Authorization/Permissions.cs | create | MCP generate_permissions |
-| 9 | Seeding/Data/.../PermissionsSeedData.cs | create | MCP generate_permissions |
-| 10 | Seeding/Data/.../RolesSeedData.cs | create | Reference Layer 1 Seed Data |
-| 10b | Seeding/{App}SeedDataProvider.cs | create | Reference core-seed-data.md (IClientSeedDataProvider + DI) |
-
-**Layer 1 — Frontend (parallel):**
+| 8 | Application/Services/.../Service.cs | create | MCP scaffold_extension |
+| 9 | Application/DTOs/.../Dto.cs | create | MCP scaffold_extension |
+| 9b | Infrastructure/Services/CodeGeneration/ | create | Reference code-generation.md (if codePattern != manual) |
+| 10 | Api/Controllers/.../Controller.cs | create | /controller skill or MCP scaffold_extension |
+
+**Layer 3 — Frontend + I18n + Documentation (parallel within layer):**
 
 | # | File | Action | Tool |
 |---|------|--------|------|
@@ -492,30 +497,32 @@ For EACH file in the plan, specify HOW it will be created/modified:
 | 12 | src/services/api/{module}Api.ts | create | MCP scaffold_api_client |
 | 13 | src/routes/{module}.tsx | create | MCP scaffold_routes |
 | 14 | src/i18n/locales/{lang}/{module}.json | create | Reference smartstack-frontend.md (4 languages) |
-
-**Layer 2b — Documentation (after frontend):**
-
-| # | File | Action | Tool |
-|---|------|--------|------|
 | 14b | src/pages/docs/business/{app}/{module}/doc-data.ts | create | /documentation skill |
 | 14c | src/pages/docs/business/{app}/{module}/index.tsx | create | /documentation skill |
 
-**Layer 3 — Tests (sequential):**
-
-| # | File | Action | Tool |
-|---|------|--------|------|
-| 15 | tests/.../EntityTests.cs | create | MCP scaffold_tests |
-| 16 | tests/.../ServiceTests.cs | create | MCP scaffold_tests |
-
 **FK Field Guidance:** If step-01 identified `fkFields[]`, every Create/Edit page MUST use `EntityLookup` for those fields (see `smartstack-frontend.md` section 6).
 
 ---
 
 ## Parallelization Strategy (Agent Teams)
 
-If NOT economy_mode AND Layer 1 has both backend and frontend work:
+> **Cross-layer parallelism is FORBIDDEN.** Layers execute sequentially: 0 → 1 → 2 → 3 → 4.
+> Agent teams are used **within** a layer to parallelize multi-entity work.
+
+If NOT economy_mode AND a layer has multiple entities to process:
+
+**Create agent teams WITHIN the layer to parallelize multi-entity work.**
+
+- **Layer 2 (Backend):** If multiple entities, spawn entity-specific teammates (each handles service + controller for one entity)
+- **Layer 3 (Frontend):** If multiple entities, spawn entity-specific teammates (each handles pages + i18n for one entity)
 
-**Create agent teams to execute Layer 1 backend and frontend in parallel.**
+| Condition | Action |
+|-----------|--------|
+| economy_mode = true | NO teams, all sequential |
+| Single entity | NO teams, agent principal handles all layers |
+| Multiple entities, Layer 2 | Teams: one teammate per entity (service + controller) |
+| Multiple entities, Layer 3 | Teams: one teammate per entity (pages + i18n) |
+| Analysis phase (step-01) | Teams: scan-backend + scan-frontend + scan-context |
 
 See `references/agent-teams-protocol.md` for team creation, teammate spawning, task coordination, and shutdown.
 
@@ -528,10 +535,10 @@ When `/ralph-loop` invokes `/apex -d {prd_path}`, PRD tasks already define the s
 Map each PRD task to a layer based on `task.category`:
 - `domain` → Layer 0
 - `infrastructure` → Layer 0
-- `application` → Layer 1
-- `api` → Layer 1
 - `seedData` → Layer 1
-- `frontend` → Layer 2
-- `test` → Layer 3
+- `application` → Layer 2
+- `api` → Layer 2
+- `frontend` → Layer 3
+- `test` → inline (Layer 2 backend tests, Layer 3 frontend tests)
 
 For each task: infer file_path, action, and tool from category. SKIP user checkpoint. Jump to "Estimated Commits" section.

package/templates/skills/apex/steps/step-02-plan.md

@@ -28,11 +28,11 @@ IF delegate_mode:
   Map each PRD task to a layer based on task.category:
     domain          → Layer 0
     infrastructure  → Layer 0
-    application     → Layer 1
-    api             → Layer 1
     seedData        → Layer 1
-    frontend        → Layer 2
-    test            → Layer 3
+    application     → Layer 2
+    api             → Layer 2
+    frontend        → Layer 3
+    test            → inline (Layer 2 backend tests, Layer 3 frontend tests)
 
   For each task:
     file_path    = task.files_changed.created[0] (primary file)
@@ -56,12 +56,12 @@ IF delegate_mode:
 ## 1-3. Layer Mapping, Skill Assignment, Parallelization
 
 > **Reference:** All planning procedures are now in `references/smartstack-layers.md` (already loaded above):
-> - Layer assignment matrix (Domain/Infrastructure/Application/API/Seed/Frontend/Tests)
+> - Layer assignment matrix (Domain/Infrastructure/Seed/Application/API/Frontend/DevData)
 > - Entity definition template (tenantMode, codePattern, fkFields, ACs)
 > - Skill/MCP assignment table (per file, per layer)
-> - Layer 0/1/2b/3 file lists with tools (see "Planning Template" section)
+> - Layer 0/1/2/3/4 file lists with tools (see "Planning Template" section)
 > - FK field guidance (EntityLookup + backend ?search= parameter)
-> - Parallelization strategy (Agent Teams for Layer 1 backend+frontend)
+> - Parallelization strategy (Agent Teams within Layer 2/3 for multi-entity)
 > - Delegate mode fast path (PRD task mapping to layers)
 
 ```
@@ -69,12 +69,22 @@ Layer 0: SEQUENTIAL (agent principal)
   → domain + infra + migration
   → dotnet build --no-restore (BLOCKING)
 
-Layer 1: PARALLEL (Agent Teams)
-  → exec-backend: application + api + seed data
-  → exec-frontend: frontend + i18n
+Layer 1: SEQUENTIAL (agent principal)
+  → seed data (navigation, permissions, roles)
+  → dotnet build (BLOCKING)
 
-Layer 2: SEQUENTIAL (agent principal)
-  → final validation + tests
+Layer 2: PARALLEL WITHIN LAYER (Agent Teams if multi-entity)
+  → services + controllers
+  → dotnet build (BLOCKING)
+  → backend tests inline (scaffold + run + fix max 3)
+
+Layer 3: PARALLEL WITHIN LAYER (Agent Teams if multi-entity)
+  → pages + i18n + documentation
+  → compliance gate (BLOCKING)
+  → frontend tests inline (scaffold + run + fix max 3)
+
+Layer 4: OPTIONAL (agent principal)
+  → DevData seeder
 ```
 
 If economy_mode: ALL layers sequential, agent principal only.
@@ -87,14 +97,15 @@ Verify the plan respects dependencies:
 
 ```
 - Migration AFTER EF configs (always)
+- Seed data AFTER migration (Layer 1 depends on Layer 0 build gate)
 - Application services AFTER domain entities (always)
 - Code generator service AFTER entity + EF config (needs DbSet for sequence query)
 - CreateDto adjustments AFTER code pattern decision (remove Code property if auto-generated)
 - Controllers AFTER application services (always)
+- Backend tests AFTER services + controllers (inline in Layer 2)
 - Frontend AFTER API controllers (API contract needed)
-- Seed data AFTER navigation module exists
-- Tests AFTER all code layers complete
-- Build check between Layer 0 and Layer 1 (BLOCKING)
+- Frontend tests AFTER pages created (inline in Layer 3)
+- Build gate between EVERY layer (BLOCKING): Layer 0 → 1 → 2 → 3 → 4
 ```
 
 ---
@@ -103,12 +114,16 @@ Verify the plan respects dependencies:
 
 ```
 feat({module}): [domain+infra] {description}
+feat({module}): [seed] navigation, permissions, roles
 feat({module}): [app+api] {description}
-feat({module}): [frontend] {description}
-feat({module}): [seed] {description}
-feat({module}): [tests] {description}
+test({module}): backend unit and integration tests
+feat({module}): [frontend] pages, routes, i18n, documentation
+test({module}): frontend form tests
+feat({module}): [devdata] test data for development  # if applicable
 ```
 
+**Maximum 7 commits per module.**
+
 ---
 
 ## 6. User Checkpoint (if NOT auto_mode)